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..57af553 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,7 +1,21 @@ -* 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..69ab116 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. @@ -756,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/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/install.adoc b/modules/ROOT/pages/install.adoc new file mode 100644 index 0000000..4cc85ff --- /dev/null +++ b/modules/ROOT/pages/install.adoc @@ -0,0 +1,365 @@ += 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. + +== Platform compatibility + +The {product} supports the following operating systems: + +[cols="1,2"] +|=== +|Operating System |Architecture + +|Linux +|x86_64, arm64 + +|macOS +|x86_64, arm64 + +|Microsoft Windows +|x86_64 +|=== + +== Install the {product} + +Select one of the following installation methods and follow the steps to install the {product}. + +[tabs,sync-group-id=platforms] +====== +Homebrew:: ++ +-- +. Install the latest version of the {product} using https://brew.sh/[Homebrew]: ++ +[source,bash] +---- +brew install datastax/astra-cli/astra-cli +---- ++ +.Result +[%collapsible] +==== +[source,console,subs="+attributes"] +---- +TBD +---- +==== + +. 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: ++ +[tabs] +===== +Scripted installation (recommended):: ++ +-- +. Run the following Bash script to install the latest version of the {product}: ++ +[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"] +---- +→ 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 +---- +==== ++ +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: ++ +[source,bash] +---- +astra +---- ++ +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]. + +. Extract the archive into the directory where you want to install the {product}: ++ +[source,bash,subs="+quotes"] +---- +sudo tar -xzvf astra-macos-**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)" +---- ++ +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. + +. 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. + +. Run the `astra` command from any directory to verify successful installation: ++ +[source,bash] +---- +astra +---- ++ +The response includes available commands and options for the {product}. +-- +===== + +Windows:: ++ +Select one of the following installation methods to install the {product} on Windows: ++ +[tabs] +===== +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" +---- ++ +.Result +[%collapsible] +==== +[source,console,subs="+attributes"] +---- +TBD +---- +==== + +. 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 +---- +==== ++ +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: ++ +[source,powershell] +---- +TBD +---- + +. Reload your shell profile or open a new command prompt. + +. Run the `astra` command from any directory to verify successful installation: ++ +[source,bash] +---- +astra +---- ++ +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]. + +. Extract the zip file into the directory where you want to install the {product}: ++ +[source,powershell,subs="+quotes"] +---- +powershell -Command "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. +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] +---- +astra +---- ++ +The response includes available commands and options for the {product}. +-- +===== + +Linux:: ++ +-- +TBD +-- + +Docker:: ++ +-- +TBD +-- +====== + +== Connect to {product-short} + +Follow these steps to set up your first connection profile: + +. {astra-url}[Sign in or create an {product-short} account.^] + +. 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! + +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 + +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/installation.adoc b/modules/ROOT/pages/installation.adoc deleted file mode 100644 index ee1fc4d..0000000 --- a/modules/ROOT/pages/installation.adoc +++ /dev/null @@ -1,595 +0,0 @@ -= Install or update the {product} -: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. - -== Platform compatibility - -The {product} supports the following operating systems: - -[cols="1,2"] -|=== -|Operating System |Architecture - -|Linux -|x86_64 - -|macOS -|x86_64, ARM64 - -|Microsoft Windows -|x86_64 - -_Requires https://learn.microsoft.com/en-us/windows/wsl/install[Windows Subsystem for Linux (WSL)]_ -|=== - -== Install the {product} - -Install the {product} using your preferred method: - -[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}: -+ -[source,bash] ----- -brew install datastax/astra-cli/astra-cli ----- -+ -.Result -[%collapsible] -==== -[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`). ----- -==== - -. Confirm that 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[] - -. Optional: If you haven't done so already, enable https://docs.brew.sh/Shell-Completion[`brew` shell completion]. -+ -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:: -+ --- -You can use `curl` to install the {product} on Linux, macOS, and Windows Subsystem for Linux (WSL): - -. Install the {product}: -+ -[source,bash] ----- -curl -Ls "https://dtsx.io/get-astra-cli" | bash ----- -+ -.Result -[%collapsible] -==== -[source,console,subs="+attributes"] ----- - - _____ __ - / _ \ _______/ |_____________ - / /_\ \ / ___/\ __\_ __ \__ \ - / | \___ \ | | | | \// __ \_ - \____|__ /____ > |__| |__| (____ / - \/ \/ \/ - -Installing Astra Cli {product-version} please wait... - -Checking prerequisites: -[OK] - Ready to install. -[OK] - unzip command is available -[OK] - curl command is available - -Preparing directories: -[OK] - Created /home/USERNAME/.astra/tmp -[OK] - Created /home/USERNAME/.astra/cli -[OK] - Created /home/USERNAME/.astra/scb - -Downloading archive: -######################################################################## 100.0% -[OK] - File downloaded -[OK] - Integrity of the archive checked - -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. ----- -==== -+ -The `~/.astra/cli` folder is added to the `PATH` environment variable. -See <> for more information. - -. Open a new terminal or restart your existing terminal. - -. Confirm that 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[] --- - -JVM:: -+ --- -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] - -. Verify that Java is version 17 or higher: -+ -[source,bash] ----- -java --version ----- - -. 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"]: -+ -[source,bash,subs="+attributes"] ----- -curl -L -o astra-cli-{product-version}.zip https://github.com/datastax/astra-cli/releases/download/{product-version}/astra-cli-{product-version}.zip ----- - -. Unzip the archive: -+ -[source,bash,subs="+attributes"] ----- -unzip astra-cli-{product-version}.zip -d ./astra-cli-{product-version} && cd astra-cli-{product-version} ----- - -. Confirm that you can successfully run the {product}: -+ -[source,bash] ----- -java -jar astra-cli.jar --version ----- -+ -.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: - -[source,bash] ----- -java -jar ./astra-cli.jar db list --token AstraCS:FZm... ----- --- - -Docker:: -+ --- -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: -+ -[source,bash] ----- -docker --version ----- -+ -.Result -[%collapsible] -==== -The command returns the Docker version that is installed: - -[source,console] ----- -Docker version 27.1.1, build 6312585 ----- -==== - -. 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. -==== -+ -.Result -[%collapsible] -==== -[source,console] ----- -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 ----- -==== - -. Confirm that you can successfully run the {product} in a Docker container: -+ -[source,bash] ----- -docker run -rm datastax/astra-cli --version ----- -+ -.Result -[%collapsible] -==== -The command returns the {product} version that is installed: - -[source,console,subs="+attributes"] ----- -{product-version} ----- -==== - -. Optional: Run the {product} with a configuration file: -+ -[source,bash,subs="+quotes"] ----- -docker run -rm -v **CONFIG_FILE**:/work/.astrarc datastax/astra-cli --version ----- -+ -Replace `**CONFIG_FILE**`with the path to your {product} configuration file. -For example: -+ -[source,bash] ----- -docker run -rm -v ~/.astrarc:/work/.astrarc datastax/astra-cli --version ----- -+ -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`: -+ -[source,bash] ----- -alias astra='docker run -rm -v ~/.astrarc:/work/.astrarc datastax/astra-cli' ----- -+ -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. -+ -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: -+ -[source,bash] ----- -astra --version ----- --- -====== - -To set up a new configuration and run your first commands, see xref:getting-started.adoc[]. - -[#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}._ -|=== - -== 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}: - -[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..b576ea4 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 @@ -2802,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. @@ -3517,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] ---- @@ -3539,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 new file mode 100644 index 0000000..72fdb07 --- /dev/null +++ b/modules/ROOT/pages/uninstall.adoc @@ -0,0 +1,61 @@ += Uninstall the {product} +:navtitle: Uninstall the CLI + +Follow the instructions for your original installation method to uninstall the {product}. + +[tabs,sync-group-id=platforms] +====== +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 +---- +-- + +macOS:: ++ +-- +-- + +Windows:: ++ +-- +-- + +Linux:: ++ +-- +-- + +Docker:: ++ +-- +-- +====== \ 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..613401c --- /dev/null +++ b/modules/ROOT/pages/upgrade.adoc @@ -0,0 +1,108 @@ += Upgrade the {product} +: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 {product}. + +[tabs,sync-group-id=platforms] +====== +Homebrew:: ++ +-- +. Run the following command to upgrade to the latest version of the {product}: ++ +[source,bash] +---- +brew upgrade datastax/astra-cli/astra-cli +---- + +. Optional: Upgrade to a specific version of the {product}: ++ +[source,bash,subs="+quotes"] +---- +brew install datastax/astra-cli/astra-cli@**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. +-- + +macOS:: ++ +-- +. 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. +-- + +Windows:: ++ +-- +. Run the `xref:commands:astra-upgrade.adoc[]` command to upgrade to the latest version of the {product}: ++ +[source,powershell] +---- +astra upgrade +---- + +. Optional: Upgrade to a specific version of the {product}: ++ +[source,powershell,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. +-- + +Linux:: ++ +-- +TBD +-- + +Docker:: ++ +-- +TBD +-- +====== diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/use-cli.adoc similarity index 94% rename from modules/ROOT/pages/getting-started.adoc rename to modules/ROOT/pages/use-cli.adoc index ffb35c7..5fea6f4 100644 --- a/modules/ROOT/pages/getting-started.adoc +++ b/modules/ROOT/pages/use-cli.adoc @@ -1,13 +1,11 @@ -= 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:installation.adoc[Install 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} 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