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 1/4] 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 2/4] 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 3/4] 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 4/4] 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}