Get started with the Astra CLI

Initialize the Astra CLI and run your first commands.

Prerequisites

To configure the Astra CLI:

  • Install the Astra CLI.

  • You must have an active Astra account.

  • You must have an application token that is assigned a role with adequate permissions to perform the tasks you’d like to accomplish with the Astra CLI.

    • Non-production organizations: If your Astra 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 Astra CLI features.

    • Production organizations: If you’re using Astra in production, DataStax recommends that you use a custom role to grant your application token the bare minimum permissions required to perform the required tasks with the Astra CLI.

  • If you plan to manage an Astra DB database that has restricted public access, then you must add your IP address to the database’s access list.

Initialize the Astra CLI

After installation, initialize the Astra CLI and connect it to an existing Astra account.

  1. Use the astra setup command to initialize the Astra CLI with your application token:

    astra setup --token APPLICATION_TOKEN

    Replace APPLICATION_TOKEN with your application token. The token format is AstraCS: followed by a unique token string.

    Result 
    [OK]    Configuration has been saved.
[OK]    Setup completed.
[INFO]  Enter 'astra help' to list available commands.

  2. List the Astra CLI configuration to confirm that your token is in use:

    astra config list
    Result 
    +--------------------------------+
| configuration                  |
+--------------------------------+
| alex@altostrat.com (in use)    |
+--------------------------------+

The Astra CLI is initialized and your application token is set as the default configuration. The Astra CLI stores configurations and their associated application tokens in the ~/.astrarc file. To create additional configurations, see Manage the Astra CLI configuration.

Application tokens are stored in plain text in the ~/.astrarc file. Your application tokens are like passwords, therefore you should take precautions to secure the configuration file.

Display help information

Use astra help to display the main help information:

astra help
Result 
usage: astra <command> [ <args> ]

Commands are:
    ?           Display this help version
    help        Display help information
    login       Authenticate against Astra.
    setup       Initialize configuration file
    config      Manage configuration file
    db          Manage databases
    org         Display Organization Info
    role        Manage roles
    streaming   Manage Streaming tenants
    token       Manage tokens
    user        Manage users

See 'astra help <command>' for more information on a specific command.

Append a command name to display help information about an individual command. For example:

astra help db
Result 
NAME
        astra db - Manage databases

