From 0a534f8f71df346780b8b101a0b5183d51575ff4 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:08:36 -0800 Subject: [PATCH] Move cli config info to getting-started --- .../modules/ROOT/pages/getting-started.adoc | 590 ++++++++++++------ .../modules/ROOT/pages/managing.adoc | 354 +---------- 2 files changed, 383 insertions(+), 561 deletions(-) diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc index 312de42..1641b86 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc @@ -21,6 +21,7 @@ To configure the {product}: * If you plan to manage an {astra_db} database that has restricted public access, then you must xref:astra-db-serverless:administration:manage-database-ip-access-list.adoc#add-ip-access-list-entries[add your IP address to the database's access list]. +[#initialize] == Initialize the {product} After installation, initialize the {product} and connect it to an existing Astra account. @@ -35,13 +36,6 @@ astra setup --token *APPLICATION_TOKEN* Replace `*APPLICATION_TOKEN*` with your application token. The token format is `AstraCS:` followed by a unique token string. + -For example: -+ -[source,bash] ----- -astra setup --token AstraCS:ozgLKiotAPSgFvBylkUEdPzB:3d061eaa636a6a032f352588f5ba2b777fefdd80f201640063576a9732c4a54d ----- -+ .Result [%collapsible] ==== @@ -53,7 +47,7 @@ astra setup --token AstraCS:ozgLKiotAPSgFvBylkUEdPzB:3d061eaa636a6a032f352588f5b ---- ==== -. List the {product} configuration to confirm that your connection profile is present: +. List the {product} configuration to confirm that your token is in use: + [source,bash] ---- @@ -73,11 +67,11 @@ astra config list ---- ==== -The {product} is initialized and your application token is set as the default connection profile. -The {product} uses the default connection profile whenever you run a command without specifying a profile. +The {product} is initialized and your application token is set as the default configuration. +The {product} uses the default configuration whenever you run a command without the `--config` option. -The {product} stores connection profiles and their associated application tokens in the `~/.astrarc` file. -To configure additional connection profiles, see <>. +The {product} stores configurations and their associated application tokens in the `~/.astrarc` file. +To create additional configurations, see <>. [IMPORTANT] ==== @@ -85,200 +79,9 @@ Application tokens are stored in plain text in the `~/.astrarc` file. Your application tokens are like passwords, therefore you should take precautions to secure the configuration file. ==== -[#connection-profiles] -== Set up connection profiles - -A _connection profile_ consists of a name and an application token. -When you run the `astra setup` command during initialization, the {product} stores your application token as the default connection profile in the `~/.astrarc` configuration file. +== Display help information -You can create additional connection profiles to make it easier to manage resources and organizations with different application tokens. - -=== Create a new connection profile - -Create a new connection profile with a different application token. - -. Use the `astra config create` command to create a new connection profile: -+ -[source,bash,subs="+quotes"] ----- -astra config create *PROFILE_NAME* --token *APPLICATION_TOKEN* ----- -+ -Replace the following: -+ --- -* `*PROFILE_NAME*`: The name you want to give the new connection profile. -* `*APPLICATION_TOKEN*`: Your application token. -The application token can be for the same or different Astra organization than the one you used to initially set up the {product}. --- -+ -For example: -+ -[source,bash] ----- -astra config create dev --token AstraCS:ozgLKiotATXgFvBylkUEdPzB:3d061eaa636a6a032f352588f5ba2b777fefdd80f201640063576a9732c4a54d ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -[OK] Configuration has been saved. ----- -==== - -. List the {product} configuration to confirm that the new profile is created: -+ -[source,bash] ----- -astra config list ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -+--------------------------------+ -| configuration | -+--------------------------------+ -| alex@altostrat.com (in use) | -| dev | -+--------------------------------+ ----- -==== - -[#switch-profiles] -=== Switch between connection profiles - -Switch to a different connection profile to connect to Astra with a different application token. - -. Use the `astra config use` command to switch to a different connection profile: -+ -[source,bash,subs="+quotes"] ----- -astra config use *PROFILE_NAME* ----- -+ -Replace `*PROFILE_NAME*` with the name of the connection profile you want to switch to. -+ -For example: -+ -[source,bash] ----- -astra config use dev ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -[OK] Section 'dev' is set as default. ----- -==== - -. List the {product} configuration to confirm that you successfully switched profiles: -+ -[source,bash] ----- -astra config list ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -+--------------------------------+ -| configuration | -+--------------------------------+ -| dev (in use) | -| alex@altostrat.com | -+--------------------------------+ ----- -==== - -=== Delete a connection profile - -Delete a connection profile that you no longer need. - -. Use the `astra config delete` command to delete a connection profile: -+ -[source,bash,subs="+quotes"] ----- -astra config delete *PROFILE_NAME* ----- -+ -Replace `*PROFILE_NAME*` with the name of the connection profile you want to delete. -+ -For example: -+ -[source,bash] ----- -astra config delete dev ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -[OK] Section 'dev' has been deleted. ----- -==== -+ -The connection profile and its associated application token are deleted from the `~/.astrarc` configuration file. -+ -[NOTE] -==== -If you delete the connection profile that is currently in use, you must <> before you can run {product} commands that connect to Astra. -==== - -. List the {product} configuration to confirm that the connection profile is deleted: -+ -[source,bash] ----- -astra config list ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -+--------------------------------+ -| configuration | -+--------------------------------+ -| alex@altostrat.com (in use) | -+--------------------------------+ ----- -==== - -== Set up auto-completion - -The {product} provides Bash auto-completion for `bash` and `zsh` shells. - -To use auto-completion, type the `astra` command and then press kbd:[Tab] twice to get a list of available options. - -[source,bash,subs="macros"] ----- -astra kbd:[Tab] kbd:[Tab] ----- - -.Result -[%collapsible%open] -==== -[source,console] ----- - --no-color config db help role setup shell user ----- -==== - -== Get help - -To display the main help: +Use `astra help` to display the main help information: [source,bash] ---- @@ -309,7 +112,8 @@ See 'astra help ' for more information on a specific command. ---- ==== -To display help for a command group, for example `db`: +Append a command name to display help information about an individual command. +For example: [source,bash] ---- @@ -435,8 +239,6 @@ SYNOPSIS ---- ==== -To display help for a specific command, for example `db list`: - [source,bash] ---- astra help db list @@ -482,3 +284,375 @@ OPTIONS Create a database with vector search enabled ---- ==== + +== Set up auto-completion + +The {product} provides Bash auto-completion for `bash` and `zsh` shells. + +To use auto-completion, type the `astra` command and then press kbd:[Tab] twice to get a list of available options. + +[source,bash,subs="macros"] +---- +astra kbd:[Tab] kbd:[Tab] +---- + +.Result +[%collapsible%open] +==== +[source,console] +---- + --no-color config db help role setup shell user +---- +==== + +[#manage-configuration] +== Manage the {product} configuration + +When you run the `astra setup` command during <>, the {product} stores your application token as the default configuration in the `~/.astrarc` configuration file. +You can create additional configurations, each with their own application token, to make it easier to manage different types of resources across one or more organizations. + +Use `astra config list` to list all current configurations: + +[source,bash] +---- +astra config list +---- + +.Result +[%collapsible] +==== +[source,console] ++----------------------------+ +| configuration | ++----------------------------+ +| Organization 1 (in use) | +| Organization 2 | ++----------------------------+ +==== + +Use `astra config create` to create a new configuration: + +[source,bash,subs="+quotes"] +---- +astra config create "**CONFIG_NAME**" --token **APPLICATION_TOKEN** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[OK] Configuration has been saved. +---- +==== + +Use `astra config use` to change the default configuration that {product} uses when executing commands: + +[source,bash,subs="+quotes"] +---- +astra config use "**CONFIG_NAME**" +---- + +.Result +[%collapsible] +==== +[source,console,subs="+quotes"] +---- +[OK] Section '**CONFIG_NAME**' is set as default. +---- + +Use `astra config list` to confirm that the selected configuration is now the default. +==== + +[TIP] +==== +Every {product} command supports the `--config` option, which lets you specify a configuration to use for that command. +This lets you use different configurations for different commands without changing the default configuration. + +For example: + +[source,bash,subs="+quotes"] +---- +astra user list --config "**CONFIG_NAME**" +---- +==== + +Use `astra config delete` to delete a configuration: + +[source,bash,subs="+quotes"] +---- +astra config delete "**CONFIG_NAME**" +---- + +.Result +[%collapsible] +==== +[source,console,subs="+quotes"] +---- +[OK] Section '**CONFIG_NAME**' has been deleted. +---- + +Use `astra config list` to confirm that the selected configuration is now the default. +==== + +[NOTE] +==== +If you delete the default configuration, the {product} does _not_ automatically select a new default configuration. +Use the `astra config use` command to select a new default configuration. +==== + +=== `config` options + +[source,console] +---- +NAME + astra config - Manage configuration file + +SYNOPSIS + astra config { create | delete | describe | get | list* | use } [--] + [ {-cf | --config-file} ] [ --no-color ] + [ {-v | --verbose} ] [ {-o | --output} ] [cmd-options] + + + Where command-specific options [cmd-options] are: + create: [ {-e | --env} ] [ {-t | --token} ] + delete: + describe: [ {-k | --key} ] + get: [ {-k | --key} ] + list: + use: + + Where command-specific arguments are: + create: [ ] + delete: + describe: + get: + list: + use: + + Where * indicates the default command(s) + See 'astra help config ' for more information on a specific command. +---- + +.`config create` options +[%collapsible] +==== +[source,console] +---- +NAME + astra config create - Create a new section in configuration + +SYNOPSIS + astra config create [ {-cf | --config-file} ] + [ {-e | --env} ] [ --no-color ] + [ {-o | --output} ] [ {-t | --token} ] + [ {-v | --verbose} ] [--] [ ] + +OPTIONS + -cf , --config-file + Configuration file (default = ~/.astrarc) + + -e , --env + Environment to use for this section. + + --no-color + Remove all colors in output + + -o , --output + Output format, valid values are: human,json,csv + + -t , --token + Key to use authenticate each call. + + -v, --verbose + Verbose mode with log in console + + -- + This option can be used to separate command-line options from the + list of arguments (useful when arguments might be mistaken for + command-line options) + + + Section in configuration file to as as default. +---- +==== + +.`config delete` options +[%collapsible] +==== +[source,console] +---- +NAME + astra config delete - Delete section in configuration + +SYNOPSIS + astra config delete [ {-cf | --config-file} ] + [ --no-color ] [ {-o | --output} ] + [ {-v | --verbose} ] [--] + +OPTIONS + -cf , --config-file + Configuration file (default = ~/.astrarc) + + --no-color + Remove all colors in output + + -o , --output + Output format, valid values are: human,json,csv + + -v, --verbose + Verbose mode with log in console + + -- + This option can be used to separate command-line options from the + list of arguments (useful when arguments might be mistaken for + command-line options) + + + Section in configuration file to as as default. +---- +==== + +.`config describe` options +[%collapsible] +==== +[source,console] +---- +NAME + astra config describe - Show details for a configuration. + +SYNOPSIS + astra config describe [ {-cf | --config-file} ] + [ {-k | --key} ] [ --no-color ] + [ {-o | --output} ] [ {-v | --verbose} ] [--] + + +OPTIONS + -cf , --config-file + Configuration file (default = ~/.astrarc) + + -k , --key + If provided return only value for a key. + + --no-color + Remove all colors in output + + -o , --output + Output format, valid values are: human,json,csv + + -v, --verbose + Verbose mode with log in console + + -- + This option can be used to separate command-line options from the + list of arguments (useful when arguments might be mistaken for + command-line options) + + + Section in configuration file to as as default. +---- +==== + +.`config get` options +[%collapsible] +==== +[source,console] +---- +NAME + astra config get - Show details for a configuration. + +SYNOPSIS + astra config get [ {-cf | --config-file} ] + [ {-k | --key} ] [ --no-color ] + [ {-o | --output} ] [ {-v | --verbose} ] [--] + + +OPTIONS + -cf , --config-file + Configuration file (default = ~/.astrarc) + + -k , --key + If provided return only value for a key. + + --no-color + Remove all colors in output + + -o , --output + Output format, valid values are: human,json,csv + + -v, --verbose + Verbose mode with log in console + + -- + This option can be used to separate command-line options from the + list of arguments (useful when arguments might be mistaken for + command-line options) + + + Section in configuration file to as as default. +---- +==== + +.`config list` options +[%collapsible] +==== +[source,console] +---- +NAME + astra config list - Show the list of available configurations. + +SYNOPSIS + astra config list [ {-cf | --config-file} ] + [ --no-color ] [ {-o | --output} ] + [ {-v | --verbose} ] + +OPTIONS + -cf , --config-file + Configuration file (default = ~/.astrarc) + + --no-color + Remove all colors in output + + -o , --output + Output format, valid values are: human,json,csv + + -v, --verbose + Verbose mode with log in console +---- +==== + +.`config use` options +[%collapsible] +==== +[source,console] +---- +NAME + astra config use - Make a section the one used by default + +SYNOPSIS + astra config use [ {-cf | --config-file} ] [ --no-color ] + [ {-o | --output} ] [ {-v | --verbose} ] [--] + + +OPTIONS + -cf , --config-file + Configuration file (default = ~/.astrarc) + + --no-color + Remove all colors in output + + -o , --output + Output format, valid values are: human,json,csv + + -v, --verbose + Verbose mode with log in console + + -- + This option can be used to separate command-line options from the + list of arguments (useful when arguments might be mistaken for + command-line options) + + + Section in configuration file to as as default. +---- +==== \ No newline at end of file diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc index 508b2a3..d76f14a 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc @@ -2701,359 +2701,7 @@ The directory must already exist before you run the command. If the directory doesn't exist, the {product} will report the following error: `INVALID_ARGUMENT: Destination folder has not been found`. ==== -== Manage the {product} configuration - -The {product} lets you manage multiple Astra organizations. -To facilitate this, the {product} lets you create multiple configurations within the `~/.astrarc` file. -Each configuration is associated with an application token, enabling you to manage multiple organizations, or manage one organization using multiple application tokens. - -Use `astra config list` to list all current configurations: - -[source,bash] ----- -astra config list ----- - -.Result -[%collapsible] -==== -[source,console] -+----------------------------+ -| configuration | -+----------------------------+ -| Organization 1 (in use) | -| Organization 2 | -+----------------------------+ -==== - -Use `astra config create` to create a new configuration: - -[source,bash,subs="+quotes"] ----- -astra config create "**CONFIG_NAME**" --token **APPLICATION_TOKEN** ----- - -.Result -[%collapsible] -==== -[source,console] ----- -[OK] Configuration has been saved. ----- -==== - -Use `astra config use` to change the default configuration that {product} uses when executing commands: - -[source,bash,subs="+quotes"] ----- -astra config use "**CONFIG_NAME**" ----- - -.Result -[%collapsible] -==== -[source,console,subs="+quotes"] ----- -[OK] Section '**CONFIG_NAME**' is set as default. ----- - -Use `astra config list` to confirm that the selected configuration is now the default. -==== - -[TIP] -==== -Every {product} command supports the `--config` option, which lets you specify a configuration to use for that command. -This lets you use different configurations for different commands without changing the default configuration. - -For example: - -[source,bash,subs="+quotes"] ----- -astra user list --config "**CONFIG_NAME**" ----- -==== - -Use `astra config delete` to delete a configuration: - -[source,bash,subs="+quotes"] ----- -astra config delete "**CONFIG_NAME**" ----- - -.Result -[%collapsible] -==== -[source,console,subs="+quotes"] ----- -[OK] Section '**CONFIG_NAME**' has been deleted. ----- - -Use `astra config list` to confirm that the selected configuration is now the default. -==== - -[NOTE] -==== -If you delete the default configuration, the {product} does _not_ automatically select a new default configuration. -Use the `astra config use` command to select a new default configuration. -==== - -=== `config` options - -[source,console] ----- -NAME - astra config - Manage configuration file - -SYNOPSIS - astra config { create | delete | describe | get | list* | use } [--] - [ {-cf | --config-file} ] [ --no-color ] - [ {-v | --verbose} ] [ {-o | --output} ] [cmd-options] - - - Where command-specific options [cmd-options] are: - create: [ {-e | --env} ] [ {-t | --token} ] - delete: - describe: [ {-k | --key} ] - get: [ {-k | --key} ] - list: - use: - - Where command-specific arguments are: - create: [ ] - delete: - describe: - get: - list: - use: - - Where * indicates the default command(s) - See 'astra help config ' for more information on a specific command. ----- - -.`config create` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config create - Create a new section in configuration - -SYNOPSIS - astra config create [ {-cf | --config-file} ] - [ {-e | --env} ] [ --no-color ] - [ {-o | --output} ] [ {-t | --token} ] - [ {-v | --verbose} ] [--] [ ] - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - -e , --env - Environment to use for this section. - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -t , --token - Key to use authenticate each call. - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -.`config delete` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config delete - Delete section in configuration - -SYNOPSIS - astra config delete [ {-cf | --config-file} ] - [ --no-color ] [ {-o | --output} ] - [ {-v | --verbose} ] [--] - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -.`config describe` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config describe - Show details for a configuration. - -SYNOPSIS - astra config describe [ {-cf | --config-file} ] - [ {-k | --key} ] [ --no-color ] - [ {-o | --output} ] [ {-v | --verbose} ] [--] - - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - -k , --key - If provided return only value for a key. - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -.`config get` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config get - Show details for a configuration. - -SYNOPSIS - astra config get [ {-cf | --config-file} ] - [ {-k | --key} ] [ --no-color ] - [ {-o | --output} ] [ {-v | --verbose} ] [--] - - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - -k , --key - If provided return only value for a key. - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -.`config list` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config list - Show the list of available configurations. - -SYNOPSIS - astra config list [ {-cf | --config-file} ] - [ --no-color ] [ {-o | --output} ] - [ {-v | --verbose} ] - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console ----- -==== - -.`config use` options -[%collapsible] -==== -[source,console] ----- -NAME - astra config use - Make a section the one used by default - -SYNOPSIS - astra config use [ {-cf | --config-file} ] [ --no-color ] - [ {-o | --output} ] [ {-v | --verbose} ] [--] - - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) - - --no-color - Remove all colors in output - - -o , --output - Output format, valid values are: human,json,csv - - -v, --verbose - Verbose mode with log in console - - -- - This option can be used to separate command-line options from the - list of arguments (useful when arguments might be mistaken for - command-line options) - - - Section in configuration file to as as default. ----- -==== - -== Manage users +== Manage organization users Use `astra user list` to list all users in your Astra organization: