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.

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.

Press Enter to continue.

Result

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

Enter your application token (AstraCS:…), and then press Enter.
Result
```
(Optional) Enter a name for your profile (defaults to your org name)
>
```
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.

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

Get general 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.

Get help for a specific command

Append the -h / --help option to any command 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.

Get help for a specific subcommand

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

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 / Folder Description

File / Folder	Description
`.astra`	The Astra CLI home folder (`ASTRA_HOME`). Default location: macOS and Linux: `~/.astra` Windows: `%USERPROFILE%\.astra` All platforms: If the `XDG_DATA_HOME` environment variable is set, then the default location is `$XDG_DATA_HOME/astra`. The Astra CLI home folder contains the following items: The `astra` executable (scripted installations only) Accessory executables that are downloaded by certain commands, such as `astra db cqlsh` and `astra db dsbulk` A Secure Connect Bundle (SCB) for each database that you’ve connected to with the Astra CLI. Cache files for command auto-completion Logs For more information about `ASTRA_HOME`, see the Astra CLI README.
`.astrarc`	The Astra CLI configuration file. Default location: macOS and Linux: `~/.astrarc` Windows: `%USERPROFILE%\.astrarc` All platforms: If the `XDG_CONFIG_HOME` environment variable is set, then the default location is `$XDG_CONFIG_HOME/astra/.astrarc`. The Astra CLI uses this file to store your configuration profiles and their associated application tokens. For more information about the Astra CLI configuration file, see the Astra CLI README.

.astra

The Astra CLI home folder (ASTRA_HOME).

Default location:

macOS and Linux: ~/.astra
Windows: %USERPROFILE%\.astra
All platforms: If the XDG_DATA_HOME environment variable is set, then the default location is $XDG_DATA_HOME/astra.

The Astra CLI home folder contains the following items:

The astra executable (scripted installations only)
Accessory executables that are downloaded by certain commands, such as astra db cqlsh and astra db dsbulk
A Secure Connect Bundle (SCB) for each database that you’ve connected to with the Astra CLI.
Cache files for command auto-completion
Logs

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

.astrarc

The Astra CLI configuration file.

Default location:

macOS and Linux: ~/.astrarc
Windows: %USERPROFILE%\.astrarc
All platforms: If the XDG_CONFIG_HOME environment variable is set, then the default location is $XDG_CONFIG_HOME/astra/.astrarc.

The Astra CLI uses this file to store your configuration profiles and their associated application tokens.

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

Override the default home folder location

You can override the default location of the Astra CLI home folder (.astra) by setting the ASTRA_HOME environment variable:

Set the environment variable dynamically

Add the following line to your shell profile:

eval "$(astra shellenv --home "HOME_FOLDER_PATH")"

Replace HOME_FOLDER_PATH with the full path to your preferred Astra CLI home folder.

Set the environment variable directly

Add the following line to your shell profile:

export ASTRA_HOME=HOME_FOLDER_PATH

Replace HOME_FOLDER_PATH with the full path to your preferred Astra CLI home folder.

Override the default configuration file location

You can override the default location of the Astra CLI configuration file (.astrarc) by setting the ASTRA_CONFIG_FILE environment variable:

Set the environment variable dynamically

Add the following line to your shell profile:

eval "$(astra shellenv --rc "CONFIG_FILE_PATH/.astrarc")"

Replace CONFIG_FILE_PATH with the full path to your preferred .astrarc configuration file.

Set the environment variable directly

Add the following line to your shell profile:

export ASTRARC=CONFIG_FILE_PATH/.astrarc

Replace CONFIG_FILE_PATH with the full path to your preferred .astrarc configuration file.

Command output formats and exit codes

Most commands support the -o / --output option to specify the format of the command output:

astra COMMAND -o FORMAT

The following output formats are available:

human (default)

Human-readable format, optimized for command-line readability.

This format uses tables, lists, and other visual elements to present information on the command line.

json

Structured JSON format, suitable for programmatic parsing.

Every command that supports JSON output always returns a response using exactly this schema:

JSON output schema

{
  "code": "OK" | "UNCAUGHT" | "DATABASE_NOT_FOUND" | "...",
  "message": "Optional human-readable description",
  "data": {
    // Command-specific payload, may be an object, array, or primitive
  },
  "nextSteps": [
    {
      "command": "astra ...",
      "comment": "Explanation of why/when to run this next"
    }
  ]
}

All field names in the JSON output are in camel case (fieldName).

JSON output fields
Name	Type	Summary
`code`	`string`	A string enum representing the exit code of the command. Common values include: `OK`: command succeeded `UNCAUGHT`: unexpected failure `DATABASE_NOT_FOUND`: referenced resource missing Other command-specific codes
`message`	`string`	Optional. A human-friendly message describing the result or error of the command. Not all commands include a message.
`data`	Any (type varies by command)	Freeform data specific to the command. Typically an object or array, but may be a primitive value (string, number, boolean, etc.) depending on the command.
`nextSteps`	`array` or `null`	Optional. Only present if there are actionable next steps that you can take (it will never be an empty list). If present, it is an array of recommended next-step objects containing the following fields: `command`: The command to run. `comment`: An explanation of why/when to run this next.

csv

Comma-separated output format, ideal for data export and analysis.

Every command that supports CSV output always returns an RFC-4180-compliant response using exactly this schema:

CSV output schema

code,message,data_field_1,data_field_2,...

All field names in the CSV output are in snake case (field_name).

The first row is always the header, defining the column names. Each subsequent row represents one data record from the command.

The code and message fields can repeat for each row of data to keep the CSV schema consistent. Values can contain commas or newlines, and they can be wrapped in quotes to ensure RFC-4180-compliant CSV output.

CSV output fields
Name	Type	Summary
`code`	`string`	A string enum representing the exit code of the command. Common values include: `OK`: command succeeded `UNCAUGHT`: unexpected failure `DATABASE_NOT_FOUND`: referenced resource missing Other command-specific codes If no rows are returned, you can assume an implicit `OK` code.
`message`	`string`	Optional. A human-friendly message describing the result or error of the command. Not all commands include a `message`, and this field is empty if there is nothing to report.
Additional data fields	Any (type varies by command)	Command-specific fields representing the actual data returned. Fields can be empty if there is nothing to report. Column order is consistent per command.

For commands that issue GET requests, the json response generally contains the raw response from the server, whereas the human and csv formats contain a simplified version of the data.

Connect and manage the Astra CLI

Get an application token

Connect the Astra CLI

Create your first configuration profile

Authenticate an individual command

Get command help

Use command auto-completion

Manage configuration profiles

List your configuration profiles

Create a new configuration profile

Set the default configuration profile

Specify a configuration profile for an individual command

Delete a configuration profile

Astra CLI file locations

Override the default home folder location

Override the default configuration file location

Command output formats and exit codes

Was this helpful?

Give Feedback