Skip to main content
The CockroachDB command-line interface (CLI) is the primary tool for interacting with CockroachDB clusters. It provides commands for starting nodes, executing SQL queries, managing cluster operations, and debugging.

​
Getting Started

The cockroach binary provides all CLI functionality through subcommands: 
cockroach [command] [flags]
Run cockroach help to see all available commands and cockroach [command] --help for detailed information about a specific command.

​
Core Commands

​
Server Operations

CommandDescription
startStart a node in a multi-node cluster
start-single-nodeStart a single-node cluster
initInitialize a cluster

​
Client Operations

CommandDescription
sqlOpen an interactive SQL shell
nodeList, inspect, drain, or remove nodes
quitDrain and shutdown a node

​
Administrative Operations

CommandDescription
debugDebugging tools for troubleshooting
genGenerate auxiliary files (certificates, docs, etc.)
versionDisplay version information

​
Common Patterns

​
Connecting to a Cluster

All client commands support standard connection flags: 
cockroach sql \
  --host=localhost:26257 \
  --certs-dir=certs \
  --user=root

​
Common Flags

These flags are available across most commands:
​
--host
string
default:"localhost:26257"
Database server host and port. Can be specified as hostname or IP address.
​
--certs-dir
string
default:"${HOME}/.cockroach-certs"
Path to certificate directory for secure connections.
​
--insecure
boolean
default:"false"
Connect without encryption (not recommended for production).
​
--user
string
default:"root"
Database user name.
​
--url
string
Full connection URL (alternative to individual connection flags).

​
Environment Variables

Many CLI flags can be set via environment variables:
Environment VariableCorresponding Flag
COCKROACH_HOST--host
COCKROACH_PORT--port
COCKROACH_DATABASE--database
COCKROACH_USER--user
COCKROACH_URL--url
Command-line flags take precedence over environment variables.

​
Exit Codes

The CLI uses standard exit codes:
  • 0: Success
  • 1: General error
  • 2: Command-line parsing error
  • 3: Connection error
  • Specific codes: See individual command documentation

​
Security Best Practices

Always use secure connections in production:
  1. Generate certificates using cockroach cert
  2. Use --certs-dir to specify certificate location
  3. Never use --insecure in production environments
  4. Protect private keys with appropriate file permissions

​
Shell Completion

Enable command completion for your shell: 
cockroach gen autocomplete bash > /etc/bash_completion.d/cockroach

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us