From f13ca76168cd915c59ee167758c73f9d5a342460 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Thu, 25 Sep 2025 19:15:06 -0500 Subject: [PATCH 01/29] First batch changes --- antora.yml | 2 +- modules/ROOT/nav.adoc | 27 +- modules/ROOT/pages/administration.adoc | 3 +- modules/ROOT/pages/astra-streaming-cli.adoc | 3 +- modules/ROOT/pages/index.adoc | 4 +- .../pages/{installation.adoc => install.adoc} | 285 +++--------------- modules/ROOT/pages/managing.adoc | 3 +- modules/ROOT/pages/uninstall.adoc | 81 +++++ modules/ROOT/pages/upgrade.adoc | 113 +++++++ .../{getting-started.adoc => use-cli.adoc} | 2 +- modules/commands/pages/astra-config.adoc | 60 ++++ modules/commands/pages/astra-db.adoc | 103 +++++++ modules/commands/pages/astra-nuke.adoc | 1 + modules/commands/pages/astra-org.adoc | 1 + modules/commands/pages/astra-role.adoc | 1 + modules/commands/pages/astra-setup.adoc | 47 +++ modules/commands/pages/astra-streaming.adoc | 1 + modules/commands/pages/astra-token.adoc | 1 + modules/commands/pages/astra-upgrade.adoc | 1 + modules/commands/pages/astra-user.adoc | 1 + modules/commands/pages/astra.adoc | 67 ++++ 21 files changed, 545 insertions(+), 262 deletions(-) rename modules/ROOT/pages/{installation.adoc => install.adoc} (59%) create mode 100644 modules/ROOT/pages/uninstall.adoc create mode 100644 modules/ROOT/pages/upgrade.adoc rename modules/ROOT/pages/{getting-started.adoc => use-cli.adoc} (99%) create mode 100644 modules/commands/pages/astra-config.adoc create mode 100644 modules/commands/pages/astra-db.adoc create mode 100644 modules/commands/pages/astra-nuke.adoc create mode 100644 modules/commands/pages/astra-org.adoc create mode 100644 modules/commands/pages/astra-role.adoc create mode 100644 modules/commands/pages/astra-setup.adoc create mode 100644 modules/commands/pages/astra-streaming.adoc create mode 100644 modules/commands/pages/astra-token.adoc create mode 100644 modules/commands/pages/astra-upgrade.adoc create mode 100644 modules/commands/pages/astra-user.adoc create mode 100644 modules/commands/pages/astra.adoc diff --git a/antora.yml b/antora.yml index 19c1906..c23c056 100644 --- a/antora.yml +++ b/antora.yml @@ -19,7 +19,7 @@ asciidoc: astra-db: 'Astra DB' product: 'Astra CLI' product-short: 'Astra' - product-version: '0.6' + product-version: '1.0' db-serverless: 'Serverless (Non-Vector)' db-serverless-vector: 'Serverless (Vector)' db-classic: 'Classic' diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 6b64342..f597200 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,7 +1,22 @@ -* xref:installation.adoc[] -* xref:getting-started.adoc[] -* xref:managing.adoc[] -* xref:astra-streaming-cli.adoc[] -* xref:administration.adoc[] -* https://github.com/datastax/astra-cli[GitHub repo] +.Get started +* xref:install.adoc[] +* xref:use-cli.adoc[] +* xref:upgrade.adoc[] +* xref:uninstall.adoc[] + +.Commands +* xref:commands:astra.adoc[] +* xref:commands:astra-setup.adoc[] +* xref:commands:astra-config.adoc[] +* xref:commands:astra-db.adoc[] +* xref:commands:astra-org.adoc[] +* xref:commands:astra-role.adoc[] +* xref:commands:astra-streaming.adoc[] +* xref:commands:astra-token.adoc[] +* xref:commands:astra-user.adoc[] +* xref:commands:astra-upgrade.adoc[] +* xref:commands:astra-nuke.adoc[] + + +.Release notes * https://github.com/datastax/astra-cli/releases[Release notes] \ No newline at end of file diff --git a/modules/ROOT/pages/administration.adoc b/modules/ROOT/pages/administration.adoc index aba8197..19d9edd 100644 --- a/modules/ROOT/pages/administration.adoc +++ b/modules/ROOT/pages/administration.adoc @@ -1,5 +1,4 @@ -= Manage your {product-short} organization with the {product} -:navtitle: Manage {product-short} administration += {product-short} administration commands Use the {product} to manage your {product-short} organization. diff --git a/modules/ROOT/pages/astra-streaming-cli.adoc b/modules/ROOT/pages/astra-streaming-cli.adoc index 7a354be..a3e621c 100644 --- a/modules/ROOT/pages/astra-streaming-cli.adoc +++ b/modules/ROOT/pages/astra-streaming-cli.adoc @@ -1,5 +1,4 @@ -= Manage {astra_stream} with the {product} -:navtitle: Manage {astra_stream} += {astra_stream} commands Use the {product} to manage your {astra_stream} deployments. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 121220d..3aadb4e 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -26,11 +26,11 @@ To make it even easier to integrate {product-short} into your applications and w
- xref:installation.adoc[] + xref:install.adoc[]
- xref:getting-started.adoc[] + xref:use-cli.adoc[]
diff --git a/modules/ROOT/pages/installation.adoc b/modules/ROOT/pages/install.adoc similarity index 59% rename from modules/ROOT/pages/installation.adoc rename to modules/ROOT/pages/install.adoc index ee1fc4d..a115994 100644 --- a/modules/ROOT/pages/installation.adoc +++ b/modules/ROOT/pages/install.adoc @@ -1,4 +1,5 @@ -= Install or update the {product} += Install the {product} +:navtitle: Install the CLI :description: {product} makes it easier to integrate {product-short} into your applications and workflows by letting you perform common platform tasks for {astra_db} and {astra_stream} from the command line. Install the {product} to create and manage {astra_db} databases and {astra_stream} tenants from the command line. @@ -25,27 +26,14 @@ _Requires https://learn.microsoft.com/en-us/windows/wsl/install[Windows Subsyste == Install the {product} -Install the {product} using your preferred method: +Select one of the following installation methods and follow the steps to install the {product}. [tabs,id=install] ====== Homebrew:: + -- -You can use Homebrew to install the {product} on macOS and Linux: - -. On macOS, set your macOS app security settings to https://support.apple.com/en-us/102445#openanyway[Allow applications from App Store & Known Developers]. - -. Make sure https://brew.sh/[Homebrew] is installed. - -. Make sure Homebrew is up to date: -+ -[source,bash] ----- -brew update ----- - -. Install the {product}: +. Install the {product} using https://brew.sh/[Homebrew]: + [source,bash] ---- @@ -57,39 +45,7 @@ brew install datastax/astra-cli/astra-cli ==== [source,console,subs="+attributes"] ---- -==> Fetching datastax/astra-cli/astra-cli -==> Downloading https://github.com/datastax/astra-cli/releases/download/{product-version}/astra-cli-{product-version}.arm64_sonoma.bottle.tar.gz -Already downloaded: /Users/USERNAME/Library/Caches/Homebrew/downloads/ca763b5f440dad257d707b2e705e98bd5a66912662fa95ae5ef417e749a2b08a--astra-cli-{product-version}.arm64_sonoma.bottle.tar.gz -==> Installing astra-cli from datastax/astra-cli -==> Pouring astra-cli-{product-version}.arm64_sonoma.bottle.tar.gz -==> Caveats ------------------------- - ENABLE AUTOCOMPLETION -------------------------- -To enable Bash completion for Astra CLI (and other brew formulae when enabled), add the following to your shell configuration file (e.g. ~/.zshrc): - -if [ -f /opt/homebrew/etc/bash_completion.d ]; then - . /opt/homebrew/etc/bash_completion.d -fi - -Once added, reload your shell or run: - -source /opt/homebrew/etc/bash_completion.d - -This will ensure the Bash completion script for Astra CLI is loaded. - -------------------- - SPECIAL COMMANDS -------------------- - -- CQLSH: You must have python 3.7+ but less than 3.12, cqlsh is still not compatible with 3.12, downgrade if needed -- DSBULK: You must have java11+ installm the cli is pulling regular dsbulk - -==> Summary -🍺 /opt/homebrew/Cellar/astra-cli/{product-version}: 4 files, 44.4MB -==> Running `brew cleanup astra-cli`... -Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP. -Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`). +TBD ---- ==== @@ -110,13 +66,40 @@ The command returns the {product} version that is installed: {product-version} ---- ==== +-- + +macOS:: + -include::ROOT:partial$macos-security-notice.adoc[] +-- +Select one of the following installation methods to install the {product} on macOS without using Homebrew: + +[tabs] +===== +Scripted install (recommended):: ++ +. Run the following shell script to install the {product}: ++ +[source,bash] +---- +sh -c "$(curl -fsSL https://raw.githubusercontent.com/toptobes/astra-cli-pico/master/scripts/install.sh)" +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +TBD +---- + +. When prompted about where to install the {product}, press kbd:[Return] to accept the default location (`~/.astra/cli/`). ++ +To install +==== -. Optional: If you haven't done so already, enable https://docs.brew.sh/Shell-Completion[`brew` shell completion]. +Manual install:: + -The {product} Homebrew formula installs a completion file named `astra` in the Homebrew-managed completions directory. -If you have shell completion enabled in Homebrew, your terminal will automatically suggest and complete {product} commands and options as you type them. +===== -- curl:: @@ -371,7 +354,7 @@ astra --version -- ====== -To set up a new configuration and run your first commands, see xref:getting-started.adoc[]. +To set up a new configuration and run your first commands, see xref:use-cli.adoc[]. [#file-locations] === Installation file locations @@ -400,196 +383,6 @@ For <>, the `astra` executable an _This file is *not* deleted when you update or re-install the {product}._ |=== -== Update the {product} - -To update the {product}, follow the procedure for the method you used to originally install the {product}: - -[tabs] -====== -Homebrew:: -+ --- -. Make sure Homebrew is up to date: -+ -[source,bash] ----- -brew update ----- - -. Update the {product}: -+ -[source,bash] ----- -brew upgrade datastax/astra-cli/astra-cli ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -==> Upgrading datastax/astra-cli/astra-cli - 0.5 -> 0.6 -==> Pouring astra-cli-0.6.arm64_sonoma.bottle.tar.gz -==> Caveats ------------------------- - ENABLE AUTOCOMPLETION -------------------------- -To enable Bash completion for Astra CLI (and other brew formulae when enabled), add the following to your shell configuration file (e.g. ~/.zshrc): - -if [ -f /opt/homebrew/etc/bash_completion.d ]; then - . /opt/homebrew/etc/bash_completion.d -fi - -Once added, reload your shell or run: - -source /opt/homebrew/etc/bash_completion.d - -This will ensure the Bash completion script for Astra CLI is loaded. - -------------------- - SPECIAL COMMANDS -------------------- - -- CQLSH: You must have python 3.7+ but less than 3.12, cqlsh is still not compatible with 3.12, downgrade if needed -- DSBULK: You must have java11+ installm the cli is pulling regular dsbulk - -==> Summary -🍺 /opt/homebrew/Cellar/astra-cli/0.6: 4 files, 44.4MB -==> Running `brew cleanup astra-cli`... -Removing: /opt/homebrew/Cellar/astra-cli/0.5... (4 files, 61.7MB) -Removing: /Users/USERNAME/Library/Caches/Homebrew/astra-cli--0.5.arm64_sonoma.bottle.tar.gz... (24.4MB) ----- -==== - -. Confirm that the latest version of the {product} is installed: -+ -[source,bash] ----- -astra --version ----- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== -+ -include::ROOT:partial$macos-security-notice.adoc[] --- - -curl:: -+ --- -. Update the {product}: -+ -[source,bash] ----- -curl -Ls "https://dtsx.io/get-astra-cli" | bash ----- - -. Confirm that the latest version of the {product} is installed: -+ -[source,bash] ----- -astra --version ----- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== --- -====== - -== Uninstall the {product} - -To uninstall the {product}, follow the procedure for the method you used to originally install the {product}: +[#install-custom-location] +== Install the {product} to a custom location -[tabs] -====== -Homebrew:: -+ --- -. Uninstall the {product}: -+ -[source,bash] ----- -brew uninstall datastax/astra-cli/astra-cli ----- -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- -Uninstalling /opt/homebrew/Cellar/astra-cli/{product-version}... (4 files, 61.7MB) ----- -==== - -. Delete the {product} and its associated installation files: -+ -[source,bash] ----- -rm -R ~/.astra ----- - -. Optional: Delete the {product} configuration file: -+ -[source,bash] ----- -rm ~/.astrarc ----- --- - -curl:: -+ --- -. Delete the {product} and its associated installation files: -+ -[source,bash] ----- -rm -R ~/.astra ----- - -. Optional: Delete the {product} configuration file: -+ -[source,bash] ----- -rm ~/.astrarc ----- - -. Optional: Remove the {product} from your shell configuration file, such as `.zshrc` or `.bashrc`: - -.. Open your shell configuration file in a text editor. -For example: -+ -[source,bash] ----- -nano ~/.zshrc ----- - -.. Remove any lines that reference the {product}. -For example: -+ -[source,bash] ----- -#THIS MUST BE AT THE END OF THE FILE FOR ASTRA_CLI TO WORK!!! -export ASTRADIR="/Users/USERNAME/.astra/cli" -[[ -s "/Users/USERNAME/.astra/cli/astra-init.sh" ]] && source "/Users/USERNAME/.astra/cli/astra-init.sh" ----- - -.. Save and close the file. --- -====== \ No newline at end of file diff --git a/modules/ROOT/pages/managing.adoc b/modules/ROOT/pages/managing.adoc index 47ec724..90fac8c 100644 --- a/modules/ROOT/pages/managing.adoc +++ b/modules/ROOT/pages/managing.adoc @@ -1,5 +1,4 @@ -= Manage {astra_db} with the {product} -:navtitle: Manage {astra_db} += {astra_db} commands :embedding-provider-name: NVIDIA :embedding-provider-name-api: nvidia :embedding-provider-model-name-api: NV-Embed-QA diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc new file mode 100644 index 0000000..0c3571b --- /dev/null +++ b/modules/ROOT/pages/uninstall.adoc @@ -0,0 +1,81 @@ += Uninstall the {product} +:navtitle: Uninstall the CLI + +To uninstall the {product}, follow the procedure for the method you used to originally install the {product}: + +[tabs] +====== +Homebrew:: ++ +-- +. Uninstall the {product}: ++ +[source,bash] +---- +brew uninstall datastax/astra-cli/astra-cli +---- ++ +.Result +[%collapsible] +==== +[source,console,subs="+attributes"] +---- +Uninstalling /opt/homebrew/Cellar/astra-cli/{product-version}... (4 files, 61.7MB) +---- +==== + +. Delete the {product} and its associated installation files: ++ +[source,bash] +---- +rm -R ~/.astra +---- + +. Optional: Delete the {product} configuration file: ++ +[source,bash] +---- +rm ~/.astrarc +---- +-- + +curl:: ++ +-- +. Delete the {product} and its associated installation files: ++ +[source,bash] +---- +rm -R ~/.astra +---- + +. Optional: Delete the {product} configuration file: ++ +[source,bash] +---- +rm ~/.astrarc +---- + +. Optional: Remove the {product} from your shell configuration file, such as `.zshrc` or `.bashrc`: + +.. Open your shell configuration file in a text editor. +For example: ++ +[source,bash] +---- +nano ~/.zshrc +---- + +.. Remove any lines that reference the {product}. +For example: ++ +[source,bash] +---- +#THIS MUST BE AT THE END OF THE FILE FOR ASTRA_CLI TO WORK!!! +export ASTRADIR="/Users/USERNAME/.astra/cli" +[[ -s "/Users/USERNAME/.astra/cli/astra-init.sh" ]] && source "/Users/USERNAME/.astra/cli/astra-init.sh" +---- + +.. Save and close the file. +-- +====== \ No newline at end of file diff --git a/modules/ROOT/pages/upgrade.adoc b/modules/ROOT/pages/upgrade.adoc new file mode 100644 index 0000000..1faba6f --- /dev/null +++ b/modules/ROOT/pages/upgrade.adoc @@ -0,0 +1,113 @@ += Upgrade the {product} +:navtitle: Upgrade the CLI + +To update the {product}, follow the procedure for the method you used to originally install the {product}: + +[tabs] +====== +Homebrew:: ++ +-- +. Make sure Homebrew is up to date: ++ +[source,bash] +---- +brew update +---- + +. Update the {product}: ++ +[source,bash] +---- +brew upgrade datastax/astra-cli/astra-cli +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +==> Upgrading datastax/astra-cli/astra-cli + 0.5 -> 0.6 +==> Pouring astra-cli-0.6.arm64_sonoma.bottle.tar.gz +==> Caveats +------------------------ + ENABLE AUTOCOMPLETION +------------------------- +To enable Bash completion for Astra CLI (and other brew formulae when enabled), add the following to your shell configuration file (e.g. ~/.zshrc): + +if [ -f /opt/homebrew/etc/bash_completion.d ]; then + . /opt/homebrew/etc/bash_completion.d +fi + +Once added, reload your shell or run: + +source /opt/homebrew/etc/bash_completion.d + +This will ensure the Bash completion script for Astra CLI is loaded. + +------------------- + SPECIAL COMMANDS +------------------- + +- CQLSH: You must have python 3.7+ but less than 3.12, cqlsh is still not compatible with 3.12, downgrade if needed +- DSBULK: You must have java11+ installm the cli is pulling regular dsbulk + +==> Summary +🍺 /opt/homebrew/Cellar/astra-cli/0.6: 4 files, 44.4MB +==> Running `brew cleanup astra-cli`... +Removing: /opt/homebrew/Cellar/astra-cli/0.5... (4 files, 61.7MB) +Removing: /Users/USERNAME/Library/Caches/Homebrew/astra-cli--0.5.arm64_sonoma.bottle.tar.gz... (24.4MB) +---- +==== + +. Confirm that the latest version of the {product} is installed: ++ +[source,bash] +---- +astra --version +---- ++ +.Result +[%collapsible] +==== +The command returns the {product} version that is installed: + +[source,console,subs="+attributes"] +---- +{product-version} +---- +==== ++ +include::ROOT:partial$macos-security-notice.adoc[] +-- + +curl:: ++ +-- +. Update the {product}: ++ +[source,bash] +---- +curl -Ls "https://dtsx.io/get-astra-cli" | bash +---- + +. Confirm that the latest version of the {product} is installed: ++ +[source,bash] +---- +astra --version +---- ++ +.Result +[%collapsible] +==== +The command returns the {product} version that is installed: + +[source,console,subs="+attributes"] +---- +{product-version} +---- +==== +-- +====== diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/use-cli.adoc similarity index 99% rename from modules/ROOT/pages/getting-started.adoc rename to modules/ROOT/pages/use-cli.adoc index ffb35c7..d8c6f9e 100644 --- a/modules/ROOT/pages/getting-started.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -7,7 +7,7 @@ Initialize the {product} and run your first commands. To configure the {product}: -* xref:ROOT:installation.adoc[Install the {product}]. +* xref:ROOT:install.adoc[Install the {product}]. * You must have an active {astra-url}[{product-short} account^]. diff --git a/modules/commands/pages/astra-config.adoc b/modules/commands/pages/astra-config.adoc new file mode 100644 index 0000000..36cc4e6 --- /dev/null +++ b/modules/commands/pages/astra-config.adoc @@ -0,0 +1,60 @@ += astra config + +Manage your Astra CLI configuration profiles. + +== Usage + +[source,console] +---- +astra config [-hqv] [--[no-]color] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [-cf=PATH] [-o=FORMAT] [COMMAND] +---- + +== Options + +`-cf`, `--config-file=PATH`:: +The astrarc file to use + +`--[no-]color`:: +Force colored output + +`--dump-logs[=FILE]`:: +Write all logs to an optionally specified file (default: ~/.astra/logs/.log) + +`-h`, `--help`:: +Show this help message and exit. + +`--no-input`:: +Never ask for user input (e.g. confirmation prompts) + +`-o`, `--output=FORMAT`:: +One of: human, json, csv + +`-q`, `--quiet`:: +Suppress informational output + +`--[no-]spinner`:: +Enable/disable the loading spinner + +`-v`, `--verbose`:: +Enable verbose logging output + +== Commands + +* list +* create +* get, describe +* use +* path +* home + +== Examples + +[source,console] +---- +# List your Astra CLI profiles. +$ astra config + +# Create a new Astra CLI profile. +$ astra config create --token @token.txt --name prod +---- \ No newline at end of file diff --git a/modules/commands/pages/astra-db.adoc b/modules/commands/pages/astra-db.adoc new file mode 100644 index 0000000..1d5d4ad --- /dev/null +++ b/modules/commands/pages/astra-db.adoc @@ -0,0 +1,103 @@ += astra db + +Manage your Astra databases. + +== Usage + +[source,console] +---- +astra db [-hqv] [--[no-]color] [--no-input] [--[no-]spinner] [--vector] + [--dump-logs[=FILE]] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [COMMAND] +---- + +== Options + +`-cf`, `--config-file=PATH`:: +The astrarc file to use (default: ~/.astrarc) + +`--[no-]color`:: +Force colored output + +`--dump-logs[=FILE]`:: +Write all logs to an optionally specified file (default: ~/.astra/logs/.log) + +`--env=ENV`:: +Override the target astra environment + +`-h`, `--help`:: +Show this help message and exit. + +`--no-input`:: +Never ask for user input (e.g. confirmation prompts) + +`-o`, `--output=FORMAT`:: +One of: human, json, csv + +`-p`, `--profile=NAME`:: +The astrarc profile to use + +`-q`, `--quiet`:: +Suppress informational output + +`--[no-]spinner`:: +Enable/disable the loading spinner + +`--token=TOKEN`:: +Override the default astra token + +`-v`, `--verbose`:: +Enable verbose logging output + +`--vector`:: +Only show vector-enabled databases + +== Commands + +* list +* get, describe +* create +* delete +* status +* cqlsh +* dsbulk +* create-dotenv +* download-scb +* resume +* list-keyspaces +* create-keyspace +* delete-keyspace +* list-collections +* create-collection +* describe-collection +* delete-collection +* truncate-collection +* list-tables +* describe-table +* delete-table +* truncate-table +* list-embedding-providers +* list-cdcs +* create-cdc +* delete-cdc +* create-region +* delete-region +* list-regions +* list-regions-classic +* list-regions-serverless +* list-regions-vector +* list-clouds +* get-endpoint-swagger +* get-endpoint-api +* get-endpoint-playground + +== Examples + +[source,console] +---- +# List all your Astra databases +$ astra db + +# List only vector-enabled Astra databases +$ astra db --vector +---- diff --git a/modules/commands/pages/astra-nuke.adoc b/modules/commands/pages/astra-nuke.adoc new file mode 100644 index 0000000..01a94ad --- /dev/null +++ b/modules/commands/pages/astra-nuke.adoc @@ -0,0 +1 @@ += astra nuke \ No newline at end of file diff --git a/modules/commands/pages/astra-org.adoc b/modules/commands/pages/astra-org.adoc new file mode 100644 index 0000000..db897a7 --- /dev/null +++ b/modules/commands/pages/astra-org.adoc @@ -0,0 +1 @@ += astra org \ No newline at end of file diff --git a/modules/commands/pages/astra-role.adoc b/modules/commands/pages/astra-role.adoc new file mode 100644 index 0000000..9343deb --- /dev/null +++ b/modules/commands/pages/astra-role.adoc @@ -0,0 +1 @@ += astra role \ No newline at end of file diff --git a/modules/commands/pages/astra-setup.adoc b/modules/commands/pages/astra-setup.adoc new file mode 100644 index 0000000..68996ed --- /dev/null +++ b/modules/commands/pages/astra-setup.adoc @@ -0,0 +1,47 @@ += astra setup + +Interactively set up the Astra CLI and create profiles + +== Usage + +[source,console] +---- +astra setup [-hqv] [--[no-]color] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [-e=ENV] [--name=NAME] [-o=FORMAT] + [-t=TOKEN] +---- + +== Options + +`--[no-]color`:: +Force colored output + +`--dump-logs[=FILE]`:: +Write all logs to an optionally specified file (default: ~/.astra/logs/.log) + +`-e`, `--env=ENV`:: +Astra environment for the token to target. If not provided, you will be prompted for it + +`-h`, `--help`:: +Show this help message and exit. + +`--name=NAME`:: +Optional name for the profile. If not provided, you will be prompted for it + +`--no-input`:: +Never ask for user input (e.g. confirmation prompts) + +`-o`, `--output=FORMAT`:: +One of: human, json, csv + +`-q`, `--quiet`:: +Suppress informational output + +`--[no-]spinner`:: +Enable/disable the loading spinner + +`-t`, `--token=TOKEN`:: +Token to use authenticate each call. If not provided, you will be prompted for it + +`-v`, `--verbose`:: +Enable verbose logging output diff --git a/modules/commands/pages/astra-streaming.adoc b/modules/commands/pages/astra-streaming.adoc new file mode 100644 index 0000000..b7ac7dc --- /dev/null +++ b/modules/commands/pages/astra-streaming.adoc @@ -0,0 +1 @@ += astra streaming \ No newline at end of file diff --git a/modules/commands/pages/astra-token.adoc b/modules/commands/pages/astra-token.adoc new file mode 100644 index 0000000..50296c2 --- /dev/null +++ b/modules/commands/pages/astra-token.adoc @@ -0,0 +1 @@ += astra token \ No newline at end of file diff --git a/modules/commands/pages/astra-upgrade.adoc b/modules/commands/pages/astra-upgrade.adoc new file mode 100644 index 0000000..8608b79 --- /dev/null +++ b/modules/commands/pages/astra-upgrade.adoc @@ -0,0 +1 @@ += astra upgrade \ No newline at end of file diff --git a/modules/commands/pages/astra-user.adoc b/modules/commands/pages/astra-user.adoc new file mode 100644 index 0000000..387101d --- /dev/null +++ b/modules/commands/pages/astra-user.adoc @@ -0,0 +1 @@ += astra user \ No newline at end of file diff --git a/modules/commands/pages/astra.adoc b/modules/commands/pages/astra.adoc new file mode 100644 index 0000000..66f1184 --- /dev/null +++ b/modules/commands/pages/astra.adoc @@ -0,0 +1,67 @@ += astra + +Manage Astra from the command line. + +== Usage + +[source,console] +---- +astra [-hqvV] [--[no-]color] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [-o=FORMAT] [COMMAND] +---- + +== Options + +`--[no-]color`:: +Force colored output + +`--dump-logs[=FILE]`:: +Write all logs to an optionally specified file (default: ~/.astra/logs/.log) + +`-h`, `--help`:: +Show this help message and exit. + +`--no-input`:: +Never ask for user input (e.g. confirmation prompts) + +`-o`, `--output=FORMAT`:: +One of: human, json, csv + +`-q`, `--quiet`:: +Suppress informational output + +`--[no-]spinner`:: +Enable/disable the loading spinner + +`-v`, `--verbose`:: +Enable verbose logging output + +`-V`, `--version`:: +Print version information and exit. + +== Commands + +* xref:commands:astra-setup.adoc[] +* xref:commands:astra-config.adoc[] +* xref:commands:astra-db.adoc[] +* xref:commands:astra-org.adoc[] +* xref:commands:astra-role.adoc[] +* xref:commands:astra-streaming.adoc[] +* xref:commands:astra-token.adoc[] +* xref:commands:astra-user.adoc[] +* xref:commands:astra-upgrade.adoc[] +* xref:commands:astra-nuke.adoc[] + +== Examples + +[source,console] +---- +# Setup the Astra CLI +$ astra setup + +# List databases +$ astra db list + +# Create a vector database +$ astra db create demo -r us-east1 +---- \ No newline at end of file From ef8d8434e79984552c268e92d4ed5e1278111ac6 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Fri, 26 Sep 2025 17:10:13 -0500 Subject: [PATCH 02/29] More install updates --- modules/ROOT/pages/install.adoc | 309 ++++++++++++-------------------- 1 file changed, 118 insertions(+), 191 deletions(-) diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index a115994..839e4d3 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -20,8 +20,6 @@ The {product} supports the following operating systems: |Microsoft Windows |x86_64 - -_Requires https://learn.microsoft.com/en-us/windows/wsl/install[Windows Subsystem for Linux (WSL)]_ |=== == Install the {product} @@ -49,35 +47,26 @@ TBD ---- ==== -. Confirm that the {product} is installed: +. Run the `astra` command from any directory to verify successful installation: + [source,bash] ---- -astra --version +astra ---- + -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== +The response includes available commands and options for the {product}. -- macOS:: + --- Select one of the following installation methods to install the {product} on macOS without using Homebrew: - ++ [tabs] ===== -Scripted install (recommended):: +Scripted installation (recommended):: + -. Run the following shell script to install the {product}: +-- +. Run the following Bash script to install the {product}: + [source,bash] ---- @@ -87,270 +76,211 @@ sh -c "$(curl -fsSL https://raw.githubusercontent.com/toptobes/astra-cli-pico/ma .Result [%collapsible] ==== -[source,console] ----- -TBD +[source,console,subs="+attributes"] ---- + _____ __ + / _ \ _______/ |_____________ + / /_\ \ / ___/\ __\_ __ \__ \ + / | \___ \ | | | | \// __ \_ + \____|__ /____ > |__| |__| (____ / + \/ \/ \/ -. When prompted about where to install the {product}, press kbd:[Return] to accept the default location (`~/.astra/cli/`). -+ -To install -==== + Installer: {product-version} -Manual install:: -+ -===== --- +→ Required tools are available. +→ No existing installation found. -curl:: -+ --- -You can use `curl` to install the {product} on Linux, macOS, and Windows Subsystem for Linux (WSL): +Ready to install Astra CLI ✅ -. Install the {product}: -+ -[source,bash] ----- -curl -Ls "https://dtsx.io/get-astra-cli" | bash +Do you want to install Astra CLI to ~/.astra/cli/? [Y]es/[d]ifferent path/[c]ancel +> ---- +==== + +. When prompted to specify the installation location, press kbd:[Return] to accept the default (`~/.astra/cli/`). + .Result [%collapsible] ==== [source,console,subs="+attributes"] ---- +→ Using installation dir ~/.astra/cli/. +→ Archive downloaded. +→ Archive verified and extracted. - _____ __ - / _ \ _______/ |_____________ - / /_\ \ / ___/\ __\_ __ \__ \ - / | \___ \ | | | | \// __ \_ - \____|__ /____ > |__| |__| (____ / - \/ \/ \/ - -Installing Astra Cli {product-version} please wait... - -Checking prerequisites: -[OK] - Ready to install. -[OK] - unzip command is available -[OK] - curl command is available +Astra CLI installed successfully! 🎉 -Preparing directories: -[OK] - Created /home/USERNAME/.astra/tmp -[OK] - Created /home/USERNAME/.astra/cli -[OK] - Created /home/USERNAME/.astra/scb +Next steps: -Downloading archive: -######################################################################## 100.0% -[OK] - File downloaded -[OK] - Integrity of the archive checked +# Append the following to your shell profile (e.g. ~/.bashrc, ~/.zshrc, etc.) +$ eval "$(~/.astra/cli/astra shellenv)" -Extracting and installation: -[OK] - Extraction is successful -[OK] - File moved to /home/USERNAME/.astra/cli -[OK] - Installation cleaned up -[OK] - astra added to /home/USERNAME/.bashrc -[OK] - astra added to /home/USERNAME/.zshrc -[OK] - Installation Successful - -Open A NEW TERMINAL and run: astra setup - -You can close this window. +# Run the following to get started! +$ astra setup ---- ==== + -The `~/.astra/cli` folder is added to the `PATH` environment variable. -See <> for more information. - -. Open a new terminal or restart your existing terminal. +To install the {product} to a different location, use the binary installation method. -. Confirm that the {product} is installed: +. Add the following lines to your shell profile (for example, `~/.zshrc` or `~/.bashrc`) to make the `astra` command executable from any directory: + [source,bash] ---- -astra --version +# Astra CLI shell configuration +eval "$(~/.astra/cli/astra shellenv)" ---- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: -[source,console,subs="+attributes"] +. Reload your shell profile or open a new terminal window. + +. Run the `astra` command from any directory to verify successful installation: ++ +[source,bash] ---- -{product-version} +astra ---- -==== + -include::ROOT:partial$macos-security-notice.adoc[] +The response includes available commands and options for the {product}. -- -JVM:: +Binary installation:: + -- -The {product} is available as a packaged Java application that you can use on any machine running a JVM. - -To run the {product} in a JVM, you must have Java 17+ installed. -You can install Java by downloading and installing the latest https://www.oracle.com/java/technologies/downloads/[Oracle JDK] +. Download the latest `macos` archive file for your CPU architecture from https://github.com/toptobes/astra-cli-pico/releases[GitHub]. -. Verify that Java is version 17 or higher: +. Extract the archive into the directory where you want to install the {product}: + -[source,bash] +[source,bash,subs="+quotes"] ---- -java --version +sudo tar -xzvf astra-macos-**ARCHITECTURE**.tar.gz -C **INSTALLATION_DIRECTORY** ---- -. Download the latest release of https://github.com/datastax/astra-cli/releases[astra-cli] image:https://img.shields.io/github/v/release/datastax/astra-cli?label=latest&color=green[alt="Latest astra-cli release on GitHub",link="https://github.com/datastax/astra-cli/releases"]: +. Add the following lines to your shell profile (for example, `~/.zshrc` or `~/.bashrc`) to make the `astra` command executable from any directory: + -[source,bash,subs="+attributes"] +[source,bash,subs="+quotes"] ---- -curl -L -o astra-cli-{product-version}.zip https://github.com/datastax/astra-cli/releases/download/{product-version}/astra-cli-{product-version}.zip +# Astra CLI shell configuration +eval "$(**PATH_TO_EXEC** shellenv)" ---- - -. Unzip the archive: + -[source,bash,subs="+attributes"] ----- -unzip astra-cli-{product-version}.zip -d ./astra-cli-{product-version} && cd astra-cli-{product-version} ----- +Replace `**PATH_TO_EXEC**` with the full path to the `astra` executable in the installation directory. -. Confirm that you can successfully run the {product}: +. Reload your shell profile or open a new terminal window. + +. Run the following command to de-quarantine the binary: + [source,bash] ---- -java -jar astra-cli.jar --version +xattr -d com.apple.quarantine $(which astra) ---- + -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== - -You can use all options and suffixes on commands when running the JAR file. -For example: +For more information +. Run the `astra` command from any directory to verify successful installation: ++ [source,bash] ---- -java -jar ./astra-cli.jar db list --token AstraCS:FZm... +astra ---- ++ +The response includes available commands and options for the {product}. -- +===== -Docker:: +Windows:: ++ +Select one of the following installation methods to install the {product} on Windows: ++ +[tabs] +===== +Scripted installation (recommended):: + -- -The {product} is available as an https://hub.docker.com/r/datastax/astra-cli[official Docker image] that you can run in a container. - -To install the {product} using Docker, you must have https://docs.docker.com/engine/install/[Docker engine] or https://www.docker.com/products/docker-desktop[Docker desktop] installed. - -. Confirm that Docker is installed and running: +. Run the following PowerShell script to install the {product}: + -[source,bash] +[source,powershell] ---- -docker --version +powershell -c "irm https://raw.githubusercontent.com/toptobes/astra-cli-pico/master/scripts/install.ps1 | iex" ---- + .Result [%collapsible] ==== -The command returns the Docker version that is installed: - -[source,console] +[source,console,subs="+attributes"] ---- -Docker version 27.1.1, build 6312585 +TBD ---- ==== -. Pull the latest {product} Docker image (`datastax/astra-cli:latest`): -+ -[source,bash,subs="+attributes"] ----- -docker pull datastax/astra-cli ----- -+ -[TIP] -==== -To pull a specific version of the Docker image, run `docker pull datastax/astra-cli:**TAG**`, replacing `**TAG**` with the version tag of the Docker image you want to pull. -==== +. When prompted to specify the installation location, press kbd:[Return] to accept the default (`~\AppData\Local\.astra\cli`). + .Result [%collapsible] ==== -[source,console] +[source,console,subs="+attributes"] ---- -Using default tag: latest -latest: Pulling from datastax/astra-cli -7890eb226106: Pull complete -f4455e290156: Pull complete -e6c3f5cd9c43: Pull complete -322cfd5270ff: Pull complete -Digest: sha256:8dcba8115cbae7bcabfc579341611f30860239ee5edbca3938edea4542ca06fb -Status: Downloaded newer image for datastax/astra-cli:latest -docker.io/datastax/astra-cli:latest - -What's next: - View a summary of image vulnerabilities and recommendations → docker scout quickview datastax/astra-cli +TBD ---- ==== ++ +To install the {product} to a different location, use the binary installation method. -. Confirm that you can successfully run the {product} in a Docker container: +. Add the following lines to your PowerShell profile to make the `astra` command executable from any directory: + -[source,bash] +[source,powershell] ---- -docker run -rm datastax/astra-cli --version +TBD ---- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== +. Reload your shell profile or open a new command prompt. -. Optional: Run the {product} with a configuration file: +. Run the `astra` command from any directory to verify successful installation: + -[source,bash,subs="+quotes"] +[source,bash] ---- -docker run -rm -v **CONFIG_FILE**:/work/.astrarc datastax/astra-cli --version +astra ---- + -Replace `**CONFIG_FILE**`with the path to your {product} configuration file. -For example: +The response includes available commands and options for the {product}. +-- + +Binary installation:: + -[source,bash] +-- +. Download the latest `windows` zip file from https://github.com/toptobes/astra-cli-pico/releases[GitHub]. + +. Extract the zip file into the directory where you want to install the {product}: ++ +[source,powershell,subs="+quotes"] ---- -docker run -rm -v ~/.astrarc:/work/.astrarc datastax/astra-cli --version +powershell -Command "Expand-Archive -Path astra-windows-x86_64.zip -DestinationPath **INSTALLATION_DIRECTORY** -Force" ---- -+ -This command mounts the `~/.astrarc` file from your local machine to the `/work/.astrarc` file in the Docker container. -This lets you use your local configuration file when running the {product} in a Docker container. -. Optional: Create a shell alias for running the {product} in a Docker container. -+ -You can create a shell alias to eliminate the need to include the `docker run` command whenever you want to run the {product} in a Docker container. -For example, the following command creates an alias named `astra`: +. Add the path to the unzipped `astra.exe` file to your `PATH` environment variable. +To learn how to update environment variables, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. + +. Reload your shell profile or open a new terminal window. + +. Run the `astra` command from any directory to verify successful installation: + [source,bash] ---- -alias astra='docker run -rm -v ~/.astrarc:/work/.astrarc datastax/astra-cli' +astra ---- + -You can run this command in your terminal to create a temporary alias for the current session, or you can add it to your shell configuration file so that the alias is available in every new terminal session. +The response includes available commands and options for the {product}. +-- +===== + +Linux:: + -After you add the alias, you can use it to run {product} commands in a Docker container using the same syntax as the `astra` binary: +-- +TBD +-- + +Docker:: + -[source,bash] ----- -astra --version ----- +-- +TBD -- ====== @@ -383,6 +313,3 @@ For <>, the `astra` executable an _This file is *not* deleted when you update or re-install the {product}._ |=== -[#install-custom-location] -== Install the {product} to a custom location - From 53d76258e75467ea16e2ae0e67ee60dc063aacdf Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Fri, 26 Sep 2025 17:30:59 -0500 Subject: [PATCH 03/29] Add upgrade steps --- modules/ROOT/nav.adoc | 1 - modules/ROOT/pages/uninstall.adoc | 2 +- modules/ROOT/pages/upgrade.adoc | 110 ++++++++++++------------------ 3 files changed, 44 insertions(+), 69 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index f597200..57af553 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -17,6 +17,5 @@ * xref:commands:astra-upgrade.adoc[] * xref:commands:astra-nuke.adoc[] - .Release notes * https://github.com/datastax/astra-cli/releases[Release notes] \ No newline at end of file diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index 0c3571b..c70d828 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -1,7 +1,7 @@ = Uninstall the {product} :navtitle: Uninstall the CLI -To uninstall the {product}, follow the procedure for the method you used to originally install the {product}: +Follow the instructions for your original installation method to uninstall the {product}. [tabs] ====== diff --git a/modules/ROOT/pages/upgrade.adoc b/modules/ROOT/pages/upgrade.adoc index 1faba6f..faf6bbe 100644 --- a/modules/ROOT/pages/upgrade.adoc +++ b/modules/ROOT/pages/upgrade.adoc @@ -1,113 +1,89 @@ = Upgrade the {product} :navtitle: Upgrade the CLI -To update the {product}, follow the procedure for the method you used to originally install the {product}: +Keep the {product} up to date to access new features, improvements, and security updates. +Follow the instructions for your original installation method to upgrade the CLI. [tabs] ====== Homebrew:: + -- -. Make sure Homebrew is up to date: +. Run the following command to upgrade to the latest version of the {product}: + [source,bash] ---- -brew update +brew upgrade datastax/astra-cli/astra-cli ---- -. Update the {product}: +. Optional: Upgrade to a specific version of the {product}: + -[source,bash] +[source,bash,subs="+quotes"] ---- -brew upgrade datastax/astra-cli/astra-cli +brew install datastax/astra-cli/astra-cli@**VERSION** ---- + -.Result -[%collapsible] -==== -[source,console] ----- -==> Upgrading datastax/astra-cli/astra-cli - 0.5 -> 0.6 -==> Pouring astra-cli-0.6.arm64_sonoma.bottle.tar.gz -==> Caveats ------------------------- - ENABLE AUTOCOMPLETION -------------------------- -To enable Bash completion for Astra CLI (and other brew formulae when enabled), add the following to your shell configuration file (e.g. ~/.zshrc): - -if [ -f /opt/homebrew/etc/bash_completion.d ]; then - . /opt/homebrew/etc/bash_completion.d -fi - -Once added, reload your shell or run: - -source /opt/homebrew/etc/bash_completion.d - -This will ensure the Bash completion script for Astra CLI is loaded. - -------------------- - SPECIAL COMMANDS -------------------- +You can also use this command to downgrade to a previous version. -- CQLSH: You must have python 3.7+ but less than 3.12, cqlsh is still not compatible with 3.12, downgrade if needed -- DSBULK: You must have java11+ installm the cli is pulling regular dsbulk - -==> Summary -🍺 /opt/homebrew/Cellar/astra-cli/0.6: 4 files, 44.4MB -==> Running `brew cleanup astra-cli`... -Removing: /opt/homebrew/Cellar/astra-cli/0.5... (4 files, 61.7MB) -Removing: /Users/USERNAME/Library/Caches/Homebrew/astra-cli--0.5.arm64_sonoma.bottle.tar.gz... (24.4MB) ----- -==== - -. Confirm that the latest version of the {product} is installed: +. Verify that the desired version of the {product} is installed: + [source,bash] ---- astra --version ---- +-- + +macOS:: ++ +-- +. Run the `astra upgrade` command to upgrade to the latest version of the {product}: + -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: +[source,bash] +---- +astra upgrade +---- -[source,console,subs="+attributes"] +. Optional: Upgrade to a specific version of the {product}: ++ +[source,bash,subs="+quotes"] ---- -{product-version} +astra upgrade --version **VERSION** ---- -==== + -include::ROOT:partial$macos-security-notice.adoc[] +You can also use this command to downgrade to a previous version. + +. Verify that the desired version of the {product} is installed: ++ +[source,bash] +---- +astra --version +---- -- -curl:: +Windows:: + -- -. Update the {product}: +. Run the `astra upgrade` command to upgrade to the latest version of the {product}: + -[source,bash] +[source,powershell] ---- -curl -Ls "https://dtsx.io/get-astra-cli" | bash +astra upgrade ---- -. Confirm that the latest version of the {product} is installed: +. Optional: Upgrade to a specific version of the {product}: + -[source,bash] +[source,powershell,subs="+quotes"] ---- -astra --version +astra upgrade --version **VERSION** ---- + -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: +You can also use this command to downgrade to a previous version. -[source,console,subs="+attributes"] +. Verify that the desired version of the {product} is installed: ++ +[source,bash] ---- -{product-version} +astra --version ---- -==== -- ====== From dc3e1cdb1657dd471451555c0220356833942818 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Mon, 29 Sep 2025 12:27:32 -0500 Subject: [PATCH 04/29] More updates to install, upgrade, uninstall --- modules/ROOT/pages/astra-streaming-cli.adoc | 2 +- modules/ROOT/pages/install.adoc | 120 ++++++++++++++------ modules/ROOT/pages/managing.adoc | 6 +- modules/ROOT/pages/uninstall.adoc | 42 ++----- modules/ROOT/pages/upgrade.adoc | 33 ++++-- modules/ROOT/pages/use-cli.adoc | 33 +++++- 6 files changed, 155 insertions(+), 81 deletions(-) diff --git a/modules/ROOT/pages/astra-streaming-cli.adoc b/modules/ROOT/pages/astra-streaming-cli.adoc index a3e621c..69ab116 100644 --- a/modules/ROOT/pages/astra-streaming-cli.adoc +++ b/modules/ROOT/pages/astra-streaming-cli.adoc @@ -755,7 +755,7 @@ default(pulsar-aws-useast2.streaming.datastax.com)> ---- ==== -Type `exit` and press kbd:[Return] to exit the Pulsar shell. +Type `exit` and press kbd:[Enter] to exit the Pulsar shell. The first time you use the `astra streaming pulsar-shell` commands, the {product} downloads and installs the `pulsar-shell` utility to the {product} installation directory (`~/.astra/lunastreaming-shell-*`). diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 839e4d3..4cc85ff 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -13,10 +13,10 @@ The {product} supports the following operating systems: |Operating System |Architecture |Linux -|x86_64 +|x86_64, arm64 |macOS -|x86_64, ARM64 +|x86_64, arm64 |Microsoft Windows |x86_64 @@ -26,12 +26,12 @@ The {product} supports the following operating systems: Select one of the following installation methods and follow the steps to install the {product}. -[tabs,id=install] +[tabs,sync-group-id=platforms] ====== Homebrew:: + -- -. Install the {product} using https://brew.sh/[Homebrew]: +. Install the latest version of the {product} using https://brew.sh/[Homebrew]: + [source,bash] ---- @@ -66,7 +66,7 @@ Select one of the following installation methods to install the {product} on mac Scripted installation (recommended):: + -- -. Run the following Bash script to install the {product}: +. Run the following Bash script to install the latest version of the {product}: + [source,bash] ---- @@ -97,7 +97,7 @@ Do you want to install Astra CLI to ~/.astra/cli/? [Y]es/[d]ifferent path/[c]anc ---- ==== -. When prompted to specify the installation location, press kbd:[Return] to accept the default (`~/.astra/cli/`). +. When prompted to specify the installation location, press kbd:[Enter] to accept the default (`~/.astra/cli/`). + .Result [%collapsible] @@ -120,7 +120,7 @@ $ astra setup ---- ==== + -To install the {product} to a different location, use the binary installation method. +To install the {product} to a different location, use the binary installation method instead. . Add the following lines to your shell profile (for example, `~/.zshrc` or `~/.bashrc`) to make the `astra` command executable from any directory: + @@ -145,7 +145,7 @@ The response includes available commands and options for the {product}. Binary installation:: + -- -. Download the latest `macos` archive file for your CPU architecture from https://github.com/toptobes/astra-cli-pico/releases[GitHub]. +. Download the `macos` archive file for your CPU architecture from https://github.com/toptobes/astra-cli-pico/releases[GitHub]. . Extract the archive into the directory where you want to install the {product}: + @@ -159,21 +159,22 @@ sudo tar -xzvf astra-macos-**ARCHITECTURE**.tar.gz -C **INSTALLATION_DIRECTORY** [source,bash,subs="+quotes"] ---- # Astra CLI shell configuration -eval "$(**PATH_TO_EXEC** shellenv)" +eval "$(**PATH_TO_BINARY** shellenv)" ---- + -Replace `**PATH_TO_EXEC**` with the full path to the `astra` executable in the installation directory. +Replace `**PATH_TO_BINARY**` with the full path to the `astra` executable in the installation directory. . Reload your shell profile or open a new terminal window. -. Run the following command to de-quarantine the binary: +. Delete the `com.apple.quarantine` attribute from the `astra` binary to remove https://support.apple.com/guide/security/gatekeeper-and-runtime-protection-sec5599b66df/web[macOS Gatekeeper restrictions]: + [source,bash] ---- xattr -d com.apple.quarantine $(which astra) ---- + -For more information +You can also remove these restrictions in your macOS System Settings. +See the https://support.apple.com/en-us/102445#openanyway[Apple support documentation] for more information. . Run the `astra` command from any directory to verify successful installation: + @@ -195,7 +196,7 @@ Select one of the following installation methods to install the {product} on Win Scripted installation (recommended):: + -- -. Run the following PowerShell script to install the {product}: +. Run the following PowerShell script to install the latest version of the {product}: + [source,powershell] ---- @@ -211,7 +212,7 @@ TBD ---- ==== -. When prompted to specify the installation location, press kbd:[Return] to accept the default (`~\AppData\Local\.astra\cli`). +. When prompted to specify the installation location, press kbd:[Enter] to accept the default (`~\AppData\Local\.astra\cli`). + .Result [%collapsible] @@ -222,7 +223,7 @@ TBD ---- ==== + -To install the {product} to a different location, use the binary installation method. +To install the {product} to a different location, use the binary installation method instead. . Add the following lines to your PowerShell profile to make the `astra` command executable from any directory: + @@ -246,7 +247,7 @@ The response includes available commands and options for the {product}. Binary installation:: + -- -. Download the latest `windows` zip file from https://github.com/toptobes/astra-cli-pico/releases[GitHub]. +. Download the `windows` zip file from https://github.com/toptobes/astra-cli-pico/releases[GitHub]. . Extract the zip file into the directory where you want to install the {product}: + @@ -284,32 +285,81 @@ TBD -- ====== -To set up a new configuration and run your first commands, see xref:use-cli.adoc[]. +== Connect to {product-short} -[#file-locations] -=== Installation file locations +Follow these steps to set up your first connection profile: -The {product} and its configuration are installed in the following locations: +. {astra-url}[Sign in or create an {product-short} account.^] -[cols="1,2"] -|=== -|File location |Description +. Generate an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] with a role that has adequate permissions to perform the tasks you want to accomplish with the {product}. ++ +-- +* *Non-production organizations*: If your {product-short} organization has no databases or streaming tenants that handle sensitive information, you can grant your application token the `Organization Administrator` role to try out all of the {product} features. + +* *Production organizations*: If you're using {product-short} in production, {company} recommends that you use a more limited xref:astra-db-serverless:administration:manage-database-access.adoc#built-in-organization-roles[built-in role] or xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom role] to grant your application token the bare minimum permissions required to perform your desired tasks with the {product}. +-- + +. Run the `astra setup` command to to create your first connection profile: ++ +[source,bash] +---- +astra setup +---- ++ +.Result +[%collapsible] +==== +[source,console,subs="+attributes"] +---- + _____ __ + / _ \ _______/ |_____________ + / /_\ \ / ___/\ __\_ __ \__ \ + / | \\___ \ | | | | \ //__ \_ + \____|__ /____ > |__| |__| (____ / + \/ \/ \/ -|`~/.astra` -a|The {product} installation directory. + Version: {product-version} -For <>, the `astra` executable and `astra-init.sh` auto-completion script are located in `~/.astra/cli`. -The `~/.astra/cli` folder is added to the `PATH` environment variable. -_This folder is deleted and recreated when you update or re-install the {product}._ +Welcome to the Astra CLI setup! -For <>, the `astra` executable and auto-completion script are located in https://docs.brew.sh/FAQ#why-should-i-install-homebrew-in-the-default-location[Homebrew's default prefix] at the following locations: +A configuration file with your profile will be created at /Users/USERNAME/.astrarc -* Executable: `HOMEBREW_PREFIX/Cellar/astra-cli/VERSION/bin/astra` -* Auto-completion script: `HOMEBREW_PREFIX/Cellar/astra-cli/VERSION/etc/bash_completion.d/astra` +If you'd prefer to provide credentials on a per-command basis rather than storing them in a file, you can either: +- Use the per-command --token flag to pass your existing AstraCS token directly. +- Use the per-command --config-file flag to specify an existing .astrarc file. -|`~/.astrarc` -|The {product} configuration file. +# Example: +$ astra db list --token -_This file is *not* deleted when you update or re-install the {product}._ -|=== +Press Enter to continue, or use Ctrl+C to cancel. +---- +==== + +. When prompted, enter your {product-short} application token and press kbd:[Enter]. + +. Enter a name for your connection profile or press kbd:[Enter] to accept the default (your organization name). ++ +.Result +[%collapsible] +==== +[source,console,subs="+quotes"] +---- +Profile PROFILE_NAME successfully created. + +It has been set as the default profile. +---- +==== + +. Test your connection by running a simple command, such as listing your databases: ++ +[source,bash] +---- +astra db list +---- ++ +If the command succeeds, your connection is configured correctly. +If your command fails, see the xref:commands:astra-setup.adoc[astra setup command] documentation for troubleshooting tips. +== Next steps + +To set up a new configuration and run your first commands, see xref:use-cli.adoc[]. diff --git a/modules/ROOT/pages/managing.adoc b/modules/ROOT/pages/managing.adoc index 90fac8c..b576ea4 100644 --- a/modules/ROOT/pages/managing.adoc +++ b/modules/ROOT/pages/managing.adoc @@ -2801,7 +2801,7 @@ token@cqlsh> ---- ==== -Type `exit` or `quit;` and press kbd:[Return] to exit `cqlsh`. +Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`. The first time you use the `astra db cqlsh` command, the {product} downloads and installs the `cqlsh` utility to the {product} installation directory (`~/.astra/cqlsh-astra`). The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the `~/.astra/scb` directory. @@ -3516,7 +3516,7 @@ token@cqlsh:dsbulk_demo_keyspace> ---- ==== + -.. Copy and paste the following CQL command into the `cqlsh` prompt and press kbd:[Return]: +.. Copy and paste the following CQL command into the `cqlsh` prompt and press kbd:[Enter]: + [source,cql] ---- @@ -3538,7 +3538,7 @@ CREATE TABLE cities_by_country ( + This command creates a table named `cities_by_country` with the appropriate schema for the `cities.csv` dataset. + -.. Type `exit` or `quit;` and press kbd:[Return] to exit `cqlsh`. +.. Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`. . Load the data from the `cities.csv` file into the `cities_by_country` table that you just created in your database: + diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index c70d828..72fdb07 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -3,7 +3,7 @@ Follow the instructions for your original installation method to uninstall the {product}. -[tabs] +[tabs,sync-group-id=platforms] ====== Homebrew:: + @@ -39,43 +39,23 @@ rm ~/.astrarc ---- -- -curl:: +macOS:: + -- -. Delete the {product} and its associated installation files: -+ -[source,bash] ----- -rm -R ~/.astra ----- +-- -. Optional: Delete the {product} configuration file: +Windows:: + -[source,bash] ----- -rm ~/.astrarc ----- - -. Optional: Remove the {product} from your shell configuration file, such as `.zshrc` or `.bashrc`: +-- +-- -.. Open your shell configuration file in a text editor. -For example: +Linux:: + -[source,bash] ----- -nano ~/.zshrc ----- +-- +-- -.. Remove any lines that reference the {product}. -For example: +Docker:: + -[source,bash] ----- -#THIS MUST BE AT THE END OF THE FILE FOR ASTRA_CLI TO WORK!!! -export ASTRADIR="/Users/USERNAME/.astra/cli" -[[ -s "/Users/USERNAME/.astra/cli/astra-init.sh" ]] && source "/Users/USERNAME/.astra/cli/astra-init.sh" ----- - -.. Save and close the file. +-- -- ====== \ No newline at end of file diff --git a/modules/ROOT/pages/upgrade.adoc b/modules/ROOT/pages/upgrade.adoc index faf6bbe..613401c 100644 --- a/modules/ROOT/pages/upgrade.adoc +++ b/modules/ROOT/pages/upgrade.adoc @@ -2,9 +2,10 @@ :navtitle: Upgrade the CLI Keep the {product} up to date to access new features, improvements, and security updates. -Follow the instructions for your original installation method to upgrade the CLI. -[tabs] +Follow the instructions for your original installation method to upgrade the {product}. + +[tabs,sync-group-id=platforms] ====== Homebrew:: + @@ -25,18 +26,20 @@ brew install datastax/astra-cli/astra-cli@**VERSION** + You can also use this command to downgrade to a previous version. -. Verify that the desired version of the {product} is installed: +. Check the {product} version to verify that the upgrade was successful: + [source,bash] ---- astra --version ---- ++ +The response returns your {product} version. -- macOS:: + -- -. Run the `astra upgrade` command to upgrade to the latest version of the {product}: +. Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: + [source,bash] ---- @@ -52,18 +55,20 @@ astra upgrade --version **VERSION** + You can also use this command to downgrade to a previous version. -. Verify that the desired version of the {product} is installed: +. Check the {product} version to verify that the upgrade was successful: + [source,bash] ---- astra --version ---- ++ +The response returns your {product} version. -- Windows:: + -- -. Run the `astra upgrade` command to upgrade to the latest version of the {product}: +. Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: + [source,powershell] ---- @@ -79,11 +84,25 @@ astra upgrade --version **VERSION** + You can also use this command to downgrade to a previous version. -. Verify that the desired version of the {product} is installed: +. Check the {product} version to verify that the upgrade was successful: + [source,bash] ---- astra --version ---- ++ +The response returns your {product} version. +-- + +Linux:: ++ +-- +TBD +-- + +Docker:: ++ +-- +TBD -- ====== diff --git a/modules/ROOT/pages/use-cli.adoc b/modules/ROOT/pages/use-cli.adoc index d8c6f9e..5fea6f4 100644 --- a/modules/ROOT/pages/use-cli.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -1,12 +1,10 @@ -= Get started with the {product} -:navtitle: Get started += Connect and configure the {product} +:navtitle: Connect and configure Initialize the {product} and run your first commands. == Prerequisites -To configure the {product}: - * xref:ROOT:install.adoc[Install the {product}]. * You must have an active {astra-url}[{product-short} account^]. @@ -19,6 +17,33 @@ 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]. +[#file-locations] +== Installation file locations + +The {product} and its configuration are installed in the following locations: + +[cols="1,2"] +|=== +|File location |Description + +|`~/.astra` +a|The {product} installation directory. + +For <>, the `astra` executable and `astra-init.sh` auto-completion script are located in `~/.astra/cli`. +The `~/.astra/cli` folder is added to the `PATH` environment variable. +_This folder is deleted and recreated when you update or re-install the {product}._ + +For <>, the `astra` executable and auto-completion script are located in https://docs.brew.sh/FAQ#why-should-i-install-homebrew-in-the-default-location[Homebrew's default prefix] at the following locations: + +* Executable: `HOMEBREW_PREFIX/Cellar/astra-cli/VERSION/bin/astra` +* Auto-completion script: `HOMEBREW_PREFIX/Cellar/astra-cli/VERSION/etc/bash_completion.d/astra` + +|`~/.astrarc` +|The {product} configuration file. + +_This file is *not* deleted when you update or re-install the {product}._ +|=== + [#initialize] == Initialize the {product} From dc8a2e43f7e40bebe256f481579c2fb3a186f7c4 Mon Sep 17 00:00:00 2001 From: toptobes Date: Fri, 7 Nov 2025 10:15:03 -0600 Subject: [PATCH 05/29] add initial command pages --- modules/ROOT/nav.adoc | 22 +-- modules/ROOT/partials/partial-nav.adoc | 108 ++++++++++++ modules/commands/pages/astra-completions.adoc | 31 ++++ .../commands/pages/astra-config-create.adoc | 56 +++++++ .../commands/pages/astra-config-delete.adoc | 42 +++++ modules/commands/pages/astra-config-get.adoc | 49 ++++++ .../pages/astra-config-home-path.adoc | 41 +++++ modules/commands/pages/astra-config-home.adoc | 29 ++++ modules/commands/pages/astra-config-list.adoc | 43 +++++ modules/commands/pages/astra-config-path.adoc | 41 +++++ modules/commands/pages/astra-config-use.adoc | 40 +++++ modules/commands/pages/astra-config.adoc | 77 +++++---- .../commands/pages/astra-db-cqlsh-exec.adoc | 54 ++++++ .../commands/pages/astra-db-cqlsh-path.adoc | 47 ++++++ .../commands/pages/astra-db-cqlsh-start.adoc | 52 ++++++ .../pages/astra-db-cqlsh-version.adoc | 45 +++++ modules/commands/pages/astra-db-cqlsh.adoc | 42 +++++ .../commands/pages/astra-db-create-cdc.adoc | 54 ++++++ .../pages/astra-db-create-collection.adoc | 70 ++++++++ .../pages/astra-db-create-dotenv.adoc | 67 ++++++++ .../pages/astra-db-create-keyspace.adoc | 53 ++++++ .../pages/astra-db-create-region.adoc | 52 ++++++ modules/commands/pages/astra-db-create.adoc | 69 ++++++++ .../commands/pages/astra-db-delete-cdc.adoc | 54 ++++++ .../pages/astra-db-delete-collection.adoc | 51 ++++++ .../pages/astra-db-delete-keyspace.adoc | 53 ++++++ .../pages/astra-db-delete-region.adoc | 52 ++++++ .../commands/pages/astra-db-delete-table.adoc | 51 ++++++ modules/commands/pages/astra-db-delete.adoc | 55 +++++++ .../pages/astra-db-describe-collection.adoc | 47 ++++++ .../pages/astra-db-describe-table.adoc | 47 ++++++ .../commands/pages/astra-db-download-scb.adoc | 50 ++++++ .../commands/pages/astra-db-dsbulk-count.adoc | 53 ++++++ .../commands/pages/astra-db-dsbulk-load.adoc | 62 +++++++ .../commands/pages/astra-db-dsbulk-path.adoc | 47 ++++++ .../pages/astra-db-dsbulk-unload.adoc | 62 +++++++ .../pages/astra-db-dsbulk-version.adoc | 40 +++++ modules/commands/pages/astra-db-dsbulk.adoc | 33 ++++ .../pages/astra-db-get-endpoint-api.adoc | 46 ++++++ .../astra-db-get-endpoint-playground.adoc | 46 ++++++ .../pages/astra-db-get-endpoint-swagger.adoc | 46 ++++++ modules/commands/pages/astra-db-get.adoc | 48 ++++++ .../commands/pages/astra-db-list-cdcs.adoc | 41 +++++ .../commands/pages/astra-db-list-clouds.adoc | 40 +++++ .../pages/astra-db-list-collections.adoc | 50 ++++++ .../astra-db-list-embedding-providers.adoc | 42 +++++ .../pages/astra-db-list-keyspaces.adoc | 41 +++++ .../pages/astra-db-list-regions-classic.adoc | 54 ++++++ .../astra-db-list-regions-serverless.adoc | 55 +++++++ .../pages/astra-db-list-regions-vector.adoc | 54 ++++++ .../commands/pages/astra-db-list-regions.adoc | 41 +++++ .../commands/pages/astra-db-list-tables.adoc | 49 ++++++ modules/commands/pages/astra-db-list.adoc | 47 ++++++ modules/commands/pages/astra-db-resume.adoc | 46 ++++++ modules/commands/pages/astra-db-status.adoc | 41 +++++ .../pages/astra-db-truncate-collection.adoc | 47 ++++++ .../pages/astra-db-truncate-table.adoc | 47 ++++++ modules/commands/pages/astra-db.adoc | 155 ++++++++---------- modules/commands/pages/astra-nuke.adoc | 60 ++++++- modules/commands/pages/astra-org-get.adoc | 50 ++++++ modules/commands/pages/astra-org-id.adoc | 40 +++++ modules/commands/pages/astra-org-name.adoc | 40 +++++ modules/commands/pages/astra-org.adoc | 55 ++++++- .../commands/pages/astra-pcu-associate.adoc | 47 ++++++ modules/commands/pages/astra-pcu-create.adoc | 56 +++++++ modules/commands/pages/astra-pcu-delete.adoc | 49 ++++++ .../pages/astra-pcu-disassociate.adoc | 47 ++++++ modules/commands/pages/astra-pcu-get.adoc | 48 ++++++ .../pages/astra-pcu-list-associations.adoc | 42 +++++ modules/commands/pages/astra-pcu-list.adoc | 43 +++++ modules/commands/pages/astra-pcu-park.adoc | 43 +++++ modules/commands/pages/astra-pcu-status.adoc | 41 +++++ .../pages/astra-pcu-transfer-association.adoc | 47 ++++++ modules/commands/pages/astra-pcu-unpark.adoc | 43 +++++ modules/commands/pages/astra-pcu-update.adoc | 53 ++++++ modules/commands/pages/astra-pcu.adoc | 56 +++++++ modules/commands/pages/astra-role-get.adoc | 47 ++++++ modules/commands/pages/astra-role-list.adoc | 40 +++++ modules/commands/pages/astra-role.adoc | 35 +++- modules/commands/pages/astra-setup.adoc | 55 +++---- modules/commands/pages/astra-shellenv.adoc | 49 ++++++ .../pages/astra-streaming-create.adoc | 58 +++++++ .../pages/astra-streaming-delete.adoc | 46 ++++++ .../commands/pages/astra-streaming-exist.adoc | 41 +++++ .../commands/pages/astra-streaming-get.adoc | 48 ++++++ .../pages/astra-streaming-list-clouds.adoc | 40 +++++ .../pages/astra-streaming-list-regions.adoc | 50 ++++++ .../commands/pages/astra-streaming-list.adoc | 42 +++++ .../pages/astra-streaming-pulsar-path.adoc | 48 ++++++ .../pages/astra-streaming-pulsar-shell.adoc | 46 ++++++ .../pages/astra-streaming-pulsar-token.adoc | 41 +++++ .../pages/astra-streaming-pulsar-version.adoc | 40 +++++ .../pages/astra-streaming-pulsar.adoc | 38 +++++ .../pages/astra-streaming-status.adoc | 41 +++++ modules/commands/pages/astra-streaming.adoc | 54 +++++- .../commands/pages/astra-token-create.adoc | 42 +++++ .../commands/pages/astra-token-delete.adoc | 48 ++++++ modules/commands/pages/astra-token-get.adoc | 45 +++++ modules/commands/pages/astra-token-list.adoc | 40 +++++ modules/commands/pages/astra-token.adoc | 51 +++++- modules/commands/pages/astra-upgrade.adoc | 52 +++++- modules/commands/pages/astra-user-delete.adoc | 45 +++++ modules/commands/pages/astra-user-get.adoc | 47 ++++++ modules/commands/pages/astra-user-invite.adoc | 50 ++++++ modules/commands/pages/astra-user-list.adoc | 43 +++++ modules/commands/pages/astra-user.adoc | 49 +++++- modules/commands/pages/astra.adoc | 67 -------- 107 files changed, 5028 insertions(+), 247 deletions(-) create mode 100644 modules/ROOT/partials/partial-nav.adoc create mode 100644 modules/commands/pages/astra-completions.adoc create mode 100644 modules/commands/pages/astra-config-create.adoc create mode 100644 modules/commands/pages/astra-config-delete.adoc create mode 100644 modules/commands/pages/astra-config-get.adoc create mode 100644 modules/commands/pages/astra-config-home-path.adoc create mode 100644 modules/commands/pages/astra-config-home.adoc create mode 100644 modules/commands/pages/astra-config-list.adoc create mode 100644 modules/commands/pages/astra-config-path.adoc create mode 100644 modules/commands/pages/astra-config-use.adoc create mode 100644 modules/commands/pages/astra-db-cqlsh-exec.adoc create mode 100644 modules/commands/pages/astra-db-cqlsh-path.adoc create mode 100644 modules/commands/pages/astra-db-cqlsh-start.adoc create mode 100644 modules/commands/pages/astra-db-cqlsh-version.adoc create mode 100644 modules/commands/pages/astra-db-cqlsh.adoc create mode 100644 modules/commands/pages/astra-db-create-cdc.adoc create mode 100644 modules/commands/pages/astra-db-create-collection.adoc create mode 100644 modules/commands/pages/astra-db-create-dotenv.adoc create mode 100644 modules/commands/pages/astra-db-create-keyspace.adoc create mode 100644 modules/commands/pages/astra-db-create-region.adoc create mode 100644 modules/commands/pages/astra-db-create.adoc create mode 100644 modules/commands/pages/astra-db-delete-cdc.adoc create mode 100644 modules/commands/pages/astra-db-delete-collection.adoc create mode 100644 modules/commands/pages/astra-db-delete-keyspace.adoc create mode 100644 modules/commands/pages/astra-db-delete-region.adoc create mode 100644 modules/commands/pages/astra-db-delete-table.adoc create mode 100644 modules/commands/pages/astra-db-delete.adoc create mode 100644 modules/commands/pages/astra-db-describe-collection.adoc create mode 100644 modules/commands/pages/astra-db-describe-table.adoc create mode 100644 modules/commands/pages/astra-db-download-scb.adoc create mode 100644 modules/commands/pages/astra-db-dsbulk-count.adoc create mode 100644 modules/commands/pages/astra-db-dsbulk-load.adoc create mode 100644 modules/commands/pages/astra-db-dsbulk-path.adoc create mode 100644 modules/commands/pages/astra-db-dsbulk-unload.adoc create mode 100644 modules/commands/pages/astra-db-dsbulk-version.adoc create mode 100644 modules/commands/pages/astra-db-dsbulk.adoc create mode 100644 modules/commands/pages/astra-db-get-endpoint-api.adoc create mode 100644 modules/commands/pages/astra-db-get-endpoint-playground.adoc create mode 100644 modules/commands/pages/astra-db-get-endpoint-swagger.adoc create mode 100644 modules/commands/pages/astra-db-get.adoc create mode 100644 modules/commands/pages/astra-db-list-cdcs.adoc create mode 100644 modules/commands/pages/astra-db-list-clouds.adoc create mode 100644 modules/commands/pages/astra-db-list-collections.adoc create mode 100644 modules/commands/pages/astra-db-list-embedding-providers.adoc create mode 100644 modules/commands/pages/astra-db-list-keyspaces.adoc create mode 100644 modules/commands/pages/astra-db-list-regions-classic.adoc create mode 100644 modules/commands/pages/astra-db-list-regions-serverless.adoc create mode 100644 modules/commands/pages/astra-db-list-regions-vector.adoc create mode 100644 modules/commands/pages/astra-db-list-regions.adoc create mode 100644 modules/commands/pages/astra-db-list-tables.adoc create mode 100644 modules/commands/pages/astra-db-list.adoc create mode 100644 modules/commands/pages/astra-db-resume.adoc create mode 100644 modules/commands/pages/astra-db-status.adoc create mode 100644 modules/commands/pages/astra-db-truncate-collection.adoc create mode 100644 modules/commands/pages/astra-db-truncate-table.adoc create mode 100644 modules/commands/pages/astra-org-get.adoc create mode 100644 modules/commands/pages/astra-org-id.adoc create mode 100644 modules/commands/pages/astra-org-name.adoc create mode 100644 modules/commands/pages/astra-pcu-associate.adoc create mode 100644 modules/commands/pages/astra-pcu-create.adoc create mode 100644 modules/commands/pages/astra-pcu-delete.adoc create mode 100644 modules/commands/pages/astra-pcu-disassociate.adoc create mode 100644 modules/commands/pages/astra-pcu-get.adoc create mode 100644 modules/commands/pages/astra-pcu-list-associations.adoc create mode 100644 modules/commands/pages/astra-pcu-list.adoc create mode 100644 modules/commands/pages/astra-pcu-park.adoc create mode 100644 modules/commands/pages/astra-pcu-status.adoc create mode 100644 modules/commands/pages/astra-pcu-transfer-association.adoc create mode 100644 modules/commands/pages/astra-pcu-unpark.adoc create mode 100644 modules/commands/pages/astra-pcu-update.adoc create mode 100644 modules/commands/pages/astra-pcu.adoc create mode 100644 modules/commands/pages/astra-role-get.adoc create mode 100644 modules/commands/pages/astra-role-list.adoc create mode 100644 modules/commands/pages/astra-shellenv.adoc create mode 100644 modules/commands/pages/astra-streaming-create.adoc create mode 100644 modules/commands/pages/astra-streaming-delete.adoc create mode 100644 modules/commands/pages/astra-streaming-exist.adoc create mode 100644 modules/commands/pages/astra-streaming-get.adoc create mode 100644 modules/commands/pages/astra-streaming-list-clouds.adoc create mode 100644 modules/commands/pages/astra-streaming-list-regions.adoc create mode 100644 modules/commands/pages/astra-streaming-list.adoc create mode 100644 modules/commands/pages/astra-streaming-pulsar-path.adoc create mode 100644 modules/commands/pages/astra-streaming-pulsar-shell.adoc create mode 100644 modules/commands/pages/astra-streaming-pulsar-token.adoc create mode 100644 modules/commands/pages/astra-streaming-pulsar-version.adoc create mode 100644 modules/commands/pages/astra-streaming-pulsar.adoc create mode 100644 modules/commands/pages/astra-streaming-status.adoc create mode 100644 modules/commands/pages/astra-token-create.adoc create mode 100644 modules/commands/pages/astra-token-delete.adoc create mode 100644 modules/commands/pages/astra-token-get.adoc create mode 100644 modules/commands/pages/astra-token-list.adoc create mode 100644 modules/commands/pages/astra-user-delete.adoc create mode 100644 modules/commands/pages/astra-user-get.adoc create mode 100644 modules/commands/pages/astra-user-invite.adoc create mode 100644 modules/commands/pages/astra-user-list.adoc delete mode 100644 modules/commands/pages/astra.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 57af553..e6d7d54 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,21 +1,13 @@ -.Get started * xref:install.adoc[] * xref:use-cli.adoc[] * xref:upgrade.adoc[] * xref:uninstall.adoc[] -.Commands -* xref:commands:astra.adoc[] -* xref:commands:astra-setup.adoc[] -* xref:commands:astra-config.adoc[] -* xref:commands:astra-db.adoc[] -* xref:commands:astra-org.adoc[] -* xref:commands:astra-role.adoc[] -* xref:commands:astra-streaming.adoc[] -* xref:commands:astra-token.adoc[] -* xref:commands:astra-user.adoc[] -* xref:commands:astra-upgrade.adoc[] -* xref:commands:astra-nuke.adoc[] +* Commands ++ +-- +include::partial$partial-nav.adoc[] +-- -.Release notes -* https://github.com/datastax/astra-cli/releases[Release notes] \ No newline at end of file +* https://github.com/datastax/astra-cli[GitHub repo] +* https://github.com/datastax/astra-cli/releases[Release notes] diff --git a/modules/ROOT/partials/partial-nav.adoc b/modules/ROOT/partials/partial-nav.adoc new file mode 100644 index 0000000..ccfd2b6 --- /dev/null +++ b/modules/ROOT/partials/partial-nav.adoc @@ -0,0 +1,108 @@ + +.Commands +* xref:commands:astra-setup.adoc[] +* xref:commands:astra-config.adoc[] +** xref:commands:astra-config-list.adoc[] +** xref:commands:astra-config-create.adoc[] +** xref:commands:astra-config-get.adoc[] +** xref:commands:astra-config-delete.adoc[] +** xref:commands:astra-config-use.adoc[] +** xref:commands:astra-config-path.adoc[] +** xref:commands:astra-config-home.adoc[] +*** xref:commands:astra-config-home-path.adoc[] +* xref:commands:astra-db.adoc[] +** xref:commands:astra-db-list.adoc[] +** xref:commands:astra-db-get.adoc[] +** xref:commands:astra-db-create.adoc[] +** xref:commands:astra-db-delete.adoc[] +** xref:commands:astra-db-status.adoc[] +** xref:commands:astra-db-cqlsh.adoc[] +*** xref:commands:astra-db-cqlsh-start.adoc[] +*** xref:commands:astra-db-cqlsh-exec.adoc[] +*** xref:commands:astra-db-cqlsh-version.adoc[] +*** xref:commands:astra-db-cqlsh-path.adoc[] +** xref:commands:astra-db-dsbulk.adoc[] +*** xref:commands:astra-db-dsbulk-count.adoc[] +*** xref:commands:astra-db-dsbulk-load.adoc[] +*** xref:commands:astra-db-dsbulk-unload.adoc[] +*** xref:commands:astra-db-dsbulk-version.adoc[] +*** xref:commands:astra-db-dsbulk-path.adoc[] +** xref:commands:astra-db-create-dotenv.adoc[] +** xref:commands:astra-db-download-scb.adoc[] +** xref:commands:astra-db-resume.adoc[] +** xref:commands:astra-db-list-keyspaces.adoc[] +** xref:commands:astra-db-create-keyspace.adoc[] +** xref:commands:astra-db-delete-keyspace.adoc[] +** xref:commands:astra-db-list-collections.adoc[] +** xref:commands:astra-db-create-collection.adoc[] +** xref:commands:astra-db-describe-collection.adoc[] +** xref:commands:astra-db-delete-collection.adoc[] +** xref:commands:astra-db-truncate-collection.adoc[] +** xref:commands:astra-db-list-tables.adoc[] +** xref:commands:astra-db-describe-table.adoc[] +** xref:commands:astra-db-delete-table.adoc[] +** xref:commands:astra-db-truncate-table.adoc[] +** xref:commands:astra-db-list-embedding-providers.adoc[] +** xref:commands:astra-db-list-cdcs.adoc[] +** xref:commands:astra-db-create-cdc.adoc[] +** xref:commands:astra-db-delete-cdc.adoc[] +** xref:commands:astra-db-create-region.adoc[] +** xref:commands:astra-db-delete-region.adoc[] +** xref:commands:astra-db-list-regions.adoc[] +** xref:commands:astra-db-list-regions-classic.adoc[] +** xref:commands:astra-db-list-regions-serverless.adoc[] +** xref:commands:astra-db-list-regions-vector.adoc[] +** xref:commands:astra-db-list-clouds.adoc[] +** xref:commands:astra-db-get-endpoint-swagger.adoc[] +** xref:commands:astra-db-get-endpoint-api.adoc[] +** xref:commands:astra-db-get-endpoint-playground.adoc[] +* xref:commands:astra-pcu.adoc[] +** xref:commands:astra-pcu-list.adoc[] +** xref:commands:astra-pcu-get.adoc[] +** xref:commands:astra-pcu-status.adoc[] +** xref:commands:astra-pcu-park.adoc[] +** xref:commands:astra-pcu-unpark.adoc[] +** xref:commands:astra-pcu-create.adoc[] +** xref:commands:astra-pcu-update.adoc[] +** xref:commands:astra-pcu-delete.adoc[] +** xref:commands:astra-pcu-associate.adoc[] +** xref:commands:astra-pcu-disassociate.adoc[] +** xref:commands:astra-pcu-list-associations.adoc[] +** xref:commands:astra-pcu-transfer-association.adoc[] +* xref:commands:astra-org.adoc[] +** xref:commands:astra-org-get.adoc[] +** xref:commands:astra-org-id.adoc[] +** xref:commands:astra-org-name.adoc[] +* xref:commands:astra-role.adoc[] +** xref:commands:astra-role-list.adoc[] +** xref:commands:astra-role-get.adoc[] +* xref:commands:astra-streaming.adoc[] +** xref:commands:astra-streaming-list.adoc[] +** xref:commands:astra-streaming-get.adoc[] +** xref:commands:astra-streaming-create.adoc[] +** xref:commands:astra-streaming-delete.adoc[] +** xref:commands:astra-streaming-exist.adoc[] +** xref:commands:astra-streaming-status.adoc[] +** xref:commands:astra-streaming-pulsar.adoc[] +*** xref:commands:astra-streaming-pulsar-shell.adoc[] +*** xref:commands:astra-streaming-pulsar-version.adoc[] +*** xref:commands:astra-streaming-pulsar-path.adoc[] +** xref:commands:astra-streaming-pulsar-token.adoc[] +** xref:commands:astra-streaming-list-regions.adoc[] +** xref:commands:astra-streaming-list-clouds.adoc[] +* xref:commands:astra-token.adoc[] +** xref:commands:astra-token-list.adoc[] +** xref:commands:astra-token-get.adoc[] +** xref:commands:astra-token-create.adoc[] +** xref:commands:astra-token-delete.adoc[] +* xref:commands:astra-user.adoc[] +** xref:commands:astra-user-list.adoc[] +** xref:commands:astra-user-get.adoc[] +** xref:commands:astra-user-invite.adoc[] +** xref:commands:astra-user-delete.adoc[] +* xref:commands:astra-completions.adoc[] +* xref:commands:astra-upgrade.adoc[] +* xref:commands:astra-shellenv.adoc[] +* xref:commands:astra-nuke.adoc[] + + diff --git a/modules/commands/pages/astra-completions.adoc b/modules/commands/pages/astra-completions.adoc new file mode 100644 index 0000000..d003c97 --- /dev/null +++ b/modules/commands/pages/astra-completions.adoc @@ -0,0 +1,31 @@ += astra completions + +[source,shell] +---- +astra completions [-n=<$cliName>] + +---- + + +See the help for the ``@{cli.name} shellenv`` command to setup completions in your shell. + +== Aliases + +`astra compgen` + + + + +== Options + +`-n`, `--cli-name`:: CLI name to use in the completion script + + +== Examples +[source,bash] +---- +# Put this in your shell profile (e.g. ``~/.zprofile``) to generate completions and set your PATH +$ eval "$(/path/to/astra shellenv)" +---- + + diff --git a/modules/commands/pages/astra-config-create.adoc b/modules/commands/pages/astra-config-create.adoc new file mode 100644 index 0000000..779d5f8 --- /dev/null +++ b/modules/commands/pages/astra-config-create.adoc @@ -0,0 +1,56 @@ += astra config create + +[source,shell] +---- +astra config create [-dqV] [--no-input] [--[no-]overwrite] [--[no-]spinner] + [--dump-logs[=FILE]] [-cf=PATH] [--color=WHEN] [-e=ENV] + [-o=FORMAT] -t=TOKEN [NAME] + +---- + + +Create a new configuration profile to store your Astra credentials. + +Use the ``--token @`` syntax to securely read the token from a file, without leaking the token to your shell history, where the file contains only the token as plain text or a JSON string. + + + + + +== Options + +`NAME`:: Unique name for the profile +`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-t`, `--token`:: Astra token (``AstraCS:...``) or ``@`` to read from file +`-e`, `--env`:: Astra environment the token targets +`-d`, `--default`:: Set the created profile as the default profile. Same as 'config use ' +`--overwrite`:: Overwrite any existing profile with the same name +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file + + +== Examples +[source,bash] +---- +# (Recommended) Interactively create a new profile +$ astra setup + +# (Recommended) Securely create a new profile with the token provided from a file +$ astra config create my_profile -t @token.txt + +# Programmatically create a new profile +$ astra config create my_profile -t AstraCS:... + +# Create a new profile with the default name (organization name) +$ astra config create -t AstraCS:... + +# Create a new profile and set it as the default profile +$ astra config create my_profile -t AstraCS:... --default +---- + + diff --git a/modules/commands/pages/astra-config-delete.adoc b/modules/commands/pages/astra-config-delete.adoc new file mode 100644 index 0000000..38bb37e --- /dev/null +++ b/modules/commands/pages/astra-config-delete.adoc @@ -0,0 +1,42 @@ += astra config delete + +[source,shell] +---- +astra config delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [-cf=PATH] [--color=WHEN] [-o=FORMAT] + [NAME] + +---- + + +Delete an existing configuration profile. + + + + + +== Options + +`NAME`:: Name of the profile to delete +`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`--if-exists`:: Do not fail if the profile does not exist +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file + + +== Examples +[source,bash] +---- +# Delete a profile named 'my_profile' +$ astra config delete my_profile + +# Delete a profile named 'my_profile' without failing if it does not exist +$ astra config delete my_profile --if-exists +---- + + diff --git a/modules/commands/pages/astra-config-get.adoc b/modules/commands/pages/astra-config-get.adoc new file mode 100644 index 0000000..2ed9d8b --- /dev/null +++ b/modules/commands/pages/astra-config-get.adoc @@ -0,0 +1,49 @@ += astra config get + +[source,shell] +---- +astra config get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-cf=PATH] [--color=WHEN] [-k=KEY] [-o=FORMAT] [NAME] + +---- + + +Get the configuration of a profile or a specific key. + +**Warning:** This command may expose your sensitive Astra token. + +== Aliases + +`astra config describe` + + + + +== Options + +`NAME`:: Name of the profile to get +`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-k`, `--key`:: Specific configuration key to retrieve +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file + + +== Examples +[source,bash] +---- +# Get the configuration of a specific profile +$ astra config get my_profile + +# Prompt for the profile to get the configuration of +$ astra config get + +# Get the value of a specific key in a profile +$ astra config get my_profile --key ASTRA_DB_APPLICATION_TOKEN +---- + + diff --git a/modules/commands/pages/astra-config-home-path.adoc b/modules/commands/pages/astra-config-home-path.adoc new file mode 100644 index 0000000..40a2210 --- /dev/null +++ b/modules/commands/pages/astra-config-home-path.adoc @@ -0,0 +1,41 @@ += astra config home path + +[source,shell] +---- +astra config home path [-pqV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] + +---- + + +Prints the expected path of the astra home folder, even if does not exist. + +Checks ``ASTRA_HOME`` __(ASTRA_HOME=~/my_folder)__ -> ``XDG_DATA_HOME`` __($XDG_DATA_HOME/astra)__ -> ``HOME`` __(~/.astra)__. + + + + + +== Options + +`-p`, `--plain`:: Print only the path to the home folder, without additional information +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file + + +== Examples +[source,bash] +---- +# Get information about the path to the astra home folder +$ astra config home path + +# Print only the path to the home folder, without additional information +$ astra config home path -p +---- + + diff --git a/modules/commands/pages/astra-config-home.adoc b/modules/commands/pages/astra-config-home.adoc new file mode 100644 index 0000000..ec15bfa --- /dev/null +++ b/modules/commands/pages/astra-config-home.adoc @@ -0,0 +1,29 @@ += astra config home + +[source,shell] +---- +astra config home [COMMAND] + +---- + + +All things related to the Astra CLI home folder + + + +== Subcommands + +* xref:astra-config-home-path.adoc[astra config home path] + + +== Options + + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-config-list.adoc b/modules/commands/pages/astra-config-list.adoc new file mode 100644 index 0000000..6d1aef4 --- /dev/null +++ b/modules/commands/pages/astra-config-list.adoc @@ -0,0 +1,43 @@ += astra config list + +[source,shell] +---- +astra config list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-cf=PATH] [--color=WHEN] [-e=ENV] [-o=FORMAT] + +---- + + +List your Astra CLI configurations. + +== Aliases + +`astra config` + + + + +== Options + +`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-e`, `--env`:: Filter by Astra environment +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file + + +== Examples +[source,bash] +---- +# List your Astra CLI configurations. +$ astra config list + +# List your Astra CLI configurations for a specific Astra environment. +$ astra config list --env dev +---- + + diff --git a/modules/commands/pages/astra-config-path.adoc b/modules/commands/pages/astra-config-path.adoc new file mode 100644 index 0000000..cff6460 --- /dev/null +++ b/modules/commands/pages/astra-config-path.adoc @@ -0,0 +1,41 @@ += astra config path + +[source,shell] +---- +astra config path [-pqV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] + +---- + + +Prints the expected path of the .astrarc file, even if does not exist. + +Checks ``ASTRARC`` __(ASTRARC=~/my_folder/.my_rc)__ -> ``XDG_CONFIG_HOME`` __($XDG_CONFIG_HOME/astra/.astrarc)__ -> ``HOME`` __(~/.astrarc)__. + + + + + +== Options + +`-p`, `--plain`:: Print only the path to the .astrarc file, without additional information +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file + + +== Examples +[source,bash] +---- +# Get information about the path to the .astrarc file +$ astra config path + +# Print only the path to the .astrarc file, without additional information +$ astra config path -p +---- + + diff --git a/modules/commands/pages/astra-config-use.adoc b/modules/commands/pages/astra-config-use.adoc new file mode 100644 index 0000000..c74488f --- /dev/null +++ b/modules/commands/pages/astra-config-use.adoc @@ -0,0 +1,40 @@ += astra config use + +[source,shell] +---- +astra config use [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-cf=PATH] [--color=WHEN] [-o=FORMAT] [NAME] + +---- + + +Sets an existing profile to be used as the default for all commands. Use the ``--default`` option when creating a new profile to set it as the default automatically. + + + + + +== Options + +`NAME`:: Profile to set as default +`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file + + +== Examples +[source,bash] +---- +# Set an existing profile as the default +$ astra config use my_profile + +# Set a profile as the default when creating it +$ astra config create my_profile -t @token.txt --default +---- + + diff --git a/modules/commands/pages/astra-config.adoc b/modules/commands/pages/astra-config.adoc index 36cc4e6..70f3bdb 100644 --- a/modules/commands/pages/astra-config.adoc +++ b/modules/commands/pages/astra-config.adoc @@ -1,60 +1,57 @@ = astra config -Manage your Astra CLI configuration profiles. - -== Usage - -[source,console] ----- -astra config [-hqv] [--[no-]color] [--no-input] [--[no-]spinner] - [--dump-logs[=FILE]] [-cf=PATH] [-o=FORMAT] [COMMAND] +[source,shell] ---- +astra config [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-cf=PATH] [--color=WHEN] [-e=ENV] [-o=FORMAT] [COMMAND] -== Options +---- -`-cf`, `--config-file=PATH`:: -The astrarc file to use -`--[no-]color`:: -Force colored output +Manage your Astra CLI configuration profiles -`--dump-logs[=FILE]`:: -Write all logs to an optionally specified file (default: ~/.astra/logs/.log) -`-h`, `--help`:: -Show this help message and exit. +**Alias of `astra config list`** -`--no-input`:: -Never ask for user input (e.g. confirmation prompts) -`-o`, `--output=FORMAT`:: -One of: human, json, csv +== Subcommands -`-q`, `--quiet`:: -Suppress informational output +* xref:astra-config-list.adoc[astra config list] +* xref:astra-config-create.adoc[astra config create] +* xref:astra-config-get.adoc[astra config get] +* xref:astra-config-delete.adoc[astra config delete] +* xref:astra-config-use.adoc[astra config use] +* xref:astra-config-path.adoc[astra config path] +* xref:astra-config-home.adoc[astra config home] -`--[no-]spinner`:: -Enable/disable the loading spinner -`-v`, `--verbose`:: -Enable verbose logging output +== Options -== Commands +`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-e`, `--env`:: Filter by Astra environment +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file -* list -* create -* get, describe -* use -* path -* home == Examples - -[source,console] +[source,bash] ---- -# List your Astra CLI profiles. +# List your configuration profiles $ astra config -# Create a new Astra CLI profile. -$ astra config create --token @token.txt --name prod ----- \ No newline at end of file +# Interactively create a new configuration profile +$ astra config setup + +# Programmatically create a new configuration profile +$ astra config create my_profile --token @token.txt + +# Set an existing configuration profile as default +$ astra config use my_profile +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh-exec.adoc b/modules/commands/pages/astra-db-cqlsh-exec.adoc new file mode 100644 index 0000000..c7bab33 --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh-exec.adoc @@ -0,0 +1,54 @@ += astra db cqlsh exec + +[source,shell] +---- +astra db cqlsh exec [-qV] [--debug] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [--connect-timeout=TIMEOUT] + [--encoding=ENCODING] [-f=FILE] [-k=KEYSPACE] [-o=FORMAT] + [-r=REGION] [--request-timeout=TIMEOUT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] [STATEMENT] + +---- + + +Execute CQL statements for your db using cqlsh + + + + + +== Options + +`DB`:: The name/ID of the Astra database to connect to +`STATEMENT`:: Execute the statement and quit +`--debug`:: Show additional debugging information +`--encoding`:: Output encoding (default: utf8) +`--connect-timeout`:: Connection timeout in seconds +`-k`, `--keyspace`:: Authenticate to the given keyspace +`--request-timeout`:: Request timeout in seconds +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`-f`, `--file`:: Execute commands from a CQL file, then exit +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Execute a CQL statement +$ astra db cqlsh exec my_db "SELECT * FROM my_keyspace.my_table" + +# Execute a CQL file +$ astra db cqlsh exec my_db -f script.cql +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh-path.adoc b/modules/commands/pages/astra-db-cqlsh-path.adoc new file mode 100644 index 0000000..c1f0274 --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh-path.adoc @@ -0,0 +1,47 @@ += astra db cqlsh path + +[source,shell] +---- +astra db cqlsh path [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Get the path to the currently installed cqlsh executable + + + + + +== Options + +`--if-exists`:: Only return path if cqlsh exists, don't install automatically +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the path to the cqlsh executable +$ astra db cqlsh path + +# Use the cqlsh exe to run a custom command +$ $(astra db cqlsh path) --help + +# Get path only if cqlsh exists, don't install +$ astra db cqlsh path --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh-start.adoc b/modules/commands/pages/astra-db-cqlsh-start.adoc new file mode 100644 index 0000000..7a36eb7 --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh-start.adoc @@ -0,0 +1,52 @@ += astra db cqlsh start + +[source,shell] +---- +astra db cqlsh start [-qV] [--debug] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [--connect-timeout=TIMEOUT] + [--encoding=ENCODING] [-k=KEYSPACE] [-o=FORMAT] + [-r=REGION] [--request-timeout=TIMEOUT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [] [DB] + +---- + + +Connect to your Astra database using cqlsh + + + + + +== Options + +`DB`:: The name/ID of the Astra database to connect to +`--debug`:: Show additional debugging information +`--encoding`:: Output encoding (default: utf8) +`--connect-timeout`:: Connection timeout in seconds +`-k`, `--keyspace`:: Authenticate to the given keyspace +`--request-timeout`:: Request timeout in seconds +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Launch cqlsh for a database +$ astra db cqlsh start my_db + +# Launch cqlsh with a specific keyspace +$ astra db cqlsh start my_db -k my_keyspace +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh-version.adoc b/modules/commands/pages/astra-db-cqlsh-version.adoc new file mode 100644 index 0000000..8c84e95 --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh-version.adoc @@ -0,0 +1,45 @@ += astra db cqlsh version + +[source,shell] +---- +astra db cqlsh version [-qV] [--debug] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [--connect-timeout=TIMEOUT] [--encoding=ENCODING] + [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] + +---- + + +Display the currently installed cqlsh's version + + + + + +== Options + +`--debug`:: Show additional debugging information +`--encoding`:: Output encoding (default: utf8) +`--connect-timeout`:: Connection timeout in seconds +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Display cqlsh's version information +$ astra db cqlsh version +---- + + diff --git a/modules/commands/pages/astra-db-cqlsh.adoc b/modules/commands/pages/astra-db-cqlsh.adoc new file mode 100644 index 0000000..b439a0e --- /dev/null +++ b/modules/commands/pages/astra-db-cqlsh.adoc @@ -0,0 +1,42 @@ += astra db cqlsh + +[source,shell] +---- +astra db cqlsh [COMMAND] + +---- + + +Connect to your Astra database using cqlsh + + + +== Subcommands + +* xref:astra-db-cqlsh-start.adoc[astra db cqlsh start] +* xref:astra-db-cqlsh-exec.adoc[astra db cqlsh exec] +* xref:astra-db-cqlsh-version.adoc[astra db cqlsh version] +* xref:astra-db-cqlsh-path.adoc[astra db cqlsh path] + + +== Options + + + +== Examples +[source,bash] +---- +# Launch cqlsh for a database +$ astra db cqlsh start my_db + +# Launch cqlsh with a specific keyspace +$ astra db cqlsh start my_db -k my_keyspace + +# Execute a CQL statement +$ astra db cqlsh exec my_db "SELECT * FROM my_keyspace.my_table" + +# Execute a CQL file +$ astra db cqlsh exec my_db -f script.cql +---- + + diff --git a/modules/commands/pages/astra-db-create-cdc.adoc b/modules/commands/pages/astra-db-create-cdc.adoc new file mode 100644 index 0000000..9124c8a --- /dev/null +++ b/modules/commands/pages/astra-db-create-cdc.adoc @@ -0,0 +1,54 @@ += astra db create-cdc + +[source,shell] +---- +astra db create-cdc [-qV] [--if-not-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-k=KEYSPACE] + [-o=FORMAT] --table=TABLE --tenant=TENANT + [--topic-partitions=PARTITIONS] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Create a CDC (Change Data Capture) for a table in a specific keyspace and tenant. + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: Keyspace where the table resides +`--table`:: The table or collection to create CDC for +`--tenant`:: The tenant name +`--topic-partitions`:: Number of topic partitions +`--if-not-exists`:: Will create a new CDC only if none exists +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Create a CDC +$ astra db create-cdc my_db --table my_table --tenant my_tenant + +# Create a CDC with a specific keyspace and topic partitions +$ astra db create-cdc my_db -k my_keyspace --table my_table --tenant my_tenant --topic-partitions 5 + +# Create a CDC without failing if it already exists +$ astra db create-cdc my_db --table my_table --tenant my_tenant --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-db-create-collection.adoc b/modules/commands/pages/astra-db-create-collection.adoc new file mode 100644 index 0000000..204e375 --- /dev/null +++ b/modules/commands/pages/astra-db-create-collection.adoc @@ -0,0 +1,70 @@ += astra db create-collection + +[source,shell] +---- +astra db create-collection [-qV] [--if-not-exists] [--no-input] [--[no-] + spinner] [--dump-logs[=FILE]] -c=COLLECTION + [--color=WHEN] [-d=DIMENSION] + [--default-id=DEFAULT_ID] + [--embedding-key=EMBEDDING_KEY] + [--embedding-model=EMBEDDING_MODEL] + [--embedding-provider=EMBEDDING_PROVIDER] + [-k=KEYSPACE] [-m=METRIC] [-o=FORMAT] + [--indexing-allow=INDEXING_ALLOW[, + INDEXING_ALLOW...]]... [--indexing-deny=INDEXING_DENY + [,INDEXING_DENY...]]... [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Create a new Data API collection in the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-c`, `--collection`:: The collection to use +`--if-not-exists`:: Will create a new collection only if none with same name +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`-d`, `--dimension`:: Dimension of the vector space for this collection +`--default-id`:: Default identifier to use for the collection +`-m`, `--metric`:: Distance metric to use for vector similarity searches +`--indexing-allow`:: List of attributes to add into index (comma separated) +`--indexing-deny`:: List of attributes to remove from index (comma separated) +`--embedding-provider`:: Using Vectorize, embedding provider to use +`--embedding-model`:: Using Vectorize, embedding model to use +`--embedding-key`:: Using Vectorize, embedding key used for shared secret + + +== Examples +[source,bash] +---- +# Create a basic collection +$ astra db create-collection my_db -c my_collection + +# Create a vector collection +$ astra db create-collection my_db -c my_collection --dimension 2048 + +# Create a collection in a non-default keyspace +$ astra db create-collection my_db -k my_keyspace -c my_collection + +# Create a collection without failing if it already exists +$ astra db create-collection my_db -c my_collection --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-db-create-dotenv.adoc b/modules/commands/pages/astra-db-create-dotenv.adoc new file mode 100644 index 0000000..e134528 --- /dev/null +++ b/modules/commands/pages/astra-db-create-dotenv.adoc @@ -0,0 +1,67 @@ += astra db create-dotenv + +[source,shell] +---- +astra db create-dotenv [-qV] [--no-input] [--[no-]overwrite] [--print] [--[no-] + spinner] [--dump-logs[=FILE]] [--color=WHEN] + [--file=FILE] [-k=KEYSPACE] [-o=FORMAT] [-r=REGION] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--keys=KEYS[,KEYS...] [--keys=KEYS[,KEYS...]]... | + --preset=PRESETS[,PRESETS...] [--preset=PRESETS[, + PRESETS...]]...] [DB] + +---- + + +Create a env file to help you connect to your Astra DB instance. + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--print`:: Output the .env file to stdout instead of saving it to the .env file. +`--overwrite`:: Whether to existing duplicate keys in the .env file. If false, the command will attempt to prompt the user before overwriting any existing keys, or fail if it can't. +`--file`:: The file to append the .env content to. If not specified, defaults to .env. If --print is true, the --file option will be used as the initial content; otherwise it will print a new .env file. +`-k`, `--keyspace`:: The keyspace to use. Uses the db's default keyspace if not specified. +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`--keys`:: Comma-separated list of keys to include in the .env file. If not specified, all keys will be included. +`--preset`:: The preset(s) to use for the .env file. If not specified, all keys (or the keys from `--keys`) will be used. + + +== Examples +[source,bash] +---- +# Create a fully-populated .env file, updating the existing one if it exists +$ astra db create-dotenv + +# Create a .env file specifying the keys to include +$ astra db create-dotenv --keys ASTRA_DB_APPLICATION_TOKEN,ASTRA_DB_API_ENDPOINT + +# Create a .env file with a preset specifying the keys to include +$ astra db create-dotenv --preset data_api_client + +# Create a .env file specifying the keyspace and/or region to target +$ astra db create-dotenv -k my_keyspace -r us-east1 + +# Print the .env file to stdout instead of saving it to a file +$ astra db create-dotenv --print + +# Specify the file to create/update +$ astra db create-dotenv -f .env.local +---- + + diff --git a/modules/commands/pages/astra-db-create-keyspace.adoc b/modules/commands/pages/astra-db-create-keyspace.adoc new file mode 100644 index 0000000..2d1c6b1 --- /dev/null +++ b/modules/commands/pages/astra-db-create-keyspace.adoc @@ -0,0 +1,53 @@ += astra db create-keyspace + +[source,shell] +---- +astra db create-keyspace [-qV] [--[no-]async] [--if-not-exists] [--no-input] [-- + [no-]spinner] [--dump-logs[=FILE]] [--color=WHEN] + -k=KEYSPACE [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [DB] + +---- + + +Create a new keyspace in the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`--if-not-exists`:: Don't error if a keyspace with the same name already exists +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Create a new keyspace +$ astra db create-keyspace my_db -k my_keyspace + +# Create a new keyspace without failing if it already exists +$ astra db create-keyspace my_db -k my_keyspace --if-not-exists + +# Create a new keyspace without waiting for the database to become active +$ astra db create-keyspace my_db -k my_keyspace --async +---- + + diff --git a/modules/commands/pages/astra-db-create-region.adoc b/modules/commands/pages/astra-db-create-region.adoc new file mode 100644 index 0000000..d538663 --- /dev/null +++ b/modules/commands/pages/astra-db-create-region.adoc @@ -0,0 +1,52 @@ += astra db create-region + +[source,shell] +---- +astra db create-region [-qV] [--[no-]async] [--if-not-exists] [--no-input] [-- + [no-]spinner] [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] -r=REGION [--timeout=] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] DB + +---- + + +Add a new region to an existing database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use +`--async`:: Do not wait for the database to become active +`--if-not-exists`:: Do not fail if the region already exists +`--timeout`:: How long the command should wait for the database to become active +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Create a region in a database +$ astra db create-region my_db -r us-west-2 + +# Create a region without failing if it already exists +$ astra db create-region my_db -r us-west-2 --if-not-exists + +# Create a region without waiting for the database to become active +$ astra db create-region my_db -r us-west-2 --async +---- + + diff --git a/modules/commands/pages/astra-db-create.adoc b/modules/commands/pages/astra-db-create.adoc new file mode 100644 index 0000000..5e31803 --- /dev/null +++ b/modules/commands/pages/astra-db-create.adoc @@ -0,0 +1,69 @@ += astra db create + +[source,shell] +---- +astra db create [-qV] [--[no-]async] [--no-input] [--non-vector] [--[no-] + spinner] [--dump-logs[=FILE]] [-c=CLOUD] + [--capacity-units=CAPACITY UNITS] [--color=WHEN] [-k=KEYSPACE] + [-o=FORMAT] [-r=REGION] [--tier=TIER] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--if-not-exists | --allow-duplicate-names] DB + +---- + + +Create a new Astra database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`--if-not-exists`:: Don't error if the database already exists +`--allow-duplicate-names`:: Allow multiple databases with the same name +`-r`, `--region`:: Cloud provider region to provision. **Use one of the `astra db list-regions-*` commands to see available regions.** +`-c`, `--cloud`:: The cloud provider where the db should be created. Inferred from the region if not provided. +`-k`, `--keyspace`:: Default keyspace for the database +`--tier`:: Tier to create the database in +`--capacity-units`:: Capacity units to create the database with +`--non-vector`:: Create a classic non-vector database + + +== Examples +[source,bash] +---- +# Create a basic Astra vector database in the 'us-east1' region +$ astra db create my_db --region us-east1 + +# Specify a specific default keyspace for the database +$ astra db create my_db --region us-east1 -k my_keyspace + +# Create a classic non-vector database +$ astra db create my_db --region us-east1 --non-vector + +# Create a database without waiting for it to become active +$ astra db create my_db --async + +# Create a database if it doesn't already exist +$ astra db create my_db --region us-east1 --if-not-exists + +# List available vector database regions for creating a database +$ astra db list-regions-vector +---- + + diff --git a/modules/commands/pages/astra-db-delete-cdc.adoc b/modules/commands/pages/astra-db-delete-cdc.adoc new file mode 100644 index 0000000..3e358b6 --- /dev/null +++ b/modules/commands/pages/astra-db-delete-cdc.adoc @@ -0,0 +1,54 @@ += astra db delete-cdc + +[source,shell] +---- +astra db delete-cdc [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + (--cdc-id=CDC_ID | [-k=KEYSPACE --table=TABLE + --tenant=TENANT]) [DB] + +---- + + +Delete a CDC (Change Data Capture) from the database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--if-exists`:: Do not fail if CDC does not exist +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`--cdc-id`:: The CDC ID to delete +`-k`, `--keyspace`:: The keyspace +`--table`:: The table +`--tenant`:: The tenant name + + +== Examples +[source,bash] +---- +# Delete a CDC by ID +$ astra db delete-cdc my_db --cdc-id abc123 + +# Delete a CDC by table and tenant +$ astra db delete-cdc my_db -k my_keyspace --table my_table --tenant my_tenant + +# Delete a CDC without failing if it doesn't exist +$ astra db delete-cdc my_db --cdc-id abc123 --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-delete-collection.adoc b/modules/commands/pages/astra-db-delete-collection.adoc new file mode 100644 index 0000000..401792c --- /dev/null +++ b/modules/commands/pages/astra-db-delete-collection.adoc @@ -0,0 +1,51 @@ += astra db delete-collection + +[source,shell] +---- +astra db delete-collection [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [-c=COLLECTION] [--color=WHEN] + [-k=KEYSPACE] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Delete an existing Data API collection from the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-c`, `--collection`:: The collection to use +`--if-exists`:: Do not fail if collection does not exist +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Delete a collection +$ astra db delete-collection my_db -c my_collection + +# Delete a collection from a non-default keyspace +$ astra db delete-collection my_db -k my_keyspace -c my_collection + +# Delete a collection without failing if it doesn't exist +$ astra db delete-collection my_db -c my_collection --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-delete-keyspace.adoc b/modules/commands/pages/astra-db-delete-keyspace.adoc new file mode 100644 index 0000000..7ac9f9b --- /dev/null +++ b/modules/commands/pages/astra-db-delete-keyspace.adoc @@ -0,0 +1,53 @@ += astra db delete-keyspace + +[source,shell] +---- +astra db delete-keyspace [-qV] [--[no-]async] [--if-exists] [--no-input] [-- + [no-]spinner] [--dump-logs[=FILE]] [--color=WHEN] + [-k=KEYSPACE] [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [DB] + +---- + + +Delete a keyspace from the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`--if-exists`:: Do not fail if keyspace does not exist +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Delete a keyspace +$ astra db delete-keyspace my_db -k my_keyspace + +# Delete a keyspace without failing if it doesn't exist +$ astra db delete-keyspace my_db -k my_keyspace --if-exists + +# Delete a keyspace without waiting for the database to become active +$ astra db delete-keyspace my_db -k my_keyspace --async +---- + + diff --git a/modules/commands/pages/astra-db-delete-region.adoc b/modules/commands/pages/astra-db-delete-region.adoc new file mode 100644 index 0000000..16638bd --- /dev/null +++ b/modules/commands/pages/astra-db-delete-region.adoc @@ -0,0 +1,52 @@ += astra db delete-region + +[source,shell] +---- +astra db delete-region [-qV] [--[no-]async] [--if-exists] [--no-input] [--[no-] + spinner] [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + -r=REGION [--timeout=] [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] DB + +---- + + +Delete a region from an existing database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use +`--async`:: Do not wait for the database to become active +`--if-exists`:: Do not fail if region does not exist +`--timeout`:: How long the command should wait for the database to become active +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Delete a region from a database +$ astra db delete-region my_db -r us-west-2 + +# Delete a region without failing if it doesn't exist +$ astra db delete-region my_db -r us-west-2 --if-exists + +# Delete a region without waiting for the database to become active +$ astra db delete-region my_db -r us-west-2 --async +---- + + diff --git a/modules/commands/pages/astra-db-delete-table.adoc b/modules/commands/pages/astra-db-delete-table.adoc new file mode 100644 index 0000000..a85cee5 --- /dev/null +++ b/modules/commands/pages/astra-db-delete-table.adoc @@ -0,0 +1,51 @@ += astra db delete-table + +[source,shell] +---- +astra db delete-table [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-k=KEYSPACE] + [-o=FORMAT] [-t=TABLE] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Delete an existing table from the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-t`, `--table`:: The table to use +`--if-exists`:: Do not fail if table does not exist +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Delete a table +$ astra db delete-table my_db -t my_table + +# Delete a table from a non-default keyspace +$ astra db delete-table my_db -k my_keyspace -t my_table + +# Delete a table without failing if it doesn't exist +$ astra db delete-table my_db -t my_table --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-delete.adoc b/modules/commands/pages/astra-db-delete.adoc new file mode 100644 index 0000000..1145435 --- /dev/null +++ b/modules/commands/pages/astra-db-delete.adoc @@ -0,0 +1,55 @@ += astra db delete + +[source,shell] +---- +astra db delete [-qV] [--[no-]async] [--if-exists] [--no-input] [--[no-] + spinner] [--yes] [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] [--timeout=] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Delete an existing Astra database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--if-exists`:: Do not fail if database does not exist +`--yes`:: Force deletion of database without prompting +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Delete an existing Astra database +$ astra db delete my_db + +# Delete an existing Astra database without confirmation (required for non-interactive shells) +$ astra db delete my_db --yes + +# Delete an existing Astra database without failing if it does not exist +$ astra db delete my_db --if-exists + +# Delete an existing Astra database without waiting for complete termination +$ astra db delete my_db --async +---- + + diff --git a/modules/commands/pages/astra-db-describe-collection.adoc b/modules/commands/pages/astra-db-describe-collection.adoc new file mode 100644 index 0000000..7bfc97e --- /dev/null +++ b/modules/commands/pages/astra-db-describe-collection.adoc @@ -0,0 +1,47 @@ += astra db describe-collection + +[source,shell] +---- +astra db describe-collection [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [-c=COLLECTION] [--color=WHEN] + [-k=KEYSPACE] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Describe an existing Data API collection with detailed information including vector configuration and indexing options + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-c`, `--collection`:: The collection to use +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Describe a collection in the default keyspace +$ astra db describe-collection my_db -c my_collection + +# Describe a collection in a specific keyspace +$ astra db describe-collection my_db -k my_keyspace -c my_collection +---- + + diff --git a/modules/commands/pages/astra-db-describe-table.adoc b/modules/commands/pages/astra-db-describe-table.adoc new file mode 100644 index 0000000..8071123 --- /dev/null +++ b/modules/commands/pages/astra-db-describe-table.adoc @@ -0,0 +1,47 @@ += astra db describe-table + +[source,shell] +---- +astra db describe-table [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-k=KEYSPACE] [-o=FORMAT] + [-t=TABLE] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +Describe an existing table with detailed information including columns and primary key structure + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-t`, `--table`:: The table to use +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Describe a table in the default keyspace +$ astra db describe-table my_db -t my_table + +# Describe a table in a specific keyspace +$ astra db describe-table my_db -k my_keyspace -t my_table +---- + + diff --git a/modules/commands/pages/astra-db-download-scb.adoc b/modules/commands/pages/astra-db-download-scb.adoc new file mode 100644 index 0000000..6461e47 --- /dev/null +++ b/modules/commands/pages/astra-db-download-scb.adoc @@ -0,0 +1,50 @@ += astra db download-scb + +[source,shell] +---- +astra db download-scb [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-f=DEST] [-o=FORMAT] [-r=REGION] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [DB] + +---- + + +Download secure connect bundle for a database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The cloud provider region to target. Defaults to the default region of the database. +`-f`, `--file`:: Destination file. Defaults to `~/.astra/scb/scb__.zip` +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Download the SCB for a database, targeting the default region +$ astra db download-scb my_db + +# Download the SCB for a database, targeting a specific region +$ astra db download-scb my_db -r us-east1 + +# Download the SCB for a database, saving it to a specific file +$ astra db download-scb my_db -f /path/to/scb.zip +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-count.adoc b/modules/commands/pages/astra-db-dsbulk-count.adoc new file mode 100644 index 0000000..b897529 --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-count.adoc @@ -0,0 +1,53 @@ += astra db dsbulk count + +[source,shell] +---- +astra db dsbulk count [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [--encoding=ENCODING] [-k=KEYSPACE] + [--log-dir=DIRECTORY] [--max-concurrent-queries=QUERIES] + [-o=FORMAT] [-query=QUERY] [-r=REGION] [-t=TABLE] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--dsbulk-config=CONFIG_FILE | -F=FLAGS [-F=FLAGS]...] + [DB] + +---- + + +Count items for a table, a query + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: Keyspace used for loading or unloading data +`-t`, `--table`:: Table used for loading or unloading data. +`--encoding`:: The file name format to use when writing. This setting is ignored when reading and for non-file URLs +`--max-concurrent-queries`:: The maximum number of concurrent queries that should be carried in parallel +`--log-dir`:: Log directory for dsbulk operations +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`-query`, `--schema.query`:: Optional query to unload or count +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`--dsbulk-config`:: Configuration file for DSBulk loader options +`-F`, `--dsbulk-flags`:: Additional flags to pass to DSBulk loader + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-load.adoc b/modules/commands/pages/astra-db-dsbulk-load.adoc new file mode 100644 index 0000000..93e3b2c --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-load.adoc @@ -0,0 +1,62 @@ += astra db dsbulk load + +[source,shell] +---- +astra db dsbulk load [-qV] [--allow-missing-fields] [--dry-run] [--header] + [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [--delimiter=DELIMITER] + [--encoding=ENCODING] [-k=KEYSPACE] [--log-dir=DIRECTORY] + [-m=MAPPING] [--max-concurrent-queries=QUERIES] + [--max-errors=COUNT] [-o=FORMAT] [-r=REGION] + [--skip-records=COUNT] [-t=TABLE] --url=URL [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--dsbulk-config=CONFIG_FILE | -F=FLAGS [-F=FLAGS]...] [DB] + +---- + + +Load data leveraging DSBulk + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: Keyspace used for loading or unloading data +`-t`, `--table`:: Table used for loading or unloading data. +`--encoding`:: The file name format to use when writing. This setting is ignored when reading and for non-file URLs +`--max-concurrent-queries`:: The maximum number of concurrent queries that should be carried in parallel +`--log-dir`:: Log directory for dsbulk operations +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`--url`:: File location to load data +`--delimiter`:: Character(s) use as field delimiter +`-m`, `--schema.mapping`:: Field-to-column mapping to use +`--header`:: Read, Write Header in input file +`--skip-records`:: Lines to skip before reading +`--max-errors`:: Maximum number of errors before aborting the operation +`--dry-run`:: Enable or disable dry-run mode +`--allow-missing-fields`:: Ease the mapping +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`--dsbulk-config`:: Configuration file for DSBulk loader options +`-F`, `--dsbulk-flags`:: Additional flags to pass to DSBulk loader + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-path.adoc b/modules/commands/pages/astra-db-dsbulk-path.adoc new file mode 100644 index 0000000..e03ffee --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-path.adoc @@ -0,0 +1,47 @@ += astra db dsbulk path + +[source,shell] +---- +astra db dsbulk path [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Get the path to the currently installed dsbulk executable + + + + + +== Options + +`--if-exists`:: Only return path if dsbulk exists, don't install automatically +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the path to the dsbulk executable +$ astra db dsbulk path + +# Use the dsbulk exe to run a custom command +$ $(astra db dsbulk path) --help + +# Get path only if dsbulk exists, don't install +$ astra db dsbulk path --if-exists +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-unload.adoc b/modules/commands/pages/astra-db-dsbulk-unload.adoc new file mode 100644 index 0000000..0d80b5e --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-unload.adoc @@ -0,0 +1,62 @@ += astra db dsbulk unload + +[source,shell] +---- +astra db dsbulk unload [-qV] [--header] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [--delimiter=DELIMITER] [--encoding=ENCODING] + [-k=KEYSPACE] [--log-dir=DIRECTORY] [-m=MAPPING] + [--max-concurrent-queries=QUERIES] [--max-errors=COUNT] + [-o=FORMAT] [-query=QUERY] [-r=REGION] + [--skip-records=COUNT] [-t=TABLE] [--url=URL] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [--dsbulk-config=CONFIG_FILE | -F=FLAGS [-F=FLAGS]...] + [DB] + +---- + + +Unload data leveraging DSBulk + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: Keyspace used for loading or unloading data +`-t`, `--table`:: Table used for loading or unloading data. +`--encoding`:: The file name format to use when writing. This setting is ignored when reading and for non-file URLs +`--max-concurrent-queries`:: The maximum number of concurrent queries that should be carried in parallel +`--log-dir`:: Log directory for dsbulk operations +`-r`, `--region`:: The region to use. Uses the db's default region if not specified. +`--url`:: The URL or path of the resource(s) to read from or write to +`--delimiter`:: Character(s) use as field delimiter +`-m`, `--schema.mapping`:: Field-to-column mapping to use +`--header`:: Enable or disable whether the files begin with a header line +`--skip-records`:: Number of records to skip from each input file before parsing +`--max-errors`:: Maximum number of errors to tolerate before aborting the operation +`-query`, `--schema.query`:: Optional query to unload or count +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`--dsbulk-config`:: Configuration file for DSBulk loader options +`-F`, `--dsbulk-flags`:: Additional flags to pass to DSBulk loader + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk-version.adoc b/modules/commands/pages/astra-db-dsbulk-version.adoc new file mode 100644 index 0000000..95aed6d --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk-version.adoc @@ -0,0 +1,40 @@ += astra db dsbulk version + +[source,shell] +---- +astra db dsbulk version [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Display the currently installed dsbulk's version + + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Display dsbulk's version information +$ astra db dsbulk version +---- + + diff --git a/modules/commands/pages/astra-db-dsbulk.adoc b/modules/commands/pages/astra-db-dsbulk.adoc new file mode 100644 index 0000000..82df9fc --- /dev/null +++ b/modules/commands/pages/astra-db-dsbulk.adoc @@ -0,0 +1,33 @@ += astra db dsbulk + +[source,shell] +---- +astra db dsbulk [COMMAND] + +---- + + +Use dsbulk to interface with your Astra DB database + + + +== Subcommands + +* xref:astra-db-dsbulk-count.adoc[astra db dsbulk count] +* xref:astra-db-dsbulk-load.adoc[astra db dsbulk load] +* xref:astra-db-dsbulk-unload.adoc[astra db dsbulk unload] +* xref:astra-db-dsbulk-version.adoc[astra db dsbulk version] +* xref:astra-db-dsbulk-path.adoc[astra db dsbulk path] + + +== Options + + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-db-get-endpoint-api.adoc b/modules/commands/pages/astra-db-get-endpoint-api.adoc new file mode 100644 index 0000000..defa740 --- /dev/null +++ b/modules/commands/pages/astra-db-get-endpoint-api.adoc @@ -0,0 +1,46 @@ += astra db get-endpoint-api + +[source,shell] +---- +astra db get-endpoint-api [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-r=REGION] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +Get the API endpoint to interact with the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the API endpoint for the database +$ astra db get-endpoint-api mydb + +# Get the API endpoint for the database in a specific region +$ astra db get-endpoint-api mydb --region us-east1 +---- + + diff --git a/modules/commands/pages/astra-db-get-endpoint-playground.adoc b/modules/commands/pages/astra-db-get-endpoint-playground.adoc new file mode 100644 index 0000000..786161b --- /dev/null +++ b/modules/commands/pages/astra-db-get-endpoint-playground.adoc @@ -0,0 +1,46 @@ += astra db get-endpoint-playground + +[source,shell] +---- +astra db get-endpoint-playground [-qV] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] [-r=REGION] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Get the GraphQL Playground for the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the GraphQL Playground for the database +$ astra db get-endpoint-playground mydb + +# Get the GraphQL Playground for the database in a specific region +$ astra db get-endpoint-playground mydb --region us-east1 +---- + + diff --git a/modules/commands/pages/astra-db-get-endpoint-swagger.adoc b/modules/commands/pages/astra-db-get-endpoint-swagger.adoc new file mode 100644 index 0000000..f3d0e34 --- /dev/null +++ b/modules/commands/pages/astra-db-get-endpoint-swagger.adoc @@ -0,0 +1,46 @@ += astra db get-endpoint-swagger + +[source,shell] +---- +astra db get-endpoint-swagger [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-r=REGION] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +Get the SwaggerUI endpoint for the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-r`, `--region`:: The region to use +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the SwaggerUI endpoint for the database +$ astra db get-endpoint-swagger mydb + +# Get the SwaggerUI endpoint for the database in a specific region +$ astra db get-endpoint-swagger mydb --region us-east1 +---- + + diff --git a/modules/commands/pages/astra-db-get.adoc b/modules/commands/pages/astra-db-get.adoc new file mode 100644 index 0000000..bd71a44 --- /dev/null +++ b/modules/commands/pages/astra-db-get.adoc @@ -0,0 +1,48 @@ += astra db get + +[source,shell] +---- +astra db get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-k=KEY] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Get information about a specific database. + +== Aliases + +`astra db describe` + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--key`:: Specific database attribute to retrieve +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get information about a specific database +$ astra db get my_db + +# Get a specific attribute of a database +$ astra db get my_db --key id +---- + + diff --git a/modules/commands/pages/astra-db-list-cdcs.adoc b/modules/commands/pages/astra-db-list-cdcs.adoc new file mode 100644 index 0000000..c8669b5 --- /dev/null +++ b/modules/commands/pages/astra-db-list-cdcs.adoc @@ -0,0 +1,41 @@ += astra db list-cdcs + +[source,shell] +---- +astra db list-cdcs [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +List all CDC (Change Data Capture) connections for the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all CDCs in a database +$ astra db list-cdcs my_db +---- + + diff --git a/modules/commands/pages/astra-db-list-clouds.adoc b/modules/commands/pages/astra-db-list-clouds.adoc new file mode 100644 index 0000000..7c8de01 --- /dev/null +++ b/modules/commands/pages/astra-db-list-clouds.adoc @@ -0,0 +1,40 @@ += astra db list-clouds + +[source,shell] +---- +astra db list-clouds [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List all cloud providers with regions available for Astra DB + + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all available cloud providers +$ astra db list-clouds +---- + + diff --git a/modules/commands/pages/astra-db-list-collections.adoc b/modules/commands/pages/astra-db-list-collections.adoc new file mode 100644 index 0000000..2924770 --- /dev/null +++ b/modules/commands/pages/astra-db-list-collections.adoc @@ -0,0 +1,50 @@ += astra db list-collections + +[source,shell] +---- +astra db list-collections [-aqV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-k=KEYSPACE] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +List the collections in the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-a`, `--all`:: List collections in all keyspaces +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all collections in the default keyspace +$ astra db list-collections my_db + +# List all collections in a specific keyspace +$ astra db list-collections my_db -k my_keyspace + +# List all collections in all keyspaces +$ astra db list-collections my_db --all +---- + + diff --git a/modules/commands/pages/astra-db-list-embedding-providers.adoc b/modules/commands/pages/astra-db-list-embedding-providers.adoc new file mode 100644 index 0000000..6e6d371 --- /dev/null +++ b/modules/commands/pages/astra-db-list-embedding-providers.adoc @@ -0,0 +1,42 @@ += astra db list-embedding-providers + +[source,shell] +---- +astra db list-embedding-providers [-qV] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Find all available embedding providers for a given database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Find all available embedding providers for a database +$ astra db list-embedding-providers my_db +---- + + diff --git a/modules/commands/pages/astra-db-list-keyspaces.adoc b/modules/commands/pages/astra-db-list-keyspaces.adoc new file mode 100644 index 0000000..501c82c --- /dev/null +++ b/modules/commands/pages/astra-db-list-keyspaces.adoc @@ -0,0 +1,41 @@ += astra db list-keyspaces + +[source,shell] +---- +astra db list-keyspaces [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +List all keyspaces in the specified database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all keyspaces in a database +$ astra db list-keyspaces my_db +---- + + diff --git a/modules/commands/pages/astra-db-list-regions-classic.adoc b/modules/commands/pages/astra-db-list-regions-classic.adoc new file mode 100644 index 0000000..db1c059 --- /dev/null +++ b/modules/commands/pages/astra-db-list-regions-classic.adoc @@ -0,0 +1,54 @@ += astra db list-regions-classic + +[source,shell] +---- +astra db list-regions-classic [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-c=FILTER[, + FILTER...]]... [-f=FILTER[,FILTER...]]... + [-z=FILTER[,FILTER...]]... [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +List all available regions for classic Astra DB databases + + + + + +== Options + +`-f`, `--filter`:: Comma-separated case-insensitive partial-match filters on the region name +`-c`, `--cloud`:: Comma-separated list of cloud providers to filter on +`-z`, `--zone`:: Comma-separated list of zones to include +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all available regions for classic Astra DB databases +$ astra db list-regions-classic + +# Filter by cloud provider +$ astra db list-regions-classic --cloud AWS,GCP + +# Filter by partial region name +$ astra db list-regions-classic --filter us-,ca- + +# Filter by zone +$ astra db list-regions-classic --zone Europe +---- + + diff --git a/modules/commands/pages/astra-db-list-regions-serverless.adoc b/modules/commands/pages/astra-db-list-regions-serverless.adoc new file mode 100644 index 0000000..a7ff9a7 --- /dev/null +++ b/modules/commands/pages/astra-db-list-regions-serverless.adoc @@ -0,0 +1,55 @@ += astra db list-regions-serverless + +[source,shell] +---- +astra db list-regions-serverless [-qV] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] [-c=FILTER[,FILTER...]]... + [-f=FILTER[,FILTER...]]... [-z=FILTER[, + FILTER...]]... [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List all available regions for serverless Astra DB databases + + + + + +== Options + +`-f`, `--filter`:: Comma-separated case-insensitive partial-match filters on the region name +`-c`, `--cloud`:: Comma-separated list of cloud providers to filter on +`-z`, `--zone`:: Comma-separated list of zones to include +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all available regions for serverless Astra DB databases +$ astra db list-regions-serverless + +# Filter by cloud provider +$ astra db list-regions-serverless --cloud AWS,GCP + +# Filter by partial region name +$ astra db list-regions-serverless --filter us-,ca- + +# Filter by zone +$ astra db list-regions-serverless --zone Europe +---- + + diff --git a/modules/commands/pages/astra-db-list-regions-vector.adoc b/modules/commands/pages/astra-db-list-regions-vector.adoc new file mode 100644 index 0000000..4dd9fb8 --- /dev/null +++ b/modules/commands/pages/astra-db-list-regions-vector.adoc @@ -0,0 +1,54 @@ += astra db list-regions-vector + +[source,shell] +---- +astra db list-regions-vector [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-c=FILTER[, + FILTER...]]... [-f=FILTER[,FILTER...]]... + [-z=FILTER[,FILTER...]]... [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] + +---- + + +List all available regions for vector Astra DB databases + + + + + +== Options + +`-f`, `--filter`:: Comma-separated case-insensitive partial-match filters on the region name +`-c`, `--cloud`:: Comma-separated list of cloud providers to filter on +`-z`, `--zone`:: Comma-separated list of zones to include +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all available regions for vector Astra DB databases +$ astra db list-regions-vector + +# Filter by cloud provider +$ astra db list-regions-vector --cloud AWS,GCP + +# Filter by partial region name +$ astra db list-regions-vector --filter us-,ca- + +# Filter by zone +$ astra db list-regions-vector --zone Europe +---- + + diff --git a/modules/commands/pages/astra-db-list-regions.adoc b/modules/commands/pages/astra-db-list-regions.adoc new file mode 100644 index 0000000..07115da --- /dev/null +++ b/modules/commands/pages/astra-db-list-regions.adoc @@ -0,0 +1,41 @@ += astra db list-regions + +[source,shell] +---- +astra db list-regions [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +List the regions for the given database + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all regions for the database +$ astra db list-regions my_db +---- + + diff --git a/modules/commands/pages/astra-db-list-tables.adoc b/modules/commands/pages/astra-db-list-tables.adoc new file mode 100644 index 0000000..3ac0c84 --- /dev/null +++ b/modules/commands/pages/astra-db-list-tables.adoc @@ -0,0 +1,49 @@ += astra db list-tables + +[source,shell] +---- +astra db list-tables [-aqV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-k=KEYSPACE] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +List the tables in the specified database and keyspace + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-a`, `--all`:: List tables in all keyspaces +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all tables in the default keyspace +$ astra db list-tables my_db + +# List all tables in a specific keyspace +$ astra db list-tables my_db -k my_keyspace + +# List all tables in all keyspaces +$ astra db list-tables my_db --all +---- + + diff --git a/modules/commands/pages/astra-db-list.adoc b/modules/commands/pages/astra-db-list.adoc new file mode 100644 index 0000000..1151e69 --- /dev/null +++ b/modules/commands/pages/astra-db-list.adoc @@ -0,0 +1,47 @@ += astra db list + +[source,shell] +---- +astra db list [-qvV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List your non-terminated Astra databases. + +== Aliases + +`astra db` + + + + +== Options + +`-v`, `--vector`:: Only show vector-enabled databases +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all your Astra databases +$ astra db list + +# List only vector-enabled Astra databases +$ astra db list --vector +---- + + diff --git a/modules/commands/pages/astra-db-resume.adoc b/modules/commands/pages/astra-db-resume.adoc new file mode 100644 index 0000000..4b98910 --- /dev/null +++ b/modules/commands/pages/astra-db-resume.adoc @@ -0,0 +1,46 @@ += astra db resume + +[source,shell] +---- +astra db resume [-qV] [--[no-]async] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Resume a database that is in a stopped state. If the database is already active, no action is taken. + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Resume a database +$ astra db resume my_db + +# Resume a database, without waiting for it to become active +$ astra db resume my_db --async +---- + + diff --git a/modules/commands/pages/astra-db-status.adoc b/modules/commands/pages/astra-db-status.adoc new file mode 100644 index 0000000..0076c92 --- /dev/null +++ b/modules/commands/pages/astra-db-status.adoc @@ -0,0 +1,41 @@ += astra db status + +[source,shell] +---- +astra db status [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Get the current status of a database. + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the status of a database +$ astra db status my_db +---- + + diff --git a/modules/commands/pages/astra-db-truncate-collection.adoc b/modules/commands/pages/astra-db-truncate-collection.adoc new file mode 100644 index 0000000..9cc056f --- /dev/null +++ b/modules/commands/pages/astra-db-truncate-collection.adoc @@ -0,0 +1,47 @@ += astra db truncate-collection + +[source,shell] +---- +astra db truncate-collection [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [-c=COLLECTION] [--color=WHEN] + [-k=KEYSPACE] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] [DB] + +---- + + +Atomically delete all documents in a Data API collection + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-c`, `--collection`:: The collection to use +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Truncate a collection in the default keyspace +$ astra db truncate-collection my_db -c my_collection + +# Truncate a collection in a specific keyspace +$ astra db truncate-collection my_db -k my_keyspace -c my_collection +---- + + diff --git a/modules/commands/pages/astra-db-truncate-table.adoc b/modules/commands/pages/astra-db-truncate-table.adoc new file mode 100644 index 0000000..8cb901f --- /dev/null +++ b/modules/commands/pages/astra-db-truncate-table.adoc @@ -0,0 +1,47 @@ += astra db truncate-table + +[source,shell] +---- +astra db truncate-table [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-k=KEYSPACE] [-o=FORMAT] + [-t=TABLE] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [DB] + +---- + + +Atomically delete all rows in a table + + + + + +== Options + +`DB`:: The name or ID of the Astra database to operate on +`-k`, `--keyspace`:: The keyspace to use +`-t`, `--table`:: The table to use +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Truncate a table in the default keyspace +$ astra db truncate-table my_db -t my_table + +# Truncate a table in a specific keyspace +$ astra db truncate-table my_db -k my_keyspace -t my_table +---- + + diff --git a/modules/commands/pages/astra-db.adoc b/modules/commands/pages/astra-db.adoc index 1d5d4ad..46f0f06 100644 --- a/modules/commands/pages/astra-db.adoc +++ b/modules/commands/pages/astra-db.adoc @@ -1,99 +1,78 @@ = astra db -Manage your Astra databases. - -== Usage - -[source,console] +[source,shell] ---- -astra db [-hqv] [--[no-]color] [--no-input] [--[no-]spinner] [--vector] - [--dump-logs[=FILE]] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | - [--token=TOKEN [--env=ENV]]] [COMMAND] +astra db [-qvV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [COMMAND] + ---- + +Manage your Astra databases + + +**Alias of `astra db list`** + + +== Subcommands + +* xref:astra-db-list.adoc[astra db list] +* xref:astra-db-get.adoc[astra db get] +* xref:astra-db-create.adoc[astra db create] +* xref:astra-db-delete.adoc[astra db delete] +* xref:astra-db-status.adoc[astra db status] +* xref:astra-db-cqlsh.adoc[astra db cqlsh] +* xref:astra-db-dsbulk.adoc[astra db dsbulk] +* xref:astra-db-create-dotenv.adoc[astra db create-dotenv] +* xref:astra-db-download-scb.adoc[astra db download-scb] +* xref:astra-db-resume.adoc[astra db resume] +* xref:astra-db-list-keyspaces.adoc[astra db list-keyspaces] +* xref:astra-db-create-keyspace.adoc[astra db create-keyspace] +* xref:astra-db-delete-keyspace.adoc[astra db delete-keyspace] +* xref:astra-db-list-collections.adoc[astra db list-collections] +* xref:astra-db-create-collection.adoc[astra db create-collection] +* xref:astra-db-describe-collection.adoc[astra db describe-collection] +* xref:astra-db-delete-collection.adoc[astra db delete-collection] +* xref:astra-db-truncate-collection.adoc[astra db truncate-collection] +* xref:astra-db-list-tables.adoc[astra db list-tables] +* xref:astra-db-describe-table.adoc[astra db describe-table] +* xref:astra-db-delete-table.adoc[astra db delete-table] +* xref:astra-db-truncate-table.adoc[astra db truncate-table] +* xref:astra-db-list-embedding-providers.adoc[astra db list-embedding-providers] +* xref:astra-db-list-cdcs.adoc[astra db list-cdcs] +* xref:astra-db-create-cdc.adoc[astra db create-cdc] +* xref:astra-db-delete-cdc.adoc[astra db delete-cdc] +* xref:astra-db-create-region.adoc[astra db create-region] +* xref:astra-db-delete-region.adoc[astra db delete-region] +* xref:astra-db-list-regions.adoc[astra db list-regions] +* xref:astra-db-list-regions-classic.adoc[astra db list-regions-classic] +* xref:astra-db-list-regions-serverless.adoc[astra db list-regions-serverless] +* xref:astra-db-list-regions-vector.adoc[astra db list-regions-vector] +* xref:astra-db-list-clouds.adoc[astra db list-clouds] +* xref:astra-db-get-endpoint-swagger.adoc[astra db get-endpoint-swagger] +* xref:astra-db-get-endpoint-api.adoc[astra db get-endpoint-api] +* xref:astra-db-get-endpoint-playground.adoc[astra db get-endpoint-playground] + + == Options -`-cf`, `--config-file=PATH`:: -The astrarc file to use (default: ~/.astrarc) - -`--[no-]color`:: -Force colored output - -`--dump-logs[=FILE]`:: -Write all logs to an optionally specified file (default: ~/.astra/logs/.log) - -`--env=ENV`:: -Override the target astra environment - -`-h`, `--help`:: -Show this help message and exit. - -`--no-input`:: -Never ask for user input (e.g. confirmation prompts) - -`-o`, `--output=FORMAT`:: -One of: human, json, csv - -`-p`, `--profile=NAME`:: -The astrarc profile to use - -`-q`, `--quiet`:: -Suppress informational output - -`--[no-]spinner`:: -Enable/disable the loading spinner - -`--token=TOKEN`:: -Override the default astra token - -`-v`, `--verbose`:: -Enable verbose logging output - -`--vector`:: -Only show vector-enabled databases - -== Commands - -* list -* get, describe -* create -* delete -* status -* cqlsh -* dsbulk -* create-dotenv -* download-scb -* resume -* list-keyspaces -* create-keyspace -* delete-keyspace -* list-collections -* create-collection -* describe-collection -* delete-collection -* truncate-collection -* list-tables -* describe-table -* delete-table -* truncate-table -* list-embedding-providers -* list-cdcs -* create-cdc -* delete-cdc -* create-region -* delete-region -* list-regions -* list-regions-classic -* list-regions-serverless -* list-regions-vector -* list-clouds -* get-endpoint-swagger -* get-endpoint-api -* get-endpoint-playground +`-v`, `--vector`:: Only show vector-enabled databases +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment -== Examples -[source,console] +== Examples +[source,bash] ---- # List all your Astra databases $ astra db @@ -101,3 +80,5 @@ $ astra db # List only vector-enabled Astra databases $ astra db --vector ---- + + diff --git a/modules/commands/pages/astra-nuke.adoc b/modules/commands/pages/astra-nuke.adoc index 01a94ad..62a0cc6 100644 --- a/modules/commands/pages/astra-nuke.adoc +++ b/modules/commands/pages/astra-nuke.adoc @@ -1 +1,59 @@ -= astra nuke \ No newline at end of file += astra nuke + +[source,shell] +---- +astra nuke [-qVy] [--dry-run] [--no-input] [--[no-]preserve-astrarc] [--[no-] + spinner] [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + +---- + + +Entirely delete Astra CLI from your system + +This command may be used to delete any files associated with Astra CLI, including: + + * The home folder, + + * The ``.astrarc`` file, + + * and the binary itself. + +This will also detect any shell rc files which need ``astra``-related lines removed. + +**Note:** Depending on how Astra CLI was installed, the binary itself may need to be deleted manually. In such cases, instructions will be provided in the command output. + + + + + +== Options + +`--dry-run`:: Simulate the nuke operation without deleting any files +`--preserve-astrarc`:: Preserve the ``.astrarc`` file in your home directory +`-y`, `--yes`:: Whether to nuke without confirmation (if not a dry run) +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file + + +== Examples +[source,bash] +---- +# Nuke Astra CLI from your system +$ astra nuke + +# Perform a dry run of the nuke operation +$ astra nuke --dry-run + +# Nuke Astra CLI without confirmation +$ astra nuke --yes + +# Nuke Astra CLI but preserve the ``.astrarc`` file +$ astra nuke --preserve-astrarc +---- + + diff --git a/modules/commands/pages/astra-org-get.adoc b/modules/commands/pages/astra-org-get.adoc new file mode 100644 index 0000000..6ed144d --- /dev/null +++ b/modules/commands/pages/astra-org-get.adoc @@ -0,0 +1,50 @@ += astra org get + +[source,shell] +---- +astra org get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Get your organization's information + +The ``--token`` flag is handy to quickly get information about another organization. + +Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. + +== Aliases + +`astra org` + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get your organization's information +$ astra org + +# Get information about another organization +$ astra org get --token AstraCS:... +---- + + diff --git a/modules/commands/pages/astra-org-id.adoc b/modules/commands/pages/astra-org-id.adoc new file mode 100644 index 0000000..27620be --- /dev/null +++ b/modules/commands/pages/astra-org-id.adoc @@ -0,0 +1,40 @@ += astra org id + +[source,shell] +---- +astra org id [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Get your organization's ID + + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get your organization's ID +$ astra org id +---- + + diff --git a/modules/commands/pages/astra-org-name.adoc b/modules/commands/pages/astra-org-name.adoc new file mode 100644 index 0000000..e4482a6 --- /dev/null +++ b/modules/commands/pages/astra-org-name.adoc @@ -0,0 +1,40 @@ += astra org name + +[source,shell] +---- +astra org name [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Get your organization's name + + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get your organization's name +$ astra org name +---- + + diff --git a/modules/commands/pages/astra-org.adoc b/modules/commands/pages/astra-org.adoc index db897a7..7b0cea8 100644 --- a/modules/commands/pages/astra-org.adoc +++ b/modules/commands/pages/astra-org.adoc @@ -1 +1,54 @@ -= astra org \ No newline at end of file += astra org + +[source,shell] +---- +astra org [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [COMMAND] + +---- + + +Get organization information + +The ``--token`` flag is handy to quickly get information about another organization. + +Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. + + +**Alias of `astra org get`** + + +== Subcommands + +* xref:astra-org-get.adoc[astra org get] +* xref:astra-org-id.adoc[astra org id] +* xref:astra-org-name.adoc[astra org name] + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get your organization's information +$ astra org + +# Get information about another organization +$ astra org get --token AstraCS:... +---- + + diff --git a/modules/commands/pages/astra-pcu-associate.adoc b/modules/commands/pages/astra-pcu-associate.adoc new file mode 100644 index 0000000..6607713 --- /dev/null +++ b/modules/commands/pages/astra-pcu-associate.adoc @@ -0,0 +1,47 @@ += astra pcu associate + +[source,shell] +---- +astra pcu associate [-qV] [--if-not-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + GROUP TARGET + +---- + + +Associate a PCU group to a datacenter + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to operate on +`TARGET`:: PCU association target (database name/id or datacenter id) +`--if-not-exists`:: Don't error if the association already exists +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Associate a specific datacenter to a PCU group +$ astra pcu associate my_pcu ee6991af-7783-4de9-8da0-c7fa250c89e2-1 + +# Associate a database with a single datacenter to a PCU group +$ astra pcu associate my_pcu my_database +---- + + diff --git a/modules/commands/pages/astra-pcu-create.adoc b/modules/commands/pages/astra-pcu-create.adoc new file mode 100644 index 0000000..0477497 --- /dev/null +++ b/modules/commands/pages/astra-pcu-create.adoc @@ -0,0 +1,56 @@ += astra pcu create + +[source,shell] +---- +astra pcu create [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [-c=CLOUD] [--color=WHEN] [-d=DESC] [-it=TYPE] [--max=MAX] + [--min=MIN] [-o=FORMAT] [-pt=TYPE] [-r=REGION] + [--reserved=RESERVED] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [--if-not-exists | --allow-duplicate-names] GROUP + +---- + + +Create a new PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to operate on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`--if-not-exists`:: Don't error if the pcu already exists +`--allow-duplicate-names`:: Allow multiple pcus with the same name +`-c`, `--cloud`:: Cloud provider this PCU will work in +`-r`, `--region`:: Cloud region this PCU will work in. **Use one of the `astra db list-regions-*` commands to see available regions.** +`-d`, `--description`:: Optional description for the PCU group +`-it`, `--instance-type`:: Cache type for the PCU group +`-pt`, `--provision-type`:: Provision type for the PCU group +`--min`:: Minimum capacity units for the PCU group +`--max`:: Maximum capacity units for the PCU group +`--reserved`:: Reserved capacity units for the PCU group + + +== Examples +[source,bash] +---- +# Create a basic pcu group +$ astra pcu create my_pcu -c AWS -r us-west-2 + +# Create a pcu group if it doesn't already exist +$ astra pcu create my_pcu --region us-east1 --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-pcu-delete.adoc b/modules/commands/pages/astra-pcu-delete.adoc new file mode 100644 index 0000000..992cdf7 --- /dev/null +++ b/modules/commands/pages/astra-pcu-delete.adoc @@ -0,0 +1,49 @@ += astra pcu delete + +[source,shell] +---- +astra pcu delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] [--yes] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Delete an existing Pcu group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`--if-exists`:: Do not fail if PCU group does not exist +`--yes`:: Force deletion of PCU group without prompting +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Delete an existing Pcu group +$ astra pcu delete my_pcu + +# Delete an existing Pcu group without confirmation (required for non-interactive shells) +$ astra pcu delete my_pcu --yes + +# Delete an existing Pcu group without failing if it does not exist +$ astra pcu delete my_pcu --if-exists +---- + + diff --git a/modules/commands/pages/astra-pcu-disassociate.adoc b/modules/commands/pages/astra-pcu-disassociate.adoc new file mode 100644 index 0000000..e24ddf4 --- /dev/null +++ b/modules/commands/pages/astra-pcu-disassociate.adoc @@ -0,0 +1,47 @@ += astra pcu disassociate + +[source,shell] +---- +astra pcu disassociate [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + GROUP TARGET + +---- + + +Disassociate a PCU group to a datacenter + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to operate on +`TARGET`:: PCU association target (database name/id or datacenter id) +`--if-exists`:: Don't error if the association doesn't exist +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Disassociate a specific datacenter from a PCU group +$ astra pcu disassociate my_pcu ee6991af-7783-4de9-8da0-c7fa250c89e2-1 + +# Disassociate a database with a single datacenter from a PCU group +$ astra pcu disassociate my_pcu my_database +---- + + diff --git a/modules/commands/pages/astra-pcu-get.adoc b/modules/commands/pages/astra-pcu-get.adoc new file mode 100644 index 0000000..b19cb10 --- /dev/null +++ b/modules/commands/pages/astra-pcu-get.adoc @@ -0,0 +1,48 @@ += astra pcu get + +[source,shell] +---- +astra pcu get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-k=KEY] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Get information about a specific PCU group. + +== Aliases + +`astra pcu describe` + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`-k`, `--key`:: Specific PCU group attribute to retrieve +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get information about a specific PCU group +$ astra pcu get my_pcu + +# Get a specific attribute of a PCU group +$ astra pcu get my_pcu --key id +---- + + diff --git a/modules/commands/pages/astra-pcu-list-associations.adoc b/modules/commands/pages/astra-pcu-list-associations.adoc new file mode 100644 index 0000000..1bcb049 --- /dev/null +++ b/modules/commands/pages/astra-pcu-list-associations.adoc @@ -0,0 +1,42 @@ += astra pcu list-associations + +[source,shell] +---- +astra pcu list-associations [-aqV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +List the associations of a PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`-a`, `--all`:: List all associations for all of your PCU groups +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List the associations of a PCU group +$ astra pcu list-associations my_pu +---- + + diff --git a/modules/commands/pages/astra-pcu-list.adoc b/modules/commands/pages/astra-pcu-list.adoc new file mode 100644 index 0000000..ce6a115 --- /dev/null +++ b/modules/commands/pages/astra-pcu-list.adoc @@ -0,0 +1,43 @@ += astra pcu list + +[source,shell] +---- +astra pcu list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List your PCU groups + +== Aliases + +`astra pcu` + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all your PCU groups +$ astra pcu list +---- + + diff --git a/modules/commands/pages/astra-pcu-park.adoc b/modules/commands/pages/astra-pcu-park.adoc new file mode 100644 index 0000000..49bf5c4 --- /dev/null +++ b/modules/commands/pages/astra-pcu-park.adoc @@ -0,0 +1,43 @@ += astra pcu park + +[source,shell] +---- +astra pcu park [-qV] [--[no-]async] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Park an existing PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Park an existing PCU group +$ astra pcu park my_pcu +---- + + diff --git a/modules/commands/pages/astra-pcu-status.adoc b/modules/commands/pages/astra-pcu-status.adoc new file mode 100644 index 0000000..5f7041d --- /dev/null +++ b/modules/commands/pages/astra-pcu-status.adoc @@ -0,0 +1,41 @@ += astra pcu status + +[source,shell] +---- +astra pcu status [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Get the current status of a PCU group. + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the status of a PCU group +$ astra db status my_db +---- + + diff --git a/modules/commands/pages/astra-pcu-transfer-association.adoc b/modules/commands/pages/astra-pcu-transfer-association.adoc new file mode 100644 index 0000000..1fa9a8f --- /dev/null +++ b/modules/commands/pages/astra-pcu-transfer-association.adoc @@ -0,0 +1,47 @@ += astra pcu transfer-association + +[source,shell] +---- +astra pcu transfer-association [-qV] [--if-not-exists] [--no-input] [--[no-] + spinner] [--dump-logs[=FILE]] [--color=WHEN] + [-o=FORMAT] -t=GROUP [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [-f=GROUP | + --or-create] TARGET + +---- + + +Transfer an association from one PCU group to another + + + + + +== Options + +`TARGET`:: PCU association target (database name/id or datacenter id) +`-t`, `--to`:: The PCU group to transfer the association to +`--if-not-exists`:: Don't error if the association already exists +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`-f`, `--from`:: The PCU group which initially holds the association. May be omitted to let the CLI automatically detect it +`--or-create`:: If the datacenter is not already associated to a PCU group, create the association first + + +== Examples +[source,bash] +---- +# Transfer a datacenter association association from one PCU group to another +$ astra pcu transfer-association ee6991af-7783-4de9-8da0-c7fa250c89e2-1 --from pcu_1 --to pcu_2 +---- + + diff --git a/modules/commands/pages/astra-pcu-unpark.adoc b/modules/commands/pages/astra-pcu-unpark.adoc new file mode 100644 index 0000000..d726b51 --- /dev/null +++ b/modules/commands/pages/astra-pcu-unpark.adoc @@ -0,0 +1,43 @@ += astra pcu unpark + +[source,shell] +---- +astra pcu unpark [-qV] [--[no-]async] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [--timeout=] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Unpark a parked PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`--async`:: Do not wait for the database to become active +`--timeout`:: How long the command should wait for the database to become active +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Unpark a parked PCU group +$ astra pcu unpark my_pcu +---- + + diff --git a/modules/commands/pages/astra-pcu-update.adoc b/modules/commands/pages/astra-pcu-update.adoc new file mode 100644 index 0000000..dbf13f5 --- /dev/null +++ b/modules/commands/pages/astra-pcu-update.adoc @@ -0,0 +1,53 @@ += astra pcu update + +[source,shell] +---- +astra pcu update [-qV] [--allow-duplicate-names] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [-c=CLOUD] [--color=WHEN] [-d=DESC] + [-it=TYPE] [--max=MAX] [--min=MIN] [-o=FORMAT] [-pt=TYPE] + [-r=REGION] [--reserved=RESERVED] [-t=TITLE] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] [GROUP] + +---- + + +Update an existing PCU group + + + + + +== Options + +`GROUP`:: The name or ID of the PCU group to work with +`--allow-duplicate-names`:: Allow multiple pcus with the same name +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`-t`, `--title`:: New title for the PCU group +`-c`, `--cloud`:: Cloud provider this PCU will work in +`-r`, `--region`:: Cloud region this PCU will work in. **Use one of the `astra db list-regions-*` commands to see available regions.** +`-d`, `--description`:: Optional description for the PCU group +`-it`, `--instance-type`:: Cache type for the PCU group +`-pt`, `--provision-type`:: Provision type for the PCU group +`--min`:: Minimum capacity units for the PCU group +`--max`:: Maximum capacity units for the PCU group +`--reserved`:: Reserved capacity units for the PCU group + + +== Examples +[source,bash] +---- +# Update an existing PCU group +$ astra pcu update my_pcu --tile new_title --min 2 --max 5 +---- + + diff --git a/modules/commands/pages/astra-pcu.adoc b/modules/commands/pages/astra-pcu.adoc new file mode 100644 index 0000000..e1de5cd --- /dev/null +++ b/modules/commands/pages/astra-pcu.adoc @@ -0,0 +1,56 @@ += astra pcu + +[source,shell] +---- +astra pcu [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [COMMAND] + +---- + + +Manage your PCU groups and associations + + +**Alias of `astra pcu list`** + + +== Subcommands + +* xref:astra-pcu-list.adoc[astra pcu list] +* xref:astra-pcu-get.adoc[astra pcu get] +* xref:astra-pcu-status.adoc[astra pcu status] +* xref:astra-pcu-park.adoc[astra pcu park] +* xref:astra-pcu-unpark.adoc[astra pcu unpark] +* xref:astra-pcu-create.adoc[astra pcu create] +* xref:astra-pcu-update.adoc[astra pcu update] +* xref:astra-pcu-delete.adoc[astra pcu delete] +* xref:astra-pcu-associate.adoc[astra pcu associate] +* xref:astra-pcu-disassociate.adoc[astra pcu disassociate] +* xref:astra-pcu-list-associations.adoc[astra pcu list-associations] +* xref:astra-pcu-transfer-association.adoc[astra pcu transfer-association] + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all your PCU groups +$ astra pcu +---- + + diff --git a/modules/commands/pages/astra-role-get.adoc b/modules/commands/pages/astra-role-get.adoc new file mode 100644 index 0000000..99fba5e --- /dev/null +++ b/modules/commands/pages/astra-role-get.adoc @@ -0,0 +1,47 @@ += astra role get + +[source,shell] +---- +astra role get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] ROLE + +---- + + +Show details for a specific role + +== Aliases + +`astra role describe` + + + + +== Options + +`ROLE`:: Role name/id to get +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get details for a specific role by name +$ astra role get "Database Administrator" + +# Get details for a specific role by ID +$ astra role get "12345678-abcd-1234-abcd-123456789012" +---- + + diff --git a/modules/commands/pages/astra-role-list.adoc b/modules/commands/pages/astra-role-list.adoc new file mode 100644 index 0000000..2589077 --- /dev/null +++ b/modules/commands/pages/astra-role-list.adoc @@ -0,0 +1,40 @@ += astra role list + +[source,shell] +---- +astra role list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Display all roles + + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all available roles in your organization +$ astra role list +---- + + diff --git a/modules/commands/pages/astra-role.adoc b/modules/commands/pages/astra-role.adoc index 9343deb..d078a4d 100644 --- a/modules/commands/pages/astra-role.adoc +++ b/modules/commands/pages/astra-role.adoc @@ -1 +1,34 @@ -= astra role \ No newline at end of file += astra role + +[source,shell] +---- +astra role [COMMAND] + +---- + + +Discover Astra roles + + + +== Subcommands + +* xref:astra-role-list.adoc[astra role list] +* xref:astra-role-get.adoc[astra role get] + + +== Options + + + +== Examples +[source,bash] +---- +# List all available roles +$ astra role list + +# Get details for a specific role +$ astra role get "Database Administrator" +---- + + diff --git a/modules/commands/pages/astra-setup.adoc b/modules/commands/pages/astra-setup.adoc index 68996ed..c70c729 100644 --- a/modules/commands/pages/astra-setup.adoc +++ b/modules/commands/pages/astra-setup.adoc @@ -1,47 +1,40 @@ = astra setup -Interactively set up the Astra CLI and create profiles - -== Usage - -[source,console] +[source,shell] ---- -astra setup [-hqv] [--[no-]color] [--no-input] [--[no-]spinner] - [--dump-logs[=FILE]] [-e=ENV] [--name=NAME] [-o=FORMAT] - [-t=TOKEN] +astra setup [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-e=ENV] [--name=NAME] [-o=FORMAT] [-t=TOKEN] + ---- -== Options -`--[no-]color`:: -Force colored output +Interactively set up the Astra CLI and create profiles + +See ``@{cli.name} config create`` for a programmatic way to create profiles without interaction. -`--dump-logs[=FILE]`:: -Write all logs to an optionally specified file (default: ~/.astra/logs/.log) -`-e`, `--env=ENV`:: -Astra environment for the token to target. If not provided, you will be prompted for it -`-h`, `--help`:: -Show this help message and exit. -`--name=NAME`:: -Optional name for the profile. If not provided, you will be prompted for it -`--no-input`:: -Never ask for user input (e.g. confirmation prompts) +== Options -`-o`, `--output=FORMAT`:: -One of: human, json, csv +`-t`, `--token`:: Token to use authenticate each call. If not provided, you will be prompted for it +`-e`, `--env`:: Astra environment for the token to target. If not provided, you will be prompted for it +`--name`:: Optional name for the profile. If not provided, you will be prompted for it +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file -`-q`, `--quiet`:: -Suppress informational output -`--[no-]spinner`:: -Enable/disable the loading spinner +== Examples +[source,bash] +---- +# Start the interactive setup process +$ astra setup +---- -`-t`, `--token=TOKEN`:: -Token to use authenticate each call. If not provided, you will be prompted for it -`-v`, `--verbose`:: -Enable verbose logging output diff --git a/modules/commands/pages/astra-shellenv.adoc b/modules/commands/pages/astra-shellenv.adoc new file mode 100644 index 0000000..b4c9e8c --- /dev/null +++ b/modules/commands/pages/astra-shellenv.adoc @@ -0,0 +1,49 @@ += astra shellenv + +[source,shell] +---- +astra shellenv [--ignore-multiple-paths] [--no-update-notifier] [--home=<$home>] + +---- + + +Completions, configuration, and more + +Eval-ing the output of this command will: + + * Add the binary to your PATH + + * Enable shell completions + + * Optionally set any other configuration environment variables. + +Intended to be added to your shell profile (``.zshrc``, ``.zprofile``, ``.bashrc``, etc.), but you can technically just eval it in any shell session to get completions and update your PATH for that session. + + + + + +== Options + +`--home`:: Sets the ``ASTRA_HOME`` env var. See ``astra config home path -h`` for how this is resolved. +`--ignore-multiple-paths`:: Ignore warnings about multiple home folders or astrarc files being present. Sets ``ASTRA_IGNORE_MULTIPLE_PATHS=true`` under the hood. +`--no-update-notifier`:: Disables background update checks notifications. Sets ``ASTRA_NO_UPDATE_NOTIFIER=true`` under the hood. + + +== Examples +[source,bash] +---- +# Put this in your shell profile (e.g. ``~/.zprofile``) to generate completions and set your PATH +$ eval "$(/path/to/astra shellenv)" + +# Set a custom ``ASTRA_HOME`` path +$ eval "$(/path/to/astra shellenv --home /path/to/astra/home)" + +# Disable update notifications +$ eval "$(/path/to/astra shellenv --no-update-notifier)" + +# Ignore warnings about multiple home folders or astrarc files +$ eval "$(/path/to/astra shellenv --ignore-multiple-paths)" +---- + + diff --git a/modules/commands/pages/astra-streaming-create.adoc b/modules/commands/pages/astra-streaming-create.adoc new file mode 100644 index 0000000..fd0879e --- /dev/null +++ b/modules/commands/pages/astra-streaming-create.adoc @@ -0,0 +1,58 @@ += astra streaming create + +[source,shell] +---- +astra streaming create [-qV] [--if-not-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + ([--plan=PLAN] | -e=EMAIL | (--cluster=CLUSTER | + [-r=REGION [-c=CLOUD]])) TENANT + +---- + + +Create a new streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on +`--if-not-exists`:: Don't error if the tenant already exists +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`--plan`:: Plan for the tenant +`-e`, `--email`:: User email +`--cluster`:: Dedicated cluster, replacement for cloud/region +`-r`, `--region`:: Cloud provider region to provision +`-c`, `--cloud`:: The cloud provider where the tenant should be created. Inferred from the region if not provided. + + +== Examples +[source,bash] +---- +# Create a basic streaming tenant in the 'us-east1' region +$ astra streaming create my_tenant --region us-east1 + +# Create a tenant with a specific cloud provider +$ astra streaming create my_tenant --region us-east1 --cloud AWS + +# Create a tenant with a dedicated cluster +$ astra streaming create my_tenant --cluster my_cluster + +# Create a tenant if it doesn't already exist +$ astra streaming create my_tenant --region us-east1 --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-streaming-delete.adoc b/modules/commands/pages/astra-streaming-delete.adoc new file mode 100644 index 0000000..c73b405 --- /dev/null +++ b/modules/commands/pages/astra-streaming-delete.adoc @@ -0,0 +1,46 @@ += astra streaming delete + +[source,shell] +---- +astra streaming delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + [TENANT] + +---- + + +Delete an existing streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on +`--if-exists`:: Do not fail if tenant does not exist +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Delete an existing streaming tenant +$ astra streaming delete my_tenant + +# Delete an existing streaming tenant without failing if it does not exist +$ astra streaming delete my_tenant --if-exists +---- + + diff --git a/modules/commands/pages/astra-streaming-exist.adoc b/modules/commands/pages/astra-streaming-exist.adoc new file mode 100644 index 0000000..49472cd --- /dev/null +++ b/modules/commands/pages/astra-streaming-exist.adoc @@ -0,0 +1,41 @@ += astra streaming exist + +[source,shell] +---- +astra streaming exist [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] TENANT + +---- + + +Show existence of a streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Check if a streaming tenant exists +$ astra streaming exist my_tenant +---- + + diff --git a/modules/commands/pages/astra-streaming-get.adoc b/modules/commands/pages/astra-streaming-get.adoc new file mode 100644 index 0000000..e5c8d2b --- /dev/null +++ b/modules/commands/pages/astra-streaming-get.adoc @@ -0,0 +1,48 @@ += astra streaming get + +[source,shell] +---- +astra streaming get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-k=KEY] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] + | [--token=TOKEN [--env=ENV]]] [TENANT] + +---- + + +Get the info about a streaming tenant. + +== Aliases + +`astra streaming describe` + + + + +== Options + +`TENANT`:: The name of the tenant to operate on +`-k`, `--key`:: Specific tenant attribute to retrieve +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get information about a specific tenant +$ astra streaming get my_tenant + +# Get a specific attribute of a tenant +$ astra streaming get my_tenant --key region +---- + + diff --git a/modules/commands/pages/astra-streaming-list-clouds.adoc b/modules/commands/pages/astra-streaming-list-clouds.adoc new file mode 100644 index 0000000..0b45f4f --- /dev/null +++ b/modules/commands/pages/astra-streaming-list-clouds.adoc @@ -0,0 +1,40 @@ += astra streaming list-clouds + +[source,shell] +---- +astra streaming list-clouds [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +List all available cloud providers for Astra streaming tenants + + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all available cloud providers for streaming tenants +$ astra streaming list-clouds +---- + + diff --git a/modules/commands/pages/astra-streaming-list-regions.adoc b/modules/commands/pages/astra-streaming-list-regions.adoc new file mode 100644 index 0000000..98739fc --- /dev/null +++ b/modules/commands/pages/astra-streaming-list-regions.adoc @@ -0,0 +1,50 @@ += astra streaming list-regions + +[source,shell] +---- +astra streaming list-regions [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [-c=FILTER[, + FILTER...]]... [-f=FILTER[,FILTER...]]... + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] + +---- + + +List all available regions for Astra streaming tenants + + + + + +== Options + +`-f`, `--filter`:: Comma-separated case-insensitive partial-match filters on the region name +`-c`, `--cloud`:: Comma-separated list of cloud providers to filter on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all available regions for streaming tenants +$ astra streaming list-regions + +# Filter by cloud provider +$ astra streaming list-regions --cloud aws,gcp + +# Filter by partial region name +$ astra streaming list-regions --filter us- +---- + + diff --git a/modules/commands/pages/astra-streaming-list.adoc b/modules/commands/pages/astra-streaming-list.adoc new file mode 100644 index 0000000..72923e3 --- /dev/null +++ b/modules/commands/pages/astra-streaming-list.adoc @@ -0,0 +1,42 @@ += astra streaming list + +[source,shell] +---- +astra streaming list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List your Astra streaming tenants + +== Aliases + +`astra streaming` + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar-path.adoc b/modules/commands/pages/astra-streaming-pulsar-path.adoc new file mode 100644 index 0000000..b5c087e --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar-path.adoc @@ -0,0 +1,48 @@ += astra streaming pulsar path + +[source,shell] +---- +astra streaming pulsar path [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] + +---- + + +Get the path to the currently installed pulsar executable + + + + + +== Options + +`--if-exists`:: Only return path if pulsar exists, don't install automatically +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the path to the pulsar executable +$ astra streaming pulsar path + +# Use the pulsar exe to run a custom command +$ $(astra streaming pulsar path) --help + +# Get path only if pulsar exists, don't install +$ astra streaming pulsar path --if-exists +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar-shell.adoc b/modules/commands/pages/astra-streaming-pulsar-shell.adoc new file mode 100644 index 0000000..92997a0 --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar-shell.adoc @@ -0,0 +1,46 @@ += astra streaming pulsar shell + +[source,shell] +---- +astra streaming pulsar shell [-FqV] [--no-input] [-np] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] + [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [-e=STATEMENT | -f=FILE] [TENANT] + +---- + + +Launch Apache Pulsar shell for a streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to connect to +`-F`, `--fail-on-error`:: Interrupt the shell if a command throws an exception +`-np`, `--no-progress`:: Display raw output of the commands without progress visualization +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment +`-e`, `--execute`:: Execute the statement and quit +`-f`, `--file`:: Input filename with a list of commands to be executed. Each command must be separated by a newline + + +== Examples +[source,bash] +---- +# Launch pulsar shell for a tenant +$ astra streaming pulsar shell my_tenant +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar-token.adoc b/modules/commands/pages/astra-streaming-pulsar-token.adoc new file mode 100644 index 0000000..7eab8f4 --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar-token.adoc @@ -0,0 +1,41 @@ += astra streaming pulsar-token + +[source,shell] +---- +astra streaming pulsar-token [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] TENANT + +---- + + +Get the Pulsar token for a streaming tenant + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the Pulsar token for a tenant +$ astra streaming pulsar-token my_tenant +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar-version.adoc b/modules/commands/pages/astra-streaming-pulsar-version.adoc new file mode 100644 index 0000000..80468a5 --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar-version.adoc @@ -0,0 +1,40 @@ += astra streaming pulsar version + +[source,shell] +---- +astra streaming pulsar version [-qV] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Display the currently installed pulsar's version + + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Display pulsar's version information +$ astra streaming pulsar version +---- + + diff --git a/modules/commands/pages/astra-streaming-pulsar.adoc b/modules/commands/pages/astra-streaming-pulsar.adoc new file mode 100644 index 0000000..3b5db45 --- /dev/null +++ b/modules/commands/pages/astra-streaming-pulsar.adoc @@ -0,0 +1,38 @@ += astra streaming pulsar + +[source,shell] +---- +astra streaming pulsar [COMMAND] + +---- + + +Apache Pulsar operations for your Astra streaming tenants + + + +== Subcommands + +* xref:astra-streaming-pulsar-shell.adoc[astra streaming pulsar shell] +* xref:astra-streaming-pulsar-version.adoc[astra streaming pulsar version] +* xref:astra-streaming-pulsar-path.adoc[astra streaming pulsar path] + + +== Options + + + +== Examples +[source,bash] +---- +# Launch pulsar shell for a tenant +$ astra streaming pulsar shell my_tenant + +# Get pulsar version +$ astra streaming pulsar version + +# Get pulsar executable path +$ astra streaming pulsar path +---- + + diff --git a/modules/commands/pages/astra-streaming-status.adoc b/modules/commands/pages/astra-streaming-status.adoc new file mode 100644 index 0000000..7bc11fc --- /dev/null +++ b/modules/commands/pages/astra-streaming-status.adoc @@ -0,0 +1,41 @@ += astra streaming status + +[source,shell] +---- +astra streaming status [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [TENANT] + +---- + + +Get the current status of a streaming tenant. + + + + + +== Options + +`TENANT`:: The name of the tenant to operate on +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get the status of a streaming tenant +$ astra streaming status my_tenant +---- + + diff --git a/modules/commands/pages/astra-streaming.adoc b/modules/commands/pages/astra-streaming.adoc index b7ac7dc..cb69898 100644 --- a/modules/commands/pages/astra-streaming.adoc +++ b/modules/commands/pages/astra-streaming.adoc @@ -1 +1,53 @@ -= astra streaming \ No newline at end of file += astra streaming + +[source,shell] +---- +astra streaming [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [COMMAND] + +---- + + +Manage Astra streaming tenants + + +**Alias of `astra streaming list`** + + +== Subcommands + +* xref:astra-streaming-list.adoc[astra streaming list] +* xref:astra-streaming-get.adoc[astra streaming get] +* xref:astra-streaming-create.adoc[astra streaming create] +* xref:astra-streaming-delete.adoc[astra streaming delete] +* xref:astra-streaming-exist.adoc[astra streaming exist] +* xref:astra-streaming-status.adoc[astra streaming status] +* xref:astra-streaming-pulsar.adoc[astra streaming pulsar] +* xref:astra-streaming-pulsar-token.adoc[astra streaming pulsar-token] +* xref:astra-streaming-list-regions.adoc[astra streaming list-regions] +* xref:astra-streaming-list-clouds.adoc[astra streaming list-clouds] + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- + +---- + + diff --git a/modules/commands/pages/astra-token-create.adoc b/modules/commands/pages/astra-token-create.adoc new file mode 100644 index 0000000..ca60ed9 --- /dev/null +++ b/modules/commands/pages/astra-token-create.adoc @@ -0,0 +1,42 @@ += astra token create + +[source,shell] +---- +astra token create [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-d=DESC] [-o=FORMAT] -r=ROLE [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] + +---- + + +Create a new token + + + + + +== Options + +`-r`, `--role`:: The role for this token +`-d`, `--description`:: An optional description for this token +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Create a token with a specific role +$ astra token create --role "Organization Administrator" +---- + + diff --git a/modules/commands/pages/astra-token-delete.adoc b/modules/commands/pages/astra-token-delete.adoc new file mode 100644 index 0000000..fb07876 --- /dev/null +++ b/modules/commands/pages/astra-token-delete.adoc @@ -0,0 +1,48 @@ += astra token delete + +[source,shell] +---- +astra token delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] + [-p=NAME]] | [--token=TOKEN [--env=ENV]]] TOKEN + +---- + + +Delete a token + +== Aliases + +`astra token revoke` + + + + +== Options + +`TOKEN`:: Token identifier +`--if-exists`:: Do not fail if token does not exist +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Delete a specific token +$ astra token delete + +# Delete a token without failing if it doesn't exist +$ astra token delete --if-exists +---- + + diff --git a/modules/commands/pages/astra-token-get.adoc b/modules/commands/pages/astra-token-get.adoc new file mode 100644 index 0000000..4359cc1 --- /dev/null +++ b/modules/commands/pages/astra-token-get.adoc @@ -0,0 +1,45 @@ += astra token get + +[source,shell] +---- +astra token get [-cqV] [--no-input] [--[no-]spinner] [--validate] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +Show your current token + +== Aliases + +`astra token` + + + + +== Options + +`-c`, `--copy`:: Copy the token to clipboard instead of printing it +`--validate`:: Validates the token before returning it +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Show your current token +$ astra token get +---- + + diff --git a/modules/commands/pages/astra-token-list.adoc b/modules/commands/pages/astra-token-list.adoc new file mode 100644 index 0000000..d1c59b1 --- /dev/null +++ b/modules/commands/pages/astra-token-list.adoc @@ -0,0 +1,40 @@ += astra token list + +[source,shell] +---- +astra token list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List your tokens' information + + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List your tokens' information +$ astra token list +---- + + diff --git a/modules/commands/pages/astra-token.adoc b/modules/commands/pages/astra-token.adoc index 50296c2..8aac7ac 100644 --- a/modules/commands/pages/astra-token.adoc +++ b/modules/commands/pages/astra-token.adoc @@ -1 +1,50 @@ -= astra token \ No newline at end of file += astra token + +[source,shell] +---- +astra token [-cqV] [--no-input] [--[no-]spinner] [--validate] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [COMMAND] + +---- + + +Manage your Astra tokens + + +**Alias of `astra token get`** + + +== Subcommands + +* xref:astra-token-list.adoc[astra token list] +* xref:astra-token-get.adoc[astra token get] +* xref:astra-token-create.adoc[astra token create] +* xref:astra-token-delete.adoc[astra token delete] + + +== Options + +`-c`, `--copy`:: Copy the token to clipboard instead of printing it +`--validate`:: Validates the token before returning it +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Show your current token +$ astra token +---- + + diff --git a/modules/commands/pages/astra-upgrade.adoc b/modules/commands/pages/astra-upgrade.adoc index 8608b79..4919ee6 100644 --- a/modules/commands/pages/astra-upgrade.adoc +++ b/modules/commands/pages/astra-upgrade.adoc @@ -1 +1,51 @@ -= astra upgrade \ No newline at end of file += astra upgrade + +[source,shell] +---- +astra upgrade [-qVy] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [-v=TAG | --pre] + +---- + + +Upgrade your Astra CLI installation + +Update notifications may occur periodically when a new version is available. + +To opt out of Update notifications, set ``ASTRA_NO_UPDATE_NOTIFIER=true``, or, even better, use the ``--no-update-notifier`` flag on the ``astra shellenv`` invocation in your shell profile (if it's set up). + + + + + +== Options + +`-y`, `--yes`:: Install the upgrade without any confirmation prompting +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-v`, `--version`:: Version to upgrade to (default: latest) +`--pre`, `--prerelease`:: Include pre-releases when looking for the latest version + + +== Examples +[source,bash] +---- +# Upgrade to the latest stable version +$ astra upgrade + +# Upgrade to the latest version, including pre-releases +$ astra upgrade --pre + +# Upgrade (or downgrade!) to a specific version +$ astra upgrade --version 1.1.0 + +# Opt out of upgrade notifications permanently in your shell profile +$ eval "$(/path/to/astra shellenv --no-update-notifier)" +---- + + diff --git a/modules/commands/pages/astra-user-delete.adoc b/modules/commands/pages/astra-user-delete.adoc new file mode 100644 index 0000000..07b3d56 --- /dev/null +++ b/modules/commands/pages/astra-user-delete.adoc @@ -0,0 +1,45 @@ += astra user delete + +[source,shell] +---- +astra user delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] [--dump-logs + [=FILE]] [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] USER + +---- + + +Delete an existing user + + + + + +== Options + +`USER`:: User email/id to delete +`--if-exists`:: Do not fail if user does not exist +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Delete a specific user +$ astra user delete john@example.com + +# Delete a user without failing if they doesn't exist +$ astra user delete john@example.com --if-exists +---- + + diff --git a/modules/commands/pages/astra-user-get.adoc b/modules/commands/pages/astra-user-get.adoc new file mode 100644 index 0000000..04730d8 --- /dev/null +++ b/modules/commands/pages/astra-user-get.adoc @@ -0,0 +1,47 @@ += astra user get + +[source,shell] +---- +astra user get [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] USER + +---- + + +Show details for a specific user + +== Aliases + +`astra user describe` + + + + +== Options + +`USER`:: User email/id to get +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Get details for a specific user by email +$ astra user get john@example.com + +# Get details for a specific user by ID +$ astra user get 12345678-abcd-1234-abcd-123456789012 +---- + + diff --git a/modules/commands/pages/astra-user-invite.adoc b/modules/commands/pages/astra-user-invite.adoc new file mode 100644 index 0000000..7f62858 --- /dev/null +++ b/modules/commands/pages/astra-user-invite.adoc @@ -0,0 +1,50 @@ += astra user invite + +[source,shell] +---- +astra user invite [-qV] [--if-not-exists] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] [-r=<$roles>[, + <$roles>...]]... [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] USER + +---- + + +Invite a user to an organization + + + + + +== Options + +`USER`:: User email/id to invite +`-r`, `--roles`:: List of roles to assign the user +`--if-not-exists`:: Do not fail if user already exists +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# Invite a user with default "Database Administrator" role +$ astra user invite john@example.com + +# Invite a user with specific roles +$ astra user invite john@example.com --role 'R/W User' --role 'Billing Admin' + +# Invite a user without failing if they already exist +$ astra user invite john@example.com --if-not-exists +---- + + diff --git a/modules/commands/pages/astra-user-list.adoc b/modules/commands/pages/astra-user-list.adoc new file mode 100644 index 0000000..25f6f5a --- /dev/null +++ b/modules/commands/pages/astra-user-list.adoc @@ -0,0 +1,43 @@ += astra user list + +[source,shell] +---- +astra user list [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] + +---- + + +List all users in the org + +== Aliases + +`astra user` + + + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all users in your organization +$ astra user list +---- + + diff --git a/modules/commands/pages/astra-user.adoc b/modules/commands/pages/astra-user.adoc index 387101d..d6a9f23 100644 --- a/modules/commands/pages/astra-user.adoc +++ b/modules/commands/pages/astra-user.adoc @@ -1 +1,48 @@ -= astra user \ No newline at end of file += astra user + +[source,shell] +---- +astra user [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | [--token=TOKEN + [--env=ENV]]] [COMMAND] + +---- + + +Manage users in your organization + + +**Alias of `astra user list`** + + +== Subcommands + +* xref:astra-user-list.adoc[astra user list] +* xref:astra-user-get.adoc[astra user get] +* xref:astra-user-invite.adoc[astra user invite] +* xref:astra-user-delete.adoc[astra user delete] + + +== Options + +`-o`, `--output`:: One of: human, json, csv +`-V`, `--verbose`:: Enable verbose logging output +`-q`, `--quiet`:: Only output essential information +`--spinner`:: Enable/disable loading spinners +`--no-input`:: Don't ask for user input (e.g. confirmation prompts) +`--color`:: One of: auto, never, always +`--dump-logs`:: Write all logs to an optionally specified file +`-cf`, `--config-file`:: The ``.astrarc`` file to use for this command +`-p`, `--profile`:: The ``.astrarc`` profile to use for this command +`--token`:: The astra token to use for this command. Use the ``--token @file`` syntax to read the token from a file, to avoid potential leaks. +`--env`:: Override the target astra environment + + +== Examples +[source,bash] +---- +# List all your Astra users +$ astra user +---- + + diff --git a/modules/commands/pages/astra.adoc b/modules/commands/pages/astra.adoc deleted file mode 100644 index 66f1184..0000000 --- a/modules/commands/pages/astra.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= astra - -Manage Astra from the command line. - -== Usage - -[source,console] ----- -astra [-hqvV] [--[no-]color] [--no-input] [--[no-]spinner] [--dump-logs - [=FILE]] [-o=FORMAT] [COMMAND] ----- - -== Options - -`--[no-]color`:: -Force colored output - -`--dump-logs[=FILE]`:: -Write all logs to an optionally specified file (default: ~/.astra/logs/.log) - -`-h`, `--help`:: -Show this help message and exit. - -`--no-input`:: -Never ask for user input (e.g. confirmation prompts) - -`-o`, `--output=FORMAT`:: -One of: human, json, csv - -`-q`, `--quiet`:: -Suppress informational output - -`--[no-]spinner`:: -Enable/disable the loading spinner - -`-v`, `--verbose`:: -Enable verbose logging output - -`-V`, `--version`:: -Print version information and exit. - -== Commands - -* xref:commands:astra-setup.adoc[] -* xref:commands:astra-config.adoc[] -* xref:commands:astra-db.adoc[] -* xref:commands:astra-org.adoc[] -* xref:commands:astra-role.adoc[] -* xref:commands:astra-streaming.adoc[] -* xref:commands:astra-token.adoc[] -* xref:commands:astra-user.adoc[] -* xref:commands:astra-upgrade.adoc[] -* xref:commands:astra-nuke.adoc[] - -== Examples - -[source,console] ----- -# Setup the Astra CLI -$ astra setup - -# List databases -$ astra db list - -# Create a vector database -$ astra db create demo -r us-east1 ----- \ No newline at end of file From 988372e0094e291f9b8ae140cadd642470417214 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Fri, 7 Nov 2025 15:00:22 -0600 Subject: [PATCH 06/29] Installation updates --- modules/ROOT/pages/install.adoc | 208 +++++++++--------------------- modules/ROOT/pages/uninstall.adoc | 53 ++++---- modules/ROOT/pages/upgrade.adoc | 32 ++++- modules/ROOT/pages/use-cli.adoc | 131 ++++++++++--------- 4 files changed, 186 insertions(+), 238 deletions(-) diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 4cc85ff..d15ac53 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -35,17 +35,8 @@ Homebrew:: + [source,bash] ---- -brew install datastax/astra-cli/astra-cli +brew install datastax/astra-cli/astra ---- -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- -TBD ----- -==== . Run the `astra` command from any directory to verify successful installation: + @@ -59,7 +50,7 @@ The response includes available commands and options for the {product}. macOS:: + -Select one of the following installation methods to install the {product} on macOS without using Homebrew: +Select one of the following installation methods to install the {product} on macOS _without_ using Homebrew: + [tabs] ===== @@ -70,55 +61,10 @@ Scripted installation (recommended):: + [source,bash] ---- -sh -c "$(curl -fsSL https://raw.githubusercontent.com/toptobes/astra-cli-pico/master/scripts/install.sh)" ----- -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- - _____ __ - / _ \ _______/ |_____________ - / /_\ \ / ___/\ __\_ __ \__ \ - / | \___ \ | | | | \// __ \_ - \____|__ /____ > |__| |__| (____ / - \/ \/ \/ - - Installer: {product-version} - -→ Required tools are available. -→ No existing installation found. - -Ready to install Astra CLI ✅ - -Do you want to install Astra CLI to ~/.astra/cli/? [Y]es/[d]ifferent path/[c]ancel -> ----- -==== - -. When prompted to specify the installation location, press kbd:[Enter] to accept the default (`~/.astra/cli/`). -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] +sh -c "$(curl -sSL https://ibm.biz/astra-cli)" ---- -→ Using installation dir ~/.astra/cli/. -→ Archive downloaded. -→ Archive verified and extracted. - -Astra CLI installed successfully! 🎉 - -Next steps: - -# Append the following to your shell profile (e.g. ~/.bashrc, ~/.zshrc, etc.) -$ eval "$(~/.astra/cli/astra shellenv)" -# Run the following to get started! -$ astra setup ----- -==== +. When prompted to specify the installation location, press kbd:[Enter] to accept the default location (`~/.astra/cli/`). + To install the {product} to a different location, use the binary installation method instead. @@ -145,7 +91,7 @@ The response includes available commands and options for the {product}. Binary installation:: + -- -. Download the `macos` archive file for your CPU architecture from https://github.com/toptobes/astra-cli-pico/releases[GitHub]. +. Download the `macos` archive file for your CPU architecture from https://github.com/datastax/astra-cli/releases[GitHub]. . Extract the archive into the directory where you want to install the {product}: + @@ -198,41 +144,23 @@ Scripted installation (recommended):: -- . Run the following PowerShell script to install the latest version of the {product}: + -[source,powershell] ----- -powershell -c "irm https://raw.githubusercontent.com/toptobes/astra-cli-pico/master/scripts/install.ps1 | iex" +[source,shell] ---- -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- -TBD +powershell -c "irm https://ibm.biz/astra-cli-win | iex" ---- -==== -. When prompted to specify the installation location, press kbd:[Enter] to accept the default (`~\AppData\Local\.astra\cli`). -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- -TBD ----- -==== +. When prompted to specify the installation location, press kbd:[Enter] to accept the default location (`~\AppData\Local\.astra\cli`). + To install the {product} to a different location, use the binary installation method instead. -. Add the following lines to your PowerShell profile to make the `astra` command executable from any directory: +. Add the following lines to your shell profile to make the `astra` command executable from any directory: + -[source,powershell] +[source,shell] ---- TBD ---- -. Reload your shell profile or open a new command prompt. +. Reload your shell profile or open a new terminal window. . Run the `astra` command from any directory to verify successful installation: + @@ -247,13 +175,13 @@ The response includes available commands and options for the {product}. Binary installation:: + -- -. Download the `windows` zip file from https://github.com/toptobes/astra-cli-pico/releases[GitHub]. +. Download the `windows` zip file from https://github.com/datastax/astra-cli/releases[GitHub]. . Extract the zip file into the directory where you want to install the {product}: + -[source,powershell,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -powershell -Command "Expand-Archive -Path astra-windows-x86_64.zip -DestinationPath **INSTALLATION_DIRECTORY** -Force" +powershell -C "Expand-Archive -Path astra-windows-x86_64.zip -DestinationPath **INSTALLATION_DIRECTORY** -Force" ---- . Add the path to the unzipped `astra.exe` file to your `PATH` environment variable. @@ -274,91 +202,79 @@ The response includes available commands and options for the {product}. Linux:: + --- -TBD --- - -Docker:: +Select one of the following installation methods to install the {product} on Linux _without_ using Homebrew: ++ +[tabs] +===== +Scripted installation (recommended):: + -- -TBD --- -====== - -== Connect to {product-short} - -Follow these steps to set up your first connection profile: +. Run the following Bash script to install the latest version of the {product}: ++ +[source,bash] +---- +sh -c "$(curl -sSL https://ibm.biz/astra-cli)" +---- -. {astra-url}[Sign in or create an {product-short} account.^] +. When prompted to specify the installation location, press kbd:[Enter] to accept the default location (`~/.astra/cli/`). ++ +To install the {product} to a different location, use the binary installation method instead. -. Generate an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] with a role that has adequate permissions to perform the tasks you want to accomplish with the {product}. +. Add the following lines to your shell profile (for example, `~/.zshrc` or `~/.bashrc`) to make the `astra` command executable from any directory: + --- -* *Non-production organizations*: If your {product-short} organization has no databases or streaming tenants that handle sensitive information, you can grant your application token the `Organization Administrator` role to try out all of the {product} features. +[source,bash] +---- +# Astra CLI shell configuration +eval "$(~/.astra/cli/astra shellenv)" +---- -* *Production organizations*: If you're using {product-short} in production, {company} recommends that you use a more limited xref:astra-db-serverless:administration:manage-database-access.adoc#built-in-organization-roles[built-in role] or xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom role] to grant your application token the bare minimum permissions required to perform your desired tasks with the {product}. --- +. Reload your shell profile or open a new terminal window. -. Run the `astra setup` command to to create your first connection profile: +. Run the `astra` command from any directory to verify successful installation: + [source,bash] ---- -astra setup +astra ---- + -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- - _____ __ - / _ \ _______/ |_____________ - / /_\ \ / ___/\ __\_ __ \__ \ - / | \\___ \ | | | | \ //__ \_ - \____|__ /____ > |__| |__| (____ / - \/ \/ \/ - - Version: {product-version} - -Welcome to the Astra CLI setup! - -A configuration file with your profile will be created at /Users/USERNAME/.astrarc - -If you'd prefer to provide credentials on a per-command basis rather than storing them in a file, you can either: -- Use the per-command --token flag to pass your existing AstraCS token directly. -- Use the per-command --config-file flag to specify an existing .astrarc file. +The response includes available commands and options for the {product}. +-- -# Example: -$ astra db list --token +Binary installation:: ++ +-- +. Download the `linux` archive file for your CPU architecture from https://github.com/datastax/astra-cli/releases[GitHub]. -Press Enter to continue, or use Ctrl+C to cancel. +. Extract the archive into the directory where you want to install the {product}: ++ +[source,bash,subs="+quotes"] +---- +sudo tar -xzvf astra-linux-**ARCHITECTURE**.tar.gz -C **INSTALLATION_DIRECTORY** ---- -==== - -. When prompted, enter your {product-short} application token and press kbd:[Enter]. -. Enter a name for your connection profile or press kbd:[Enter] to accept the default (your organization name). +. Add the following lines to your shell profile (for example, `~/.zshrc` or `~/.bashrc`) to make the `astra` command executable from any directory: + -.Result -[%collapsible] -==== -[source,console,subs="+quotes"] +[source,bash,subs="+quotes"] ---- -Profile PROFILE_NAME successfully created. - -It has been set as the default profile. +# Astra CLI shell configuration +eval "$(**PATH_TO_BINARY** shellenv)" ---- -==== ++ +Replace `**PATH_TO_BINARY**` with the full path to the `astra` executable in the installation directory. -. Test your connection by running a simple command, such as listing your databases: +. Reload your shell profile or open a new terminal window. + +. Run the `astra` command from any directory to verify successful installation: + [source,bash] ---- -astra db list +astra ---- + -If the command succeeds, your connection is configured correctly. -If your command fails, see the xref:commands:astra-setup.adoc[astra setup command] documentation for troubleshooting tips. +The response includes available commands and options for the {product}. +-- +===== +====== == Next steps diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index 72fdb07..41e9a00 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -8,54 +8,63 @@ Follow the instructions for your original installation method to uninstall the { Homebrew:: + -- -. Uninstall the {product}: +. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and configuration profile (`~/.astra` and `~/.astrarc`): + [source,bash] ---- -brew uninstall datastax/astra-cli/astra-cli +astra nuke ---- + -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- -Uninstalling /opt/homebrew/Cellar/astra-cli/{product-version}... (4 files, 61.7MB) ----- -==== - -. Delete the {product} and its associated installation files: +When prompted to confirm, type kbd:[y] and press kbd:[Enter]. + -[source,bash] ----- -rm -R ~/.astra ----- +The `astra nuke` command will list any shell profile containing references to the `astra` command. +Delete these references manually if desired. -. Optional: Delete the {product} configuration file: +. Uninstall the {product} using Homebrew: + [source,bash] ---- -rm ~/.astrarc +brew uninstall datastax/astra-cli/astra ---- -- macOS:: + -- +Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: + +[source,bash] +---- +astra nuke +---- + +When prompted to confirm, type kbd:[y] and press kbd:[Enter]. + +The `astra nuke` command deletes the {product} home directory and configuration profile (`~/.astra` and `~/.astrarc`). +It also lists any shell profile containing references to the `astra` command. +Delete these references manually if desired. -- Windows:: + -- +TBD -- Linux:: + -- --- +Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: -Docker:: -+ --- +[source,bash] +---- +astra nuke +---- + +When prompted to confirm, type kbd:[y] and press kbd:[Enter]. + +The `astra nuke` command deletes the {product} home directory and configuration profile (`~/.astra` and `~/.astrarc`). +It also lists any shell profile containing references to the `astra` command. +Delete these references manually if desired. -- ====== \ No newline at end of file diff --git a/modules/ROOT/pages/upgrade.adoc b/modules/ROOT/pages/upgrade.adoc index 613401c..67df9fa 100644 --- a/modules/ROOT/pages/upgrade.adoc +++ b/modules/ROOT/pages/upgrade.adoc @@ -14,14 +14,14 @@ Homebrew:: + [source,bash] ---- -brew upgrade datastax/astra-cli/astra-cli +brew upgrade datastax/astra-cli/astra ---- . Optional: Upgrade to a specific version of the {product}: + [source,bash,subs="+quotes"] ---- -brew install datastax/astra-cli/astra-cli@**VERSION** +brew install datastax/astra-cli/astra@**VERSION** ---- + You can also use this command to downgrade to a previous version. @@ -97,12 +97,30 @@ The response returns your {product} version. Linux:: + -- -TBD --- +. Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: ++ +[source,bash] +---- +astra upgrade +---- -Docker:: +. Optional: Upgrade to a specific version of the {product}: + +[source,bash,subs="+quotes"] +---- +astra upgrade --version **VERSION** +---- ++ +You can also use this command to downgrade to a previous version. + +. Check the {product} version to verify that the upgrade was successful: ++ +[source,bash] +---- +astra --version +---- ++ +The response returns your {product} version. -- -TBD --- + ====== diff --git a/modules/ROOT/pages/use-cli.adoc b/modules/ROOT/pages/use-cli.adoc index 5fea6f4..53ebf33 100644 --- a/modules/ROOT/pages/use-cli.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -3,19 +3,80 @@ Initialize the {product} and run your first commands. -== Prerequisites +== Connect to {product-short} -* xref:ROOT:install.adoc[Install the {product}]. +After xref:ROOT:install.adoc[installing the {product}], follow these steps to set up your first connection profile: -* You must have an active {astra-url}[{product-short} account^]. +. {astra-url}[Sign in or create an {product-short} account.^] -* [[get-credentials]]You must have an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] that is assigned a _role_ with adequate _permissions_ to perform the tasks you'd like to accomplish with the {product}. +. Generate an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] with a role that has adequate permissions to perform the tasks you want to accomplish with the {product}. ++ +-- +* *Non-production organizations*: If your {product-short} organization has no databases or streaming tenants that handle sensitive information, you can grant your application token the `Organization Administrator` role to try out all of the {product} features. + +* *Production organizations*: If you're using {product-short} in production, {company} recommends that you use a more limited xref:astra-db-serverless:administration:manage-database-access.adoc#built-in-organization-roles[built-in role] or xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom role] to grant your application token the bare minimum permissions required to perform your desired tasks with the {product}. +-- + +. Run the `astra setup` command to to create your first connection profile: ++ +[source,bash] +---- +astra setup +---- ++ +.Result +[%collapsible] +==== +[source,console,subs="+attributes"] +---- + _____ __ + / _ \ _______/ |_____________ + / /_\ \ / ___/\ __\_ __ \__ \ + / | \\___ \ | | | | \ //__ \_ + \____|__ /____ > |__| |__| (____ / + \/ \/ \/ + + Version: {product-version} + +Welcome to the Astra CLI setup! -** *Non-production organizations*: If your {product-short} organization has no databases or streaming tenants that handle sensitive information, you can grant your application token the `Organization Administrator` role to try out all of the {product} features. +A configuration file with your profile will be created at /Users/USERNAME/.astrarc -** *Production organizations*: If you're using {product-short} in production, {company} recommends that you use a xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom role] to grant your application token the bare minimum xref:astra-db-serverless:administration:manage-database-access.adoc#about-permissions[permissions] required to perform the required tasks with the {product}. +If you'd prefer to provide credentials on a per-command basis rather than storing them in a file, you can either: +- Use the per-command --token flag to pass your existing AstraCS token directly. +- Use the per-command --config-file flag to specify an existing .astrarc file. + +# Example: +$ astra db list --token + +Press Enter to continue, or use Ctrl+C to cancel. +---- +==== -* 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]. +. When prompted, enter your {product-short} application token and press kbd:[Enter]. + +. Enter a name for your connection profile or press kbd:[Enter] to accept the default (your organization name). ++ +.Result +[%collapsible] +==== +[source,console,subs="+quotes"] +---- +Profile PROFILE_NAME successfully created. + +It has been set as the default profile. +---- +==== + +. Test your connection by running a simple command, such as listing your databases: ++ +[source,bash] +---- +astra db list +---- ++ +If the command succeeds, your connection is configured correctly. +If your command fails, see the xref:commands:astra-setup.adoc[astra setup command] documentation for troubleshooting tips. [#file-locations] == Installation file locations @@ -44,62 +105,6 @@ For <>, the `astra` executable an _This file is *not* deleted when you update or re-install the {product}._ |=== -[#initialize] -== Initialize the {product} - -After installation, initialize the {product} and connect it to an existing {product-short} account. - -. Use the `astra setup` command to initialize the {product} with your xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token]: -+ -[source,bash,subs="+quotes"] ----- -astra setup --token *APPLICATION_TOKEN* ----- -+ -Replace `*APPLICATION_TOKEN*` with your application token. -The token format is `AstraCS:` followed by a unique token string. -+ -.Result -[%collapsible] -==== -[source,console] ----- -[OK] Configuration has been saved. -[OK] Setup completed. -[INFO] Enter 'astra help' to list available commands. ----- -==== - -. List the {product} configuration to confirm that your token is in use: -+ -[source,bash] ----- -astra config list ----- -+ -.Result -[%collapsible] -==== -[source,console] ----- -+--------------------------------+ -| configuration | -+--------------------------------+ -| alex@altostrat.com (in use) | -+--------------------------------+ ----- -==== - -The {product} is initialized and your application token is set as the default configuration. -The {product} stores configurations and their associated application tokens in the `~/.astrarc` file. -To create additional configurations, see <>. - -[IMPORTANT] -==== -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. -==== - == Print help information Use `astra help` to print general {product} help information: From 22334f1d92fea2e555b66e66aa2a043f6d30a570 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Fri, 7 Nov 2025 23:11:38 -0600 Subject: [PATCH 07/29] Review feedback and more updates --- modules/ROOT/nav.adoc | 9 +-- modules/ROOT/pages/install.adoc | 106 +++++------------------------- modules/ROOT/pages/uninstall.adoc | 45 ++++--------- modules/ROOT/pages/upgrade.adoc | 36 ++++------ 4 files changed, 46 insertions(+), 150 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e6d7d54..d749438 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,13 +1,10 @@ +.Get Started * xref:install.adoc[] * xref:use-cli.adoc[] * xref:upgrade.adoc[] * xref:uninstall.adoc[] -* Commands -+ --- -include::partial$partial-nav.adoc[] --- +include::ROOT:partial$partial-nav.adoc[] -* https://github.com/datastax/astra-cli[GitHub repo] +.Release notes * https://github.com/datastax/astra-cli/releases[Release notes] diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index d15ac53..784163f 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -28,29 +28,10 @@ Select one of the following installation methods and follow the steps to install [tabs,sync-group-id=platforms] ====== -Homebrew:: +macOS and Linux:: + --- -. Install the latest version of the {product} using https://brew.sh/[Homebrew]: -+ -[source,bash] ----- -brew install datastax/astra-cli/astra ----- - -. Run the `astra` command from any directory to verify successful installation: -+ -[source,bash] ----- -astra ----- -+ -The response includes available commands and options for the {product}. --- - -macOS:: -+ -Select one of the following installation methods to install the {product} on macOS _without_ using Homebrew: +Select one of the following installation methods to install the {product} on macOS and Linux. +If you prefer to use a package manager, follow the Homebrew instructions instead. + [tabs] ===== @@ -61,14 +42,14 @@ Scripted installation (recommended):: + [source,bash] ---- -sh -c "$(curl -sSL https://ibm.biz/astra-cli)" +curl -sSL ibm.biz/astra-cli | sh ---- . When prompted to specify the installation location, press kbd:[Enter] to accept the default location (`~/.astra/cli/`). + To install the {product} to a different location, use the binary installation method instead. -. Add the following lines to your shell profile (for example, `~/.zshrc` or `~/.bashrc`) to make the `astra` command executable from any directory: +. Add the following lines to your shell profile (for example, `~/.zprofile` or `~/.bash_profile`) to make the `astra` command executable from any directory: + [source,bash] ---- @@ -91,16 +72,17 @@ The response includes available commands and options for the {product}. Binary installation:: + -- -. Download the `macos` archive file for your CPU architecture from https://github.com/datastax/astra-cli/releases[GitHub]. +. Download the appropriate binary archive for your OS and CPU architecture from https://github.com/datastax/astra-cli/releases[GitHub]. -. Extract the archive into the directory where you want to install the {product}: +. Extract the archive into the directory where you want to install the {product}. +For example: + [source,bash,subs="+quotes"] ---- -sudo tar -xzvf astra-macos-**ARCHITECTURE**.tar.gz -C **INSTALLATION_DIRECTORY** +sudo tar -xzvf astra-macos-arm64.tar.gz -C **INSTALLATION_DIRECTORY** ---- -. Add the following lines to your shell profile (for example, `~/.zshrc` or `~/.bashrc`) to make the `astra` command executable from any directory: +. Add the following lines to your shell profile (for example, `~/.zprofile` or `~/.bash_profile`) to make the `astra` command executable from any directory: + [source,bash,subs="+quotes"] ---- @@ -112,15 +94,14 @@ Replace `**PATH_TO_BINARY**` with the full path to the `astra` executable in the . Reload your shell profile or open a new terminal window. -. Delete the `com.apple.quarantine` attribute from the `astra` binary to remove https://support.apple.com/guide/security/gatekeeper-and-runtime-protection-sec5599b66df/web[macOS Gatekeeper restrictions]: +. On macOS: Delete the `com.apple.quarantine` attribute from the `astra` binary to remove https://support.apple.com/guide/security/gatekeeper-and-runtime-protection-sec5599b66df/web[macOS Gatekeeper restrictions]: + [source,bash] ---- xattr -d com.apple.quarantine $(which astra) ---- + -You can also remove these restrictions in your macOS System Settings. -See the https://support.apple.com/en-us/102445#openanyway[Apple support documentation] for more information. +Alternatively, you can remove these restrictions in your https://support.apple.com/en-us/102445#openanyway[macOS System Settings]. . Run the `astra` command from any directory to verify successful installation: + @@ -200,69 +181,15 @@ The response includes available commands and options for the {product}. -- ===== -Linux:: -+ -Select one of the following installation methods to install the {product} on Linux _without_ using Homebrew: -+ -[tabs] -===== -Scripted installation (recommended):: +Homebrew:: + -- -. Run the following Bash script to install the latest version of the {product}: -+ -[source,bash] ----- -sh -c "$(curl -sSL https://ibm.biz/astra-cli)" ----- - -. When prompted to specify the installation location, press kbd:[Enter] to accept the default location (`~/.astra/cli/`). -+ -To install the {product} to a different location, use the binary installation method instead. - -. Add the following lines to your shell profile (for example, `~/.zshrc` or `~/.bashrc`) to make the `astra` command executable from any directory: -+ -[source,bash] ----- -# Astra CLI shell configuration -eval "$(~/.astra/cli/astra shellenv)" ----- - -. Reload your shell profile or open a new terminal window. - -. Run the `astra` command from any directory to verify successful installation: +. Install the latest version of the {product} using https://brew.sh/[Homebrew]: + [source,bash] ---- -astra ----- -+ -The response includes available commands and options for the {product}. --- - -Binary installation:: -+ --- -. Download the `linux` archive file for your CPU architecture from https://github.com/datastax/astra-cli/releases[GitHub]. - -. Extract the archive into the directory where you want to install the {product}: -+ -[source,bash,subs="+quotes"] ----- -sudo tar -xzvf astra-linux-**ARCHITECTURE**.tar.gz -C **INSTALLATION_DIRECTORY** ----- - -. Add the following lines to your shell profile (for example, `~/.zshrc` or `~/.bashrc`) to make the `astra` command executable from any directory: -+ -[source,bash,subs="+quotes"] ----- -# Astra CLI shell configuration -eval "$(**PATH_TO_BINARY** shellenv)" +brew install datastax/astra-cli/astra ---- -+ -Replace `**PATH_TO_BINARY**` with the full path to the `astra` executable in the installation directory. - -. Reload your shell profile or open a new terminal window. . Run the `astra` command from any directory to verify successful installation: + @@ -273,9 +200,8 @@ astra + The response includes available commands and options for the {product}. -- -===== ====== == Next steps -To set up a new configuration and run your first commands, see xref:use-cli.adoc[]. +To connect to {product-short} run your first commands, see xref:use-cli.adoc[]. diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index 41e9a00..2d90486 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -5,30 +5,7 @@ Follow the instructions for your original installation method to uninstall the { [tabs,sync-group-id=platforms] ====== -Homebrew:: -+ --- -. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and configuration profile (`~/.astra` and `~/.astrarc`): -+ -[source,bash] ----- -astra nuke ----- -+ -When prompted to confirm, type kbd:[y] and press kbd:[Enter]. -+ -The `astra nuke` command will list any shell profile containing references to the `astra` command. -Delete these references manually if desired. - -. Uninstall the {product} using Homebrew: -+ -[source,bash] ----- -brew uninstall datastax/astra-cli/astra ----- --- - -macOS:: +macOS and Linux:: + -- Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: @@ -51,20 +28,26 @@ Windows:: TBD -- -Linux:: +Homebrew:: + -- -Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: - +. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and configuration profile (`~/.astra` and `~/.astrarc`): ++ [source,bash] ---- astra nuke ---- - ++ When prompted to confirm, type kbd:[y] and press kbd:[Enter]. - -The `astra nuke` command deletes the {product} home directory and configuration profile (`~/.astra` and `~/.astrarc`). -It also lists any shell profile containing references to the `astra` command. ++ +The `astra nuke` command will list any shell profile containing references to the `astra` command. Delete these references manually if desired. + +. Uninstall the {product} using Homebrew: ++ +[source,bash] +---- +brew uninstall datastax/astra-cli/astra +---- -- ====== \ No newline at end of file diff --git a/modules/ROOT/pages/upgrade.adoc b/modules/ROOT/pages/upgrade.adoc index 67df9fa..db03019 100644 --- a/modules/ROOT/pages/upgrade.adoc +++ b/modules/ROOT/pages/upgrade.adoc @@ -7,21 +7,21 @@ Follow the instructions for your original installation method to upgrade the {pr [tabs,sync-group-id=platforms] ====== -Homebrew:: +macOS and Linux:: + -- -. Run the following command to upgrade to the latest version of the {product}: +. Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: + [source,bash] ---- -brew upgrade datastax/astra-cli/astra +astra upgrade ---- . Optional: Upgrade to a specific version of the {product}: + [source,bash,subs="+quotes"] ---- -brew install datastax/astra-cli/astra@**VERSION** +astra upgrade --version **VERSION** ---- + You can also use this command to downgrade to a previous version. @@ -36,19 +36,19 @@ astra --version The response returns your {product} version. -- -macOS:: +Windows:: + -- . Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: + -[source,bash] +[source,powershell] ---- astra upgrade ---- . Optional: Upgrade to a specific version of the {product}: + -[source,bash,subs="+quotes"] +[source,powershell,subs="+quotes"] ---- astra upgrade --version **VERSION** ---- @@ -65,19 +65,19 @@ astra --version The response returns your {product} version. -- -Windows:: +Linux:: + -- . Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: + -[source,powershell] +[source,bash] ---- astra upgrade ---- . Optional: Upgrade to a specific version of the {product}: + -[source,powershell,subs="+quotes"] +[source,bash,subs="+quotes"] ---- astra upgrade --version **VERSION** ---- @@ -94,24 +94,15 @@ astra --version The response returns your {product} version. -- -Linux:: +Homebrew:: + -- -. Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: +. Run the following command to upgrade to the latest version of the {product}: + [source,bash] ---- -astra upgrade ----- - -. Optional: Upgrade to a specific version of the {product}: -+ -[source,bash,subs="+quotes"] ----- -astra upgrade --version **VERSION** +brew upgrade datastax/astra-cli/astra ---- -+ -You can also use this command to downgrade to a previous version. . Check the {product} version to verify that the upgrade was successful: + @@ -122,5 +113,4 @@ astra --version + The response returns your {product} version. -- - ====== From 87d9912a81120c66c627885a0ddaab0700c9493d Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Fri, 7 Nov 2025 23:58:34 -0600 Subject: [PATCH 08/29] Document deleted content from Serverless docs --- modules/ROOT/pages/.quickstart-databases.adoc | 296 ++++++++++++++++++ 1 file changed, 296 insertions(+) create mode 100644 modules/ROOT/pages/.quickstart-databases.adoc diff --git a/modules/ROOT/pages/.quickstart-databases.adoc b/modules/ROOT/pages/.quickstart-databases.adoc new file mode 100644 index 0000000..3e40a45 --- /dev/null +++ b/modules/ROOT/pages/.quickstart-databases.adoc @@ -0,0 +1,296 @@ +// Author's note: This page is incomplete and not currently published. += Manage databases with the {product} +:navtitle: Quickstart for databases +:organization-administrator-role: pass:q[xref:astra-db-serverless:administration:rbac.adoc#organization-administrator-role[*Organization Administrator*]] +:database-administrator-role: pass:q[xref:astra-db-serverless:administration:rbac.adoc#database-administrator-role[*Database Administrator*]] + +You can use the {product} to perform administrative operations on your {astra-db} databases and keyspaces. + +[IMPORTANT] +==== +To perform database operations, you need an application token with permission to create and configure databases, such as the {organization-administrator-role} role. + +To work within databases, you need an application token with permission to interact with the target database, such as the {database-administrator-role} role. +==== + +When you xref:ROOT:use-cli.adoc[connect the {product}], you provide an application token that authorizes you to run the CLI commands. + +== Find available regions + +Get a list of available regions for database creation. + +== Create a database + +You can create {db-serverless-vector} and {db-serverless} databases. + +[NOTE] +==== +If your organization requires that new databases belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you cannot use the {product} to create databases because it doesn't support PCU group assignment with database creation. +==== + +Create a database: + +[source,console,subs="+quotes"] +---- +astra db create *DB_NAME* --region *REGION* --cloud *CLOUD_PROVIDER* \ +-k *KEYSPACE* --if-not-exist --async +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `db_name` +| `String` +a| The database name. + +Database names must follow these rules: + +include::common:ROOT:partial$database-name-rules.adoc[] + +| `region` +| `String` (OPTIONAL) +a| A valid xref:databases:regions.adoc[cloud provider region], depending on your xref:administration:subscription-plans.adoc[subscription plan] and the database type. + +include::astra-db-serverless:databases:partial$get-regions-endpoint.adoc[] + +| `cloud` +| `String` (OPTIONAL) +| The cloud provider (`gcp,azure,aws`) to use for the database. + +| `keyspace` +| `String` (OPTIONAL) +a| The name of the database's initial keyspace. +If omitted, the default is `default_keyspace`. + +| `--if-not-exists` +| `flag` (OPTIONAL) +| If provided, this makes the operation idempotent. +Check for an existing database with the same configuration. + +| `--async` +| `flag` (OPTIONAL) +| By default, the operation is synchronous and waits for the database to become active. +Include this option to make the operation asynchronous. + +|=== + +[IMPORTANT] +==== +By default, the command waits until the database is created and ready to use. + +You can set `--async` to skip waiting while the database activates. +However, you cannot perform operations on the new database before it is active. + +To learn more, run `astra help db create`. +==== + +== Find a database + +Get information about one database. + +Get database metadata by database ID: + +[source,console,subs="+quotes"] +---- +astra db describe *DB_ID* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `String` +| The ID of the target database. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. + +You can also get metadata by providing the database name, but this doesn't guarantee uniqueness. +|=== + +.Result +[%collapsible] +==== +[source,console] +---- ++------------------+-----------------------------------------+ +| Attribute | Value | ++------------------+-----------------------------------------+ +| Name | astra_db_client | +| id | 4391daae-016c-49e3-8d0a-b4633a86082c | +| Cloud | GCP | +| Regions | us-east1 | +| Status | ACTIVE | +| Vector | Enabled | +| Default Keyspace | default_keyspace | +| Creation Time | 2024-02-24T01:20:03Z | +| | | +| Keyspaces | [0] default_keyspace | +| | | +| | | +| Regions | [0] us-east1 | +| | | ++------------------+-----------------------------------------+ +---- +==== + +=== Find all databases + +Retrieve the listing of all databases. + +List all of your databases: + +[source,console] +---- +astra db list +---- + +.Result +[%collapsible] +==== +[source,console,subs="+quotes"] +---- ++---------------------+--------------+-----------+-------+---+-----------+ +| Name | id | Regions | Cloud | V | Status | ++---------------------+--------------+-----------+-------+---+-----------+ +| astra_db_client | *DB_ID* | us-east1 | gcp | ■ | ACTIVE | ++---------------------+--------------+-----------+-------+---+-----------+ +---- +//ID truncated to prevent bad wrapping. +==== + +== Drop a database + +include::common:ROOT:partial$terminate-db-warn.adoc[] + +Delete a database and erase all data stored in it. + +Delete a database by ID: + +[source,console,subs="+quotes"] +---- +astra db delete *DB_ID* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `UUID` +| The ID of the database to delete. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. + +You can also delete a database by name. +However, {company} recommends using the ID to ensure the correct database is deleted. +|=== + +== Create a keyspace + +{db-serverless-vector} databases have an initial keyspace named `default_keyspace`. +You can override the initial keyspace name when you create the database, if desired. + +You can create more keyspaces as needed, such as for better application structure. + +Create a keyspace in a database: + +[source,console,subs="+quotes"] +---- +astra db create-keyspace *DB_ID* -k *KEYSPACE_NAME* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `String` +| The ID of the database where you want to create the keyspace. +The database must already exist. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. + +| `KEYSPACE_NAME` +| `String` +a| The unique name for the keyspace. + +Keyspace names must follow these rules: + +include::common:ROOT:partial$keyspace-name-rules.adoc[] +|=== + +== List keyspaces + +Get a list of the keyspaces in a database. + +List keyspaces in a database: + +[source,console,subs="+quotes"] +---- +astra db list-keyspaces *DB_ID* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `String` +| The ID of the database from which to get the keyspaces. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. +|=== + +.Result +[%collapsible] +==== +[source,console] +---- ++----------------------------+ +| Name | ++----------------------------+ +| default_keyspace (default) | +| keyspace2 | ++----------------------------+ +---- +==== + +== Drop a keyspace + +Delete a keyspace in a database and erase all data stored in that keyspace. + +Delete a keyspace: + +[source,console,subs="+quotes"] +---- +astra db delete-keyspace *DB_ID* -k *KEYSPACE_NAME* +---- + +Parameters: + +[cols="1,1,2"] +|=== +| Name | Type | Summary + +| `DB_ID` +| `String` +| The ID of the database where you want to delete a keyspace. +See xref:databases:create-database.adoc#get-db-id[Get your database ID]. + +| `KEYSPACE_NAME` +| `String` +| The name of the keyspace to delete. +|=== + +== Find embedding providers + +Get information about embedding providers for xref:databases:embedding-generation.adoc[{astra-db} vectorize], including supported providers, models, dimensions, and other configuration parameters. + From 0959a311956e7c6548099711556686cd20b07340 Mon Sep 17 00:00:00 2001 From: toptobes <96998732+toptobes@users.noreply.github.com> Date: Mon, 10 Nov 2025 13:00:14 -0600 Subject: [PATCH 09/29] update install, update, use pages, and the autogenerated commands (#30) --- modules/ROOT/pages/install.adoc | 27 +- modules/ROOT/pages/uninstall.adoc | 107 ++- modules/ROOT/pages/upgrade.adoc | 29 - modules/ROOT/pages/use-cli.adoc | 682 +++++++----------- modules/commands/pages/astra-completions.adoc | 2 +- .../commands/pages/astra-config-create.adoc | 2 +- .../commands/pages/astra-config-delete.adoc | 2 +- modules/commands/pages/astra-config-get.adoc | 2 +- .../pages/astra-config-home-path.adoc | 22 +- modules/commands/pages/astra-config-list.adoc | 2 +- modules/commands/pages/astra-config-path.adoc | 22 +- modules/commands/pages/astra-config-use.adoc | 2 +- modules/commands/pages/astra-config.adoc | 2 +- modules/commands/pages/astra-setup.adoc | 2 +- modules/commands/pages/astra-shellenv.adoc | 9 +- modules/commands/pages/astra-upgrade.adoc | 5 +- 16 files changed, 401 insertions(+), 518 deletions(-) diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 784163f..782ce2c 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -38,16 +38,14 @@ If you prefer to use a package manager, follow the Homebrew instructions instead Scripted installation (recommended):: + -- -. Run the following Bash script to install the latest version of the {product}: +. Run the following Bash script to install the latest version of the {product} to the default location: + [source,bash] ---- curl -sSL ibm.biz/astra-cli | sh ---- - -. When prompted to specify the installation location, press kbd:[Enter] to accept the default location (`~/.astra/cli/`). + -To install the {product} to a different location, use the binary installation method instead. +To install the {product} to a custom location, export the `ASTRA_HOME` environment variable first. . Add the following lines to your shell profile (for example, `~/.zprofile` or `~/.bash_profile`) to make the `astra` command executable from any directory: + @@ -123,25 +121,16 @@ Select one of the following installation methods to install the {product} on Win Scripted installation (recommended):: + -- -. Run the following PowerShell script to install the latest version of the {product}: +. Run the following PowerShell script to install the latest version of the {product} to the default location: + [source,shell] ---- -powershell -c "irm https://ibm.biz/astra-cli-win | iex" +powershell -c "irm ibm.biz/astra-cli-win | iex" ---- - -. When prompted to specify the installation location, press kbd:[Enter] to accept the default location (`~\AppData\Local\.astra\cli`). + -To install the {product} to a different location, use the binary installation method instead. +To install the {product} to a custom location, export the `ASTRA_HOME` environment variable first. -. Add the following lines to your shell profile to make the `astra` command executable from any directory: -+ -[source,shell] ----- -TBD ----- - -. Reload your shell profile or open a new terminal window. +. Start a new PowerShell session by opening a new terminal window. . Run the `astra` command from any directory to verify successful installation: + @@ -168,7 +157,7 @@ powershell -C "Expand-Archive -Path astra-windows-x86_64.zip -DestinationPath ** . Add the path to the unzipped `astra.exe` file to your `PATH` environment variable. To learn how to update environment variables, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. -. Reload your shell profile or open a new terminal window. +. Start a new PowerShell session by opening a new terminal window. . Run the `astra` command from any directory to verify successful installation: + @@ -204,4 +193,4 @@ The response includes available commands and options for the {product}. == Next steps -To connect to {product-short} run your first commands, see xref:use-cli.adoc[]. +To connect to {product-short} and run your first commands, see xref:use-cli.adoc[]. diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index 2d90486..ea6a19c 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -7,6 +7,12 @@ Follow the instructions for your original installation method to uninstall the { ====== macOS and Linux:: + +Select one of the following methods to uninstall the {product} on macOS and Linux: ++ +[tabs] +===== +Nuke command (recommended):: ++ -- Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: @@ -17,21 +23,110 @@ astra nuke When prompted to confirm, type kbd:[y] and press kbd:[Enter]. -The `astra nuke` command deletes the {product} home directory and configuration profile (`~/.astra` and `~/.astrarc`). +The `astra nuke` command deletes the {product} home directory and optionally the configuration file (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`). It also lists any shell profile containing references to the `astra` command. Delete these references manually if desired. -- +Manual removal:: ++ +-- +. Optional: Remove the `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[.astrarc]` file if you don't need your credentials anymore: ++ +[source,bash] +---- +rm $(astra config path -p) +---- + +. Delete the https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[{product} home directory] ++ +[source,bash] +---- +rm -rf $(astra config home path -p) +---- + +. Remove the `astra` binary if it still exists ++ +[source,bash] +---- +rm -f $(which astra) +---- + +. Remove any references to the `astra` command from your shell profile (for example, `~/.zprofile` or `~/.bash_profile`). +-- +===== + Windows:: + +Select one of the following methods to uninstall the {product} on Windows: ++ +[tabs] +===== +Uninstaller (recommended):: ++ +-- +*Note:* This method assumes you installed the {product} using the xref:install.adoc#_install_the_astra_cli[scripted installer]. + +. Optional: Remove the `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[.astrarc]` file if you don't need your credentials anymore: ++ +[source,powershell] +---- +rm -f $(astra config path -p) +---- +. Navigate to the https://support.microsoft.com/en-us/windows/uninstall-or-remove-apps-and-programs-in-windows-4b55f974-2cc6-2d2b-d092-5905080eaf98[Add or Remove Programs] settings page. +. Locate {product} in the list of installed applications. +. Select {product} and click kbd:[Uninstall]. +-- + +Nuke command:: ++ -- -TBD +Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: + +[source,powershell] +---- +astra nuke +---- + +When prompted to confirm, type kbd:[y] and press kbd:[Enter]. + +The `astra nuke` command deletes the {product} home directory and optionally the configuration file (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`). + +You will still need to remove `astra` from your system PATH manually. +-- + +Manual removal:: ++ +-- +. Optional: Remove the `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[.astrarc]` file if you don't need your credentials anymore: ++ +[source,powershell] +---- +rm -f $(astra config path -p) +---- + +. Delete the https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[{product} home directory] ++ +[source,powershell] +---- +rm -r -f $(astra config home path -p) +---- + +. Remove the `astra` binary if it still exists ++ +[source,powershell] +---- +rm -f (Get-Command astra).Source +---- + +. Remove `astra` from your system PATH. -- +===== Homebrew:: + -- -. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and configuration profile (`~/.astra` and `~/.astrarc`): +. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and optionally the configuration file (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`): + [source,bash] ---- @@ -39,9 +134,7 @@ astra nuke ---- + When prompted to confirm, type kbd:[y] and press kbd:[Enter]. -+ -The `astra nuke` command will list any shell profile containing references to the `astra` command. -Delete these references manually if desired. + . Uninstall the {product} using Homebrew: + @@ -50,4 +143,4 @@ Delete these references manually if desired. brew uninstall datastax/astra-cli/astra ---- -- -====== \ No newline at end of file +====== diff --git a/modules/ROOT/pages/upgrade.adoc b/modules/ROOT/pages/upgrade.adoc index db03019..6cc2344 100644 --- a/modules/ROOT/pages/upgrade.adoc +++ b/modules/ROOT/pages/upgrade.adoc @@ -65,35 +65,6 @@ astra --version The response returns your {product} version. -- -Linux:: -+ --- -. Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: -+ -[source,bash] ----- -astra upgrade ----- - -. Optional: Upgrade to a specific version of the {product}: -+ -[source,bash,subs="+quotes"] ----- -astra upgrade --version **VERSION** ----- -+ -You can also use this command to downgrade to a previous version. - -. Check the {product} version to verify that the upgrade was successful: -+ -[source,bash] ----- -astra --version ----- -+ -The response returns your {product} version. --- - Homebrew:: + -- diff --git a/modules/ROOT/pages/use-cli.adoc b/modules/ROOT/pages/use-cli.adoc index 53ebf33..413e413 100644 --- a/modules/ROOT/pages/use-cli.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -107,11 +107,11 @@ _This file is *not* deleted when you update or re-install the {product}._ == Print help information -Use `astra help` to print general {product} help information: +Simply print `astra` to print general {product} help information: [source,bash] ---- -astra help +astra ---- .Result @@ -119,149 +119,174 @@ astra help ==== [source,console] ---- -usage: astra [ ] -Commands are: - ? Display this help version - help Display help information - login Authenticate against Astra. - setup Initialize configuration file - config Manage configuration file - db Manage databases - org Display Organization Info - role Manage roles - streaming Manage Streaming tenants - token Manage tokens - user Manage users + _____ __ + / _ \ _______/ |_____________ + / /_\ \ / ___/\ __\_ __ \__ \ + / | \\___ \ | | | | \ //__ \_ + \____|__ /____ > |__| |__| (____ / + \/ \/ \/ + + Version: 1.0.0-rc.4 + +Documentation: https://docs.datastax.com/en/astra-cli + +Usage: astra [-qVv] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [COMMAND] -See 'astra help ' for more information on a specific command. + -v, --version Print version information and exit. + (default: false) + +Common Options: + --color=WHEN One of: auto, never, always + (default: auto) + --dump-logs[=FILE] Write all logs to an optionally specified file + (default: ~/.astra-dev/logs/.log) + --no-input Don't ask for user input (e.g. confirmation prompts) + -o, --output=FORMAT One of: human, json, csv + (default: human) + -q, --quiet Only output essential information + --[no-]spinner Enable/disable loading spinners + (default: enabled if tty) + -V, --verbose Enable verbose logging output + +Commands: + setup Interactively set up the Astra CLI and create profiles + config Manage your Astra CLI configuration profiles + db Manage your Astra databases + pcu Manage your PCU groups and associations + org Get organization information + role Discover Astra roles + streaming Manage Astra streaming tenants + token Manage your Astra tokens + user Manage users in your organization + upgrade Upgrade your Astra CLI installation + shellenv Completions, configuration, and more + nuke Entirely delete Astra CLI from your system + +Examples: + # Create a new profile + $ astra setup + + # List databases + $ astra db list + + # Create a vector database + $ astra db create demo -r us-east1 + +See 'astra --help' for help on a specific subcommand. ---- ==== -Append a command name to print help information about an individual command. -For example: +Use the `--help` (or `-h`) flag to print help information and examples for an individual command: -[source,bash] ----- -astra help db ----- .Result [%collapsible] ==== [source,console] ---- -NAME - astra db - Manage databases - -SYNOPSIS - astra db { count | cqlsh | create | create-cdc | create-collection | - create-dotenv | create-keyspace | create-region | delete | - delete-cdc | delete-collection | delete-keyspace | - delete-region | describe | download-scb | get | - get-endpoint-api | get-endpoint-playground | - get-endpoint-swagger | list* | list-cdc | list-clouds | - list-collections | list-keyspaces | list-regions | - list-regions-classic | list-regions-serverless | - list-regions-vector | load | resume | status | unload } [--] - [ --token ] [ --no-color ] [ {-v | --verbose} ] - [ {-conf | --config} ] - [ {-cf | --config-file} ] [ --env ] - [ {-o | --output} ] [cmd-options] - - Where command-specific options [cmd-options] are: - count: [ {-k | --keyspace} ] [ -encoding ] [ {-t | --table} ] - [ {-query | --schema.query} ] [ --dsbulk-config ] - [ -maxConcurrentQueries ] [ -logDir ] - cqlsh: [ --debug ] [ {-f | --file} ] [ {-k | --keyspace} ] - [ --version ] [ --connect-timeout ] [ {-e | --execute} ] - [ --request-timeout ] [ --encoding ] - create: [ {-c | --cloud} ] [ {-k | --keyspace} ] - [ --vector ] [ --timeout ] [ {-r | --region} ] - [ {--if-not-exist | --if-not-exists} ] [ --async ] [ --tier ] - [ --capacity-units ] - create-cdc: [ {-k | --keyspace} ] [ --tenant ] - [ -p, --partition ] [ --table
] - create-collection: [ {-m | --metric} ] {-c | --collection} - [ {-d | --dimension} ] - create-dotenv: [ {-k | --keyspace} ] [ {-d | --directory} ] - [ {-r | --region} ] - create-keyspace: {-k | --keyspace} [ --if-not-exist ] [ --wait ] - create-region: [ {-c | --cloud} ] [ --timeout ] - {-r | --region} [ --wait ] [ {-t | --tier} ] - [ --async ] [ --if-not-exist ] - delete: [ --async ] [ --timeout ] [ --wait ] - delete-cdc: [ {-k | --keyspace} ] [ -id ] [ --tenant ] - [ --table
] - delete-collection: {-c | --collection} - delete-keyspace: {-k | --keyspace} - delete-region: [ --async ] [ --timeout ] {-r | --region} - [ --wait ] - describe: [ {-k | --key} ] - download-scb: [ {-f | --output-file} ] [ {-r | --region} ] - get: [ {-k | --key} ] - get-endpoint-api: [ {-r | --region} ] - get-endpoint-playground: [ {-r | --region} ] - get-endpoint-swagger: [ {-r | --region} ] - list: [ --vector ] - list-cdc: - list-clouds: - list-collections: - list-keyspaces: - list-regions: - list-regions-classic: [ {-c | --cloud} ] [ {-f | --filter} ] - list-regions-serverless: [ {-c | --cloud} ] [ {-f | --filter} ] - list-regions-vector: [ {-c | --cloud} ] [ {-f | --filter} ] - load: [ {-k | --keyspace} ] [ -maxErrors ] [ -encoding ] - [ {-t | --table}
] [ {-query | --schema.query} ] - [ -skipRecords ] [ --schema.allowMissingFields ] - -url [ --dsbulk-config ] [ -dryRun ] - [ -header
] [ -delim ] [ -maxConcurrentQueries ] - [ -logDir ] [ {-m | --schema.mapping} ] - resume: [ --async ] [ --timeout ] [ --wait ] - status: - unload: [ {-k | --keyspace} ] [ -maxErrors ] - [ -encoding ] [ {-t | --table}
] [ {-query | --schema.query} ] - [ -skipRecords ] [ -url ] [ --dsbulk-config ] - [ -header
] [ -delim ] [ -maxConcurrentQueries ] - [ -logDir ] [ {-m | --schema.mapping} ] - - Where command-specific arguments are: - count: - cqlsh: - create: - create-cdc: - create-collection: - create-dotenv: - create-keyspace: - create-region: - delete: - delete-cdc: - delete-collection: - delete-keyspace: - delete-region: - describe: - download-scb: - get: - get-endpoint-api: - get-endpoint-playground: - get-endpoint-swagger: - list: - list-cdc: - list-clouds: - list-collections: - list-keyspaces: - list-regions: - list-regions-classic: - list-regions-serverless: - list-regions-vector: - load: - resume: - status: - unload: - - Where * indicates the default command(s) - See 'astra help db ' for more information on a specific command. +Usage: astra db [-qvV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [COMMAND] + +Manage your Astra databases + + -v, --vector Only show vector-enabled databases + (default: false) + +Common Options: + --color=WHEN One of: auto, never, always + (default: auto) + --dump-logs[=FILE] Write all logs to an optionally specified file + (default: ~/.astra-dev/logs/.log) + --no-input Don't ask for user input (e.g. confirmation prompts) + -o, --output=FORMAT One of: human, json, csv + (default: human) + -q, --quiet Only output essential information + --[no-]spinner Enable/disable loading spinners + (default: enabled if tty) + -V, --verbose Enable verbose logging output + +Connection Options: + -cf, --config-file=PATH + The .astrarc file to use for this command + (default: ~/.astrarc-dev) + --env=ENV Override the target astra environment + -p, --profile=NAME The .astrarc profile to use for this command + --token=TOKEN The astra token to use for this command. Use the + --token @file syntax to read the token from a + file, to avoid potential leaks. + +Commands: + list List your non-terminated Astra databases. + get, describe Get information about a specific database. + create Create a new Astra database + delete Delete an existing Astra database + status Get the current status of a database. + cqlsh Connect to your Astra database using cqlsh + dsbulk Use dsbulk to interface with your Astra DB database + create-dotenv Create a env file to help you connect to your Astra + DB instance. + download-scb Download secure connect bundle for a database + resume Resume a database that is in a stopped state. If + the database is already active, no action is + taken. + list-keyspaces List all keyspaces in the specified database + create-keyspace Create a new keyspace in the specified database + delete-keyspace Delete a keyspace from the specified database + list-collections List the collections in the specified database and + keyspace + create-collection Create a new Data API collection in the specified + database and keyspace + describe-collection Describe an existing Data API collection with + detailed information including vector + configuration and indexing options + delete-collection Delete an existing Data API collection from the + specified database and keyspace + truncate-collection Atomically delete all documents in a Data API + collection + list-tables List the tables in the specified database and + keyspace + describe-table Describe an existing table with detailed + information including columns and primary key + structure + delete-table Delete an existing table from the specified + database and keyspace + truncate-table Atomically delete all rows in a table + list-embedding-providers Find all available embedding providers for a given + database + list-cdcs List all CDC (Change Data Capture) connections for + the specified database + create-cdc Create a CDC (Change Data Capture) for a table in a + specific keyspace and tenant. + delete-cdc Delete a CDC (Change Data Capture) from the database + create-region Add a new region to an existing database + delete-region Delete a region from an existing database + list-regions List the regions for the given database + list-regions-classic List all available regions for classic Astra DB + databases + list-regions-serverless List all available regions for serverless Astra DB + databases + list-regions-vector List all available regions for vector Astra DB + databases + list-clouds List all cloud providers with regions available for + Astra DB + get-endpoint-swagger Get the SwaggerUI endpoint for the specified + database + get-endpoint-api Get the API endpoint to interact with the specified + database + get-endpoint-playground Get the GraphQL Playground for the specified + database + +Examples: + # List all your Astra databases + $ astra db + + # List only vector-enabled Astra databases + $ astra db --vector + +See 'astra --help' for help on a specific subcommand. ---- ==== @@ -269,7 +294,7 @@ Append a subcommand for further specificity: [source,bash] ---- -astra help db list +astra db list --help ---- .Result @@ -277,46 +302,55 @@ astra help db list ==== [source,console] ---- -NAME - astra db list - Display the list of Databases in an organization - -SYNOPSIS - astra db list [ {-cf | --config-file} ] - [ {-conf | --config} ] [ --env ] - [ --no-color ] [ {-o | --output} ] - [ --token ] [ {-v | --verbose} ] [ --vector ] - -OPTIONS - -cf , --config-file - Configuration file (default = ~/.astrarc) +Usage: astra db list [-qvV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] - -conf , --config - Section in configuration file (default = ~/.astrarc) +List your non-terminated Astra databases. - --env - Astra Environment to use + -v, --vector Only show vector-enabled databases + (default: false) - --no-color - Remove all colors in output +Common Options: + --color=WHEN One of: auto, never, always + (default: auto) + --dump-logs[=FILE] Write all logs to an optionally specified file + (default: ~/.astra-dev/logs/.log) + --no-input Don't ask for user input (e.g. confirmation prompts) + -o, --output=FORMAT One of: human, json, csv + (default: human) + -q, --quiet Only output essential information + --[no-]spinner Enable/disable loading spinners + (default: enabled if tty) + -V, --verbose Enable verbose logging output - -o , --output - Output format, valid values are: human,json,csv +Connection Options: + -cf, --config-file=PATH + The .astrarc file to use for this command + (default: ~/.astrarc-dev) + --env=ENV Override the target astra environment + -p, --profile=NAME The .astrarc profile to use for this command + --token=TOKEN The astra token to use for this command. Use the + --token @file syntax to read the token from a + file, to avoid potential leaks. - --token - Key to use authenticate each call. +Examples: + # List all your Astra databases + $ astra db list - -v, --verbose - Verbose mode with log in console + # List only vector-enabled Astra databases + $ astra db list --vector - --vector - Create a database with vector search enabled +See 'astra --help' for help on a specific subcommand. ---- ==== -== Set up auto-completion +== Using auto-completion The {product} provides Bash auto-completion for `bash` and `zsh` shells. +See the xref:install.adoc[installation instructions] for your platform to enable auto-completion. + 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"] @@ -329,20 +363,39 @@ astra kbd:[Tab] kbd:[Tab] ==== [source,console] ---- - --no-color config db help role setup shell user +config nuke pcu setup streaming upgrade +db org role shellenv token user +---- +==== + +Certain dynamic arguments, such as database names, also support auto-completion once the CLI discovers them. + +For example, after running `astra db list`, type a `astra db get` followed by kbd:[Tab] twice to see a list of your database names. + +[source,bash,subs="macros"] +---- +astra db get kbd:[Tab] kbd:[Tab] +---- + +.Result +[%collapsible%open] +==== +[source,console] +---- +prod_db test_db playground_db ---- ==== [#manage-configuration] -== Manage the {product} configuration +== Manage your {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. +You can create additional configuration profiless, each with their own application token, to make it easier to manage different types of resources across one or more organizations. === Get and set configurations -. Use `astra config list` to list all current configurations: +. Use `astra config list` to list all current configuration profiles: + [source,bash] ---- @@ -353,15 +406,17 @@ astra config list [%collapsible] ==== [source,console] -+----------------------------+ -| configuration | -+----------------------------+ -| Organization 1 (in use) | -| Organization 2 | -+----------------------------+ +---- +┌───────────────────────────────────┐ +│ configuration │ +├───────────────────────────────────┤ +│ Production (in use) │ +│ Testing │ +└───────────────────────────────────┘ +---- ==== -. Use `astra config create` to create a new configuration: +. Use `astra config create` or `astra setup` again to create a new configuration profile: + [source,bash,subs="+quotes"] ---- @@ -371,9 +426,14 @@ astra config create "**CONFIG_NAME**" --token **APPLICATION_TOKEN** .Result [%collapsible] ==== -[source,console] +[source,console,subs="+quotes"] ---- -[OK] Configuration has been saved. +Configuration profile '**CONFIG_NAME**' successfully created. + +(Hint: Use 'astra setup' for an interactive profile creation experience!) + +# Set it as the default profile: +$ astra config use **CONFIG_NAME** ---- ==== @@ -389,7 +449,7 @@ astra config use "**CONFIG_NAME**" ==== [source,console,subs="+quotes"] ---- -[OK] Section '**CONFIG_NAME**' is set as default. +Default profile set to '**CONFIG_NAME**'. ---- ==== @@ -397,8 +457,8 @@ astra config use "**CONFIG_NAME**" === Set the configuration for a single run -Every {product} command supports the `--config` option. -This option lets you use a different configuration when running a command without changing the default configuration. +Every {product} command supports the `--profile` option. +This option lets you use a different configuration profile when running a command without changing the default configuration profile. For example: [source,bash,subs="+quotes"] @@ -415,9 +475,9 @@ For example: astra user list --token "**APPLICATION_TOKEN**" ---- -=== Delete a configuration +=== Delete a configuration profile -Use `astra config delete` to delete a configuration: +Use `astra config delete` to delete a configuration profile: [source,bash,subs="+quotes"] ---- @@ -429,7 +489,7 @@ astra config delete "**CONFIG_NAME**" ==== [source,console,subs="+quotes"] ---- -[OK] Section '**CONFIG_NAME**' has been deleted. +Profile 'tem' deleted successfully. ---- ==== @@ -439,268 +499,8 @@ If you delete the default configuration, the {product} _doesn't_ automatically s Use the `astra config use` command to select a new default configuration. ==== -=== `config` options - -The following options are available for the `astra config` command: - -[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. ----- - -See the following sections for `config` subcommand options: - -.Expand to see all `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. ----- -==== - -.Expand to see all `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. ----- -==== - -.Expand to see all `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. ----- -==== - -.Expand to see all `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. ----- -==== - -.Expand to see all `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 ----- -==== - -.Expand to see all `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. ----- -==== - == Next steps * xref:ROOT:managing.adoc[] * xref:ROOT:astra-streaming-cli.adoc[] -* xref:ROOT:administration.adoc[] \ No newline at end of file +* xref:ROOT:administration.adoc[] diff --git a/modules/commands/pages/astra-completions.adoc b/modules/commands/pages/astra-completions.adoc index d003c97..6c95a6c 100644 --- a/modules/commands/pages/astra-completions.adoc +++ b/modules/commands/pages/astra-completions.adoc @@ -7,7 +7,7 @@ astra completions [-n=<$cliName>] ---- -See the help for the ``@{cli.name} shellenv`` command to setup completions in your shell. +See the help for the ``astra shellenv`` command to setup completions in your shell. == Aliases diff --git a/modules/commands/pages/astra-config-create.adoc b/modules/commands/pages/astra-config-create.adoc index 779d5f8..0d96a09 100644 --- a/modules/commands/pages/astra-config-create.adoc +++ b/modules/commands/pages/astra-config-create.adoc @@ -20,7 +20,7 @@ Use the ``--token @`` syntax to securely read the token from a file, witho == Options `NAME`:: Unique name for the profile -`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. `-t`, `--token`:: Astra token (``AstraCS:...``) or ``@`` to read from file `-e`, `--env`:: Astra environment the token targets `-d`, `--default`:: Set the created profile as the default profile. Same as 'config use ' diff --git a/modules/commands/pages/astra-config-delete.adoc b/modules/commands/pages/astra-config-delete.adoc index 38bb37e..12f34c3 100644 --- a/modules/commands/pages/astra-config-delete.adoc +++ b/modules/commands/pages/astra-config-delete.adoc @@ -18,7 +18,7 @@ Delete an existing configuration profile. == Options `NAME`:: Name of the profile to delete -`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. `--if-exists`:: Do not fail if the profile does not exist `-o`, `--output`:: One of: human, json, csv `-V`, `--verbose`:: Enable verbose logging output diff --git a/modules/commands/pages/astra-config-get.adoc b/modules/commands/pages/astra-config-get.adoc index 2ed9d8b..6ff76d7 100644 --- a/modules/commands/pages/astra-config-get.adoc +++ b/modules/commands/pages/astra-config-get.adoc @@ -22,7 +22,7 @@ Get the configuration of a profile or a specific key. == Options `NAME`:: Name of the profile to get -`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. `-k`, `--key`:: Specific configuration key to retrieve `-o`, `--output`:: One of: human, json, csv `-V`, `--verbose`:: Enable verbose logging output diff --git a/modules/commands/pages/astra-config-home-path.adoc b/modules/commands/pages/astra-config-home-path.adoc index 40a2210..af3a25f 100644 --- a/modules/commands/pages/astra-config-home-path.adoc +++ b/modules/commands/pages/astra-config-home-path.adoc @@ -2,15 +2,23 @@ [source,shell] ---- -astra config home path [-pqV] [--no-input] [--[no-]spinner] [--dump-logs - [=FILE]] [--color=WHEN] [-o=FORMAT] +astra config home path [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [-p | -i] ---- Prints the expected path of the astra home folder, even if does not exist. -Checks ``ASTRA_HOME`` __(ASTRA_HOME=~/my_folder)__ -> ``XDG_DATA_HOME`` __($XDG_DATA_HOME/astra)__ -> ``HOME`` __(~/.astra)__. +The folder is resolved in the following order: + + 1. The ``ASTRA_HOME`` environment variable __(e.g. ASTRA_HOME=~/my_folder)__ + + 2. The ``XDG_DATA_HOME`` spec __(e.g. $XDG_DATA_HOME/astra)__ + + 3. The default home directory __(e.g. ~/.astra)__ + +By default, shows informational output when running in a TTY (interactive terminal), and plain path output when piped or redirected. @@ -18,7 +26,6 @@ Checks ``ASTRA_HOME`` __(ASTRA_HOME=~/my_folder)__ -> ``XDG_DATA_HOME`` __($XDG_ == Options -`-p`, `--plain`:: Print only the path to the home folder, without additional information `-o`, `--output`:: One of: human, json, csv `-V`, `--verbose`:: Enable verbose logging output `-q`, `--quiet`:: Only output essential information @@ -26,6 +33,8 @@ Checks ``ASTRA_HOME`` __(ASTRA_HOME=~/my_folder)__ -> ``XDG_DATA_HOME`` __($XDG_ `--no-input`:: Don't ask for user input (e.g. confirmation prompts) `--color`:: One of: auto, never, always `--dump-logs`:: Write all logs to an optionally specified file +`-p`, `--plain`:: Print only the path to the home folder, without additional information (always) +`-i`, `--info`:: Print informational output with context about the path (always) == Examples @@ -34,8 +43,11 @@ Checks ``ASTRA_HOME`` __(ASTRA_HOME=~/my_folder)__ -> ``XDG_DATA_HOME`` __($XDG_ # Get information about the path to the astra home folder $ astra config home path -# Print only the path to the home folder, without additional information +# Force only the plain path to the .astrarc file, without additional information $ astra config home path -p + +# Force informational output even when piped or redirected +$ astra config home path -i ---- diff --git a/modules/commands/pages/astra-config-list.adoc b/modules/commands/pages/astra-config-list.adoc index 6d1aef4..261fa4d 100644 --- a/modules/commands/pages/astra-config-list.adoc +++ b/modules/commands/pages/astra-config-list.adoc @@ -19,7 +19,7 @@ List your Astra CLI configurations. == Options -`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. `-e`, `--env`:: Filter by Astra environment `-o`, `--output`:: One of: human, json, csv `-V`, `--verbose`:: Enable verbose logging output diff --git a/modules/commands/pages/astra-config-path.adoc b/modules/commands/pages/astra-config-path.adoc index cff6460..428b9fd 100644 --- a/modules/commands/pages/astra-config-path.adoc +++ b/modules/commands/pages/astra-config-path.adoc @@ -2,15 +2,23 @@ [source,shell] ---- -astra config path [-pqV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] - [--color=WHEN] [-o=FORMAT] +astra config path [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [-p | -i] ---- Prints the expected path of the .astrarc file, even if does not exist. -Checks ``ASTRARC`` __(ASTRARC=~/my_folder/.my_rc)__ -> ``XDG_CONFIG_HOME`` __($XDG_CONFIG_HOME/astra/.astrarc)__ -> ``HOME`` __(~/.astrarc)__. +The file is resolved in the following order: + + 1. The ``ASTRARC`` environment variable __(e.g. ASTRARC=~/my_folder/.my_rc)__ + + 2. The ``XDG_CONFIG_HOME`` spec __(e.g. $XDG_CONFIG_HOME/astra/.astrarc)__ + + 3. The default home directory __(e.g. ~/.astrarc)__ + +By default, shows informational output when running in a TTY (interactive terminal), and plain path output when piped or redirected. @@ -18,7 +26,6 @@ Checks ``ASTRARC`` __(ASTRARC=~/my_folder/.my_rc)__ -> ``XDG_CONFIG_HOME`` __($X == Options -`-p`, `--plain`:: Print only the path to the .astrarc file, without additional information `-o`, `--output`:: One of: human, json, csv `-V`, `--verbose`:: Enable verbose logging output `-q`, `--quiet`:: Only output essential information @@ -26,6 +33,8 @@ Checks ``ASTRARC`` __(ASTRARC=~/my_folder/.my_rc)__ -> ``XDG_CONFIG_HOME`` __($X `--no-input`:: Don't ask for user input (e.g. confirmation prompts) `--color`:: One of: auto, never, always `--dump-logs`:: Write all logs to an optionally specified file +`-p`, `--plain`:: Print only the path to the .astrarc file, without additional information (always) +`-i`, `--info`:: Print informational output with context about the path (always) == Examples @@ -34,8 +43,11 @@ Checks ``ASTRARC`` __(ASTRARC=~/my_folder/.my_rc)__ -> ``XDG_CONFIG_HOME`` __($X # Get information about the path to the .astrarc file $ astra config path -# Print only the path to the .astrarc file, without additional information +# Force only the plain path to the .astrarc file, without additional information $ astra config path -p + +# Force informational output even when piped or redirected +$ astra config path -i ---- diff --git a/modules/commands/pages/astra-config-use.adoc b/modules/commands/pages/astra-config-use.adoc index c74488f..f205e4e 100644 --- a/modules/commands/pages/astra-config-use.adoc +++ b/modules/commands/pages/astra-config-use.adoc @@ -17,7 +17,7 @@ Sets an existing profile to be used as the default for all commands. Use the ``- == Options `NAME`:: Profile to set as default -`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. `-o`, `--output`:: One of: human, json, csv `-V`, `--verbose`:: Enable verbose logging output `-q`, `--quiet`:: Only output essential information diff --git a/modules/commands/pages/astra-config.adoc b/modules/commands/pages/astra-config.adoc index 70f3bdb..51d6d33 100644 --- a/modules/commands/pages/astra-config.adoc +++ b/modules/commands/pages/astra-config.adoc @@ -27,7 +27,7 @@ Manage your Astra CLI configuration profiles == Options -`-cf`, `--config-file`:: The .astrarc file to work with. See ``@{cli.name} config path -h`` for how this is resolved. +`-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved. `-e`, `--env`:: Filter by Astra environment `-o`, `--output`:: One of: human, json, csv `-V`, `--verbose`:: Enable verbose logging output diff --git a/modules/commands/pages/astra-setup.adoc b/modules/commands/pages/astra-setup.adoc index c70c729..7916f5a 100644 --- a/modules/commands/pages/astra-setup.adoc +++ b/modules/commands/pages/astra-setup.adoc @@ -10,7 +10,7 @@ astra setup [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] Interactively set up the Astra CLI and create profiles -See ``@{cli.name} config create`` for a programmatic way to create profiles without interaction. +See ``astra config create`` for a programmatic way to create profiles without interaction. diff --git a/modules/commands/pages/astra-shellenv.adoc b/modules/commands/pages/astra-shellenv.adoc index b4c9e8c..f53fb33 100644 --- a/modules/commands/pages/astra-shellenv.adoc +++ b/modules/commands/pages/astra-shellenv.adoc @@ -2,7 +2,8 @@ [source,shell] ---- -astra shellenv [--ignore-multiple-paths] [--no-update-notifier] [--home=<$home>] +astra shellenv [--ignore-multiple-paths] [--no-update-notifier] + [--home=<$home>] [--rc=<$rc>] ---- @@ -17,7 +18,7 @@ Eval-ing the output of this command will: * Optionally set any other configuration environment variables. -Intended to be added to your shell profile (``.zshrc``, ``.zprofile``, ``.bashrc``, etc.), but you can technically just eval it in any shell session to get completions and update your PATH for that session. +Intended to be added to your shell profile (``.zprofile``, ``.bash_profile``, ``.profile``, etc.), but you can technically just eval it in any shell session to get completions and update your PATH for that session. @@ -26,6 +27,7 @@ Intended to be added to your shell profile (``.zshrc``, ``.zprofile``, ``.bashrc == Options `--home`:: Sets the ``ASTRA_HOME`` env var. See ``astra config home path -h`` for how this is resolved. +`--rc`:: Sets the ``ASTRARC`` env var. See ``astra config path -h`` for how this is resolved. `--ignore-multiple-paths`:: Ignore warnings about multiple home folders or astrarc files being present. Sets ``ASTRA_IGNORE_MULTIPLE_PATHS=true`` under the hood. `--no-update-notifier`:: Disables background update checks notifications. Sets ``ASTRA_NO_UPDATE_NOTIFIER=true`` under the hood. @@ -39,6 +41,9 @@ $ eval "$(/path/to/astra shellenv)" # Set a custom ``ASTRA_HOME`` path $ eval "$(/path/to/astra shellenv --home /path/to/astra/home)" +# Set a custom ``ASTRARC`` path +$ eval "$(/path/to/astra shellenv --rc /path/to/astrarc)" + # Disable update notifications $ eval "$(/path/to/astra shellenv --no-update-notifier)" diff --git a/modules/commands/pages/astra-upgrade.adoc b/modules/commands/pages/astra-upgrade.adoc index 4919ee6..1bca3ab 100644 --- a/modules/commands/pages/astra-upgrade.adoc +++ b/modules/commands/pages/astra-upgrade.adoc @@ -2,8 +2,8 @@ [source,shell] ---- -astra upgrade [-qVy] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] - [--color=WHEN] [-o=FORMAT] [-v=TAG | --pre] +astra upgrade [-qVy] [--allow-reinstall] [--no-input] [--[no-]spinner] + [--dump-logs[=FILE]] [--color=WHEN] [-o=FORMAT] [-v=TAG | --pre] ---- @@ -21,6 +21,7 @@ To opt out of Update notifications, set ``ASTRA_NO_UPDATE_NOTIFIER=true``, or, e == Options `-y`, `--yes`:: Install the upgrade without any confirmation prompting +`--allow-reinstall`:: Allow re-installing the same version `-o`, `--output`:: One of: human, json, csv `-V`, `--verbose`:: Enable verbose logging output `-q`, `--quiet`:: Only output essential information From d50d780709fc74e7cdc74d888360d303861ebcff Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Mon, 10 Nov 2025 15:16:33 -0600 Subject: [PATCH 10/29] Update install and upgrade content --- modules/ROOT/pages/install.adoc | 77 ++++++++++++++++++++++--------- modules/ROOT/pages/uninstall.adoc | 48 +++++++++++-------- modules/ROOT/pages/upgrade.adoc | 17 ++++--- 3 files changed, 94 insertions(+), 48 deletions(-) diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 782ce2c..317668e 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -38,14 +38,25 @@ If you prefer to use a package manager, follow the Homebrew instructions instead Scripted installation (recommended):: + -- -. Run the following Bash script to install the latest version of the {product} to the default location: +. Run the following command to install the latest version of the {product} to the default location: + -[source,bash] +[source,shell] ---- curl -sSL ibm.biz/astra-cli | sh ---- + -To install the {product} to a custom location, export the `ASTRA_HOME` environment variable first. +.Install to a custom location +[%collapsible] +==== +To install the {product} to a custom location, export the `ASTRA_HOME` environment variable before running the installation command: + +[source,bash,subs="+quotes"] +---- +export ASTRA_HOME=**INSTALLATION_DIRECTORY** +---- + +Replace `**INSTALLATION_DIRECTORY**` with the full path to your preferred installation directory. +==== . Add the following lines to your shell profile (for example, `~/.zprofile` or `~/.bash_profile`) to make the `astra` command executable from any directory: + @@ -59,7 +70,7 @@ eval "$(~/.astra/cli/astra shellenv)" . Run the `astra` command from any directory to verify successful installation: + -[source,bash] +[source,shell] ---- astra ---- @@ -75,10 +86,16 @@ Binary installation:: . Extract the archive into the directory where you want to install the {product}. For example: + -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -sudo tar -xzvf astra-macos-arm64.tar.gz -C **INSTALLATION_DIRECTORY** +sudo tar -xzvf astra-**OS**-**ARCHITECTURE**.tar.gz -C **INSTALLATION_DIRECTORY** ---- ++ +Replace the following: ++ +* `**OS**`: Your operating system (`macos` or `linux`). +* `**ARCHITECTURE**`: Your CPU architecture (`x86_64` or `arm64`). +* `**INSTALLATION_DIRECTORY**`: The full path to your preferred installation directory. . Add the following lines to your shell profile (for example, `~/.zprofile` or `~/.bash_profile`) to make the `astra` command executable from any directory: + @@ -90,20 +107,22 @@ eval "$(**PATH_TO_BINARY** shellenv)" + Replace `**PATH_TO_BINARY**` with the full path to the `astra` executable in the installation directory. -. Reload your shell profile or open a new terminal window. - . On macOS: Delete the `com.apple.quarantine` attribute from the `astra` binary to remove https://support.apple.com/guide/security/gatekeeper-and-runtime-protection-sec5599b66df/web[macOS Gatekeeper restrictions]: + -[source,bash] +[source,shell] ---- xattr -d com.apple.quarantine $(which astra) ---- + Alternatively, you can remove these restrictions in your https://support.apple.com/en-us/102445#openanyway[macOS System Settings]. ++ +If you don't remove the restrictions, you will receive a security alert stating `“astra” Not Opened` when you run the `astra` command. + +. Reload your shell profile or open a new terminal window. . Run the `astra` command from any directory to verify successful installation: + -[source,bash] +[source,shell] ---- astra ---- @@ -121,20 +140,31 @@ Select one of the following installation methods to install the {product} on Win Scripted installation (recommended):: + -- -. Run the following PowerShell script to install the latest version of the {product} to the default location: +. Run the following command to install the latest version of the {product} to the default location: + -[source,shell] +[source,powershell] ---- powershell -c "irm ibm.biz/astra-cli-win | iex" ---- + -To install the {product} to a custom location, export the `ASTRA_HOME` environment variable first. +.Install to a custom location +[%collapsible] +==== +To install the {product} to a custom location, export the `ASTRA_HOME` environment variable before running the installation command: -. Start a new PowerShell session by opening a new terminal window. +[source,powershell,subs="+quotes"] +---- +$env:ASTRA_HOME = "C:\path\to\your\custom\directory" +---- + +Replace `**INSTALLATION_DIRECTORY**` with the full path to your preferred installation directory. +==== + +. Reload your shell profile or open a new terminal window. . Run the `astra` command from any directory to verify successful installation: + -[source,bash] +[source,powershell] ---- astra ---- @@ -145,14 +175,19 @@ The response includes available commands and options for the {product}. Binary installation:: + -- -. Download the `windows` zip file from https://github.com/datastax/astra-cli/releases[GitHub]. +. Download the appropriate `windows` zip file for your CPU architecture from https://github.com/datastax/astra-cli/releases[GitHub]. . Extract the zip file into the directory where you want to install the {product}: + -[source,shell,subs="+quotes"] +[source,powershell,subs="+quotes"] ---- -powershell -C "Expand-Archive -Path astra-windows-x86_64.zip -DestinationPath **INSTALLATION_DIRECTORY** -Force" +powershell -C "Expand-Archive -Path astra-windows-**ARCHITECTURE**.zip -DestinationPath **INSTALLATION_DIRECTORY** -Force" ---- ++ +Replace the following: ++ +* `**ARCHITECTURE**`: Your CPU architecture (`x86_64` or `arm64`). +* `**INSTALLATION_DIRECTORY**`: The full path to your preferred installation directory. . Add the path to the unzipped `astra.exe` file to your `PATH` environment variable. To learn how to update environment variables, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. @@ -161,7 +196,7 @@ To learn how to update environment variables, see the https://learn.microsoft.co . Run the `astra` command from any directory to verify successful installation: + -[source,bash] +[source,powershell] ---- astra ---- @@ -175,14 +210,14 @@ Homebrew:: -- . Install the latest version of the {product} using https://brew.sh/[Homebrew]: + -[source,bash] +[source,shell] ---- brew install datastax/astra-cli/astra ---- . Run the `astra` command from any directory to verify successful installation: + -[source,bash] +[source,shell] ---- astra ---- diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index ea6a19c..29aa51e 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -11,19 +11,19 @@ Select one of the following methods to uninstall the {product} on macOS and Linu + [tabs] ===== -Nuke command (recommended):: +`astra nuke` command (recommended):: + -- Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: -[source,bash] +[source,shell] ---- astra nuke ---- -When prompted to confirm, type kbd:[y] and press kbd:[Enter]. +When prompted, type kbd:[y] and press kbd:[Enter] to proceed with the uninstallation. -The `astra nuke` command deletes the {product} home directory and optionally the configuration file (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`). +The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`). It also lists any shell profile containing references to the `astra` command. Delete these references manually if desired. -- @@ -33,21 +33,21 @@ Manual removal:: -- . Optional: Remove the `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[.astrarc]` file if you don't need your credentials anymore: + -[source,bash] +[source,shell] ---- rm $(astra config path -p) ---- . Delete the https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[{product} home directory] + -[source,bash] +[source,shell] ---- rm -rf $(astra config home path -p) ---- . Remove the `astra` binary if it still exists + -[source,bash] +[source,shell] ---- rm -f $(which astra) ---- @@ -65,7 +65,7 @@ Select one of the following methods to uninstall the {product} on Windows: Uninstaller (recommended):: + -- -*Note:* This method assumes you installed the {product} using the xref:install.adoc#_install_the_astra_cli[scripted installer]. +Only use this method if you installed the {product} using the xref:ROOT:install.adoc[scripted installer]. . Optional: Remove the `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[.astrarc]` file if you don't need your credentials anymore: + @@ -73,12 +73,18 @@ Uninstaller (recommended):: ---- rm -f $(astra config path -p) ---- -. Navigate to the https://support.microsoft.com/en-us/windows/uninstall-or-remove-apps-and-programs-in-windows-4b55f974-2cc6-2d2b-d092-5905080eaf98[Add or Remove Programs] settings page. -. Locate {product} in the list of installed applications. -. Select {product} and click kbd:[Uninstall]. + +. Go to *Start > Settings > Apps > Installed apps*. +Find the {product}, select icon:ellipsis-vertical[name="More"], and then select *Uninstall*. ++ +[NOTE] +==== +The steps to locate and uninstall applications may vary depending on your version of Windows. +For detailed instructions, see the https://support.microsoft.com/en-us/windows/uninstall-or-remove-apps-and-programs-in-windows-4b55f974-2cc6-2d2b-d092-5905080eaf98[Microsoft Windows documentation]. +==== -- -Nuke command:: +`astra nuke` command:: + -- Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: @@ -88,11 +94,12 @@ Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: astra nuke ---- -When prompted to confirm, type kbd:[y] and press kbd:[Enter]. +When prompted, type kbd:[y] and press kbd:[Enter] to proceed with the uninstallation. -The `astra nuke` command deletes the {product} home directory and optionally the configuration file (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`). +The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`). -You will still need to remove `astra` from your system PATH manually. +You must remove `astra` from your system `PATH` manually, if desired. +For more information, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. -- Manual removal:: @@ -119,26 +126,27 @@ rm -r -f $(astra config home path -p) rm -f (Get-Command astra).Source ---- -. Remove `astra` from your system PATH. +. Remove `astra` from your system `PATH`. +For more information, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. -- ===== Homebrew:: + -- -. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and optionally the configuration file (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`): +. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and optionally the configuration files (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`): + -[source,bash] +[source,shell] ---- astra nuke ---- + -When prompted to confirm, type kbd:[y] and press kbd:[Enter]. +When prompted, type kbd:[y] and press kbd:[Enter] to proceed. . Uninstall the {product} using Homebrew: + -[source,bash] +[source,shell] ---- brew uninstall datastax/astra-cli/astra ---- diff --git a/modules/ROOT/pages/upgrade.adoc b/modules/ROOT/pages/upgrade.adoc index 6cc2344..41d8bb2 100644 --- a/modules/ROOT/pages/upgrade.adoc +++ b/modules/ROOT/pages/upgrade.adoc @@ -3,7 +3,10 @@ Keep the {product} up to date to access new features, improvements, and security updates. -Follow the instructions for your original installation method to upgrade the {product}. +[NOTE] +==== +If you used a package manager to install the {product}, such as Homebrew, then you must use the same package manager to upgrade the {product}. +==== [tabs,sync-group-id=platforms] ====== @@ -12,14 +15,14 @@ macOS and Linux:: -- . Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: + -[source,bash] +[source,shell] ---- astra upgrade ---- . Optional: Upgrade to a specific version of the {product}: + -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- astra upgrade --version **VERSION** ---- @@ -28,7 +31,7 @@ You can also use this command to downgrade to a previous version. . Check the {product} version to verify that the upgrade was successful: + -[source,bash] +[source,shell] ---- astra --version ---- @@ -57,7 +60,7 @@ You can also use this command to downgrade to a previous version. . Check the {product} version to verify that the upgrade was successful: + -[source,bash] +[source,powershell] ---- astra --version ---- @@ -70,14 +73,14 @@ Homebrew:: -- . Run the following command to upgrade to the latest version of the {product}: + -[source,bash] +[source,shell] ---- brew upgrade datastax/astra-cli/astra ---- . Check the {product} version to verify that the upgrade was successful: + -[source,bash] +[source,shell] ---- astra --version ---- From f996a991c8511a8d0f3de77a6170b32ba7d73ab4 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Tue, 11 Nov 2025 02:04:31 -0600 Subject: [PATCH 11/29] Update manging info --- modules/ROOT/pages/install.adoc | 2 +- modules/ROOT/pages/use-cli.adoc | 306 ++++++++++++++++---------------- 2 files changed, 154 insertions(+), 154 deletions(-) diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 317668e..185c97c 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -4,7 +4,7 @@ Install the {product} to create and manage {astra_db} databases and {astra_stream} tenants from the command line. -== Platform compatibility +== Supported platforms The {product} supports the following operating systems: diff --git a/modules/ROOT/pages/use-cli.adoc b/modules/ROOT/pages/use-cli.adoc index 413e413..fc6ff88 100644 --- a/modules/ROOT/pages/use-cli.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -1,25 +1,53 @@ -= Connect and configure the {product} -:navtitle: Connect and configure += Connect and manage the {product} +:navtitle: Connect and manage the CLI -Initialize the {product} and run your first commands. +Learn how to connect and run commands with the {product}. -== Connect to {product-short} +If you haven't installed the {product} yet, see xref:ROOT:install.adoc[]. -After xref:ROOT:install.adoc[installing the {product}], follow these steps to set up your first connection profile: +== Get an application token -. {astra-url}[Sign in or create an {product-short} account.^] +The {product} requires an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] to connect to {product-short}. -. Generate an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] with a role that has adequate permissions to perform the tasks you want to accomplish with the {product}. +xref:astra-db-serverless:administration:manage-application-tokens.adoc#org-token[Generate an application token] and copy the token string (`AstraCS:…`) before moving on to the next section. + +[TIP] +==== +If this is your first time using the {product}, {company} recommends that you connect it to a non-production organization first. +That way, you can assign your application token a more expansive role, such as *Organization Administrator*, to try out all of the {product}'s features without putting production data at risk. + +If you're using the{product} in production, {company} strongly recommends that you assign your application token only the bare minimum permissions required to perform the intended tasks. +==== + +== Connect the {product} + +You can configure the {product} to authenticate in the following ways: + +Save configuration profiles:: +Configuration profiles let you save and manage connection information for use in {product} sessions. + --- -* *Non-production organizations*: If your {product-short} organization has no databases or streaming tenants that handle sensitive information, you can grant your application token the `Organization Administrator` role to try out all of the {product} features. +Each configuration profile consists of a name and an application token. +When you set a profile as the default, the {product} authenticates all commands using that profile's application token, unless overridden. ++ +See <>. -* *Production organizations*: If you're using {product-short} in production, {company} recommends that you use a more limited xref:astra-db-serverless:administration:manage-database-access.adoc#built-in-organization-roles[built-in role] or xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom role] to grant your application token the bare minimum permissions required to perform your desired tasks with the {product}. --- +Authenticate individual commands:: +You can supply an application token to authenticate individual commands. ++ +This method is useful if you want to run a command without having to create a configuration profile. ++ +See <>. + +[#create-first-configuration-profile] +=== Create your first configuration profile + +The following procedure describes how to create your first configuration profile interactively, and is recommended for users who are new to the {product}. + +For more advanced methods of creating and using configuration profiles, see <>. -. Run the `astra setup` command to to create your first connection profile: +. Run the `xref:commands:astra-setup.adoc[astra setup]` command: + -[source,bash] +[source,shell] ---- astra setup ---- @@ -27,7 +55,7 @@ astra setup .Result [%collapsible] ==== -[source,console,subs="+attributes"] +[source,console] ---- _____ __ / _ \ _______/ |_____________ @@ -36,7 +64,7 @@ astra setup \____|__ /____ > |__| |__| (____ / \/ \/ \/ - Version: {product-version} + Version: x.x.x Welcome to the Astra CLI setup! @@ -53,63 +81,73 @@ Press Enter to continue, or use Ctrl+C to cancel. ---- ==== -. When prompted, enter your {product-short} application token and press kbd:[Enter]. +. Press kbd:[Enter] to continue. + +. Enter your application token (`AstraCS:...`), and press kbd:[Enter]. -. Enter a name for your connection profile or press kbd:[Enter] to accept the default (your organization name). +. Enter a name for your configuration profile, or press kbd:[Enter] to accept the default (your organization name). + .Result [%collapsible] ==== -[source,console,subs="+quotes"] +[source,console] ---- Profile PROFILE_NAME successfully created. It has been set as the default profile. ---- ==== ++ +The {product} automatically sets the configuration profile as the default. +All subsequent commands use this profile unless you override it. -. Test your connection by running a simple command, such as listing your databases: +. Run a command to test the connection. +For example: ++ +[source,shell] +---- +astra db list-clouds +---- + -[source,bash] +.Result +[%collapsible] +==== +[source,console] ---- -astra db list +┌─────────────────┐ +│ Cloud Provider │ +├─────────────────┤ +│ gcp │ +│ azure │ +│ aws │ +└─────────────────┘ ---- +==== + If the command succeeds, your connection is configured correctly. -If your command fails, see the xref:commands:astra-setup.adoc[astra setup command] documentation for troubleshooting tips. - -[#file-locations] -== Installation file locations -The {product} and its configuration are installed in the following locations: -[cols="1,2"] -|=== -|File location |Description - -|`~/.astra` -a|The {product} installation directory. -For <>, the `astra` executable and `astra-init.sh` auto-completion script are located in `~/.astra/cli`. -The `~/.astra/cli` folder is added to the `PATH` environment variable. -_This folder is deleted and recreated when you update or re-install the {product}._ +[#authenticate-individual-command] +=== Authenticate an individual command -For <>, the `astra` executable and auto-completion script are located in https://docs.brew.sh/FAQ#why-should-i-install-homebrew-in-the-default-location[Homebrew's default prefix] at the following locations: +Every command lets you supply an application token using the `--token` option. +This method is useful if you want to run a command without having to create a configuration profile. -* Executable: `HOMEBREW_PREFIX/Cellar/astra-cli/VERSION/bin/astra` -* Auto-completion script: `HOMEBREW_PREFIX/Cellar/astra-cli/VERSION/etc/bash_completion.d/astra` +For example: -|`~/.astrarc` -|The {product} configuration file. +[source,shell,subs="+quotes"] +---- +astra user list --token "**APPLICATION_TOKEN**" +---- -_This file is *not* deleted when you update or re-install the {product}._ -|=== +The `--token` option bypasses the default configuration profile (if one exists) and uses the supplied application token for that command only. -== Print help information +== Get command help -Simply print `astra` to print general {product} help information: +Run `astra` by itself to print general help information: -[source,bash] +[source,shell] ---- astra ---- @@ -119,7 +157,6 @@ astra ==== [source,console] ---- - _____ __ / _ \ _______/ |_____________ / /_\ \ / ___/\ __\_ __ \__ \ @@ -127,7 +164,7 @@ astra \____|__ /____ > |__| |__| (____ / \/ \/ \/ - Version: 1.0.0-rc.4 + Version: x.x.x Documentation: https://docs.datastax.com/en/astra-cli @@ -141,7 +178,7 @@ Common Options: --color=WHEN One of: auto, never, always (default: auto) --dump-logs[=FILE] Write all logs to an optionally specified file - (default: ~/.astra-dev/logs/.log) + (default: ~/.astra/logs/.log) --no-input Don't ask for user input (e.g. confirmation prompts) -o, --output=FORMAT One of: human, json, csv (default: human) @@ -178,28 +215,35 @@ See 'astra --help' for help on a specific subcommand. ---- ==== -Use the `--help` (or `-h`) flag to print help information and examples for an individual command: +Append the `-h`/`--help` option to any command or subcommand to get specific help information and examples: +[source,shell] +---- +astra org --help +---- .Result [%collapsible] ==== [source,console] ---- -Usage: astra db [-qvV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] - [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | - [--token=TOKEN [--env=ENV]]] [COMMAND] +Usage: astra org [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]] + [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] | + [--token=TOKEN [--env=ENV]]] [COMMAND] -Manage your Astra databases +Get organization information + +The --token flag is handy to quickly get information about another organization. + +Use the --token @file syntax to read the token from a file, to avoid potential +leaks. - -v, --vector Only show vector-enabled databases - (default: false) Common Options: --color=WHEN One of: auto, never, always (default: auto) --dump-logs[=FILE] Write all logs to an optionally specified file - (default: ~/.astra-dev/logs/.log) + (default: ~/.astra/logs/.log) --no-input Don't ask for user input (e.g. confirmation prompts) -o, --output=FORMAT One of: human, json, csv (default: human) @@ -211,7 +255,7 @@ Common Options: Connection Options: -cf, --config-file=PATH The .astrarc file to use for this command - (default: ~/.astrarc-dev) + (default: ~/.astrarc) --env=ENV Override the target astra environment -p, --profile=NAME The .astrarc profile to use for this command --token=TOKEN The astra token to use for this command. Use the @@ -219,72 +263,16 @@ Connection Options: file, to avoid potential leaks. Commands: - list List your non-terminated Astra databases. - get, describe Get information about a specific database. - create Create a new Astra database - delete Delete an existing Astra database - status Get the current status of a database. - cqlsh Connect to your Astra database using cqlsh - dsbulk Use dsbulk to interface with your Astra DB database - create-dotenv Create a env file to help you connect to your Astra - DB instance. - download-scb Download secure connect bundle for a database - resume Resume a database that is in a stopped state. If - the database is already active, no action is - taken. - list-keyspaces List all keyspaces in the specified database - create-keyspace Create a new keyspace in the specified database - delete-keyspace Delete a keyspace from the specified database - list-collections List the collections in the specified database and - keyspace - create-collection Create a new Data API collection in the specified - database and keyspace - describe-collection Describe an existing Data API collection with - detailed information including vector - configuration and indexing options - delete-collection Delete an existing Data API collection from the - specified database and keyspace - truncate-collection Atomically delete all documents in a Data API - collection - list-tables List the tables in the specified database and - keyspace - describe-table Describe an existing table with detailed - information including columns and primary key - structure - delete-table Delete an existing table from the specified - database and keyspace - truncate-table Atomically delete all rows in a table - list-embedding-providers Find all available embedding providers for a given - database - list-cdcs List all CDC (Change Data Capture) connections for - the specified database - create-cdc Create a CDC (Change Data Capture) for a table in a - specific keyspace and tenant. - delete-cdc Delete a CDC (Change Data Capture) from the database - create-region Add a new region to an existing database - delete-region Delete a region from an existing database - list-regions List the regions for the given database - list-regions-classic List all available regions for classic Astra DB - databases - list-regions-serverless List all available regions for serverless Astra DB - databases - list-regions-vector List all available regions for vector Astra DB - databases - list-clouds List all cloud providers with regions available for - Astra DB - get-endpoint-swagger Get the SwaggerUI endpoint for the specified - database - get-endpoint-api Get the API endpoint to interact with the specified - database - get-endpoint-playground Get the GraphQL Playground for the specified - database + get Get your organization's information + id Get your organization's ID + name Get your organization's name Examples: - # List all your Astra databases - $ astra db + # Get your organization's information + $ astra org - # List only vector-enabled Astra databases - $ astra db --vector + # Get information about another organization + $ astra org get --token AstraCS:... See 'astra --help' for help on a specific subcommand. ---- @@ -292,7 +280,7 @@ See 'astra --help' for help on a specific subcommand. Append a subcommand for further specificity: -[source,bash] +[source,shell] ---- astra db list --help ---- @@ -315,7 +303,7 @@ Common Options: --color=WHEN One of: auto, never, always (default: auto) --dump-logs[=FILE] Write all logs to an optionally specified file - (default: ~/.astra-dev/logs/.log) + (default: ~/.astra/logs/.log) --no-input Don't ask for user input (e.g. confirmation prompts) -o, --output=FORMAT One of: human, json, csv (default: human) @@ -327,7 +315,7 @@ Common Options: Connection Options: -cf, --config-file=PATH The .astrarc file to use for this command - (default: ~/.astrarc-dev) + (default: ~/.astrarc) --env=ENV Override the target astra environment -p, --profile=NAME The .astrarc profile to use for this command --token=TOKEN The astra token to use for this command. Use the @@ -345,15 +333,14 @@ See 'astra --help' for help on a specific subcommand. ---- ==== -== Using auto-completion +[#command-auto-completion] +== Use command auto-completion -The {product} provides Bash auto-completion for `bash` and `zsh` shells. +The {product} provides command auto-completion for Bash and ZSH shells. -See the xref:install.adoc[installation instructions] for your platform to enable auto-completion. +To use auto-completion, type the `astra` command and then press kbd:[Tab] twice to get a list of available options: -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"] +[source,shell,subs="+macros"] ---- astra kbd:[Tab] kbd:[Tab] ---- @@ -369,10 +356,9 @@ db org role shellenv token user ==== Certain dynamic arguments, such as database names, also support auto-completion once the CLI discovers them. +For example, after running `astra db list`, type `astra db get` followed by kbd:[Tab] twice to see a list of your database names: -For example, after running `astra db list`, type a `astra db get` followed by kbd:[Tab] twice to see a list of your database names. - -[source,bash,subs="macros"] +[source,shell,subs="macros"] ---- astra db get kbd:[Tab] kbd:[Tab] ---- @@ -386,10 +372,10 @@ prod_db test_db playground_db ---- ==== -[#manage-configuration] -== Manage your {product} configuration +[#manage-configuration-profiles] +== Manage configuration profiles -When you run the `astra setup` command during <>, the {product} stores your application token as the default configuration in the `~/.astrarc` configuration file. +If you ran the `astra setup` command to <>, the {product} automatically sets it as the default configuration profile. stores your application token as the default configuration in the `~/.astrarc` configuration file. You can create additional configuration profiless, each with their own application token, to make it easier to manage different types of resources across one or more organizations. @@ -397,7 +383,7 @@ You can create additional configuration profiless, each with their own applicati . Use `astra config list` to list all current configuration profiles: + -[source,bash] +[source,shell] ---- astra config list ---- @@ -418,7 +404,7 @@ astra config list . Use `astra config create` or `astra setup` again to create a new configuration profile: + -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- astra config create "**CONFIG_NAME**" --token **APPLICATION_TOKEN** ---- @@ -439,7 +425,7 @@ $ astra config use **CONFIG_NAME** . Use `astra config use` to change the default configuration that {product} uses when executing commands: + -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- astra config use "**CONFIG_NAME**" ---- @@ -461,25 +447,16 @@ Every {product} command supports the `--profile` option. This option lets you use a different configuration profile when running a command without changing the default configuration profile. For example: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- astra user list --config "**CONFIG_NAME**" ---- -Alternatively, you can use the `--token` option to supply an application token when running a command. -This option lets you use a different application token without having to create a new configuration. -For example: - -[source,bash,subs="+quotes"] ----- -astra user list --token "**APPLICATION_TOKEN**" ----- - === Delete a configuration profile Use `astra config delete` to delete a configuration profile: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- astra config delete "**CONFIG_NAME**" ---- @@ -499,8 +476,31 @@ If you delete the default configuration, the {product} _doesn't_ automatically s Use the `astra config use` command to select a new default configuration. ==== -== Next steps +[#file-locations] +== {product} file locations + +The {product} stores installation and configuration files in the following locations: + +[cols="1h,2"] +|=== +|File / Directory |Description + +|`.astra` +a|The `ASTRA_HOME` directory. + +_Default location_: `~/.astra` (macOS and Linux), `%USERPROFILE%\.astra` (Windows) + +The {product} stores the following items in this directory: + +* The {product} executable (scripted installations only) +* Accessory executables for commands like `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]` +* Cache files for <> +* Logs -* xref:ROOT:managing.adoc[] -* xref:ROOT:astra-streaming-cli.adoc[] -* xref:ROOT:administration.adoc[] +|`.astrarc` +|The {product} configuration file. + +_Default location_: `~/.astrarc` (macOS and Linux), `%USERPROFILE%\.astrarc` (Windows) + +This file stores your <> and their associated application tokens. +|=== From 130b140ad7931c4c812c01051a9d50908a319669 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Tue, 11 Nov 2025 02:07:09 -0600 Subject: [PATCH 12/29] minor edits --- modules/ROOT/pages/use-cli.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/ROOT/pages/use-cli.adoc b/modules/ROOT/pages/use-cli.adoc index fc6ff88..b6ec755 100644 --- a/modules/ROOT/pages/use-cli.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -219,7 +219,7 @@ Append the `-h`/`--help` option to any command or subcommand to get specific hel [source,shell] ---- -astra org --help +astra org -h ---- .Result @@ -278,8 +278,6 @@ See 'astra --help' for help on a specific subcommand. ---- ==== -Append a subcommand for further specificity: - [source,shell] ---- astra db list --help From b743ab16ccd54ce1b9d7cf7f677093c268b17cb1 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Tue, 11 Nov 2025 15:10:16 -0600 Subject: [PATCH 13/29] Polish up management content --- modules/ROOT/pages/use-cli.adoc | 123 +++++++++++++++++++++----------- 1 file changed, 83 insertions(+), 40 deletions(-) diff --git a/modules/ROOT/pages/use-cli.adoc b/modules/ROOT/pages/use-cli.adoc index b6ec755..5b60be2 100644 --- a/modules/ROOT/pages/use-cli.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -13,12 +13,13 @@ xref:astra-db-serverless:administration:manage-application-tokens.adoc#org-token [TIP] ==== -If this is your first time using the {product}, {company} recommends that you connect it to a non-production organization first. +If this is your first time using the {product}, {company} recommends that you connect to a non-production organization first. That way, you can assign your application token a more expansive role, such as *Organization Administrator*, to try out all of the {product}'s features without putting production data at risk. -If you're using the{product} in production, {company} strongly recommends that you assign your application token only the bare minimum permissions required to perform the intended tasks. +If you're using the {product} in production, {company} strongly recommends that you assign your application token only the bare minimum permissions required to perform the intended tasks. ==== +[#connect-to-astra] == Connect the {product} You can configure the {product} to authenticate in the following ways: @@ -43,9 +44,9 @@ See <>. The following procedure describes how to create your first configuration profile interactively, and is recommended for users who are new to the {product}. -For more advanced methods of creating and using configuration profiles, see <>. +For more advanced methods of creating and managing configuration profiles, see <>. -. Run the `xref:commands:astra-setup.adoc[astra setup]` command: +. Run the `xref:commands:astra-setup.adoc[]` command: + [source,shell] ---- @@ -126,23 +127,24 @@ astra db list-clouds + If the command succeeds, your connection is configured correctly. - - [#authenticate-individual-command] === Authenticate an individual command Every command lets you supply an application token using the `--token` option. -This method is useful if you want to run a command without having to create a configuration profile. +This option is useful if you want to run a command without having to create a configuration profile. For example: [source,shell,subs="+quotes"] ---- -astra user list --token "**APPLICATION_TOKEN**" +astra user list --token **APPLICATION_TOKEN** ---- The `--token` option bypasses the default configuration profile (if one exists) and uses the supplied application token for that command only. +Alternatively, if you have multiple application tokens saved in different configuration profiles, you can specify a configuration profile for an individual command. +See <>. + == Get command help Run `astra` by itself to print general help information: @@ -370,22 +372,35 @@ prod_db test_db playground_db ---- ==== +== Use resource names that contain space characters + +If the name of a resource contains one or more space characters, you must wrap the entire name in single quotes (''), otherwise the {product} will return an `Unmatched argument` or other similar error. + +For example, when creating a token with the role `Organization Administrator`, you must wrap the role name in single quotes: + +[source,shell,subs="+quotes"] +---- +astra token create --role **'Organization Administrator'** +---- + [#manage-configuration-profiles] == Manage configuration profiles -If you ran the `astra setup` command to <>, the {product} automatically sets it as the default configuration profile. stores your application token as the default configuration in the `~/.astrarc` configuration file. +Configuration profiles provide a convenient way to save and manage application tokens for <>. +Configuration profiles consist of a name and an application token and are stored in the `<>` configuration file. -You can create additional configuration profiless, each with their own application token, to make it easier to manage different types of resources across one or more organizations. +If you ran the `xref:commands:astra-setup.adoc[]` command to <>, the {product} automatically sets it as the default configuration profile. +You can create additional configuration profiles, each with their own application token, to make it easier to manage different types of resources across one or more organizations. -=== Get and set configurations +=== List your configuration profiles + +Use the `xref:commands:astra-config-list.adoc[]` command to list all of your configuration profiles: -. Use `astra config list` to list all current configuration profiles: -+ [source,shell] ---- astra config list ---- -+ + .Result [%collapsible] ==== @@ -400,63 +415,91 @@ astra config list ---- ==== -. Use `astra config create` or `astra setup` again to create a new configuration profile: -+ +The default configuration profile is indicated by `(in use)`. + +Configuration profiles are stored in the `<>` file in the following format: + +[source,ini,subs="+quotes"] +---- +[Production] +ASTRA_DB_APPLICATION_TOKEN=AstraCS:**IGXWg...** + +[default] +ASTRA_DB_APPLICATION_TOKEN=AstraCS:**IGXWg...** + +[Testing] +ASTRA_DB_APPLICATION_TOKEN=AstraCS:WeaYR... +---- + +The `[default]` profile references the application token of the default configuration profile. + +=== Create a new configuration profile + +Use the `xref:commands:astra-config-create.adoc[]` command to create a new configuration profile: + [source,shell,subs="+quotes"] ---- -astra config create "**CONFIG_NAME**" --token **APPLICATION_TOKEN** +astra config create '**CONFIG_NAME**' --token **APPLICATION_TOKEN** ---- -+ + .Result [%collapsible] ==== -[source,console,subs="+quotes"] +[source,console] ---- -Configuration profile '**CONFIG_NAME**' successfully created. +Configuration profile Development successfully created. -(Hint: Use 'astra setup' for an interactive profile creation experience!) +(Hint: Use astra setup for an interactive profile creation experience!) # Set it as the default profile: -$ astra config use **CONFIG_NAME** +$ astra config use Development ---- ==== -. Use `astra config use` to change the default configuration that {product} uses when executing commands: -+ +You can also use the `xref:commands:astra-setup.adoc[]` command again to create additional configuration profiles interactively. + +=== Set the default configuration profile + +Use the `xref:commands:astra-config-use.adoc[]` command to change the default configuration that the {product} uses when executing commands: + [source,shell,subs="+quotes"] ---- -astra config use "**CONFIG_NAME**" +astra config use '**CONFIG_NAME**' ---- -+ + .Result [%collapsible] ==== -[source,console,subs="+quotes"] +[source,console] ---- -Default profile set to '**CONFIG_NAME**'. +Default profile set to Development. ---- ==== -. Optional: Rerun `astra config list` to verify that the new default configuration is set. +[#specify-configuration-profile-individual-command] +=== Specify a configuration profile for an individual command -=== Set the configuration for a single run +Every command lets you specify a configuration profile using the `-p`/`--profile` option. +This method is useful if you want to run a command using a different configuration profile without changing the default configuration profile. -Every {product} command supports the `--profile` option. -This option lets you use a different configuration profile when running a command without changing the default configuration profile. For example: [source,shell,subs="+quotes"] ---- -astra user list --config "**CONFIG_NAME**" +astra user list --profile '**CONFIG_NAME**' ---- +The `--profile` option bypasses the default configuration profile and uses the supplied configuration profile for that command only. + +If you want to run a command using an application token directly, without having to create a new profile, see <>. + === Delete a configuration profile -Use `astra config delete` to delete a configuration profile: +Use the `xref:commands:astra-config-delete.adoc[]` command to delete a configuration profile: [source,shell,subs="+quotes"] ---- -astra config delete "**CONFIG_NAME**" +astra config delete '**CONFIG_NAME**' ---- .Result @@ -464,14 +507,14 @@ astra config delete "**CONFIG_NAME**" ==== [source,console,subs="+quotes"] ---- -Profile 'tem' deleted successfully. +Profile Development deleted successfully. ---- ==== -[IMPORTANT] +[NOTE] ==== -If you delete the default configuration, the {product} _doesn't_ automatically select a new default configuration. -Use the `astra config use` command to select a new default configuration. +If you delete the default configuration profile, the {product} _doesn't_ automatically select a new default configuration profile. +You must use the `xref:commands:astra-config-use.adoc[]` command to set a new default configuration profile. ==== [#file-locations] @@ -491,7 +534,7 @@ _Default location_: `~/.astra` (macOS and Linux), `%USERPROFILE%\.astra` (Window The {product} stores the following items in this directory: * The {product} executable (scripted installations only) -* Accessory executables for commands like `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]` +* Accessory executables downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]` * Cache files for <> * Logs From 56ea953f4e535bd5afb81770e5c616b8f2f9aebf Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Tue, 11 Nov 2025 18:04:33 -0600 Subject: [PATCH 14/29] Update results --- modules/ROOT/nav.adoc | 3 +- modules/ROOT/pages/use-cli.adoc | 97 ++++++++++++++++----------------- 2 files changed, 49 insertions(+), 51 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index d749438..7d915b9 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -7,4 +7,5 @@ include::ROOT:partial$partial-nav.adoc[] .Release notes -* https://github.com/datastax/astra-cli/releases[Release notes] +* https://github.com/datastax/astra-cli?tab=readme-ov-file#whats-changed[Release notes] +* https://github.com/datastax/astra-cli[GitHub repository] diff --git a/modules/ROOT/pages/use-cli.adoc b/modules/ROOT/pages/use-cli.adoc index 5b60be2..bf4f9d7 100644 --- a/modules/ROOT/pages/use-cli.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -14,7 +14,7 @@ xref:astra-db-serverless:administration:manage-application-tokens.adoc#org-token [TIP] ==== If this is your first time using the {product}, {company} recommends that you connect to a non-production organization first. -That way, you can assign your application token a more expansive role, such as *Organization Administrator*, to try out all of the {product}'s features without putting production data at risk. +That way, you can assign your application token a more expansive role, such as *Organization Administrator*, so that you can try out all of the {product}'s features without putting production data at risk. If you're using the {product} in production, {company} strongly recommends that you assign your application token only the bare minimum permissions required to perform the intended tasks. ==== @@ -67,24 +67,37 @@ astra setup Version: x.x.x -Welcome to the Astra CLI setup! +Welcome to the interactive Astra CLI setup! -A configuration file with your profile will be created at /Users/USERNAME/.astrarc - -If you'd prefer to provide credentials on a per-command basis rather than storing them in a file, you can either: -- Use the per-command --token flag to pass your existing AstraCS token directly. -- Use the per-command --config-file flag to specify an existing .astrarc file. - -# Example: -$ astra db list --token +Your configuration file will be created at /Users/USERNAME/.astrarc Press Enter to continue, or use Ctrl+C to cancel. ---- ==== . Press kbd:[Enter] to continue. ++ +.Result +[%collapsible] +==== +[source,console] +---- +(Required) Enter your Astra token (it should start with AstraCS) +> input hidden for security +---- +==== -. Enter your application token (`AstraCS:...`), and press kbd:[Enter]. +. Enter your application token (`AstraCS:...`), and then press kbd:[Enter]. ++ +.Result +[%collapsible] +==== +[source,console] +---- +(Optional) Enter a name for your profile (defaults to your org name) +> +---- +==== . Enter a name for your configuration profile, or press kbd:[Enter] to accept the default (your organization name). + @@ -93,14 +106,14 @@ Press Enter to continue, or use Ctrl+C to cancel. ==== [source,console] ---- -Profile PROFILE_NAME successfully created. +Profile 'PROFILE_NAME' successfully created. It has been set as the default profile. ---- ==== + The {product} automatically sets the configuration profile as the default. -All subsequent commands use this profile unless you override it. +All subsequent commands use this profile unless you <>. . Run a command to test the connection. For example: @@ -342,35 +355,20 @@ To use auto-completion, type the `astra` command and then press kbd:[Tab] twice [source,shell,subs="+macros"] ---- -astra kbd:[Tab] kbd:[Tab] ----- - -.Result -[%collapsible%open] -==== -[source,console] ----- +% astra kbd:[Tab] kbd:[Tab] config nuke pcu setup streaming upgrade db org role shellenv token user ---- -==== Certain dynamic arguments, such as database names, also support auto-completion once the CLI discovers them. -For example, after running `astra db list`, type `astra db get` followed by kbd:[Tab] twice to see a list of your database names: -[source,shell,subs="macros"] ----- -astra db get kbd:[Tab] kbd:[Tab] ----- +For example, after running `astra db list`, type `astra db get` followed by kbd:[Tab] twice to see a list of your database names: -.Result -[%collapsible%open] -==== -[source,console] +[source,shell,subs="+macros"] ---- +% astra db get kbd:[Tab] kbd:[Tab] prod_db test_db playground_db ---- -==== == Use resource names that contain space characters @@ -389,8 +387,7 @@ astra token create --role **'Organization Administrator'** Configuration profiles provide a convenient way to save and manage application tokens for <>. Configuration profiles consist of a name and an application token and are stored in the `<>` configuration file. -If you ran the `xref:commands:astra-setup.adoc[]` command to <>, the {product} automatically sets it as the default configuration profile. -You can create additional configuration profiles, each with their own application token, to make it easier to manage different types of resources across one or more organizations. +The following sections describe how to create additional configuration profiles, each with their own application token, to make it easier to manage different types of resources across one or more organizations. === List your configuration profiles @@ -406,12 +403,12 @@ astra config list ==== [source,console] ---- -┌───────────────────────────────────┐ -│ configuration │ -├───────────────────────────────────┤ -│ Production (in use) │ -│ Testing │ -└───────────────────────────────────┘ +┌─────────────────────┐ +│ configuration │ +├─────────────────────┤ +│ Production (in use) │ +│ Testing │ +└─────────────────────┘ ---- ==== @@ -439,7 +436,7 @@ Use the `xref:commands:astra-config-create.adoc[]` command to create a new confi [source,shell,subs="+quotes"] ---- -astra config create '**CONFIG_NAME**' --token **APPLICATION_TOKEN** +astra config create '**PROFILE_NAME**' --token **APPLICATION_TOKEN** ---- .Result @@ -447,12 +444,12 @@ astra config create '**CONFIG_NAME**' --token **APPLICATION_TOKEN** ==== [source,console] ---- -Configuration profile Development successfully created. +Configuration profile 'PROFILE_NAME' successfully created. -(Hint: Use astra setup for an interactive profile creation experience!) +(Hint: Use 'astra setup' for an interactive profile creation experience!) # Set it as the default profile: -$ astra config use Development +$ astra config use 'PROFILE_NAME' ---- ==== @@ -464,7 +461,7 @@ Use the `xref:commands:astra-config-use.adoc[]` command to change the default co [source,shell,subs="+quotes"] ---- -astra config use '**CONFIG_NAME**' +astra config use '**PROFILE_NAME**' ---- .Result @@ -472,7 +469,7 @@ astra config use '**CONFIG_NAME**' ==== [source,console] ---- -Default profile set to Development. +Default profile set to 'PROFILE_NAME'. ---- ==== @@ -486,7 +483,7 @@ For example: [source,shell,subs="+quotes"] ---- -astra user list --profile '**CONFIG_NAME**' +astra user list --profile '**PROFILE_NAME**' ---- The `--profile` option bypasses the default configuration profile and uses the supplied configuration profile for that command only. @@ -499,15 +496,15 @@ Use the `xref:commands:astra-config-delete.adoc[]` command to delete a configura [source,shell,subs="+quotes"] ---- -astra config delete '**CONFIG_NAME**' +astra config delete '**PROFILE_NAME**' ---- .Result [%collapsible] ==== -[source,console,subs="+quotes"] +[source,console] ---- -Profile Development deleted successfully. +Profile 'PROFILE_NAME' deleted successfully. ---- ==== From 2d531f3a4b32fae0b53a04497a0d83ca9b909842 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Tue, 11 Nov 2025 18:57:09 -0600 Subject: [PATCH 15/29] Reviewer feedback and other updates --- modules/ROOT/pages/install.adoc | 17 ++++++------- modules/ROOT/pages/uninstall.adoc | 16 ++++++------- modules/ROOT/pages/use-cli.adoc | 40 ++++++++++++++++++++----------- 3 files changed, 41 insertions(+), 32 deletions(-) diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 185c97c..5c5990a 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -13,13 +13,13 @@ The {product} supports the following operating systems: |Operating System |Architecture |Linux -|x86_64, arm64 +|`x86_64`, `arm64` |macOS -|x86_64, arm64 +|`x86_64`, `arm64` |Microsoft Windows -|x86_64 +|`x86_64` |=== == Install the {product} @@ -154,13 +154,13 @@ To install the {product} to a custom location, export the `ASTRA_HOME` environme [source,powershell,subs="+quotes"] ---- -$env:ASTRA_HOME = "C:\path\to\your\custom\directory" +$env:ASTRA_HOME = "**INSTALLATION_DIRECTORY**" ---- Replace `**INSTALLATION_DIRECTORY**` with the full path to your preferred installation directory. ==== -. Reload your shell profile or open a new terminal window. +. Open a new terminal window. . Run the `astra` command from any directory to verify successful installation: + @@ -181,13 +181,10 @@ Binary installation:: + [source,powershell,subs="+quotes"] ---- -powershell -C "Expand-Archive -Path astra-windows-**ARCHITECTURE**.zip -DestinationPath **INSTALLATION_DIRECTORY** -Force" +powershell -C "Expand-Archive -Path astra-windows-x86_64.zip -DestinationPath **INSTALLATION_DIRECTORY** -Force" ---- + -Replace the following: -+ -* `**ARCHITECTURE**`: Your CPU architecture (`x86_64` or `arm64`). -* `**INSTALLATION_DIRECTORY**`: The full path to your preferred installation directory. +Replace `**INSTALLATION_DIRECTORY**` with the full path to your preferred installation directory. . Add the path to the unzipped `astra.exe` file to your `PATH` environment variable. To learn how to update environment variables, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index 29aa51e..3124b9a 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -23,7 +23,7 @@ astra nuke When prompted, type kbd:[y] and press kbd:[Enter] to proceed with the uninstallation. -The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`). +The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`xref:ROOT:use-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:use-cli.adoc#file-locations[~/.astrarc]`). It also lists any shell profile containing references to the `astra` command. Delete these references manually if desired. -- @@ -31,14 +31,14 @@ Delete these references manually if desired. Manual removal:: + -- -. Optional: Remove the `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[.astrarc]` file if you don't need your credentials anymore: +. Optional: Remove the `xref:ROOT:use-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: + [source,shell] ---- rm $(astra config path -p) ---- -. Delete the https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[{product} home directory] +. Delete the xref:ROOT:use-cli.adoc#file-locations[{product} home directory] + [source,shell] ---- @@ -67,7 +67,7 @@ Uninstaller (recommended):: -- Only use this method if you installed the {product} using the xref:ROOT:install.adoc[scripted installer]. -. Optional: Remove the `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[.astrarc]` file if you don't need your credentials anymore: +. Optional: Remove the `xref:ROOT:use-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: + [source,powershell] ---- @@ -96,7 +96,7 @@ astra nuke When prompted, type kbd:[y] and press kbd:[Enter] to proceed with the uninstallation. -The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`). +The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`xref:ROOT:use-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:use-cli.adoc#file-locations[~/.astrarc]`). You must remove `astra` from your system `PATH` manually, if desired. For more information, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. @@ -105,14 +105,14 @@ For more information, see the https://learn.microsoft.com/en-us/powershell/modul Manual removal:: + -- -. Optional: Remove the `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[.astrarc]` file if you don't need your credentials anymore: +. Optional: Remove the `xref:ROOT:use-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: + [source,powershell] ---- rm -f $(astra config path -p) ---- -. Delete the https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[{product} home directory] +. Delete the xref:ROOT:use-cli.adoc#file-locations[{product} home directory] + [source,powershell] ---- @@ -134,7 +134,7 @@ For more information, see the https://learn.microsoft.com/en-us/powershell/modul Homebrew:: + -- -. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and optionally the configuration files (`https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[~/.astra]` and `https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[~/.astrarc]`): +. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and optionally the configuration files (`xref:ROOT:use-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:use-cli.adoc#file-locations[~/.astrarc]`): + [source,shell] ---- diff --git a/modules/ROOT/pages/use-cli.adoc b/modules/ROOT/pages/use-cli.adoc index bf4f9d7..23970d8 100644 --- a/modules/ROOT/pages/use-cli.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -360,7 +360,7 @@ config nuke pcu setup streaming upgrade db org role shellenv token user ---- -Certain dynamic arguments, such as database names, also support auto-completion once the CLI discovers them. +Certain dynamic arguments, such as database names, also support auto-completion once the {product} discovers them. For example, after running `astra db list`, type `astra db get` followed by kbd:[Tab] twice to see a list of your database names: @@ -370,17 +370,6 @@ For example, after running `astra db list`, type `astra db get` followed by kbd: prod_db test_db playground_db ---- -== Use resource names that contain space characters - -If the name of a resource contains one or more space characters, you must wrap the entire name in single quotes (''), otherwise the {product} will return an `Unmatched argument` or other similar error. - -For example, when creating a token with the role `Organization Administrator`, you must wrap the role name in single quotes: - -[source,shell,subs="+quotes"] ----- -astra token create --role **'Organization Administrator'** ----- - [#manage-configuration-profiles] == Manage configuration profiles @@ -414,8 +403,9 @@ astra config list The default configuration profile is indicated by `(in use)`. -Configuration profiles are stored in the `<>` file in the following format: +Configuration profiles are stored in the following format in the `<>` file: +..astrarc [source,ini,subs="+quotes"] ---- [Production] @@ -428,7 +418,8 @@ ASTRA_DB_APPLICATION_TOKEN=AstraCS:**IGXWg...** ASTRA_DB_APPLICATION_TOKEN=AstraCS:WeaYR... ---- -The `[default]` profile references the application token of the default configuration profile. +The `[default]` profile duplicates the application token of the configuration profile that is currently <>. +In the previous example, you can tell the `Production` profile is the default profile because `[Production]` and `[default]` have the same application token. === Create a new configuration profile @@ -455,6 +446,23 @@ $ astra config use 'PROFILE_NAME' You can also use the `xref:commands:astra-setup.adoc[]` command again to create additional configuration profiles interactively. +.Enclose arguments in quotes when they contain spaces +[TIP] +==== +When specifying arguments that contain spaces (for example, profile names like `Test 1`), you must wrap the value in single quotes (`''`). +This ensures the {product} treats the entire phrase as one argument rather than splitting it into separate words. + +For example: + +[source,shell,subs="+quotes"] +---- +astra config create **'Test 1'** --token AstraCS:... +---- + +Without quotes, the command would interpret `Test` and `1` as two different arguments and cause an `Unmatched argument` or other similar error. +==== + +[#set-default-configuration-profile] === Set the default configuration profile Use the `xref:commands:astra-config-use.adoc[]` command to change the default configuration that the {product} uses when executing commands: @@ -535,10 +543,14 @@ The {product} stores the following items in this directory: * Cache files for <> * Logs +For more information about the `ASTRA_HOME` directory, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[README]. + |`.astrarc` |The {product} configuration file. _Default location_: `~/.astrarc` (macOS and Linux), `%USERPROFILE%\.astrarc` (Windows) This file stores your <> and their associated application tokens. + +For more information about the {product} configuration file, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[README]. |=== From 81634c15524a1cd033d18c266ef67ce30cf87c83 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Tue, 11 Nov 2025 20:32:40 -0600 Subject: [PATCH 16/29] Move old pages into unpublished module --- modules/{ROOT => .tutorials}/pages/administration.adoc | 0 modules/{ROOT => .tutorials}/pages/astra-streaming-cli.adoc | 0 modules/{ROOT => .tutorials}/pages/managing.adoc | 0 .../pages/quickstart-databases.adoc} | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename modules/{ROOT => .tutorials}/pages/administration.adoc (100%) rename modules/{ROOT => .tutorials}/pages/astra-streaming-cli.adoc (100%) rename modules/{ROOT => .tutorials}/pages/managing.adoc (100%) rename modules/{ROOT/pages/.quickstart-databases.adoc => .tutorials/pages/quickstart-databases.adoc} (100%) diff --git a/modules/ROOT/pages/administration.adoc b/modules/.tutorials/pages/administration.adoc similarity index 100% rename from modules/ROOT/pages/administration.adoc rename to modules/.tutorials/pages/administration.adoc diff --git a/modules/ROOT/pages/astra-streaming-cli.adoc b/modules/.tutorials/pages/astra-streaming-cli.adoc similarity index 100% rename from modules/ROOT/pages/astra-streaming-cli.adoc rename to modules/.tutorials/pages/astra-streaming-cli.adoc diff --git a/modules/ROOT/pages/managing.adoc b/modules/.tutorials/pages/managing.adoc similarity index 100% rename from modules/ROOT/pages/managing.adoc rename to modules/.tutorials/pages/managing.adoc diff --git a/modules/ROOT/pages/.quickstart-databases.adoc b/modules/.tutorials/pages/quickstart-databases.adoc similarity index 100% rename from modules/ROOT/pages/.quickstart-databases.adoc rename to modules/.tutorials/pages/quickstart-databases.adoc From c52d1f3bacbe6bfa3703a8fff933b116a2fe39f8 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Tue, 11 Nov 2025 20:32:47 -0600 Subject: [PATCH 17/29] Update landing page --- modules/ROOT/pages/index.adoc | 66 ++++++++++++++--------------------- 1 file changed, 26 insertions(+), 40 deletions(-) diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 3aadb4e..62de09d 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -1,64 +1,50 @@ = {product} :page-layout: landing -The {product} is a free utility that you can use to create and manage {product-short} resources. -You can use the {product} to perform common platform tasks for {astra_db} and {astra_stream} from the command line or with automation to control your {product-short} resources at scale. +A fast, reliable command-line tool for working with {company} {product-short}. -To make it even easier to integrate {product-short} into your applications and workflows, the {product} provides seamless integration with the following external tools: - -* DSBulk -* cqlsh -* pulshar-shell -* Useful shortcuts like dotenv file generation +{product} gives you full control of your {product-short} resources directly from your terminal. +It's designed for developers and operators who prefer automation, scripting, and repeatable workflows over clicking through the {astra-ui} or interfacing directly with the APIs. [.[&>h2]:!hidden] == {empty} [subs="macros,attributes"] ++++ -
-
- - svg:common:ROOT:icons/datastax/create-db-now.svg[role="mx-auto max-w-xs md:mx-0 lg:max-w-none"] +
+
-

Get started

+

Get started

- - -
- xref:install.adoc[] -
+

Ready to bring {product-short} to the command line? Install the CLI and learn how to connect and start managing your {product-short} resources in minutes.

-
- xref:use-cli.adoc[] +
+ xref:ROOT:install.adoc[Install the {product},role="btn btn-primary btn-solid"] + xref:commands:astra-setup.adoc[Command reference,role="btn btn-neutral btn-outlined"]
-
- - svg:common:ROOT:icons/datastax/cloud-db.svg[role="mx-auto max-w-xs md:mx-0 lg:max-w-none"] - -

Manage {astra_db}

- - - -
- xref:managing.adoc[] -
+ -
+[source,bash,subs="+quotes",role="nolang absolute bottom-1/2 translate-y-1/2 right-0 w-full inverse-theme [&_.source-toolbox]:hidden"] +---- +# Set up connection profiles +astra setup - svg:common:ROOT:icons/datastax/streaming.svg[role="mx-auto max-w-xs md:mx-0 lg:max-w-none"] +# Manage databases +astra db create my_db -r us-east1 -

Manage {astra_stream}

+# Manage streaming tenants +astra streaming create my_tenant --region us-east1 - - -
- xref:astra-streaming-cli.adoc[] -
+# Run built-in utilities +astra db cqlsh start my_db +astra streaming pulsar shell my_tenant +---- +[subs="macros,attributes"] +++++
++++ From 6f1fe732898efeea717cdf7d042a527b2100354d Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Tue, 11 Nov 2025 22:51:29 -0600 Subject: [PATCH 18/29] use-cli.adoc to manage-cli.adoc --- .../.tutorials/pages/quickstart-databases.adoc | 2 +- modules/ROOT/nav.adoc | 2 +- modules/ROOT/pages/index.adoc | 2 +- modules/ROOT/pages/install.adoc | 2 +- .../ROOT/pages/{use-cli.adoc => manage-cli.adoc} | 0 modules/ROOT/pages/uninstall.adoc | 16 ++++++++-------- 6 files changed, 12 insertions(+), 12 deletions(-) rename modules/ROOT/pages/{use-cli.adoc => manage-cli.adoc} (100%) diff --git a/modules/.tutorials/pages/quickstart-databases.adoc b/modules/.tutorials/pages/quickstart-databases.adoc index 3e40a45..a3a6958 100644 --- a/modules/.tutorials/pages/quickstart-databases.adoc +++ b/modules/.tutorials/pages/quickstart-databases.adoc @@ -13,7 +13,7 @@ To perform database operations, you need an application token with permission to To work within databases, you need an application token with permission to interact with the target database, such as the {database-administrator-role} role. ==== -When you xref:ROOT:use-cli.adoc[connect the {product}], you provide an application token that authorizes you to run the CLI commands. +When you xref:ROOT:manage-cli.adoc[connect the {product}], you provide an application token that authorizes you to run the CLI commands. == Find available regions diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 7d915b9..7eff3f3 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,6 +1,6 @@ .Get Started * xref:install.adoc[] -* xref:use-cli.adoc[] +* xref:manage-cli.adoc[] * xref:upgrade.adoc[] * xref:uninstall.adoc[] diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 62de09d..244f7d2 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -3,7 +3,7 @@ A fast, reliable command-line tool for working with {company} {product-short}. -{product} gives you full control of your {product-short} resources directly from your terminal. +The {product} gives you full control of your {product-short} resources directly from your terminal. It's designed for developers and operators who prefer automation, scripting, and repeatable workflows over clicking through the {astra-ui} or interfacing directly with the APIs. [.[&>h2]:!hidden] diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 5c5990a..71b7cd9 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -225,4 +225,4 @@ The response includes available commands and options for the {product}. == Next steps -To connect to {product-short} and run your first commands, see xref:use-cli.adoc[]. +To connect to {product-short} and run your first commands, see xref:manage-cli.adoc[]. diff --git a/modules/ROOT/pages/use-cli.adoc b/modules/ROOT/pages/manage-cli.adoc similarity index 100% rename from modules/ROOT/pages/use-cli.adoc rename to modules/ROOT/pages/manage-cli.adoc diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index 3124b9a..619c63a 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -23,7 +23,7 @@ astra nuke When prompted, type kbd:[y] and press kbd:[Enter] to proceed with the uninstallation. -The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`xref:ROOT:use-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:use-cli.adoc#file-locations[~/.astrarc]`). +The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`). It also lists any shell profile containing references to the `astra` command. Delete these references manually if desired. -- @@ -31,14 +31,14 @@ Delete these references manually if desired. Manual removal:: + -- -. Optional: Remove the `xref:ROOT:use-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: +. Optional: Remove the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: + [source,shell] ---- rm $(astra config path -p) ---- -. Delete the xref:ROOT:use-cli.adoc#file-locations[{product} home directory] +. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory] + [source,shell] ---- @@ -67,7 +67,7 @@ Uninstaller (recommended):: -- Only use this method if you installed the {product} using the xref:ROOT:install.adoc[scripted installer]. -. Optional: Remove the `xref:ROOT:use-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: +. Optional: Remove the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: + [source,powershell] ---- @@ -96,7 +96,7 @@ astra nuke When prompted, type kbd:[y] and press kbd:[Enter] to proceed with the uninstallation. -The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`xref:ROOT:use-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:use-cli.adoc#file-locations[~/.astrarc]`). +The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`). You must remove `astra` from your system `PATH` manually, if desired. For more information, see the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables[Microsoft PowerShell documentation]. @@ -105,14 +105,14 @@ For more information, see the https://learn.microsoft.com/en-us/powershell/modul Manual removal:: + -- -. Optional: Remove the `xref:ROOT:use-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: +. Optional: Remove the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: + [source,powershell] ---- rm -f $(astra config path -p) ---- -. Delete the xref:ROOT:use-cli.adoc#file-locations[{product} home directory] +. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory] + [source,powershell] ---- @@ -134,7 +134,7 @@ For more information, see the https://learn.microsoft.com/en-us/powershell/modul Homebrew:: + -- -. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and optionally the configuration files (`xref:ROOT:use-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:use-cli.adoc#file-locations[~/.astrarc]`): +. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and optionally the configuration files (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`): + [source,shell] ---- From 27f6d629d6928d15d9101622dbeaac3032ac438f Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 01:21:23 -0600 Subject: [PATCH 19/29] Move files around and add cqlsh quickstart --- .../pages => in-progress}/administration.adoc | 1 + .../astra-streaming-cli.adoc | 1 + .../pages => in-progress}/managing.adoc | 1 + .../quickstart-databases.adoc | 2 +- modules/ROOT/nav.adoc | 3 + modules/quickstarts/pages/cqlsh.adoc | 182 ++++++++++++++++++ 6 files changed, 189 insertions(+), 1 deletion(-) rename {modules/.tutorials/pages => in-progress}/administration.adoc (99%) rename {modules/.tutorials/pages => in-progress}/astra-streaming-cli.adoc (99%) rename {modules/.tutorials/pages => in-progress}/managing.adoc (99%) rename {modules/.tutorials/pages => in-progress}/quickstart-databases.adoc (97%) create mode 100644 modules/quickstarts/pages/cqlsh.adoc diff --git a/modules/.tutorials/pages/administration.adoc b/in-progress/administration.adoc similarity index 99% rename from modules/.tutorials/pages/administration.adoc rename to in-progress/administration.adoc index 19d9edd..8c7bc6b 100644 --- a/modules/.tutorials/pages/administration.adoc +++ b/in-progress/administration.adoc @@ -1,3 +1,4 @@ +// Writer's note: This page is no longer published but there is still content that should be retained and reformatted for Astra CLI 1.0. = {product-short} administration commands Use the {product} to manage your {product-short} organization. diff --git a/modules/.tutorials/pages/astra-streaming-cli.adoc b/in-progress/astra-streaming-cli.adoc similarity index 99% rename from modules/.tutorials/pages/astra-streaming-cli.adoc rename to in-progress/astra-streaming-cli.adoc index 69ab116..4a98f0d 100644 --- a/modules/.tutorials/pages/astra-streaming-cli.adoc +++ b/in-progress/astra-streaming-cli.adoc @@ -1,3 +1,4 @@ +// Writer's note: This page is no longer published but there is still content that should be retained and reformatted for Astra CLI 1.0. = {astra_stream} commands Use the {product} to manage your {astra_stream} deployments. diff --git a/modules/.tutorials/pages/managing.adoc b/in-progress/managing.adoc similarity index 99% rename from modules/.tutorials/pages/managing.adoc rename to in-progress/managing.adoc index d753d8f..9c9c7fc 100644 --- a/modules/.tutorials/pages/managing.adoc +++ b/in-progress/managing.adoc @@ -1,3 +1,4 @@ +// Writer's note: This page is no longer published but there is still content that should be retained and reformatted for Astra CLI 1.0. = {astra_db} commands :embedding-provider-name: NVIDIA :embedding-provider-name-api: nvidia diff --git a/modules/.tutorials/pages/quickstart-databases.adoc b/in-progress/quickstart-databases.adoc similarity index 97% rename from modules/.tutorials/pages/quickstart-databases.adoc rename to in-progress/quickstart-databases.adoc index a3a6958..dd47d5b 100644 --- a/modules/.tutorials/pages/quickstart-databases.adoc +++ b/in-progress/quickstart-databases.adoc @@ -1,4 +1,4 @@ -// Author's note: This page is incomplete and not currently published. +// Writer's note: This page contains a selection of content that was deleted from the Astra Serverless docs. We should retain relevant content reformat it for Astra CLI 1.0. = Manage databases with the {product} :navtitle: Quickstart for databases :organization-administrator-role: pass:q[xref:astra-db-serverless:administration:rbac.adoc#organization-administrator-role[*Organization Administrator*]] diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 7eff3f3..e2617e8 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -4,6 +4,9 @@ * xref:upgrade.adoc[] * xref:uninstall.adoc[] +.Quickstarts +* xref:quickstarts:cqlsh.adoc[] + include::ROOT:partial$partial-nav.adoc[] .Release notes diff --git a/modules/quickstarts/pages/cqlsh.adoc b/modules/quickstarts/pages/cqlsh.adoc new file mode 100644 index 0000000..7f221e0 --- /dev/null +++ b/modules/quickstarts/pages/cqlsh.adoc @@ -0,0 +1,182 @@ += Run CQL commands with cqlsh + +`cqlsh` is an interface that you can use to issue xref:astra@cql:ROOT:index.adoc[{cass-short} Query Language (CQL)] commands to your database. + +The {product} provides built-in `cqlsh` support by downloading, installing, configuring, and wapping the `cqlsh` utility. +This can act as a convenient alternative to installing and configuring a xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[standalone cqlsh]. + +== Prerequisites + +To use `cqlsh` commands, you must have a supported version of Python installed on your system. + +The underlying `cqlsh` utility requires Python 2.7 (with TLS support) or Python 3.6--3.11. +Python versions 3.12 and later are not supported. +For more details, see this https://support.datastax.com/s/article/cqlsh-may-fail-with-A-Python-installation-with-SSL-is-required-to-connect-to-a-cloud-cluster-when-connecting-to-Astra[Support article] + +== Start cqlsh + +Use the `xref:commands:astra-db-cqlsh.adoc[]` command to start `cqlsh` in interactive mode: + +[source,bash,subs="+quotes"] +---- +astra db cqlsh **DATABASE_ID** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Downloading Cqlshell, please wait... +[INFO] Installing archive, please wait... +[INFO] Cqlsh is starting, please wait for connection establishment... +Connected to cndb at 127.0.0.1:9042. +[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] +Use HELP for help. +token@cqlsh> +---- +==== + +Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`. + +The first time you use `astra db cqlsh`, the {product} downloads and installs the `cqlsh` utility to the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]. +The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the home directory. + +[TIP] +====== +If the {product} reports `ModuleNotFoundError`, check that you have a supported version of Python available in your terminal: + +[source,bash] +---- +python -V +---- + +.Result +[%collapsible] +==== +[source,console] +---- +Python 3.11.10 +---- +==== +====== + +== Connect to a specific keyspace + +Use the `-k` / `--keyspace` option to connect directly to a specific keyspace: + +[source,bash,subs="+quotes"] +---- +astra db cqlsh **DATABASE_ID** -k **KEYSPACE_NAME** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... +Connected to cndb at 127.0.0.1:9042. +[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] +Use HELP for help. +token@cqlsh:keyspace2> +---- +==== + +== Issue a CQL statement + +Use the `-e` / `--execute` option to issue a CQL statement: + +[source,bash,subs="+quotes"] +---- +astra db cqlsh **DATABASE_ID** -e "describe keyspaces;" +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... + +system_auth data_endpoint_auth system_traces +datastax_sla default_keyspace system_virtual_schema +system_schema system system_views +---- +==== + +== Execute a CQL file + +Use the `-f` / `--file` option to execute a CQL file: + +[source,bash,subs="+quotes"] +---- +astra db cqlsh **DATABASE_ID** -f sample.cql +---- + +.Example CQL file +[%collapsible] +==== +.sample.cql +[source,cql] +---- +-- Use a specific keyspace +USE keyspace1; + +-- Create a table +CREATE TABLE IF NOT EXISTS users ( + id UUID PRIMARY KEY, + name TEXT, + email TEXT +); + +-- Insert some data +INSERT INTO users (id, name, email) VALUES (uuid(), 'Alice', 'alice@example.com'); +INSERT INTO users (id, name, email) VALUES (uuid(), 'Bob', 'bob@example.com'); + +-- Query the data +SELECT * FROM users; +---- +==== + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... + + id | email | name +--------------------------------------+-------------------+------- + 62a32f14-5432-4a28-add7-761d3626373e | bob@example.com | Bob + 0a489e53-0eed-4385-81a6-081143c228f1 | alice@example.com | Alice + +(2 rows) +---- +==== + +[TIP] +====== +You can also execute a CQL file using the `xref:astra@cql:reference:cqlsh-commands/source.adoc[]` CQL command: + +[source,bash,subs="+quotes"] +---- +astra db cqlsh **DATABASE_ID** -e "SOURCE 'sample.cql'" +---- + +.Result +[%collapsible] +==== +[source,cql] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... + + id | email | name +--------------------------------------+-------------------+------- + 62a32f14-5432-4a28-add7-761d3626373e | bob@example.com | Bob + 0a489e53-0eed-4385-81a6-081143c228f1 | alice@example.com | Alice + +(2 rows) +---- +==== +====== From f4cfd421b4141f89be59f538efd10772b52a8ad5 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 01:30:19 -0600 Subject: [PATCH 20/29] Add DSBulk quickstart --- in-progress/astra-streaming-cli.adoc | 2 +- in-progress/managing.adoc | 4 +- modules/ROOT/nav.adoc | 1 + modules/quickstarts/pages/cqlsh.adoc | 2 +- modules/quickstarts/pages/dsbulk.adoc | 369 ++++++++++++++++++++++++++ 5 files changed, 374 insertions(+), 4 deletions(-) create mode 100644 modules/quickstarts/pages/dsbulk.adoc diff --git a/in-progress/astra-streaming-cli.adoc b/in-progress/astra-streaming-cli.adoc index 4a98f0d..bbbd236 100644 --- a/in-progress/astra-streaming-cli.adoc +++ b/in-progress/astra-streaming-cli.adoc @@ -727,7 +727,7 @@ OPTIONS The https://pulsar.apache.org/docs/next/administration-pulsar-shell/[Pulsar shell] is an interactive command-line interface tool for managing and interacting with Pulsar clusters. It is designed to allow developers and administrators to execute Pulsar commands interactively or in a script-like fashion, facilitating tasks such as creating topics, producing and consuming messages, managing schemas, and more. -The {product} provides built-in Pulsar shell support by downloading, installing, configuring, and wapping the `pulsar-shell` utility. +The {product} provides built-in Pulsar shell support by downloading, installing, configuring, and wrapping the `pulsar-shell` utility. Use the `astra streaming pulsar-shell` command to start the Pulsar shell in interactive mode: diff --git a/in-progress/managing.adoc b/in-progress/managing.adoc index 9c9c7fc..d9246f6 100644 --- a/in-progress/managing.adoc +++ b/in-progress/managing.adoc @@ -2772,7 +2772,7 @@ OPTIONS == Use cqlsh `cqlsh` is an interface that you can use to issue xref:astra@cql:ROOT:index.adoc[{cass-short} Query Language (CQL)] commands to your database. -The {product} provides built-in `cqlsh` support by downloading, installing, configuring, and wapping the `cqlsh` utility. +The {product} provides built-in `cqlsh` support by downloading, installing, configuring, and wrapping the `cqlsh` utility. This can act as a convenient alternative to installing and configuring a xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[standalone cqlsh]. To use `cqlsh` commands, you must have a supported version of Python installed on your system. @@ -3020,7 +3020,7 @@ astra db cqlsh **DATABASE_ID** -e "SOURCE 'sample.cql'" == Use DataStax Bulk Loader The xref:dsbulk:overview:dsbulk-about.adoc[DataStax Bulk Loader (DSBulk)] lets you load, unload, and count data in your database tables. -The {product} provides built-in DSBulk support by downloading, installing, configuring, and wapping the `dsbulk` utility. +The {product} provides built-in DSBulk support by downloading, installing, configuring, and wrapping the `dsbulk` utility. The {product} exposes DSBulk functionality through the `astra db load`, `astra db unload`, and `astra db count` commands. diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e2617e8..c452362 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -6,6 +6,7 @@ .Quickstarts * xref:quickstarts:cqlsh.adoc[] +* xref:quickstarts:dsbulk.adoc[] include::ROOT:partial$partial-nav.adoc[] diff --git a/modules/quickstarts/pages/cqlsh.adoc b/modules/quickstarts/pages/cqlsh.adoc index 7f221e0..33866d1 100644 --- a/modules/quickstarts/pages/cqlsh.adoc +++ b/modules/quickstarts/pages/cqlsh.adoc @@ -2,7 +2,7 @@ `cqlsh` is an interface that you can use to issue xref:astra@cql:ROOT:index.adoc[{cass-short} Query Language (CQL)] commands to your database. -The {product} provides built-in `cqlsh` support by downloading, installing, configuring, and wapping the `cqlsh` utility. +The {product} provides built-in `cqlsh` support by downloading, installing, configuring, and wrapping the `cqlsh` utility. This can act as a convenient alternative to installing and configuring a xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[standalone cqlsh]. == Prerequisites diff --git a/modules/quickstarts/pages/dsbulk.adoc b/modules/quickstarts/pages/dsbulk.adoc new file mode 100644 index 0000000..62e2a3f --- /dev/null +++ b/modules/quickstarts/pages/dsbulk.adoc @@ -0,0 +1,369 @@ += Run DataStax Bulk Loader (DSBulk) commands + +The xref:dsbulk:overview:dsbulk-about.adoc[DataStax Bulk Loader (DSBulk)] lets you load, unload, and count data in your database tables. +The {product} provides built-in DSBulk support by downloading, installing, configuring, and wrapping the `dsbulk` utility. + +The {product} exposes DSBulk functionality through the `astra db load`, `astra db unload`, and `astra db count` commands. + +The first time you run `astra db load`, `astra db unload`, or `astra db count` commands, the {product} downloads and installs the `dsbulk` utility to the {product} installation directory (`~/.astra/dsbulk-*`). +The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the `~/.astra/scb` directory. + +== Load data + +Use the `astra db load` command to load data from a file into a database table: + +[source,bash,subs="+quotes"] +---- +astra db load **DATABASE_ID** \ + -k **KEYSPACE_NAME** \ + -t **TABLE_NAME** \ + -url **FILE_LOCATION** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Downloading Dsbulk, please wait... +[INFO] Installing archive, please wait... +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk load -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url cities.csv -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +A cloud secure connect bundle was provided and selected operation performs writes: changing default consistency level to LOCAL_QUORUM. +Operation directory: /Users/USERNAME/logs/LOAD_20250123-020734-995267 +Setting executor.maxPerSecond not set when connecting to DataStax Astra: applying a limit of 27,000 ops/second based on the number of coordinators (9). +If your Astra database has higher limits, please define executor.maxPerSecond explicitly. + total | failed | rows/s | p50ms | p99ms | p999ms | batches +148,266 | 0 | 19,588 | 240.82 | 771.75 | 964.69 | 30.72 +Operation LOAD_20250123-020734-995267 completed successfully in 7 seconds. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/LOAD_20250123-020734-995267/checkpoint.csv +---- +==== + +[TIP] +====== +You can use the `cqlsh` command to check that the data imported successfully: + +[source,bash,subs="+quotes"] +---- +astra db cqlsh **DATABASE_ID** -e \ +"SELECT * FROM **KEYSPACE_NAME**.**TABLE_NAME** LIMIT 20;" +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... + + country_name | name | country_code | country_id | id | latitude | longitude | state_code | state_id | state_name | wikidataid +--------------+---------------------+--------------+------------+------+----------+-----------+------------+----------+---------------------+------------ + Bangladesh | Azimpur | BD | 19 | 8454 | 23.7298 | 90.3854 | 13 | 771 | Dhaka District | null + Bangladesh | Badarganj | BD | 19 | 8455 | 25.67419 | 89.05377 | 55 | 759 | Rangpur District | null + Bangladesh | Bagerhat | BD | 19 | 8456 | 22.4 | 89.75 | 27 | 811 | Khulna District | null + Bangladesh | Bandarban | BD | 19 | 8457 | 22 | 92.33333 | B | 803 | Chittagong Division | null + Bangladesh | Baniachang | BD | 19 | 8458 | 24.51863 | 91.35787 | 60 | 767 | Sylhet District | null + Bangladesh | Barguna | BD | 19 | 8459 | 22.13333 | 90.13333 | 06 | 818 | Barisal District | null + Bangladesh | Barisal | BD | 19 | 8460 | 22.8 | 90.5 | 06 | 818 | Barisal District | null + Bangladesh | Bera | BD | 19 | 8462 | 24.07821 | 89.63262 | 54 | 813 | Rajshahi District | null + Bangladesh | Bhairab Bāzār | BD | 19 | 8463 | 24.0524 | 90.9764 | 13 | 771 | Dhaka District | null + Bangladesh | Bherāmāra | BD | 19 | 8464 | 24.02452 | 88.99234 | 27 | 811 | Khulna District | null + Bangladesh | Bhola | BD | 19 | 8465 | 22.36667 | 90.81667 | 06 | 818 | Barisal District | null + Bangladesh | Bhāndāria | BD | 19 | 8466 | 22.48898 | 90.06273 | 06 | 818 | Barisal District | null + Bangladesh | Bhātpāra Abhaynagar | BD | 19 | 8467 | 23.01472 | 89.43936 | 27 | 811 | Khulna District | null + Bangladesh | Bibir Hat | BD | 19 | 8468 | 22.68347 | 91.79058 | B | 803 | Chittagong Division | null + Bangladesh | Bogra | BD | 19 | 8469 | 24.78333 | 89.35 | 54 | 813 | Rajshahi District | null + Bangladesh | Brahmanbaria | BD | 19 | 8470 | 23.98333 | 91.16667 | B | 803 | Chittagong Division | null + Bangladesh | Burhānuddin | BD | 19 | 8471 | 22.49518 | 90.72391 | 06 | 818 | Barisal District | null + Bangladesh | Bājitpur | BD | 19 | 8472 | 24.21623 | 90.95002 | 13 | 771 | Dhaka District | null + Bangladesh | Chandpur | BD | 19 | 8474 | 23.25 | 90.83333 | B | 803 | Chittagong Division | null + Bangladesh | Chapai Nababganj | BD | 19 | 8475 | 24.68333 | 88.25 | 54 | 813 | Rajshahi District | null + +(20 rows) +---- +==== +====== + +== Unload data + +Use the `astra db unload` command to unload database table rows into a file: + +[source,bash,subs="+quotes"] +---- +astra db unload **DATABASE_ID** \ + -k **KEYSPACE_NAME** \ + -t **TABLE_NAME** \ + -url **FILE_LOCATION** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk unload -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url unloaded_data -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +Operation directory: /Users/USERNAME/logs/UNLOAD_20250123-021231-557959 + total | failed | rows/s | p50ms | p99ms | p999ms +134,574 | 0 | 29,767 | 281.25 | 591.40 | 591.40 +Operation UNLOAD_20250123-021231-557959 completed successfully in 4 seconds. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/UNLOAD_20250123-021231-557959/checkpoint.csv +---- +==== + +== Count data + +Use the `astra db count` command to get information about loaded data: + +[source,bash,subs="+quotes"] +---- +astra db count **DATABASE_ID** \ + -k **KEYSPACE_NAME** \ + -t **TABLE_NAME** +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk count -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +Operation directory: /Users/USERNAME/logs/COUNT_20250123-021120-127216 + total | failed | rows/s | p50ms | p99ms | p999ms +134,574 | 0 | 65,674 | 213.18 | 329.25 | 329.25 +Operation COUNT_20250123-021120-127216 completed successfully in 1 second. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/COUNT_20250123-021120-127216/checkpoint.csv +134574 +---- +==== + +== Complete DSBulk example + +The following end-to-end example shows how to use the {product}'s built-in DSBulk support to load data into a database, get information about the data, and unload the data into CSV files: + +. Create an {astra_db} {db-serverless} database: ++ +[source,bash] +---- +astra db create dsbulk_demo_db -k dsbulk_demo_keyspace +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Database 'dsbulk_demo_db' does not exist. Creating database 'dsbulk_demo_db' with keyspace 'dsbulk_demo_keyspace' +[INFO] Database 'dsbulk_demo_db' and keyspace 'dsbulk_demo_keyspace' are being created. +[INFO] Database 'dsbulk_demo_db' has status 'PENDING' waiting to be 'ACTIVE' ... +[INFO] Database 'dsbulk_demo_db' has status 'ACTIVE' (took 471460 millis) +[OK] Database 'dsbulk_demo_db' is ready. +---- +==== + +. Download the xref:ROOT:attachment$cities.csv[cities.csv] file and move it to the directory where you run {product} commands. ++ +The `cities.csv` dataset contains information about cities around the world: ++ +.cities.csv +[source,csv] +---- +id,name,state_id,state_code,state_name,country_id,country_code,country_name,latitude,longitude,wikiDataId +52,Ashkāsham,3901,BDS,Badakhshan,1,AF,Afghanistan,36.68333000,71.53333000,Q4805192 +68,Fayzabad,3901,BDS,Badakhshan,1,AF,Afghanistan,37.11664000,70.58002000,Q156558 +... +---- + +. Create a table in your database to store your data. ++ +.. Start `cqlsh` in interactive mode: ++ +[source,bash] +---- +astra db cqlsh dsbulk_demo_db -k dsbulk_demo_keyspace +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... +Connected to cndb at 127.0.0.1:9042. +[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] +Use HELP for help. +token@cqlsh:dsbulk_demo_keyspace> +---- +==== ++ +.. Copy and paste the following CQL command into the `cqlsh` prompt and press kbd:[Enter]: ++ +[source,cql] +---- +CREATE TABLE cities_by_country ( + country_name text, + name text, + id int, + state_id text, + state_code text, + state_name text, + country_id text, + country_code text, + latitude double, + longitude double, + wikiDataId text, + PRIMARY KEY ((country_name), name) +); +---- ++ +This command creates a table named `cities_by_country` with the appropriate schema for the `cities.csv` dataset. ++ +.. Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`. + +. Load the data from the `cities.csv` file into the `cities_by_country` table that you just created in your database: ++ +[source,bash] +---- +astra db load dsbulk_demo_db \ + -k dsbulk_demo_keyspace \ + -t cities_by_country \ + -url cities.csv +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk load -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url cities.csv -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +A cloud secure connect bundle was provided and selected operation performs writes: changing default consistency level to LOCAL_QUORUM. +Operation directory: /Users/USERNAME/logs/LOAD_20250123-020734-995267 +Setting executor.maxPerSecond not set when connecting to DataStax Astra: applying a limit of 27,000 ops/second based on the number of coordinators (9). +If your Astra database has higher limits, please define executor.maxPerSecond explicitly. + total | failed | rows/s | p50ms | p99ms | p999ms | batches +148,266 | 0 | 19,588 | 240.82 | 771.75 | 964.69 | 30.72 +Operation LOAD_20250123-020734-995267 completed successfully in 7 seconds. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/LOAD_20250123-020734-995267/checkpoint.csv +---- +==== + +. Confirm that the data loaded successfully: ++ +[source,bash] +---- +astra db cqlsh dsbulk_demo_db -e \ +"select * from dsbulk_demo_keyspace.cities_by_country LIMIT 20;" +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... + + country_name | name | country_code | country_id | id | latitude | longitude | state_code | state_id | state_name | wikidataid +--------------+---------------------+--------------+------------+------+----------+-----------+------------+----------+---------------------+------------ + Bangladesh | Azimpur | BD | 19 | 8454 | 23.7298 | 90.3854 | 13 | 771 | Dhaka District | null + Bangladesh | Badarganj | BD | 19 | 8455 | 25.67419 | 89.05377 | 55 | 759 | Rangpur District | null + Bangladesh | Bagerhat | BD | 19 | 8456 | 22.4 | 89.75 | 27 | 811 | Khulna District | null + Bangladesh | Bandarban | BD | 19 | 8457 | 22 | 92.33333 | B | 803 | Chittagong Division | null + Bangladesh | Baniachang | BD | 19 | 8458 | 24.51863 | 91.35787 | 60 | 767 | Sylhet District | null + Bangladesh | Barguna | BD | 19 | 8459 | 22.13333 | 90.13333 | 06 | 818 | Barisal District | null + Bangladesh | Barisal | BD | 19 | 8460 | 22.8 | 90.5 | 06 | 818 | Barisal District | null + Bangladesh | Bera | BD | 19 | 8462 | 24.07821 | 89.63262 | 54 | 813 | Rajshahi District | null + Bangladesh | Bhairab Bāzār | BD | 19 | 8463 | 24.0524 | 90.9764 | 13 | 771 | Dhaka District | null + Bangladesh | Bherāmāra | BD | 19 | 8464 | 24.02452 | 88.99234 | 27 | 811 | Khulna District | null + Bangladesh | Bhola | BD | 19 | 8465 | 22.36667 | 90.81667 | 06 | 818 | Barisal District | null + Bangladesh | Bhāndāria | BD | 19 | 8466 | 22.48898 | 90.06273 | 06 | 818 | Barisal District | null + Bangladesh | Bhātpāra Abhaynagar | BD | 19 | 8467 | 23.01472 | 89.43936 | 27 | 811 | Khulna District | null + Bangladesh | Bibir Hat | BD | 19 | 8468 | 22.68347 | 91.79058 | B | 803 | Chittagong Division | null + Bangladesh | Bogra | BD | 19 | 8469 | 24.78333 | 89.35 | 54 | 813 | Rajshahi District | null + Bangladesh | Brahmanbaria | BD | 19 | 8470 | 23.98333 | 91.16667 | B | 803 | Chittagong Division | null + Bangladesh | Burhānuddin | BD | 19 | 8471 | 22.49518 | 90.72391 | 06 | 818 | Barisal District | null + Bangladesh | Bājitpur | BD | 19 | 8472 | 24.21623 | 90.95002 | 13 | 771 | Dhaka District | null + Bangladesh | Chandpur | BD | 19 | 8474 | 23.25 | 90.83333 | B | 803 | Chittagong Division | null + Bangladesh | Chapai Nababganj | BD | 19 | 8475 | 24.68333 | 88.25 | 54 | 813 | Rajshahi District | null + +(20 rows) +---- +==== + +. Count the loaded data: ++ +[source,bash] +---- +astra db count dsbulk_demo_db \ + -k dsbulk_demo_keyspace \ + -t cities_by_country +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk count -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +Operation directory: /Users/USERNAME/logs/COUNT_20250123-021120-127216 + total | failed | rows/s | p50ms | p99ms | p999ms +134,574 | 0 | 65,674 | 213.18 | 329.25 | 329.25 +Operation COUNT_20250123-021120-127216 completed successfully in 1 second. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/COUNT_20250123-021120-127216/checkpoint.csv +134574 +---- +==== + +. Unload the data into CSV files: ++ +[source,bash] +---- +astra db unload dsbulk_demo_db \ + -k dsbulk_demo_keyspace \ + -t cities_by_country \ + -url unloaded_data +---- ++ +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk unload -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url unloaded_data -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 +[INFO] DSBulk is starting please wait ... +Username and password provided but auth provider not specified, inferring PlainTextAuthProvider +A cloud secure connect bundle was provided: ignoring all explicit contact points. +Operation directory: /Users/USERNAME/logs/UNLOAD_20250123-021231-557959 + total | failed | rows/s | p50ms | p99ms | p999ms +134,574 | 0 | 29,767 | 281.25 | 591.40 | 591.40 +Operation UNLOAD_20250123-021231-557959 completed successfully in 4 seconds. +Checkpoints for the current operation were written to checkpoint.csv. +To resume the current operation, re-run it with the same settings, and add the following command line flag: +--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/UNLOAD_20250123-021231-557959/checkpoint.csv +---- +==== ++ +This command unloads row data from the `cities_by_country` table, and stores it as CSV files within a subsirectory names `unloaded_data` in the same directory where you ran the command. From fbe3c6e6d9d263a24ecc98ef5fc5038ca6a8a45e Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 14:14:36 -0600 Subject: [PATCH 21/29] Update quickstart content --- modules/ROOT/nav.adoc | 1 + modules/ROOT/pages/manage-cli.adoc | 1 + .../pages/change-data-capture.adoc | 169 ++++++++++++++++++ modules/quickstarts/pages/cqlsh.adoc | 76 ++++---- modules/quickstarts/pages/dsbulk.adoc | 68 +++---- 5 files changed, 240 insertions(+), 75 deletions(-) create mode 100644 modules/quickstarts/pages/change-data-capture.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index c452362..a8e6d37 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -7,6 +7,7 @@ .Quickstarts * xref:quickstarts:cqlsh.adoc[] * xref:quickstarts:dsbulk.adoc[] +* xref:quickstarts:change-data-capture.adoc[] include::ROOT:partial$partial-nav.adoc[] diff --git a/modules/ROOT/pages/manage-cli.adoc b/modules/ROOT/pages/manage-cli.adoc index 23970d8..72bc763 100644 --- a/modules/ROOT/pages/manage-cli.adoc +++ b/modules/ROOT/pages/manage-cli.adoc @@ -540,6 +540,7 @@ The {product} stores the following items in this directory: * The {product} executable (scripted installations only) * Accessory executables downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]` +* {scb}s * Cache files for <> * Logs diff --git a/modules/quickstarts/pages/change-data-capture.adoc b/modules/quickstarts/pages/change-data-capture.adoc new file mode 100644 index 0000000..4b27b18 --- /dev/null +++ b/modules/quickstarts/pages/change-data-capture.adoc @@ -0,0 +1,169 @@ += Change Data Capture (CDC) + +CDC for {astra_db} automatically captures changes in real time, de-duplicates the changes, and then streams the clean set of changed data into xref:astra-streaming:ROOT:index.adoc[{astra_stream}] where it can be processed by client applications or sent to downstream systems. + +This page describes an end-to-end example showing how to use the {product} to create a CDC connection for a table in a {db-serverless} database. + +[IMPORTANT] +==== +CDC for {astra_db} incurs billed charges based on your {astra_stream} usage. +For more information, see https://www.ibm.com/docs/en/astra-streaming?topic=astra-streaming-annual-price-plans[{astra_stream} pricing]. +==== + +== Create a database + +Create an {astra_db} {db-serverless} database: + +[source,shell] +---- +astra db create cdc_demo_db \ + -c aws \ + -r us-east-1 \ + -k cdc_demo_keyspace +---- + +.Result +[%collapsible] +==== +[source,console] +---- +REGION OK +[INFO] Database 'cdc_demo_db' does not exist. Creating database 'cdc_demo_db' with keyspace 'cdc_demo_keyspace' +get CLoud provider +[INFO] Database 'cdc_demo_db' and keyspace 'cdc_demo_keyspace' are being created. +[INFO] Database 'cdc_demo_db' has status 'PENDING' waiting to be 'ACTIVE' ... +[INFO] Database 'cdc_demo_db' has status 'ACTIVE' (took 112117 millis) +[OK] Database 'cdc_demo_db' is ready. +---- +==== + +== Create a streaming tenant + +Create an {astra_stream} tenant in the same region as your database: + +[source,shell] +---- +astra streaming create cdc-demo-tenant \ + -c aws \ + -r useast1 +---- + +.Result +[%collapsible] +==== +[source,console] +---- +https://api.astra.datastax.com/v2/streaming/tenants/cdc-demo-tenant +[OK] Tenant 'cdc-demo-tenant' has being created. +---- +==== + +== Create a table in your database + +Use `xref:commands:astra-db-cqlsh.adoc[]` to create a table with a primary key column in your database: + +[source,shell] +---- +astra db cqlsh cdc_demo_db -e \ +"CREATE TABLE IF NOT EXISTS cdc_demo_keyspace.cdc_demo_table ( \ + key text PRIMARY KEY, \ + c1 text \ +);" +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... +---- +==== + +Confirm table creation: ++ +[source,shell] +---- +astra db cqlsh cdc_demo_db -e \ +"SELECT * FROM cdc_demo_keyspace.cdc_demo_table" +---- + +.Result +[%collapsible] +==== +[source,console] +---- +[INFO] Cqlsh is starting, please wait for connection establishment... + + key | c1 +-----+---- + +(0 rows) +---- +==== + +== Create a CDC connection + +Use `xref:commands:astra-db-create-cdc.adoc[]` to create a CDC connection between your database table and streaming tenant: + +[source,shell] +---- +astra db create-cdc cdc_demo_db \ + -k cdc_demo_keyspace \ + --table cdc_demo_table \ + --tenant cdc-demo-tenant +---- ++ +//// +// TODO: The command is not working as expected. Must investigate and figure out why it is reporting the following error: [ERROR] INVALID_ARGUMENT: Error Code=422(422) Invalid information provided to create DB: 422 Unprocessable Entity: databaseId, keyspace, tableName, and orgId are mandatory fields +.Result +[%collapsible] +==== +[source,console] +---- + +---- +==== +//// + +Use `xref:commands:astra-db-list-cdcs.adoc[]` to confirm CDC details for the database and tenant: + +[source,shell] +---- +astra db list-cdcs cdc_demo_db +---- + +.Result +[%collapsible] +==== +[source,console] +---- ++-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+ +| id | keyspace | table | tenant | cluster | namespace | Status | ++-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+ +| 57a3024f-cdcdemotable | cdc_demo_keyspace | cdc_demo_table | cdc-demo-tenant| pulsar-aws-useast1 | astracdc | Running | ++-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+ +---- +==== + +[source,shell] +---- +astra streaming list-cdc cdc-demo-tenant +---- + +.Result +[%collapsible] +==== +[source,console] +---- ++--------------------+----------------+----------------+-------------------+----------------+----------------+ +| cluster | namespace | database | keyspace | table | status | ++--------------------+----------------+----------------+-------------------+----------------+----------------+ +| pulsar-aws-useast1 | astracdc | cdc_demo_db | cdc_demo_keyspace | cdc_demo_table | running | ++--------------------+----------------+----------------+-------------------+----------------+----------------+ +---- +==== + +== Connect a sink + +After you enable CDC on your {db-serverless} database, you're ready to xref:astra-streaming:developing:astream-cdc.adoc#connect-a-sink[connect a sink]. diff --git a/modules/quickstarts/pages/cqlsh.adoc b/modules/quickstarts/pages/cqlsh.adoc index 33866d1..0fab87d 100644 --- a/modules/quickstarts/pages/cqlsh.adoc +++ b/modules/quickstarts/pages/cqlsh.adoc @@ -1,10 +1,14 @@ -= Run CQL commands with cqlsh += Issue CQL commands with cqlsh in the {product} +:navtitle: Issue CQL commands with cqlsh -`cqlsh` is an interface that you can use to issue xref:astra@cql:ROOT:index.adoc[{cass-short} Query Language (CQL)] commands to your database. +The {cass-short} Query Language Shell (`cqlsh`) is a utility that you can use to issue xref:astra@cql:reference:cql-quick-reference.adoc[CQL commands] to your {product} database. -The {product} provides built-in `cqlsh` support by downloading, installing, configuring, and wrapping the `cqlsh` utility. +The {product} provides embedded `cqlsh` support by downloading, installing, configuring, and wrapping the `cqlsh` utility. This can act as a convenient alternative to installing and configuring a xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[standalone cqlsh]. +The first time you use a `astra db cqlsh` command, the {product} downloads and installs the `cqlsh` utility to the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`). +The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files. + == Prerequisites To use `cqlsh` commands, you must have a supported version of Python installed on your system. @@ -13,13 +17,13 @@ The underlying `cqlsh` utility requires Python 2.7 (with TLS support) or Python Python versions 3.12 and later are not supported. For more details, see this https://support.datastax.com/s/article/cqlsh-may-fail-with-A-Python-installation-with-SSL-is-required-to-connect-to-a-cloud-cluster-when-connecting-to-Astra[Support article] -== Start cqlsh +== Start an interactive cqlsh session -Use the `xref:commands:astra-db-cqlsh.adoc[]` command to start `cqlsh` in interactive mode: +Use the `xref:commands:astra-db-cqlsh-start.adoc[]` command to start `cqlsh` in interactive mode: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -astra db cqlsh **DATABASE_ID** +astra db cqlsh start **DB_ID** ---- .Result @@ -27,9 +31,7 @@ astra db cqlsh **DATABASE_ID** ==== [source,console] ---- -[INFO] Downloading Cqlshell, please wait... -[INFO] Installing archive, please wait... -[INFO] Cqlsh is starting, please wait for connection establishment... +[INFO] Patched cqlsh script to try known supported Python versions first Connected to cndb at 127.0.0.1:9042. [cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] Use HELP for help. @@ -39,14 +41,11 @@ token@cqlsh> Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`. -The first time you use `astra db cqlsh`, the {product} downloads and installs the `cqlsh` utility to the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]. -The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the home directory. - [TIP] ====== If the {product} reports `ModuleNotFoundError`, check that you have a supported version of Python available in your terminal: -[source,bash] +[source,shell] ---- python -V ---- @@ -63,11 +62,11 @@ Python 3.11.10 == Connect to a specific keyspace -Use the `-k` / `--keyspace` option to connect directly to a specific keyspace: +Use the `-k` / `--keyspace` option with the `xref:commands:astra-db-cqlsh-start.adoc[]` and `xref:commands:astra-db-cqlsh-exec.adoc[]` commands to connect directly to a specific keyspace: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -astra db cqlsh **DATABASE_ID** -k **KEYSPACE_NAME** +astra db cqlsh start **DB_ID** -k **KEYSPACE_NAME** ---- .Result @@ -75,21 +74,20 @@ astra db cqlsh **DATABASE_ID** -k **KEYSPACE_NAME** ==== [source,console] ---- -[INFO] Cqlsh is starting, please wait for connection establishment... Connected to cndb at 127.0.0.1:9042. [cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] Use HELP for help. -token@cqlsh:keyspace2> +token@cqlsh:my_keyspace> ---- ==== == Issue a CQL statement -Use the `-e` / `--execute` option to issue a CQL statement: +Use the `xref:commands:astra-db-cqlsh-exec.adoc[]` command to issue a CQL statement directly from your terminal without starting an interactive `cqlsh` session: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -astra db cqlsh **DATABASE_ID** -e "describe keyspaces;" +astra db cqlsh exec **DB_ID** "describe keyspaces;" ---- .Result @@ -97,21 +95,19 @@ astra db cqlsh **DATABASE_ID** -e "describe keyspaces;" ==== [source,console] ---- -[INFO] Cqlsh is starting, please wait for connection establishment... - -system_auth data_endpoint_auth system_traces -datastax_sla default_keyspace system_virtual_schema -system_schema system system_views +system_auth data_endpoint_auth default_keyspace system_views +my_keyspace system system_traces system_virtual_schema +system_schema datastax_sla my_keyspace2 ---- ==== -== Execute a CQL file +=== Execute a CQL file -Use the `-f` / `--file` option to execute a CQL file: +Use the `-f` / `--file` option with the `xref:commands:astra-db-cqlsh-exec.adoc[]` command to execute a CQL file: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -astra db cqlsh **DATABASE_ID** -f sample.cql +astra db cqlsh exec **DB_ID** -f sample.cql ---- .Example CQL file @@ -121,7 +117,7 @@ astra db cqlsh **DATABASE_ID** -f sample.cql [source,cql] ---- -- Use a specific keyspace -USE keyspace1; +USE default_keyspace; -- Create a table CREATE TABLE IF NOT EXISTS users ( @@ -144,12 +140,10 @@ SELECT * FROM users; ==== [source,console] ---- -[INFO] Cqlsh is starting, please wait for connection establishment... - id | email | name --------------------------------------+-------------------+------- - 62a32f14-5432-4a28-add7-761d3626373e | bob@example.com | Bob - 0a489e53-0eed-4385-81a6-081143c228f1 | alice@example.com | Alice + 8b901d74-ac31-48e2-a403-dbcee8efe935 | bob@example.com | Bob + 0d712e1e-b764-4bbd-b587-579b75f29f32 | alice@example.com | Alice (2 rows) ---- @@ -159,9 +153,9 @@ SELECT * FROM users; ====== You can also execute a CQL file using the `xref:astra@cql:reference:cqlsh-commands/source.adoc[]` CQL command: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -astra db cqlsh **DATABASE_ID** -e "SOURCE 'sample.cql'" +astra db cqlsh exec **DB_ID** "SOURCE 'sample.cql'" ---- .Result @@ -169,12 +163,10 @@ astra db cqlsh **DATABASE_ID** -e "SOURCE 'sample.cql'" ==== [source,cql] ---- -[INFO] Cqlsh is starting, please wait for connection establishment... - id | email | name --------------------------------------+-------------------+------- - 62a32f14-5432-4a28-add7-761d3626373e | bob@example.com | Bob - 0a489e53-0eed-4385-81a6-081143c228f1 | alice@example.com | Alice + f497124c-0095-4ba6-84e7-c704749e3927 | bob@example.com | Bob + 93b9fe1b-b8c8-4492-b26e-7a2467e73005 | alice@example.com | Alice (2 rows) ---- diff --git a/modules/quickstarts/pages/dsbulk.adoc b/modules/quickstarts/pages/dsbulk.adoc index 62e2a3f..f1e5d05 100644 --- a/modules/quickstarts/pages/dsbulk.adoc +++ b/modules/quickstarts/pages/dsbulk.adoc @@ -1,23 +1,27 @@ = Run DataStax Bulk Loader (DSBulk) commands -The xref:dsbulk:overview:dsbulk-about.adoc[DataStax Bulk Loader (DSBulk)] lets you load, unload, and count data in your database tables. -The {product} provides built-in DSBulk support by downloading, installing, configuring, and wrapping the `dsbulk` utility. +xref:dsbulk:overview:dsbulk-about.adoc[DataStax Bulk Loader (DSBulk)] is a utility that you can use to load, unload, and count data in your database tables. +The {product} provides embedded DSBulk support by downloading, installing, configuring, and wrapping the `dsbulk` utility. -The {product} exposes DSBulk functionality through the `astra db load`, `astra db unload`, and `astra db count` commands. +The {product} exposes DSBulk functionality through the following commands: -The first time you run `astra db load`, `astra db unload`, or `astra db count` commands, the {product} downloads and installs the `dsbulk` utility to the {product} installation directory (`~/.astra/dsbulk-*`). -The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the `~/.astra/scb` directory. +* `xref:commands:astra-db-dsbulk-load.adoc[]` +* `xref:commands:astra-db-dsbulk-unload.adoc[]` +* `xref:commands:astra-db-dsbulk-count.adoc[]` + +The first time you use one of these commands, the {product} downloads and installs the `dsbulk` utility to the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`). +The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files. == Load data Use the `astra db load` command to load data from a file into a database table: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -astra db load **DATABASE_ID** \ +astra db load **DB_ID** \ -k **KEYSPACE_NAME** \ -t **TABLE_NAME** \ - -url **FILE_LOCATION** + --url **FILE_LOCATION** ---- .Result @@ -48,9 +52,9 @@ To resume the current operation, re-run it with the same settings, and add the f ====== You can use the `cqlsh` command to check that the data imported successfully: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -astra db cqlsh **DATABASE_ID** -e \ +astra db cqlsh **DB_ID** -e \ "SELECT * FROM **KEYSPACE_NAME**.**TABLE_NAME** LIMIT 20;" ---- @@ -93,12 +97,12 @@ astra db cqlsh **DATABASE_ID** -e \ Use the `astra db unload` command to unload database table rows into a file: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -astra db unload **DATABASE_ID** \ +astra db unload **DB_ID** \ -k **KEYSPACE_NAME** \ -t **TABLE_NAME** \ - -url **FILE_LOCATION** + --url **FILE_LOCATION** ---- .Result @@ -124,9 +128,9 @@ To resume the current operation, re-run it with the same settings, and add the f Use the `astra db count` command to get information about loaded data: -[source,bash,subs="+quotes"] +[source,shell,subs="+quotes"] ---- -astra db count **DATABASE_ID** \ +astra db count **DB_ID** \ -k **KEYSPACE_NAME** \ -t **TABLE_NAME** ---- @@ -157,9 +161,9 @@ The following end-to-end example shows how to use the {product}'s built-in DSBul . Create an {astra_db} {db-serverless} database: + -[source,bash] +[source,shell] ---- -astra db create dsbulk_demo_db -k dsbulk_demo_keyspace +astra db create dsbulk_demo_db -r us-east1 -k dsbulk_demo_keyspace ---- + .Result @@ -167,11 +171,10 @@ astra db create dsbulk_demo_db -k dsbulk_demo_keyspace ==== [source,console] ---- -[INFO] Database 'dsbulk_demo_db' does not exist. Creating database 'dsbulk_demo_db' with keyspace 'dsbulk_demo_keyspace' -[INFO] Database 'dsbulk_demo_db' and keyspace 'dsbulk_demo_keyspace' are being created. -[INFO] Database 'dsbulk_demo_db' has status 'PENDING' waiting to be 'ACTIVE' ... -[INFO] Database 'dsbulk_demo_db' has status 'ACTIVE' (took 471460 millis) -[OK] Database 'dsbulk_demo_db' is ready. +⠇ Checking if database 2c5f2157-d5b3-4697-97f0-78bcdd0123c1 is status ACTIVE (currently INITIALIZING, elapsed Database dsbulk_demo_db has been created with id 2c5f2157-d5b3-4697-97f0-78bcdd0123c1. It is now active after waiting 422 seconds. + +# Get more information about the new database: +$ astra db get dsbulk_demo_db ---- ==== @@ -192,9 +195,9 @@ id,name,state_id,state_code,state_name,country_id,country_code,country_name,lati + .. Start `cqlsh` in interactive mode: + -[source,bash] +[source,shell] ---- -astra db cqlsh dsbulk_demo_db -k dsbulk_demo_keyspace +astra db cqlsh start dsbulk_demo_db -k dsbulk_demo_keyspace ---- + .Result @@ -202,7 +205,6 @@ astra db cqlsh dsbulk_demo_db -k dsbulk_demo_keyspace ==== [source,console] ---- -[INFO] Cqlsh is starting, please wait for connection establishment... Connected to cndb at 127.0.0.1:9042. [cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] Use HELP for help. @@ -210,7 +212,7 @@ token@cqlsh:dsbulk_demo_keyspace> ---- ==== + -.. Copy and paste the following CQL command into the `cqlsh` prompt and press kbd:[Enter]: +.. Copy and paste the following CQL statement into the `cqlsh` prompt and press kbd:[Enter]: + [source,cql] ---- @@ -230,18 +232,18 @@ CREATE TABLE cities_by_country ( ); ---- + -This command creates a table named `cities_by_country` with the appropriate schema for the `cities.csv` dataset. +This CQL statement creates a table named `cities_by_country` with the appropriate schema for the `cities.csv` dataset. + .. Type `exit` or `quit;` and press kbd:[Enter] to exit `cqlsh`. . Load the data from the `cities.csv` file into the `cities_by_country` table that you just created in your database: + -[source,bash] +[source,shell] ---- astra db load dsbulk_demo_db \ -k dsbulk_demo_keyspace \ -t cities_by_country \ - -url cities.csv + --url cities.csv ---- + .Result @@ -268,7 +270,7 @@ To resume the current operation, re-run it with the same settings, and add the f . Confirm that the data loaded successfully: + -[source,bash] +[source,shell] ---- astra db cqlsh dsbulk_demo_db -e \ "select * from dsbulk_demo_keyspace.cities_by_country LIMIT 20;" @@ -310,7 +312,7 @@ astra db cqlsh dsbulk_demo_db -e \ . Count the loaded data: + -[source,bash] +[source,shell] ---- astra db count dsbulk_demo_db \ -k dsbulk_demo_keyspace \ @@ -339,12 +341,12 @@ To resume the current operation, re-run it with the same settings, and add the f . Unload the data into CSV files: + -[source,bash] +[source,shell] ---- astra db unload dsbulk_demo_db \ -k dsbulk_demo_keyspace \ -t cities_by_country \ - -url unloaded_data + --url unloaded_data ---- + .Result From 121bbc42066be8f5341279085e16f222a2c01c4b Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 14:24:33 -0600 Subject: [PATCH 22/29] More dsbulk edits --- modules/quickstarts/pages/dsbulk.adoc | 42 ++++++++------------------- 1 file changed, 12 insertions(+), 30 deletions(-) diff --git a/modules/quickstarts/pages/dsbulk.adoc b/modules/quickstarts/pages/dsbulk.adoc index f1e5d05..2874e26 100644 --- a/modules/quickstarts/pages/dsbulk.adoc +++ b/modules/quickstarts/pages/dsbulk.adoc @@ -14,14 +14,11 @@ The {product} also downloads the {scb} for each database you connect to and stor == Load data -Use the `astra db load` command to load data from a file into a database table: +Use the `xref:commands:astra-db-dsbulk-load.adoc[]` command to load data from a file into a database table: [source,shell,subs="+quotes"] ---- -astra db load **DB_ID** \ - -k **KEYSPACE_NAME** \ - -t **TABLE_NAME** \ - --url **FILE_LOCATION** +astra db dsbulk load **DB_ID** -k **KEYSPACE_NAME** -t **TABLE_NAME** --url **FILE_LOCATION** ---- .Result @@ -50,12 +47,11 @@ To resume the current operation, re-run it with the same settings, and add the f [TIP] ====== -You can use the `cqlsh` command to check that the data imported successfully: +You can use the `xref:commands:astra-db-cqlsh-exec.adoc[]` command to check that the data imported successfully: [source,shell,subs="+quotes"] ---- -astra db cqlsh **DB_ID** -e \ -"SELECT * FROM **KEYSPACE_NAME**.**TABLE_NAME** LIMIT 20;" +astra db cqlsh exec **DB_ID** "SELECT * FROM **KEYSPACE_NAME**.**TABLE_NAME** LIMIT 20;" ---- .Result @@ -95,14 +91,11 @@ astra db cqlsh **DB_ID** -e \ == Unload data -Use the `astra db unload` command to unload database table rows into a file: +Use the `xref:commands:astra-db-dsbulk-unload.adoc[]` command to unload database table rows into a file: [source,shell,subs="+quotes"] ---- -astra db unload **DB_ID** \ - -k **KEYSPACE_NAME** \ - -t **TABLE_NAME** \ - --url **FILE_LOCATION** +astra db dsbulk unload **DB_ID** -k **KEYSPACE_NAME** -t **TABLE_NAME** --url **FILE_LOCATION** ---- .Result @@ -126,13 +119,11 @@ To resume the current operation, re-run it with the same settings, and add the f == Count data -Use the `astra db count` command to get information about loaded data: +Use the `xref:commands:astra-db-dsbulk-count.adoc[]` command to get information about loaded data: [source,shell,subs="+quotes"] ---- -astra db count **DB_ID** \ - -k **KEYSPACE_NAME** \ - -t **TABLE_NAME** +astra db dsbulk count **DB_ID** -k **KEYSPACE_NAME** -t **TABLE_NAME** ---- .Result @@ -240,10 +231,7 @@ This CQL statement creates a table named `cities_by_country` with the appropriat + [source,shell] ---- -astra db load dsbulk_demo_db \ - -k dsbulk_demo_keyspace \ - -t cities_by_country \ - --url cities.csv +astra db dsbulk load dsbulk_demo_db -k dsbulk_demo_keyspace -t cities_by_country --url cities.csv ---- + .Result @@ -272,8 +260,7 @@ To resume the current operation, re-run it with the same settings, and add the f + [source,shell] ---- -astra db cqlsh dsbulk_demo_db -e \ -"select * from dsbulk_demo_keyspace.cities_by_country LIMIT 20;" +astra db cqlsh exec dsbulk_demo_db "select * from dsbulk_demo_keyspace.cities_by_country LIMIT 20;" ---- + .Result @@ -314,9 +301,7 @@ astra db cqlsh dsbulk_demo_db -e \ + [source,shell] ---- -astra db count dsbulk_demo_db \ - -k dsbulk_demo_keyspace \ - -t cities_by_country +astra db dsbulk count dsbulk_demo_db -k dsbulk_demo_keyspace -t cities_by_country ---- + .Result @@ -343,10 +328,7 @@ To resume the current operation, re-run it with the same settings, and add the f + [source,shell] ---- -astra db unload dsbulk_demo_db \ - -k dsbulk_demo_keyspace \ - -t cities_by_country \ - --url unloaded_data +astra db dsbulk unload dsbulk_demo_db -k dsbulk_demo_keyspace -t cities_by_country --url unloaded_data ---- + .Result From 3e28168253ad62977b0277374beff12e72a1d89a Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 15:03:12 -0600 Subject: [PATCH 23/29] Add page alias redirects --- modules/ROOT/pages/install.adoc | 1 + modules/ROOT/pages/manage-cli.adoc | 10 ++++++++++ 2 files changed, 11 insertions(+) diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 71b7cd9..0cafbaa 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -1,5 +1,6 @@ = Install the {product} :navtitle: Install the CLI +:page-aliases: ROOT:installation.adoc, ROOT:getting-started.adoc :description: {product} makes it easier to integrate {product-short} into your applications and workflows by letting you perform common platform tasks for {astra_db} and {astra_stream} from the command line. Install the {product} to create and manage {astra_db} databases and {astra_stream} tenants from the command line. diff --git a/modules/ROOT/pages/manage-cli.adoc b/modules/ROOT/pages/manage-cli.adoc index 72bc763..38cb7b0 100644 --- a/modules/ROOT/pages/manage-cli.adoc +++ b/modules/ROOT/pages/manage-cli.adoc @@ -1,5 +1,15 @@ = Connect and manage the {product} :navtitle: Connect and manage the CLI +:page-aliases: ROOT:managing.adoc, ROOT:astra-streaming-cli.adoc, ROOT:administration.adoc + +//// +Author's note: The following pages used to serve as de facto command references: + +ROOT:managing.adoc, ROOT:astra-streaming-cli.adoc, ROOT:administration.adoc + +However, since the new command reference pages are auto-generated, there isn't a good place to redirect them to (yet). +Once we have quickstarts for Astra DB, Astra Streaming, and Astra administration, we can move the page aliases. +//// Learn how to connect and run commands with the {product}. From 1a6ef1837f27a52cd32cdee3076403cbc98dd397 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 16:08:34 -0600 Subject: [PATCH 24/29] Update section title --- modules/ROOT/pages/install.adoc | 2 +- modules/ROOT/pages/manage-cli.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 0cafbaa..85f151a 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -23,7 +23,7 @@ The {product} supports the following operating systems: |`x86_64` |=== -== Install the {product} +== Install the CLI Select one of the following installation methods and follow the steps to install the {product}. diff --git a/modules/ROOT/pages/manage-cli.adoc b/modules/ROOT/pages/manage-cli.adoc index 38cb7b0..390922d 100644 --- a/modules/ROOT/pages/manage-cli.adoc +++ b/modules/ROOT/pages/manage-cli.adoc @@ -7,7 +7,7 @@ Author's note: The following pages used to serve as de facto command references: ROOT:managing.adoc, ROOT:astra-streaming-cli.adoc, ROOT:administration.adoc -However, since the new command reference pages are auto-generated, there isn't a good place to redirect them to (yet). +However, since the new command reference pages are programmatically generated, there isn't a good place to redirect them to (yet). Once we have quickstarts for Astra DB, Astra Streaming, and Astra administration, we can move the page aliases. //// From d99bb62d91a002d1f60d3b9f8d291af5a17571e3 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 18:42:41 -0600 Subject: [PATCH 25/29] =?UTF-8?q?Unpublish=20files=20that=20aren=E2=80=99t?= =?UTF-8?q?=20needed/ready?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../change-data-capture.adoc | 48 +++++++------------ .../pages => in-progress}/dsbulk.adoc | 6 +-- modules/ROOT/nav.adoc | 2 - .../ROOT/partials/async-option-active.adoc | 2 - .../ROOT/partials/macos-security-notice.adoc | 10 ---- modules/quickstarts/pages/cqlsh.adoc | 16 +++---- 6 files changed, 26 insertions(+), 58 deletions(-) rename {modules/quickstarts/pages => in-progress}/change-data-capture.adoc (66%) rename {modules/quickstarts/pages => in-progress}/dsbulk.adoc (97%) delete mode 100644 modules/ROOT/partials/async-option-active.adoc delete mode 100644 modules/ROOT/partials/macos-security-notice.adoc diff --git a/modules/quickstarts/pages/change-data-capture.adoc b/in-progress/change-data-capture.adoc similarity index 66% rename from modules/quickstarts/pages/change-data-capture.adoc rename to in-progress/change-data-capture.adoc index 4b27b18..0227bfa 100644 --- a/modules/quickstarts/pages/change-data-capture.adoc +++ b/in-progress/change-data-capture.adoc @@ -1,25 +1,17 @@ -= Change Data Capture (CDC) += Configure Change Data Capture (CDC) with the {product} +:navtitle: Change Data Capture quickstart -CDC for {astra_db} automatically captures changes in real time, de-duplicates the changes, and then streams the clean set of changed data into xref:astra-streaming:ROOT:index.adoc[{astra_stream}] where it can be processed by client applications or sent to downstream systems. +Change Data Capture (CDC) for {astra_db} automatically captures changes in real time, de-duplicates the changes, and then streams the clean set of changed data into xref:astra-streaming:ROOT:index.adoc[{astra_stream}] where it can be processed by client applications or sent to downstream systems. -This page describes an end-to-end example showing how to use the {product} to create a CDC connection for a table in a {db-serverless} database. - -[IMPORTANT] -==== -CDC for {astra_db} incurs billed charges based on your {astra_stream} usage. -For more information, see https://www.ibm.com/docs/en/astra-streaming?topic=astra-streaming-annual-price-plans[{astra_stream} pricing]. -==== +This page provides an end-to-end example that shows you how to use the {product} to enable CDC for an {astra-db} database. == Create a database -Create an {astra_db} {db-serverless} database: +Create an {astra_db} database: [source,shell] ---- -astra db create cdc_demo_db \ - -c aws \ - -r us-east-1 \ - -k cdc_demo_keyspace +astra db create cdc_demo_db -r us-east1 -k cdc_demo_keyspace ---- .Result @@ -27,13 +19,7 @@ astra db create cdc_demo_db \ ==== [source,console] ---- -REGION OK -[INFO] Database 'cdc_demo_db' does not exist. Creating database 'cdc_demo_db' with keyspace 'cdc_demo_keyspace' -get CLoud provider -[INFO] Database 'cdc_demo_db' and keyspace 'cdc_demo_keyspace' are being created. -[INFO] Database 'cdc_demo_db' has status 'PENDING' waiting to be 'ACTIVE' ... -[INFO] Database 'cdc_demo_db' has status 'ACTIVE' (took 112117 millis) -[OK] Database 'cdc_demo_db' is ready. +Database 'cdc_demo_db' has been created with id 'ce5e563c-3248-4064-b03c-5892433a1347'. It is now active after waiting 422 seconds. ---- ==== @@ -43,9 +29,7 @@ Create an {astra_stream} tenant in the same region as your database: [source,shell] ---- -astra streaming create cdc-demo-tenant \ - -c aws \ - -r useast1 +astra streaming create cdc-demo-tenant -c gcp -r useast1 ---- .Result @@ -60,15 +44,15 @@ https://api.astra.datastax.com/v2/streaming/tenants/cdc-demo-tenant == Create a table in your database -Use `xref:commands:astra-db-cqlsh.adoc[]` to create a table with a primary key column in your database: +Use `xref:commands:astra-db-cqlsh-exec.adoc[]` to create a table with a primary key column in your database: [source,shell] ---- -astra db cqlsh cdc_demo_db -e \ -"CREATE TABLE IF NOT EXISTS cdc_demo_keyspace.cdc_demo_table ( \ - key text PRIMARY KEY, \ - c1 text \ -);" +astra db cqlsh exec cdc_demo_db \ + "CREATE TABLE IF NOT EXISTS cdc_demo_keyspace.cdc_demo_table ( \ + key text PRIMARY KEY, \ + c1 text \ + );" ---- .Result @@ -84,8 +68,8 @@ Confirm table creation: + [source,shell] ---- -astra db cqlsh cdc_demo_db -e \ -"SELECT * FROM cdc_demo_keyspace.cdc_demo_table" +astra db cqlsh exec cdc_demo_db \ + "SELECT * FROM cdc_demo_keyspace.cdc_demo_table" ---- .Result diff --git a/modules/quickstarts/pages/dsbulk.adoc b/in-progress/dsbulk.adoc similarity index 97% rename from modules/quickstarts/pages/dsbulk.adoc rename to in-progress/dsbulk.adoc index 2874e26..d88523e 100644 --- a/modules/quickstarts/pages/dsbulk.adoc +++ b/in-progress/dsbulk.adoc @@ -1,4 +1,5 @@ = Run DataStax Bulk Loader (DSBulk) commands +:navtitle: DSBulk quickstart xref:dsbulk:overview:dsbulk-about.adoc[DataStax Bulk Loader (DSBulk)] is a utility that you can use to load, unload, and count data in your database tables. The {product} provides embedded DSBulk support by downloading, installing, configuring, and wrapping the `dsbulk` utility. @@ -162,10 +163,7 @@ astra db create dsbulk_demo_db -r us-east1 -k dsbulk_demo_keyspace ==== [source,console] ---- -⠇ Checking if database 2c5f2157-d5b3-4697-97f0-78bcdd0123c1 is status ACTIVE (currently INITIALIZING, elapsed Database dsbulk_demo_db has been created with id 2c5f2157-d5b3-4697-97f0-78bcdd0123c1. It is now active after waiting 422 seconds. - -# Get more information about the new database: -$ astra db get dsbulk_demo_db +Database 'dsbulk_demo_db' has been created with id '8b8fea68-404e-4f12-9a79-02079060adfa'. It is now active after waiting 433 seconds. ---- ==== diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index a8e6d37..e2617e8 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -6,8 +6,6 @@ .Quickstarts * xref:quickstarts:cqlsh.adoc[] -* xref:quickstarts:dsbulk.adoc[] -* xref:quickstarts:change-data-capture.adoc[] include::ROOT:partial$partial-nav.adoc[] diff --git a/modules/ROOT/partials/async-option-active.adoc b/modules/ROOT/partials/async-option-active.adoc deleted file mode 100644 index f310874..0000000 --- a/modules/ROOT/partials/async-option-active.adoc +++ /dev/null @@ -1,2 +0,0 @@ -By default, the command runs synchronously and doesn't return the command prompt until the database reaches *Active* or *Error* status. -To run the command _asynchronously_, add the `--async` option. \ No newline at end of file diff --git a/modules/ROOT/partials/macos-security-notice.adoc b/modules/ROOT/partials/macos-security-notice.adoc deleted file mode 100644 index a85b76b..0000000 --- a/modules/ROOT/partials/macos-security-notice.adoc +++ /dev/null @@ -1,10 +0,0 @@ -.macOS security alerts -[IMPORTANT] -==== -The first time you run the `astra` command after installing or updating the {product} on macOS, the operating system may display the following alert: `“astra” Not Opened`. - -image::ROOT:install-macos-security-alert.png[] - -If you encounter this alert, then you must override your Mac security settings before you can run {product} commands. -See the https://support.apple.com/en-us/102445#openanyway[Apple support documentation] for more information. -==== diff --git a/modules/quickstarts/pages/cqlsh.adoc b/modules/quickstarts/pages/cqlsh.adoc index 0fab87d..120af8b 100644 --- a/modules/quickstarts/pages/cqlsh.adoc +++ b/modules/quickstarts/pages/cqlsh.adoc @@ -1,13 +1,13 @@ = Issue CQL commands with cqlsh in the {product} -:navtitle: Issue CQL commands with cqlsh +:navtitle: CQL quickstart -The {cass-short} Query Language Shell (`cqlsh`) is a utility that you can use to issue xref:astra@cql:reference:cql-quick-reference.adoc[CQL commands] to your {product} database. +The {cass-short} Query Language Shell (`cqlsh`) is a utility that you can use to issue xref:astra@cql:reference:cql-quick-reference.adoc[CQL commands] to your {astra-db} database. -The {product} provides embedded `cqlsh` support by downloading, installing, configuring, and wrapping the `cqlsh` utility. +The {product} provides embedded `cqlsh` support by downloading and installing the `cqlsh` utility in the background and exposing it through the `xref:commands:astra-db-cqlsh.adoc[]` commands. This can act as a convenient alternative to installing and configuring a xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[standalone cqlsh]. -The first time you use a `astra db cqlsh` command, the {product} downloads and installs the `cqlsh` utility to the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`). -The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files. +The {product} doesn't download the `cqlsh` utility until the first time you use an `astra db cqlsh` command. +When this happens, the {product} downloads and installs the `cqlsh` utility, and the {scb} for each database you connect to, into the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`). == Prerequisites @@ -15,7 +15,7 @@ To use `cqlsh` commands, you must have a supported version of Python installed o The underlying `cqlsh` utility requires Python 2.7 (with TLS support) or Python 3.6--3.11. Python versions 3.12 and later are not supported. -For more details, see this https://support.datastax.com/s/article/cqlsh-may-fail-with-A-Python-installation-with-SSL-is-required-to-connect-to-a-cloud-cluster-when-connecting-to-Astra[Support article] +For more details, see this https://support.datastax.com/s/article/cqlsh-may-fail-with-A-Python-installation-with-SSL-is-required-to-connect-to-a-cloud-cluster-when-connecting-to-Astra[support article] == Start an interactive cqlsh session @@ -81,7 +81,7 @@ token@cqlsh:my_keyspace> ---- ==== -== Issue a CQL statement +== Issue a CQL statement directly Use the `xref:commands:astra-db-cqlsh-exec.adoc[]` command to issue a CQL statement directly from your terminal without starting an interactive `cqlsh` session: @@ -161,7 +161,7 @@ astra db cqlsh exec **DB_ID** "SOURCE 'sample.cql'" .Result [%collapsible] ==== -[source,cql] +[source,console] ---- id | email | name --------------------------------------+-------------------+------- From fe204b38188985071b920b8cf2c0e70522a60f7d Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 18:57:38 -0600 Subject: [PATCH 26/29] Fix typo --- modules/ROOT/pages/manage-cli.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/manage-cli.adoc b/modules/ROOT/pages/manage-cli.adoc index 390922d..3012807 100644 --- a/modules/ROOT/pages/manage-cli.adoc +++ b/modules/ROOT/pages/manage-cli.adoc @@ -550,7 +550,7 @@ The {product} stores the following items in this directory: * The {product} executable (scripted installations only) * Accessory executables downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]` -* {scb}s +* {scb-brief}s * Cache files for <> * Logs From 8fe35409c0ddf03ef24daada67e201c6b2392010 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 19:23:43 -0600 Subject: [PATCH 27/29] Another typo --- modules/ROOT/pages/manage-cli.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/manage-cli.adoc b/modules/ROOT/pages/manage-cli.adoc index 3012807..7f503fc 100644 --- a/modules/ROOT/pages/manage-cli.adoc +++ b/modules/ROOT/pages/manage-cli.adoc @@ -240,7 +240,7 @@ See 'astra --help' for help on a specific subcommand. ---- ==== -Append the `-h`/`--help` option to any command or subcommand to get specific help information and examples: +Append the `-h` / `--help` option to any command or subcommand to get specific help information and examples: [source,shell] ---- @@ -494,7 +494,7 @@ Default profile set to 'PROFILE_NAME'. [#specify-configuration-profile-individual-command] === Specify a configuration profile for an individual command -Every command lets you specify a configuration profile using the `-p`/`--profile` option. +Every command lets you specify a configuration profile using the `-p` / `--profile` option. This method is useful if you want to run a command using a different configuration profile without changing the default configuration profile. For example: From 9e70f520b44caa7daeac81a5480f7d8f48746f4e Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 19:28:09 -0600 Subject: [PATCH 28/29] Windows has one architecture --- modules/ROOT/pages/install.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/install.adoc b/modules/ROOT/pages/install.adoc index 85f151a..168594c 100644 --- a/modules/ROOT/pages/install.adoc +++ b/modules/ROOT/pages/install.adoc @@ -176,7 +176,7 @@ The response includes available commands and options for the {product}. Binary installation:: + -- -. Download the appropriate `windows` zip file for your CPU architecture from https://github.com/datastax/astra-cli/releases[GitHub]. +. Download the `windows` zip file from https://github.com/datastax/astra-cli/releases[GitHub]. . Extract the zip file into the directory where you want to install the {product}: + From 29d0b7968096b059ba8c76d3fad1baa45de9767c Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Wed, 12 Nov 2025 19:48:17 -0600 Subject: [PATCH 29/29] Consistency updates in uninstall topic --- modules/ROOT/pages/uninstall.adoc | 35 ++++++++++++++++++------------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index 619c63a..c616b49 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -14,7 +14,7 @@ Select one of the following methods to uninstall the {product} on macOS and Linu `astra nuke` command (recommended):: + -- -Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: +Use the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: [source,shell] ---- @@ -25,34 +25,37 @@ When prompted, type kbd:[y] and press kbd:[Enter] to proceed with the uninstalla The `astra nuke` command deletes the {product} home directory and optionally the configuration files (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`). It also lists any shell profile containing references to the `astra` command. -Delete these references manually if desired. +Delete these references manually, if desired. -- Manual removal:: + -- -. Optional: Remove the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: +. Optional: Delete the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file: + [source,shell] ---- rm $(astra config path -p) ---- ++ +Only do this if you don't want to preserve your xref:ROOT:manage-cli.adoc#manage-configuration-profiles[configuration profiles]. -. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory] +. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]: + [source,shell] ---- rm -rf $(astra config home path -p) ---- -. Remove the `astra` binary if it still exists +. Delete the `astra` binary if it still exists: + [source,shell] ---- rm -f $(which astra) ---- -. Remove any references to the `astra` command from your shell profile (for example, `~/.zprofile` or `~/.bash_profile`). +. Remove any references to the `astra` command from your shell profile. +For example, from `~/.zprofile` or `~/.bash_profile`. -- ===== @@ -67,27 +70,29 @@ Uninstaller (recommended):: -- Only use this method if you installed the {product} using the xref:ROOT:install.adoc[scripted installer]. -. Optional: Remove the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: +. Optional: Delete the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file: + [source,powershell] ---- rm -f $(astra config path -p) ---- ++ +Only do this if you don't want to preserve your xref:ROOT:manage-cli.adoc#manage-configuration-profiles[configuration profiles]. . Go to *Start > Settings > Apps > Installed apps*. -Find the {product}, select icon:ellipsis-vertical[name="More"], and then select *Uninstall*. +In the list of apps, find the {product}, select icon:ellipsis-vertical[name="More"], and then select *Uninstall*. + [NOTE] ==== The steps to locate and uninstall applications may vary depending on your version of Windows. -For detailed instructions, see the https://support.microsoft.com/en-us/windows/uninstall-or-remove-apps-and-programs-in-windows-4b55f974-2cc6-2d2b-d092-5905080eaf98[Microsoft Windows documentation]. +For more information, see the https://support.microsoft.com/en-us/windows/uninstall-or-remove-apps-and-programs-in-windows-4b55f974-2cc6-2d2b-d092-5905080eaf98[Microsoft Windows documentation]. ==== -- `astra nuke` command:: + -- -Run the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: +Use the `xref:commands:astra-nuke.adoc[]` command to uninstall the {product}: [source,powershell] ---- @@ -105,21 +110,23 @@ For more information, see the https://learn.microsoft.com/en-us/powershell/modul Manual removal:: + -- -. Optional: Remove the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file if you don't need your credentials anymore: +. Optional: Delete the `xref:ROOT:manage-cli.adoc#file-locations[.astrarc]` file: + [source,powershell] ---- rm -f $(astra config path -p) ---- ++ +Only do this if you don't want to preserve your xref:ROOT:manage-cli.adoc#manage-configuration-profiles[configuration profiles]. -. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory] +. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]: + [source,powershell] ---- rm -r -f $(astra config home path -p) ---- -. Remove the `astra` binary if it still exists +. Delete the `astra` binary if it still exists: + [source,powershell] ---- @@ -134,7 +141,7 @@ For more information, see the https://learn.microsoft.com/en-us/powershell/modul Homebrew:: + -- -. Optional: Run the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and optionally the configuration files (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`): +. Optional: Use the `xref:commands:astra-nuke.adoc[]` command to delete the {product} home directory and optionally the configuration files (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]` and `xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`): + [source,shell] ----