Install or update the Astra CLI

Install the Astra CLI to create and manage Astra DB databases and Astra Streaming tenants from the command line.

Platform compatibility

The Astra CLI supports the following operating systems:

Operating System Architecture

Linux

x86_64

macOS

x86_64, ARM64

Microsoft Windows

x86_64

Requires Windows Subsystem for Linux (WSL)

Install the Astra CLI

Install the Astra CLI using your preferred method:

  • Homebrew

  • curl

  • JVM

  • Docker

You can use Homebrew to install the Astra CLI on macOS and Linux.

Prerequisites

  • You must have Homebrew installed.

  • On macOS, you must set your macOS app security settings to Allow applications from App Store & Known Developers.

    1. Make sure Homebrew is up to date:

      brew update

    2. Install the Astra CLI:

      brew install datastax/astra-cli/astra-cli
      Result 
      ==> Fetching datastax/astra-cli/astra-cli
==> Downloading https://github.com/datastax/astra-cli/releases/download/0.6/astra-cli-0.6.arm64_sonoma.bottle.tar.gz
Already downloaded: /Users/USERNAME/Library/Caches/Homebrew/downloads/ca763b5f440dad257d707b2e705e98bd5a66912662fa95ae5ef417e749a2b08a--astra-cli-0.6.arm64_sonoma.bottle.tar.gz
==> Installing astra-cli from datastax/astra-cli
==> 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 enable, 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`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).

    3. Confirm that the Astra CLI is installed:

      astra --version
      Result 
      0.6

      The command returns the Astra CLI version that is installed.

      macOS security alerts

      The first time you run the astra command after installing or updating the Astra CLI on macOS, the operating system may display the following alert: “astra” Not Opened.

      install macos security alert

      If you encounter this alert, then you must override your Mac security settings before you can run Astra CLI commands. See the Apple support documentation for more information.

    4. (Optional) If you haven’t done so already, enable brew shell completion.

      The Astra CLI 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 Astra CLI commands and options as you type them.

You can use curl to install the Astra CLI on Linux, macOS, and Windows Subsystem for Linux (WSL).

  1. Install the Astra CLI:

    curl -Ls "https://dtsx.io/get-astra-cli" | bash
    Result 
        _____            __
   /  _  \   _______/  |_____________
  /  /_\  \ /  ___/\   __\_  __ \__  \
 /    |    \___ \  |  |  |  | \// __ \_
 \____|__  /____  > |__|  |__|  (____  /
         \/     \/                   \/

Installing Astra Cli 0.6  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 Installation file locations for more information.

  2. Open a new terminal or restart your existing terminal.

  3. Confirm that the Astra CLI is installed:

    astra --version
    Result 
    0.6

    The command returns the Astra CLI version that is installed.

    macOS security alerts

    The first time you run the astra command after installing or updating the Astra CLI on macOS, the operating system may display the following alert: “astra” Not Opened.

    install macos security alert

    If you encounter this alert, then you must override your Mac security settings before you can run Astra CLI commands. See the Apple support documentation for more information.

The Astra CLI is available as a packaged Java application that you can use on any machine running a JVM.

To run the Astra CLI in a JVM, you must have Java 17+ installed. You can install Java by downloading and installing the latest Oracle JDK

  1. Verify that Java is version 17 or higher:

    java --version

  2. Download the latest release of astra-cli Latest astra-cli release on GitHub:

    curl -L -o astra-cli-0.6.zip https://github.com/datastax/astra-cli/releases/download/0.6/astra-cli-0.6.zip

  3. Unzip the archive:

    unzip astra-cli-0.6.zip -d ./astra-cli-0.6 && cd astra-cli-0.6

  4. Confirm that you can successfully run the Astra CLI:

    java -jar astra-cli.jar --version
    Result 
    0.6

    The command returns the Astra CLI version that is installed.

You can use all options and suffixes on this command when running the JAR file. For example:

java -jar ./astra-cli.jar db list --token AstraCS:FZm...

The Astra CLI is available as an official Docker image that you can run in a container.

To install the Astra CLI using Docker, you must have Docker engine or Docker desktop installed.

  1. Confirm that Docker is installed and running:

    docker --version
    Result 
    Docker version 27.1.1, build 6312585

  2. Pull the latest Astra CLI Docker image:

    docker pull datastax/astra-cli
    Result 
    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

    When you run docker pull datastax/astra-cli, Docker automatically pulls the latest version of the Docker image (datastax/astra-cli:latest).

    To pull a specific version of the Docker image, run the following command:

    docker pull datastax/astra-cli:TAG

    Replace TAG with the version tag of the Docker image you want to pull.

  3. Confirm that you can successfully run the Astra CLI in a Docker container:

    docker run -rm datastax/astra-cli --version
    Result 
    0.6

    The command returns the Astra CLI version that is installed.

  4. (Optional) Run the Astra CLI with a configuration file:

    docker run -rm -v CONFIG_FILE:/work/.astrarc datastax/astra-cli --version

    Replace `CONFIG_FILE`with the path to your Astra CLI configuration file. For example:

    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 Astra CLI in a Docker container.

  5. (Optional) Create a shell alias for running the Astra CLI 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 Astra CLI in a Docker container. For example, the following command creates an alias named astra:

    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 Astra CLI commands in a Docker container using the same syntax as the astra binary:

    astra --version

To set up a new configuration and run your first commands, see Get started with the Astra CLI.

Installation file locations

The Astra CLI and its configuration are installed in the following locations:

File location Description

~/.astra

The Astra CLI installation directory.

For curl-based installations, 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 Astra CLI.

For Homebrew-based installations, the astra executable and auto-completion script are located in 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 Astra CLI configuration file.

This file is not deleted when you update or re-install the Astra CLI.

Update the Astra CLI

To update the Astra CLI, follow the procedure for the method you used to originally install the Astra CLI:

  • Homebrew

  • curl

  1. Make sure Homebrew is up to date:

    brew update

  2. Update the Astra CLI:

    brew upgrade datastax/astra-cli/astra-cli
    Result 
    ==> 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 enable, 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)

  3. Confirm that the latest version of the Astra CLI is installed:

    astra --version
    Result 
    0.6

    The command returns the Astra CLI version that is installed.

    macOS security alerts

    The first time you run the astra command after installing or updating the Astra CLI on macOS, the operating system may display the following alert: “astra” Not Opened.

    install macos security alert

    If you encounter this alert, then you must override your Mac security settings before you can run Astra CLI commands. See the Apple support documentation for more information.

  1. Update the Astra CLI:

    curl -Ls "https://dtsx.io/get-astra-cli" | bash

  2. Confirm that the latest version of the Astra CLI is installed:

    astra --version
    Result 
    0.6

Uninstall the Astra CLI

To uninstall the Astra CLI, follow the procedure for the method you used to originally install the Astra CLI:

  • Homebrew

  • curl

  1. Uninstall the Astra CLI:

    brew uninstall datastax/astra-cli/astra-cli
    Result 
    Uninstalling /opt/homebrew/Cellar/astra-cli/0.6... (4 files, 61.7MB)

  2. Delete the Astra CLI and its associated installation files:

    rm -R ~/.astra

  3. (Optional) Delete the Astra CLI configuration file:

    rm ~/.astrarc

  1. Delete the Astra CLI and its associated installation files:

    rm -R ~/.astra

  2. (Optional) Delete the Astra CLI configuration file:

    rm ~/.astrarc

  3. (Optional) Remove the Astra CLI from your shell configuration file (for example, .zshrc or .bashrc).

    1. Open your shell configuration file in a text editor. For example:

      nano ~/.zshrc

    2. Remove any lines that reference the Astra CLI. For example:

      #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"

    3. Save and close the file.

Was this helpful?

Edit this page

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com