SYNOPSIS
        astra db { count | cqlsh | create | create-cdc | create-collection |
                create-dotenv | create-keyspace | create-region | delete |
                delete-cdc | delete-collection | delete-keyspace |
                delete-region | describe | download-scb | get |
                get-endpoint-api | get-endpoint-playground |
                get-endpoint-swagger | list* | list-cdc | list-clouds |
                list-collections | list-keyspaces | list-regions |
                list-regions-classic | list-regions-serverless |
                list-regions-vector | load | resume | status | unload } [--]
                [ --token <AUTH_TOKEN> ] [ --no-color ] [ {-v | --verbose} ]
                [ {-conf | --config} <CONFIG_SECTION> ]
                [ {-cf | --config-file} <CONFIG_FILE> ] [ --env <Environment> ]
                [ {-o | --output} <FORMAT> ] [cmd-options] <cmd-args>

        Where command-specific options [cmd-options] are:
            count: [ {-k | --keyspace} <KEYSPACE> ] [ -encoding <ENCODING> ] [ {-t | --table} <TABLE> ]
                    [ {-query | --schema.query} <QUERY> ] [ --dsbulk-config <DSBULK_CONF_FILE> ]
                    [ -maxConcurrentQueries <maxConcurrentQueries> ] [ -logDir <log directory> ]
            cqlsh: [ --debug ] [ {-f | --file} <FILE> ] [ {-k | --keyspace} <KEYSPACE> ]
                    [ --version ] [ --connect-timeout <TIMEOUT> ] [ {-e | --execute} <STATEMENT> ]
                    [ --request-timeout <TIMEOUT> ] [ --encoding <ENCODING> ]
            create: [ {-c | --cloud} <cloud> ] [ {-k | --keyspace} <KEYSPACE> ]
                    [ --vector ] [ --timeout <timeout> ] [ {-r | --region} <DB_REGION> ]
                    [ {--if-not-exist | --if-not-exists} ] [ --async ] [ --tier <TIER> ]
                    [ --capacity-units <CAPACITY UNITS> ]
            create-cdc: [ {-k | --keyspace} <KEYSPACE> ] [ --tenant <TENANT> ]
                    [ -p, --partition <PARTITION TOKEN> ] [ --table <TABLE> ]
            create-collection: [ {-m | --metric} <METRIC> ] {-c | --collection}
                    <COLLECTION> [ {-d | --dimension} <DIMENSION> ]
            create-dotenv: [ {-k | --keyspace} <KEYSPACE> ] [ {-d | --directory} <DIRECTORY> ]
                    [ {-r | --region} <DB_REGION> ]
            create-keyspace: {-k | --keyspace} <KEYSPACE> [ --if-not-exist ] [ --wait ]
            create-region: [ {-c | --cloud} <CLOUD> ] [ --timeout <timeout> ]
                    {-r | --region} <REGION> [ --wait ] [ {-t | --tier} <CLOUD> ]
                    [ --async ] [ --if-not-exist ]
            delete: [ --async ] [ --timeout <timeout> ] [ --wait ]
            delete-cdc: [ {-k | --keyspace} <KEYSPACE> ] [ -id <CDC_ID> ] [ --tenant <TENANT> ]
                    [ --table <TABLE> ]
            delete-collection: {-c | --collection} <COLLECTION>
            delete-keyspace: {-k | --keyspace} <KEYSPACE>
            delete-region: [ --async ] [ --timeout <timeout> ] {-r | --region}
                    <REGION> [ --wait ]
            describe: [ {-k | --key} <Key> ]
            download-scb: [ {-f | --output-file} <DEST> ] [ {-r | --region} <DB_REGION> ]
            get: [ {-k | --key} <Key> ]
            get-endpoint-api: [ {-r | --region} <DB_REGION> ]
            get-endpoint-playground: [ {-r | --region} <DB_REGION> ]
            get-endpoint-swagger: [ {-r | --region} <DB_REGION> ]
            list: [ --vector ]
            list-cdc:
            list-clouds:
            list-collections:
            list-keyspaces:
            list-regions:
            list-regions-classic: [ {-c | --cloud} <CLOUD> ] [ {-f | --filter} <filter> ]
            list-regions-serverless: [ {-c | --cloud} <CLOUD> ] [ {-f | --filter} <filter> ]
            list-regions-vector: [ {-c | --cloud} <CLOUD> ] [ {-f | --filter} <filter> ]
            load: [ {-k | --keyspace} <KEYSPACE> ] [ -maxErrors <maxErrors> ] [ -encoding <ENCODING> ]
                    [ {-t | --table} <TABLE> ] [ {-query | --schema.query} <QUERY> ]
                    [ -skipRecords <skipRecords> ] [ --schema.allowMissingFields <allowMissingFields> ]
                    -url <url> [ --dsbulk-config <DSBULK_CONF_FILE> ] [ -dryRun ]
                    [ -header <header> ] [ -delim <delim> ] [ -maxConcurrentQueries <maxConcurrentQueries> ]
                    [ -logDir <log directory> ] [ {-m | --schema.mapping} <mapping> ]
            resume: [ --async ] [ --timeout <timeout> ] [ --wait ]
            status:
            unload: [ {-k | --keyspace} <KEYSPACE> ] [ -maxErrors <maxErrors> ]
                    [ -encoding <ENCODING> ] [ {-t | --table} <TABLE> ] [ {-query | --schema.query} <QUERY> ]
                    [ -skipRecords <skipRecords> ] [ -url <url> ] [ --dsbulk-config <DSBULK_CONF_FILE> ]
                    [ -header <header> ] [ -delim <delim> ] [ -maxConcurrentQueries <maxConcurrentQueries> ]
                    [ -logDir <log directory> ] [ {-m | --schema.mapping} <mapping> ]

        Where command-specific arguments <cmd-args> are:
            count: <DB>
            cqlsh: <DB>
            create: <DB>
            create-cdc: <DB>
            create-collection: <DB>
            create-dotenv: <DB>
            create-keyspace: <DB>
            create-region: <DB>
            delete: <DB>
            delete-cdc: <DB>
            delete-collection: <DB>
            delete-keyspace: <DB>
            delete-region: <DB>
            describe: <DB>
            download-scb: <DB>
            get: <DB>
            get-endpoint-api: <DB>
            get-endpoint-playground: <DB>
            get-endpoint-swagger: <DB>
            list:
            list-cdc: <DB>
            list-clouds:
            list-collections: <DB>
            list-keyspaces: <DB>
            list-regions: <DB>
            list-regions-classic:
            list-regions-serverless:
            list-regions-vector:
            load: <DB>
            resume: <DB>
            status: <DB>
            unload: <DB>

        Where * indicates the default command(s)
        See 'astra help db <command>' for more information on a specific command.
