Connect and manage the Astra CLI

Learn how to connect and run commands with the Astra CLI.

If you haven’t installed the Astra CLI yet, see Install the Astra CLI.

Get an application token

The Astra CLI requires an application token to connect to Astra.

Generate an application token and copy the token string (AstraCS:…) before moving on to the next section.

If this is your first time using the Astra CLI, DataStax recommends that you connect to a non-production organization first. That way, you can assign your application token a more expansive role, such as Organization Administrator, so that you can try out all of the Astra CLI’s features without putting production data at risk.

If you’re using the Astra CLI in production, DataStax strongly recommends that you follow the principle of least privilege: Make sure your application token’s role provides only the minimum required permissions. For example, don’t grant an administrator-level role to a token that won’t be used to execute those types of commands.

Connect the Astra CLI

You can configure the Astra CLI to authenticate in the following ways:

Save configuration profiles

Configuration profiles let you save and manage connection information for use in Astra CLI sessions.

Each configuration profile consists of a name and an application token. When you set a profile as the default, the Astra CLI authenticates all commands using that profile’s application token, unless overridden.

See Create your first configuration profile.

Authenticate individual commands

You can supply an application token to authenticate individual commands.

This method is useful if you want to run a command without having to create a configuration profile.

See Authenticate an individual command.

Create your first configuration profile

The following procedure describes how to create your first configuration profile interactively, and is recommended for users who are new to the Astra CLI.

For more advanced methods of creating and managing configuration profiles, see Manage configuration profiles.

  1. Run the astra setup command:

    astra setup
    Result 
         _____            __
    /  _  \   _______/  |_____________
   /  /_\  \ /  ___/\   __\_  __ \__  \
  /    |    \\___ \  |  |  |  | \ //__ \_
  \____|__  /____  > |__|  |__|  (____  /
          \/     \/                   \/

                       Version: x.x.x

Welcome to the interactive Astra CLI setup!

Your configuration file will be created at /Users/username/.astrarc

Press Enter to continue, or use Ctrl+C to cancel.

  2. Press Enter to continue.

    Result 
    (Required) Enter your Astra token (it should start with AstraCS)
> input hidden for security

  3. Enter your application token (AstraCS:…​), and then press Enter.

    Result 
    (Optional) Enter a name for your profile (defaults to your org name)
>

  4. Enter a name for your configuration profile, or press Enter to accept the default (your organization name).

    Result 
    Profile 'PROFILE_NAME' successfully created.

It has been set as the default profile.

    The Astra CLI automatically sets the configuration profile as the default. All subsequent commands use this profile unless you override it.

  5. Run a command to test the connection. For example:

    astra db list-clouds
    Result 
    ┌─────────────────┐
│ Cloud Provider  │
├─────────────────┤
│ gcp             │
│ azure           │
│ aws             │
└─────────────────┘

    If the command succeeds, your connection is configured correctly.

Authenticate an individual command

Every command lets you supply an application token using the --token option. This option is useful if you want to run a command without having to create a configuration profile.

For example:

astra user list --token APPLICATION_TOKEN

The --token option bypasses the default configuration profile (if one exists) and uses the supplied application token for that command only.

Alternatively, if you have multiple application tokens saved in different configuration profiles, you can specify a configuration profile for an individual command. See Specify a configuration profile for an individual command.

Get command help

Run astra by itself to print general help information:

astra
Result 
     _____            __
    /  _  \   _______/  |_____________
   /  /_\  \ /  ___/\   __\_  __ \__  \
  /    |    \\___ \  |  |  |  | \ //__ \_
  \____|__  /____  > |__|  |__|  (____  /
          \/     \/                   \/

                       Version: x.x.x

Documentation: https://docs.datastax.com/en/astra-cli

Usage: astra [-qVv] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]]
             [--color=WHEN] [-o=FORMAT] [COMMAND]

  -v, --version            Print version information and exit.
                             (default: false)

Common Options:
      --color=WHEN         One of: auto, never, always
                             (default: auto)
      --dump-logs[=FILE]   Write all logs to an optionally specified file
                             (default: ~/.astra/logs/<file>.log)
      --no-input           Don't ask for user input (e.g. confirmation prompts)
  -o, --output=FORMAT      One of: human, json, csv
                             (default: human)
  -q, --quiet              Only output essential information
      --[no-]spinner       Enable/disable loading spinners
                             (default: enabled if tty)
  -V, --verbose            Enable verbose logging output

