On this page 
Warning:
GA releases for CockroachDB v23.1 are no longer supported. Cockroach Labs will stop providing LTS Assistance Support for v23.1 LTS releases on November 13, 2025. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy.
This page introduces the cockroach commands for configuring, starting, and managing a CockroachDB cluster, as well as environment variables that can be used in place of certain flags.
You can run cockroach help in your shell to get similar guidance.
Commands
| Command | Usage |
|---|---|
cockroach start |
Start a node as part of a multi-node cluster. |
cockroach init |
Initialize a multi-node cluster. |
cockroach start-single-node |
Start a single-node cluster. |
cockroach cert |
Create CA, node, and client certificates. |
cockroach sql |
Use the built-in SQL client. |
cockroach sqlfmt |
Reformat SQL queries for enhanced clarity. |
cockroach node |
List node IDs, show their status, decommission nodes for removal, or recommission nodes. |
cockroach nodelocal upload |
Upload a file to the externalIODir on a node's local file system. |
cockroach auth-session |
Create and manage web sessions and authentication tokens to the HTTP interface from the command line. |
cockroach demo |
Start a temporary, in-memory CockroachDB cluster, and open an interactive SQL shell to it. |
cockroach debug ballast |
Create a large, unused file in a node's storage directory that you can delete if the node runs out of disk space. |
cockroach debug encryption-active-key |
View the encryption algorithm and store key. |
cockroach debug job-trace |
Generate trace payloads for an executing job from a particular node. |
cockroach debug list-files |
Show the files that will be collected by using cockroach debug zip. |
cockroach debug merge-logs |
Merge log files from multiple nodes into a single time-ordered stream of messages with an added per-message prefix to indicate the corresponding node. |
cockroach debug tsdump |
Generate a diagnostic dump of timeseries metrics that can help Cockroach Labs troubleshoot issues with your cluster. |
cockroach debug zip |
Generate a .zip file that can help Cockroach Labs troubleshoot issues with your cluster. |
cockroach convert-url |
Convert a connection URL to a format recognized by a supported client driver. |
cockroach gen |
Generate man pages, a bash completion file, example SQL data, or an HAProxy configuration file for a running cluster. |
cockroach statement-diag |
Manage and download statement diagnostics bundles. |
cockroach userfile upload |
Upload a file to user-scoped file storage. |
cockroach userfile list |
List the files stored in the user-scoped file storage. |
cockroach userfile get |
Fetch a file from the user-scoped file storage. |
cockroach userfile delete |
Delete the files stored in the user-scoped file storage. |
cockroach version |
Output CockroachDB version details. |
cockroach workload |
Run a built-in load generator against a cluster. |
cockroach import |
Import a table or database from a local dump file into a running cluster. Supported file formats are PGDUMP and MYSQLDUMP. |
Environment variables
For many common cockroach flags, such as --port and --user, you can set environment variables once instead of manually passing the flags each time you execute commands.
- To find out which flags support environment variables, see the documentation for each command.
- To output the current configuration of CockroachDB and other environment variables, run
env. - When a node uses environment variables on startup, the variable names are printed to the node's logs; however, the variable values are not.
CockroachDB prioritizes command flags, environment variables, and defaults as follows:
- If a flag is set for a command, CockroachDB uses it.
- If a flag is not set for a command, CockroachDB uses the corresponding environment variable.
- If neither the flag nor environment variable is set, CockroachDB uses the default for the flag.
- If there's no flag default, CockroachDB gives an error.
For more details, see Client Connection Parameters.
Was this helpful?
