CLI Authentication and Adding Tokens
Overview
To start using CLI commands, you must first authenticate yourself after installing the CLI and configuring the region. The Contentstack CLI Authentication feature allows you to securely log in or use tokens—such as Management or Delivery tokens—to perform content management tasks via the terminal.
It supports login credentials, Two-Factor Authentication, and Single Sign-On (SSO). You can authenticate either by using the login command or by adding a Management Token to the local config.
Prerequisites
Commands
Authentication
Login
The auth:login command lets you log in to Contentstack and save the login information in your local storage.
Note The Contentstack CLI supports Two-factor Authentication for enhanced security.
Open the terminal and run the following command to log in with your Contentstack account credentials. Once you log in, you can use the Contentstack CLI commands such as export, import, clone, bulk publish and unpublish, seed, bootstrap, migration, etc.
Usage
csdx auth:login
OR
csdx login
Options
| Flag | Short Flag | Type | Required | Default | Description |
|---|---|---|---|---|---|
| --username | -u | string | No. Prompted if omitted | - | Email address of your Contentstack account. Cannot be used with --oauth. |
| --password | -p | string | No. Prompted if omitted | - | Password of your Contentstack account. Cannot be used with --oauth. |
| --oauth | - | boolean | No | false | Enables Single Sign-On (SSO) for the Contentstack CLI. Cannot be used with --username or --password. |
Note To enable automatic OTP generation for MFA-enabled Contentstack accounts, set the CONTENTSTACK_MFA_SECRET environment variable using the MFA secret key provided by Contentstack. This allows the Contentstack CLI to generate one-time passwords (OTPs) automatically, eliminating the need to enter them manually from an authenticator app.
Logout
The auth:logout command lets you log out and clear the authentication from the local storage.
Usage
csdx auth:logout
OR
csdx logout
Options
| Flag | Short Flag | Type | Required | Default | Description |
|---|---|---|---|---|---|
| --yes | -y | boolean | No | false | Skips the confirmation prompt and forces the logout process. |
Display Username of the Logged in User
The csdx auth:whoami command returns the username (email address) of the user who is currently logged in.
Usage
csdx auth:whoami
OR
csdx whoami
Token Management
Add Management Token
Note Ensure you have already generated a Management Token in your stack before running this command.
The following command lets you add an existing Management Token from your Contentstack account to the local config for further use.
Usage
csdx auth:tokens:add --management
Options
| Flag | Short Flag | Type | Required | Default | Description |
|---|---|---|---|---|---|
| --alias | -a | string | No. Prompted if omitted | - | Alias (name) you want to assign to the token. |
| --management | - | boolean | No. Prompted for the token type if neither is used | - | Flag to save the Management Token. Cannot be used with --delivery or --environment. |
| --stack-api-key | -k | string | No. Prompted if omitted | - | API key of the stack where the token exists. |
| --token | - | string | No. Prompted if omitted | - | Value of the token. |
| --yes | -y | boolean | No | - | Skips the confirmation and replaces any existing token with the same alias. |
Add Delivery Token
Note Ensure you have already generated a Delivery Token in your stack before running this command.
For CLI commands, you may use a Delivery Token instead of a Management Token. However, Delivery Tokens cannot be used for importing or exporting content.
Usage
csdx auth:tokens:add --delivery
Options
| Flag | Short Flag | Type | Required | Default | Description |
|---|---|---|---|---|---|
| --alias | -a | string | No. Prompted if omitted | - | Alias (name) you want to assign to the token. |
| --delivery | - | boolean | No. Prompted for the token type if neither is used | - | Flag to save the Delivery Token. Cannot be used with --management. |
| --environment | -e | string | Yes, for a delivery token. Prompted if omitted | - | Environment name for the Delivery Token. Cannot be used with --management. |
| --stack-api-key | -k | string | No. Prompted if omitted | - | API key of the stack where the token exists. |
| --token | - | string | No. Prompted if omitted | - | Value of the token. |
| --yes | -y | boolean | No | - | Skips the confirmation and replaces any existing token with the same alias. |
Delete Token
Note This command will not delete the Management/Delivery token from the stack; it deletes the token from the local config.
Usage
csdx auth:tokens:remove
Options
| Flag | Short Flag | Type | Required | Default | Description |
|---|---|---|---|---|---|
| --alias | -a | string | No | - | Alias (name) of the token to delete. |
List All Tokens
The auth:tokens:list command lists all tokens stored in the local config. The output table has the columns alias, token, apiKey, environment, and type. The environment column shows - for a management token. If you have not added any tokens, the command prints No tokens are added. Use auth:tokens:add command to add tokens.
Usage
csdx auth:tokens:list
Warning csdx auth:tokens does not list tokens. It prints the help text for its sub-commands to standard output and exits successfully. A script that parses its output for a token table receives help text instead, with no error code to detect the problem. Use csdx auth:tokens:list to list tokens.
The short alias csdx tokens is no longer available and fails with a command-not-found error.
Options
| Flag | Short Flag | Type | Required | Default | Description |
|---|---|---|---|---|---|
| --columns | - | string | No | - | Columns to display, comma-separated. Available columns: alias, token, apiKey, environment, type. |
| --sort | - | string | No | - | Column to sort the table by. Prefix the column name with - to sort in descending order. |
| --filter | - | string | No | - | Shows only the rows whose column value contains the given text, in the format <COLUMN>=<VALUE>. For example, --filter type=management. The match ignores case. |
| --csv | - | boolean | No | - | Prints the output in CSV format. |
| --no-truncate | - | boolean | No | - | Prevents truncation of long text in columns. |
| --no-header | - | boolean | No | - | Hides the table header in the output. |
| --output | - | string | No | - |
Prints the output in a machine-readable format.
Supported values: csv, json, yaml |
Examples
List Tokens
csdx auth:tokens:list
csdx auth:tokens:list --columns alias,type
csdx auth:tokens:list --filter type=management --output json
Login
csdx auth:login -u [email protected]
csdx auth:login -u [email protected] -p *****
csdx auth:login --username [email protected] --password *****
csdx login -u [email protected]
csdx auth:login --oauth
Logout
csdx auth:logout -y
csdx logout -y
Add Management Token
csdx auth:tokens:add --management -a tokenname -k blt******** --token cs*********
csdx auth:tokens:add --management -a tokenname -k blt******** --token cs********* -y
Note This command does not generate a new token in your stack. It only allows you to use an existing Management Token with the CLI.
Add Delivery Token
csdx auth:tokens:add --delivery -a tokenname -k blt******** -e <ENVIRONMENT> --token cs*********
csdx auth:tokens:add --delivery -a tokenname -k blt******** -e <ENVIRONMENT> --token cs********* -y
Delete Token
csdx auth:tokens:remove -a mytoken
csdx auth:tokens:remove --alias=mytoken
Limitations
- --delivery and --management on auth:tokens:add are mutually exclusive. Add a delivery token or a management token in one call, not both.
- --environment only applies to a delivery token. It is rejected together with --management.
- --oauth on auth:login is mutually exclusive with --username and --password. Log in with SSO or with credentials, not a mix of both.
Next Steps
- Export and import content
- Publish entries/assets in bulk