Commands:
  setup      Interactively set up the Astra CLI and create profiles
  config     Manage your Astra CLI configuration profiles
  db         Manage your Astra databases
  pcu        Manage your PCU groups and associations
  org        Get organization information
  role       Discover Astra roles
  streaming  Manage Astra streaming tenants
  token      Manage your Astra tokens
  user       Manage users in your organization
  upgrade    Upgrade your Astra CLI installation
  shellenv   Completions, configuration, and more
  nuke       Entirely delete Astra CLI from your system

Examples:
  # Create a new profile
  $ astra setup

  # List databases
  $ astra db list

  # Create a vector database
  $ astra db create demo -r us-east1

See 'astra <command> <subcommand> --help' for help on a specific subcommand.

Append the -h / --help option to any command or subcommand to get specific help information and examples:

astra org -h
Result 
Usage: astra org [-qV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]]
                 [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] |
                 [--token=TOKEN [--env=ENV]]] [COMMAND]

Get organization information

The --token flag is handy to quickly get information about another organization.

Use the --token @file syntax to read the token from a file, to avoid potential
leaks.


Common Options:
      --color=WHEN         One of: auto, never, always
                             (default: auto)
      --dump-logs[=FILE]   Write all logs to an optionally specified file
                             (default: ~/.astra/logs/<file>.log)
      --no-input           Don't ask for user input (e.g. confirmation prompts)
  -o, --output=FORMAT      One of: human, json, csv
                             (default: human)
  -q, --quiet              Only output essential information
      --[no-]spinner       Enable/disable loading spinners
                             (default: enabled if tty)
  -V, --verbose            Enable verbose logging output

Connection Options:
      -cf, --config-file=PATH
                           The .astrarc file to use for this command
                             (default: ~/.astrarc)
      --env=ENV            Override the target astra environment
  -p, --profile=NAME       The .astrarc profile to use for this command
      --token=TOKEN        The astra token to use for this command. Use the
                             --token @file syntax to read the token from a
                             file, to avoid potential leaks.

Commands:
  get   Get your organization's information
  id    Get your organization's ID
  name  Get your organization's name

Examples:
  # Get your organization's information
  $ astra org

  # Get information about another organization
  $ astra org get --token AstraCS:...

See 'astra <command> <subcommand> --help' for help on a specific subcommand.
astra db list --help
Result 
Usage: astra db list [-qvV] [--no-input] [--[no-]spinner] [--dump-logs[=FILE]]
                     [--color=WHEN] [-o=FORMAT] [[[-cf=PATH] [-p=NAME]] |
                     [--token=TOKEN [--env=ENV]]]

List your non-terminated Astra databases.

  -v, --vector             Only show vector-enabled databases
                             (default: false)

Common Options:
      --color=WHEN         One of: auto, never, always
                             (default: auto)
      --dump-logs[=FILE]   Write all logs to an optionally specified file
                             (default: ~/.astra/logs/<file>.log)
      --no-input           Don't ask for user input (e.g. confirmation prompts)
  -o, --output=FORMAT      One of: human, json, csv
                             (default: human)
  -q, --quiet              Only output essential information
      --[no-]spinner       Enable/disable loading spinners
                             (default: enabled if tty)
  -V, --verbose            Enable verbose logging output

Connection Options:
      -cf, --config-file=PATH
                           The .astrarc file to use for this command
                             (default: ~/.astrarc)
      --env=ENV            Override the target astra environment
  -p, --profile=NAME       The .astrarc profile to use for this command
      --token=TOKEN        The astra token to use for this command. Use the
                             --token @file syntax to read the token from a
                             file, to avoid potential leaks.

Examples:
  # List all your Astra databases
  $ astra db list

  # List only vector-enabled Astra databases
  $ astra db list --vector

See 'astra <command> <subcommand> --help' for help on a specific subcommand.

Use command auto-completion

The Astra CLI provides command auto-completion for Bash and ZSH shells.