astra help db list
Result 
NAME
        astra db list - Display the list of Databases in an organization

SYNOPSIS
        astra db list [ {-cf | --config-file} <CONFIG_FILE> ]
                [ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
                [ --no-color ] [ {-o | --output} <FORMAT> ]
                [ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [ --vector ]

OPTIONS
        -cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
            Configuration file (default = ~/.astrarc)

        -conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
            Section in configuration file (default = ~/.astrarc)

        --env <Environment>
            Astra Environment to use

        --no-color
            Remove all colors in output

        -o <FORMAT>, --output <FORMAT>
            Output format, valid values are: human,json,csv

        --token <AUTH_TOKEN>
            Key to use authenticate each call.

        -v, --verbose
            Verbose mode with log in console

        --vector
            Create a database with vector search enabled

Set up auto-completion

The Astra CLI provides Bash 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
Result 
 --no-color  config      db          help        role        setup       shell       user

Manage the Astra CLI configuration

When you run the astra setup command during initialization, the Astra CLI stores your application token as the default configuration in the ~/.astrarc configuration file. You can create additional configurations, each with their own application token, to make it easier to manage different types of resources across one or more organizations.

Use astra config list to list all current configurations:

astra config list
Result 
+----------------------------+
| configuration              |
+----------------------------+
| Organization 1 (in use)    |
| Organization 2             |
+----------------------------+

Use astra config create to create a new configuration:

astra config create "CONFIG_NAME" --token APPLICATION_TOKEN
Result 
[OK]    Configuration has been saved.

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

astra config use "CONFIG_NAME"
Result 
[OK]    Section 'CONFIG_NAME' is set as default.

Use astra config list to confirm that the selected configuration is now the default.

Every Astra CLI command supports the --config option. This option lets you use a different configuration when running a command without changing the default configuration.

astra user list --config "CONFIG_NAME"

Alternatively, you can use the --token option to supply an application token when running a command. This option lets you use a different application token without having to create a new configuration.

astra user list --token "APPLICATION_TOKEN"

Use astra config delete to delete a configuration:

astra config delete "CONFIG_NAME"
Result 
[OK]    Section 'CONFIG_NAME' has been deleted.

Use astra config list to confirm that the selected configuration is now the default.

If you delete the default configuration, the Astra CLI does not automatically select a new default configuration. Use the astra config use command to select a new default configuration.

config options

NAME
        astra config - Manage configuration file

SYNOPSIS
        astra config { create | delete | describe | get | list* | use } [--]
                [ {-cf | --config-file} <CONFIG_FILE> ] [ --no-color ]
                [ {-v | --verbose} ] [ {-o | --output} <FORMAT> ] [cmd-options]
                <cmd-args>

        Where command-specific options [cmd-options] are:
            create: [ {-e | --env} <Environment> ] [ {-t | --token} <AuthToken> ]
            delete:
            describe: [ {-k | --key} <Key in the section> ]
            get: [ {-k | --key} <Key in the section> ]
            list:
            use:

        Where command-specific arguments <cmd-args> are:
            create: [ <sectionName> ]
            delete: <sectionName>
            describe: <sectionName>
            get: <sectionName>
            list:
            use: <sectionName>

        Where * indicates the default command(s)
        See 'astra help config <command>' for more information on a specific command.
Expand to see all config create options 
NAME
        astra config create - Create a new section in configuration

SYNOPSIS
        astra config create [ {-cf | --config-file} <CONFIG_FILE> ]
                [ {-e | --env} <Environment> ] [ --no-color ]
                [ {-o | --output} <FORMAT> ] [ {-t | --token} <AuthToken> ]
                [ {-v | --verbose} ] [--] [ <sectionName> ]

OPTIONS
        -cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
            Configuration file (default = ~/.astrarc)

        -e <Environment>, --env <Environment>
            Environment to use for this section.

        --no-color
            Remove all colors in output

        -o <FORMAT>, --output <FORMAT>
            Output format, valid values are: human,json,csv

        -t <AuthToken>, --token <AuthToken>
            Key to use authenticate each call.

        -v, --verbose
            Verbose mode with log in console

        --
            This option can be used to separate command-line options from the
            list of arguments (useful when arguments might be mistaken for
            command-line options)

        <sectionName>
            Section in configuration file to as as default.
Expand to see all config delete options 
NAME
        astra config delete - Delete section in configuration

SYNOPSIS
        astra config delete [ {-cf | --config-file} <CONFIG_FILE> ]
                [ --no-color ] [ {-o | --output} <FORMAT> ]
                [ {-v | --verbose} ] [--] <sectionName>

OPTIONS
        -cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
            Configuration file (default = ~/.astrarc)

        --no-color
            Remove all colors in output

        -o <FORMAT>, --output <FORMAT>
            Output format, valid values are: human,json,csv

        -v, --verbose
            Verbose mode with log in console

        --
            This option can be used to separate command-line options from the
            list of arguments (useful when arguments might be mistaken for
            command-line options)

        <sectionName>
            Section in configuration file to as as default.
Expand to see all config describe options 
NAME
        astra config describe - Show details for a configuration.

SYNOPSIS
        astra config describe [ {-cf | --config-file} <CONFIG_FILE> ]
                [ {-k | --key} <Key in the section> ] [ --no-color ]
                [ {-o | --output} <FORMAT> ] [ {-v | --verbose} ] [--]
                <sectionName>

OPTIONS
        -cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
            Configuration file (default = ~/.astrarc)

        -k <Key in the section>, --key <Key in the section>
            If provided return only value for a key.

        --no-color
            Remove all colors in output

        -o <FORMAT>, --output <FORMAT>
            Output format, valid values are: human,json,csv

        -v, --verbose
            Verbose mode with log in console

        --
            This option can be used to separate command-line options from the
            list of arguments (useful when arguments might be mistaken for
            command-line options)

        <sectionName>
            Section in configuration file to as as default.
Expand to see all config get options 
NAME
        astra config get - Show details for a configuration.

SYNOPSIS
        astra config get [ {-cf | --config-file} <CONFIG_FILE> ]
                [ {-k | --key} <Key in the section> ] [ --no-color ]
                [ {-o | --output} <FORMAT> ] [ {-v | --verbose} ] [--]
                <sectionName>

OPTIONS
        -cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
            Configuration file (default = ~/.astrarc)

        -k <Key in the section>, --key <Key in the section>
            If provided return only value for a key.

        --no-color
            Remove all colors in output

        -o <FORMAT>, --output <FORMAT>
            Output format, valid values are: human,json,csv

        -v, --verbose
            Verbose mode with log in console

        --
            This option can be used to separate command-line options from the
            list of arguments (useful when arguments might be mistaken for
            command-line options)

        <sectionName>
            Section in configuration file to as as default.
Expand to see all config list options 
NAME
        astra config list - Show the list of available configurations.

SYNOPSIS
        astra config list [ {-cf | --config-file} <CONFIG_FILE> ]
                [ --no-color ] [ {-o | --output} <FORMAT> ]
                [ {-v | --verbose} ]

OPTIONS
        -cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
            Configuration file (default = ~/.astrarc)

        --no-color
            Remove all colors in output

        -o <FORMAT>, --output <FORMAT>
            Output format, valid values are: human,json,csv

        -v, --verbose
            Verbose mode with log in console
Expand to see all config use options 
NAME
        astra config use - Make a section the one used by default

SYNOPSIS
        astra config use [ {-cf | --config-file} <CONFIG_FILE> ] [ --no-color ]
                [ {-o | --output} <FORMAT> ] [ {-v | --verbose} ] [--]
                <sectionName>

OPTIONS
        -cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
            Configuration file (default = ~/.astrarc)

        --no-color
            Remove all colors in output

        -o <FORMAT>, --output <FORMAT>
            Output format, valid values are: human,json,csv

        -v, --verbose
            Verbose mode with log in console

        --
            This option can be used to separate command-line options from the
            list of arguments (useful when arguments might be mistaken for
            command-line options)

        <sectionName>
            Section in configuration file to as as default.

Next steps

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