To use auto-completion, type the astra command and then press Tab twice to get a list of available options:

% astra Tab Tab
config     nuke       pcu        setup      streaming  upgrade
db         org        role       shellenv   token      user

Certain dynamic arguments, such as database names, also support auto-completion once the Astra CLI discovers them.

For example, after running astra db list, type astra db get followed by Tab twice to see a list of your database names:

% astra db get Tab Tab
prod_db    test_db    playground_db

Most dynamic auto-completions are tied to configuration profiles. When you switch to a different configuration profile, only resources that have been discovered by that profile are available for auto-completion.

Manage configuration profiles

Configuration profiles provide a convenient way to save and manage application tokens for connecting the Astra CLI. Configuration profiles consist of a name and an application token and are stored in the .astrarc configuration file.

The following sections describe how to create additional configuration profiles, each with their own application token, to make it easier to manage different types of resources across one or more organizations.

List your configuration profiles

Use the astra config list command to list all of your configuration profiles:

astra config list
Result 
┌─────────────────────┐
│ configuration       │
├─────────────────────┤
│ Production (in use) │
│ Testing             │
└─────────────────────┘

The default configuration profile is indicated by (in use).

Configuration profiles are stored in the following format in the .astrarc file:

.astrarc
[Production]
ASTRA_DB_APPLICATION_TOKEN=AstraCS:IGXWg...

[default]
ASTRA_DB_APPLICATION_TOKEN=AstraCS:IGXWg...

[Testing]
ASTRA_DB_APPLICATION_TOKEN=AstraCS:WeaYR...

The [default] profile duplicates the application token of the configuration profile that is currently set as the default. In the previous example, you can tell the Production profile is the default profile because [Production] and [default] have the same application token.

Create a new configuration profile

Use the astra config create command to create a new configuration profile:

astra config create 'PROFILE_NAME' --token APPLICATION_TOKEN
Result 
Configuration profile 'PROFILE_NAME' successfully created.

(Hint: Use 'astra setup' for an interactive profile creation experience!)

# Set it as the default profile:
$ astra config use 'PROFILE_NAME'

You can also use the astra setup command again to create additional configuration profiles interactively.

Enclose arguments in quotes when they contain spaces

When specifying arguments that contain spaces (for example, profile names like Test 1), you must wrap the value in single quotes (''). This ensures that your shell treats the entire phrase as one argument rather than splitting it into separate words.

For example:

astra config create 'Test 1' --token AstraCS:...

Without quotes, your shell would interpret Test and 1 as two different arguments and cause the command to return an Unmatched argument or other similar error.

Set the default configuration profile

Use the astra config use command to change the default configuration that the Astra CLI uses when executing commands:

astra config use 'PROFILE_NAME'
Result 
Default profile set to 'PROFILE_NAME'.

Specify a configuration profile for an individual command

Every command lets you specify a configuration profile using the -p / --profile option. This method is useful if you want to run a command using a different configuration profile without changing the default configuration profile.

For example:

astra user list --profile 'PROFILE_NAME'

The --profile option bypasses the default configuration profile and uses the supplied configuration profile for that command only.

If you want to run a command using an application token directly, without having to create a new profile, see Authenticate an individual command.

Delete a configuration profile

Use the astra config delete command to delete a configuration profile:

astra config delete 'PROFILE_NAME'
Result 
Profile 'PROFILE_NAME' deleted successfully.

If you delete the default configuration profile, the Astra CLI doesn’t automatically select a new default configuration profile. You must use the astra config use command to set a new default configuration profile.

Astra CLI file locations

The Astra CLI stores installation and configuration files in the following locations:

File / Directory Description

.astra

The ASTRA_HOME directory.

Default location: ~/.astra (macOS and Linux), %USERPROFILE%\.astra (Windows)

The Astra CLI stores the following items in this directory:

For more information about the ASTRA_HOME directory, see the Astra CLI README.

.astrarc

The Astra CLI configuration file.

Default location: ~/.astrarc (macOS and Linux), %USERPROFILE%\.astrarc (Windows)

This file stores your configuration profiles and their associated application tokens.

For more information about the Astra CLI configuration file, see the Astra CLI README.

Was this helpful?

Edit this page

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2025 | 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: Contact IBM