Get Started with the ccloud CLI

On this page

The ccloud tool is a command-line interface (CLI) tool that allows you to create, manage, and connect to CockroachDB Cloud clusters. If you are new to CockroachDB Cloud, install ccloud and use the ccloud quickstart command to interactively log in and create a new CockroachDB Serverless cluster.

Install `ccloud`

Choose your OS:

You can install ccloud using either Homebrew or by downloading the binary.

Use Homebrew

Install Homebrew.
Install using the ccloud tap:
```
brew install cockroachdb/tap/ccloud
```

Download the binary

In a terminal, enter the following command to download and extract the ccloud binary and add it to your PATH:

curl https://binaries.cockroachdb.com/ccloud/ccloud_darwin-amd64_0.6.12.tar.gz | tar -xJ && cp -i ccloud /usr/local/bin/

Use the ARM 64 binary if you have an M-series Mac:

curl https://binaries.cockroachdb.com/ccloud/ccloud_darwin-arm64_0.6.12.tar.gz | tar -xJ && cp -i ccloud /usr/local/bin/

In a terminal, enter the following command to download and extract the ccloud binary and add it to your PATH:

curl https://binaries.cockroachdb.com/ccloud/ccloud_linux-amd64_0.6.12.tar.gz | tar -xz && cp -i ccloud /usr/local/bin/

In a PowerShell window, enter the following command to download and extract the ccloud binary and add it to your PATH:

$ErrorActionPreference = "Stop"; [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; $ProgressPreference = 'SilentlyContinue'; $null = New-Item -Type Directory -Force $env:appdata/ccloud; Invoke-WebRequest -Uri https://binaries.cockroachdb.com/ccloud/ccloud_windows-amd64_0.6.12.zip -OutFile ccloud.zip; Expand-Archive -Force -Path ccloud.zip; Copy-Item -Force ccloud/ccloud.exe -Destination $env:appdata/ccloud; $Env:PATH += ";$env:appdata/ccloud"; # We recommend adding ";$env:appdata/ccloud" to the Path variable for your system environment. See https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables#saving-changes-to-environment-variables for more information.

Use `ccloud quickstart`

The easiest way of getting started with CockroachDB Cloud is to use ccloud quickstart. The ccloud quickstart command guides you through logging in to CockroachDB Cloud, creating a new CockroachDB Serverless cluster, and connecting to the new cluster. Run ccloud quickstart and follow the instructions:

ccloud quickstart

The ccloud quickstart command will open a browser window to log you in to CockroachDB Cloud. If you are new to CockroachDB Cloud, you can register using one of the single-sign-on options, or create a new account using an email address.

Log in to CockroachDB Cloud using `ccloud auth`

In order to use the ccloud commands to configure and manage your clusters, you first need to log in to CockroachDB Cloud. Use the ccloud auth login command to open a browser window to log in to CockroachDB Cloud.

Run the ccloud auth login command and press Enter to open a browser window:
```
ccloud auth login
```
This will take you to the CockroachDB Cloud login page.
Enter your username and password if you already have a CockroachDB Cloud account, then click Continue.

If you do not have a CockroachDB Cloud account, click one of the single sign-on (SSO) options or Sign up to register.
Close the browser window and return to your terminal.

If you are a member of more than one CockroachDB Cloud organization, use the --org flag to set the organization name when authenticating.

ccloud auth login --org {organization-label}

The organization label is found on the Settings page of the CockroachDB Cloud Console.

If your organization has a custom URL, use the --vanity-name flag to log in:

ccloud auth login --vanity-name {custom-organization-name}

Replace {custom-organization-name} with the portion of the custom sign-in URL that follows /login/. Do not pass the full custom sign-in URL.

Log in to CockroachDB Cloud on a headless server

If you are using ccloud on a headless machine, use the --no-redirect flag to log in. This allows you to log in to CockroachDB Cloud on a different machine, retrieve an authorization code, and enter the code on the headless machine so ccloud can complete authentication.

ccloud auth login --no-redirect

Create a new cluster using `ccloud cluster create`

There are two ways to create clusters using ccloud: ccloud quickstart create and ccloud cluster create.

The ccloud quickstart create command interactively guides you through creating and connecting to a new CockroachDB Serverless cluster.

The ccloud cluster create command creates a new CockroachDB Serverless or CockroachDB Advanced CockroachDB cluster in your organization.

Use the ccloud cluster create command to create a new CockroachDB Serverless cluster.

ccloud cluster create

This command creates a CockroachDB Serverless cluster in the default cloud infrastructure provider (GCP) and the closest region for that provider. It will generate a cluster name.

∙∙∙ Creating cluster...
Success! Created cluster
  name: blue-dog
  id: ec5e50eb-67dd-4d25-93b0-91ee7ece778d

The id in the output is the cluster ID. You use the name in other ccloud commands to identify the cluster on which the ccloud command operates.

You can set the cluster name, cloud infrastructure provider, region, and resource limits as command options. The following command is equivalent to the previous command that uses the default values.

ccloud cluster create serverless blue-dog us-central1 --cloud GCP --spend-limit 0

Use the ccloud cluster create command to create a new CockroachDB Advanced cluster.

ccloud cluster create dedicated

This command creates a 1-node CockroachDB Advanced cluster with 4 virtual CPUs (vCPUs) and 110 GiB of storage in the default cloud infrastructure provider (GCP) and the closest region for that provider. It will generate a cluster name. The CockroachDB version will be the latest stable version.

You can set the cluster name, cloud infrastructure provider, region, number of nodes, and storage as command options. The following command is equivalent to the previous command that uses the default values.

ccloud cluster create dedicated blue-dog us-central1:1 --cloud GCP --vcpus 4 --storage-gib 110

∙∙∙ Creating cluster
Success! Created cluster
  name: blue-dog
  id: ec5e50eb-67dd-4d25-93b0-91ee7ece778d

The id in the output is the cluster ID. You use the name in other ccloud commands to identify the cluster on which the ccloud command operates.

When creating multi-region clusters, you must specify how many nodes should be in each region supported by the cloud infrastructure provider. For example, the following command creates a 12-node cluster where 8 nodes are in us-central1 and 4 nodes are in us-west2. For optimum performance, it is generally recommended to configure the same number of nodes in each region.

ccloud cluster create dedicated blue-dog us-central1:8 us-west2:4 --cloud GCP --vcpus 4 --storage-gib 110

Create and manage IP allowlists using `ccloud cluster networking allowlist`

Use the ccloud cluster networking allowlist create command to create an IP allowlist, which allows incoming network connections from the specified network IP range. Use the --sql flag to allow incoming CockroachDB SQL shell connections from the specified network. Use the --ui flag to allow access to the DB Console from the specified network.

The IP range must be in Classless Inter-Domain Routing (CIDR) format. For more information on CIDR, see Understanding IP Addresses, Subnets, and CIDR Notation for Networking.

For example, to allow incoming connections from a single IP address, 1.1.1.1, to your cluster, including the CockroachDB SQL shell and DB Console, use the following command:

ccloud cluster networking allowlist create blue-dog 1.1.1.1/32 --sql --ui

∙∙∙ Creating IP allowlist entry...
Success! Created IP allowlist entry for
 network: 1.1.1.1/32
 cluster: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d

Use the ccloud cluster networking allowlist list command to list the IP allowlists for your cluster:

ccloud cluster networking allowlist list blue-dog

∙●∙ Retrieving cluster allowlist...
NETWORK         NAME  UI  SQL
1.1.1.1/32            ✔   ✔

To modify an allowlist entry, use the ccloud cluster networking allowlist update command. The following command adds a descriptive name to the previously created entry.

ccloud cluster networking allowlist update blue-dog 1.1.1.1/32 --name home

∙∙● Updating IP allowlist entry...
Success! Updated IP allowlist entry for
 network: 1.1.1.1/32
 cluster: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d

Rerunning the allowlist list command shows the updated entry:

ccloud cluster networking allowlist list blue-dog

∙∙∙ Retrieving cluster allowlist...
NETWORK         NAME  UI  SQL
1.1.1.1/32      home  ✔   ✔

To delete an entry, run the ccloud cluster networking allowlist delete command.

ccloud cluster networking allowlist delete blue-dog 1.1.1.1/32

∙∙∙ Deleting IP allowlist entry...
Success! Deleted IP allowlist entry for
 network: 1.1.1.1/32
 cluster: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d

Get a list of all the clusters in your organization using `ccloud cluster list`

Use the ccloud cluster list command to show information about the clusters in your organization. It outputs columns with the cluster name, the cluster ID, the cluster plan, the creation date, the cluster's current state, the cloud provider, and the version of CockroachDB.

ccloud cluster list

∙∙∙ Retrieving clusters...
NAME                 ID                                    PLAN TYPE        CREATED AT                            STATE                   CLOUD               VERSION
blue-dog              041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d  PLAN_SERVERLESS  2022-03-20 13:47:40.529531 +0000 UTC  CLUSTER_STATE_CREATED   CLOUD_PROVIDER_GCP  v21.2.4
...

∙∙∙ Retrieving clusters...
NAME      ID                                    PLAN TYPE        CREATED AT                            STATE                   CLOUD               VERSION
blue-dog   041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d  PLAN_DEDICATED   2022-03-22 21:07:35.7177 +0000 UTC    CLUSTER_STATE_CREATING  CLOUD_PROVIDER_GCP  v21.2.4
...

Get information about your cluster using `ccloud cluster info`

Use the ccloud cluster info command with the cluster name as the parameter to show detailed information about your cluster. Find the Name column in the output of ccloud cluster list to find the name of the cluster.

ccloud cluster info blue-dog

∙∙∙ Retrieving cluster...
Cluster info
 name: blue-dog
 id: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
 cockroach version: v25.4
 cloud: CLOUD_PROVIDER_GCP
 plan type: PLAN_SERVERLESS
 state: CLUSTER_STATE_CREATED
 resource limit: 0
 regions: us-central1

∙∙∙ Retrieving cluster...
Cluster info
 name: ievans-blue-dog-dos
 id: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
 cockroach version: v25.4
 cloud: CLOUD_PROVIDER_GCP
 plan type: PLAN_DEDICATED
 state: CLUSTER_STATE_CREATING
 hardware per node:
  4 vCPU
  7.500000 GiB RAM
  110 GiB disk
  450 IOPS
 region nodes:
  us-central1: 1

Use a SQL client with a cluster using `ccloud cluster sql`

Use the ccloud cluster sql command to start a CockroachDB SQL shell connection to the specified cluster using the cluster ID. If you haven't created a SQL user for the specified cluster, you will be prompted to create a new user and set the user password.

ccloud cluster sql blue-dog

∙∙∙ Retrieving cluster info...
∙∙∙ Retrieving SQL user list...
No SQL users found. Create one now: y
Create a new SQL user:
Username: user
Password: ****************
∙∙∙ Creating SQL user...
Success! Created SQL user
 name: user
 cluster: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
Starting CockroachDB SQL shell...
#
# Welcome to the CockroachDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
# Client version: CockroachDB CCL v21.2.5 (x86_64-apple-darwin19, built 2022/02/07 21:04:05, go1.16.6)
# Server version: CockroachDB CCL v21.2.4-1-g70835279ac (x86_64-unknown-linux-gnu, built 2022/02/03 22:31:25, go1.16.6)

warning: server version older than client! proceed with caution; some features may not be available.

# Cluster ID: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
#
# Enter \? for a brief introduction.
#
user@free-tier7.gcp-us-central1.crdb.io:26257/defaultdb>

Connect to your cluster using SSO

Use the --sso flag to connect to your cluster using single sign-on (SSO) authentication, which will allow you to start a SQL shell without using a password.

ccloud cluster sql --sso blue-dog

This will open a browser window on the local machine where you will log in to your organization if you are not already authenticated.

If you are running ccloud on a remote machine, use the --no-redirect flag. ccloud will output a URL that you must copy and paste in your local machine's browser in order to authenticate. After authentication, paste in the authorization code you received in the remote terminal to complete the login process.

ccloud cluster sql --sso --no-redirect blue-dog

Using SSO login requires that a separate SSO SQL user for your account is created on the cluster you are connecting to. SSO SQL usernames are prefixed with sso_. The SSO SQL username you use must match the SSO SQL username generated for you.

To create a SSO SQL user:

Connect to the cluster using the --sso flag.
```
ccloud cluster sql --sso blue-dog
```
Log in to your organization when prompted by ccloud.
Copy the command in the error message to create the SSO SQL user with the correct username.

You must have admin privileges to create the SSO SQL user.
Create the SSO SQL user by pasting and running the command you copied.

For example, if the command in the error message creates a sso_maxroach user:
```
ccloud cluster user create blue-dog sso_maxroach
```
Re-run the SQL client command to login and connect to your cluster.
```
ccloud cluster sql blue-dog --sso
```

Note:

Use the ccloud auth whoami command to check that you are logged into the correct organization.

If the organization is incorrect:

Log out of the current organization.
```
ccloud auth logout
```
Log in to the correct organization.
```
ccloud auth login --org {organization name}
```

Skip the IP allowlist check when connecting to your cluster

By default, the ccloud cluster sql command will allow connections only from IP addresses in your cluster's allowlist. Use the --skip-ip-check flag to disable the client-side IP allowlist check:

ccloud cluster sql blue-dog --skip-ip-check

Get the connection information for your cluster using `ccloud cluster sql`

Use the ccloud cluster sql command to get connection information for the specified cluster using the cluster name.

To get the connection URL, use the --connection-url option.

ccloud cluster sql --connection-url blue-dog

∙∙∙ Retrieving cluster info...
postgresql://blue-dog-147.6wr.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=%2FUsers%2Fuser%2F.postgresql%2Froot.crt

∙∙∙ Retrieving cluster info...
postgresql://blue-dog-5bct.gcp-us-east4.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=%2FUsers%2Fuser%2FLibrary%2FCockroachCloud%2Fcerts%2Fblue-dog-ca.crt

To get the individual connection parameters, use the --connection-params option.

ccloud cluster sql --connection-params blue-dog

Connection parameters
 Database:  defaultdb
 Host:      blue-dog-147.6wr.cockroachlabs.cloud
 Port:      26257

∙∙∙ Retrieving cluster info...
Connection parameters
 Database:  defaultdb
 Host:      blue-dog-5bct.gcp-us-east4.cockroachlabs.cloud
 Port:      26257

Get a connection string using `ccloud cluster connection-string`

Use the ccloud cluster connection-string command to get a formatted connection string for a cluster. You can optionally specify the database and SQL user.

ccloud cluster connection-string blue-dog

∙∙∙ Retrieving cluster info...
postgresql://blue-dog-5bct.gcp-us-east4.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full

To specify a database and SQL user:

ccloud cluster connection-string blue-dog --database myapp --sql-user maxroach

∙∙∙ Retrieving cluster info...
postgresql://maxroach@blue-dog-5bct.gcp-us-east4.cockroachlabs.cloud:26257/myapp?sslmode=verify-full

Create a SQL user using `ccloud cluster user create`

Use the ccloud cluster user create command to create a new SQL user by passing in the cluster name and the username. By default, newly created users are assigned to the admin role. An admin SQL user has full privileges for all databases and tables in your cluster. This user can also create additional users and grant them appropriate privileges.

ccloud cluster user create blue-dog maxroach

Password: ****************
∙∙∙ Creating SQL user...

Manage databases using `ccloud cluster database`

Use the ccloud cluster database commands to list, create, and delete databases within a cluster.

To list all databases in a cluster:

ccloud cluster database list blue-dog

∙∙∙ Retrieving databases...
NAME        TABLE COUNT
defaultdb   0
myapp       12

To create a new database:

ccloud cluster database create blue-dog myapp

∙∙∙ Creating database...
Success! Created database
 name: myapp

To delete a database:

ccloud cluster database delete blue-dog myapp

∙∙∙ Deleting database...
Success! Deleted database
 name: myapp

Manage backups using `ccloud cluster backup`

Use the ccloud cluster backup commands to list backups and manage backup configuration for a cluster.

To list backups for a cluster:

ccloud cluster backup list blue-dog

∙∙∙ Retrieving backups...
BACKUP ID                             POINT IN TIME (UTC)
a1b2c3d4-e5f6-7890-abcd-ef1234567890  2026-03-01 10:30:00Z
b2c3d4e5-f6a7-8901-bcde-f12345678901  2026-02-28 10:30:00Z

To get the current backup configuration:

ccloud cluster backup config get blue-dog

∙∙∙ Retrieving backup configuration...
ENABLED  FREQUENCY (MIN)  RETENTION (DAYS)
true     60               30

To update the backup configuration:

ccloud cluster backup config update blue-dog --enabled true --frequency 120 --retention 60

∙∙∙ Updating backup configuration...
Success! Updated backup configuration

Restore from a backup using `ccloud cluster restore`

Use the ccloud cluster restore commands to list and create restore operations from backups.

To list restores for a cluster:

ccloud cluster restore list blue-dog

∙∙∙ Retrieving restores...
ID                                    BACKUP ID                             TYPE     STATUS     COMPLETION %  CREATED AT
c3d4e5f6-a7b8-9012-cdef-123456789012  a1b2c3d4-e5f6-7890-abcd-ef1234567890  CLUSTER  COMPLETE   100%          2026-03-01 12:00:00Z

To restore from a specific backup to a destination cluster:

ccloud cluster restore create blue-dog --backup-id a1b2c3d4-e5f6-7890-abcd-ef1234567890

∙∙∙ Creating restore...
Successfully initiated restore
Restore ID: d4e5f6a7-b8c9-0123-defa-234567890123
Backup ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Type: CLUSTER
Status: RUNNING

If you are restoring from a different cluster, specify the source cluster ID:

ccloud cluster restore create blue-dog --source-cluster-id a1b2c3d4-e5f6-7890-abcd-ef1234567890

You can also specify the restore type (CLUSTER, DATABASE, or TABLE) using the --type flag:

ccloud cluster restore create blue-dog --backup-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 --type DATABASE

List available CockroachDB versions using `ccloud cluster versions`

Use the ccloud cluster versions command to list the CockroachDB major versions available for new clusters or upgrades.

ccloud cluster versions

∙∙∙ Retrieving versions...
VERSION  RELEASE DATE  END OF SUPPORT
v25.2    2025-11-18    2026-11-18
v25.1    2025-05-19    2026-05-19
v24.3    2024-11-18    2025-11-18

Manage version deferral using `ccloud cluster version-deferral`

Use the ccloud cluster version-deferral commands to get or set the version upgrade deferral policy for a CockroachDB Advanced cluster. Version deferral lets you delay automatic major version upgrades.

To get the current deferral policy:

ccloud cluster version-deferral get blue-dog

∙∙∙ Retrieving version deferral...
DEFERRAL POLICY
NOT_DEFERRED

To set the deferral policy:

ccloud cluster version-deferral set blue-dog --policy DEFERRAL_60_DAYS

∙∙∙ Setting version deferral...
Success! Set version deferral policy
 policy: DEFERRAL_60_DAYS

Valid deferral policies are NOT_DEFERRED, DEFERRAL_30_DAYS, DEFERRAL_60_DAYS, and DEFERRAL_90_DAYS.

Manage blackout windows using `ccloud cluster blackout-window`

Use the ccloud cluster blackout-window commands to manage blackout windows for a CockroachDB Advanced cluster. Blackout windows prevent automatic maintenance operations during specified time periods.

To list blackout windows:

ccloud cluster blackout-window list blue-dog

∙∙∙ Retrieving blackout windows...
ID                                    START TIME            END TIME
e5f6a7b8-c9d0-1234-efab-345678901234  2026-04-01 00:00:00Z  2026-04-07 00:00:00Z

To create a blackout window, specify the start and end times in RFC3339 format. The start time must be at least 7 days in the future, and the end time must be within 14 days of the start time.

ccloud cluster blackout-window create blue-dog --start 2026-04-01T00:00:00Z --end 2026-04-07T00:00:00Z

∙∙∙ Creating blackout window...
Successfully created blackout window
ID: e5f6a7b8-c9d0-1234-efab-345678901234
Start: 2026-04-01 00:00:00Z
End: 2026-04-07 00:00:00Z

To delete a blackout window:

ccloud cluster blackout-window delete blue-dog e5f6a7b8-c9d0-1234-efab-345678901234

∙∙∙ Deleting blackout window...
Success! Deleted blackout window
 id: e5f6a7b8-c9d0-1234-efab-345678901234

Manage maintenance windows using `ccloud cluster maintenance`

Use the ccloud cluster maintenance commands to configure the preferred maintenance window for a CockroachDB Advanced cluster. The maintenance window determines when automatic maintenance operations are performed. The window duration must be at least 6 hours and less than 1 week.

To get the current maintenance window:

ccloud cluster maintenance get blue-dog

∙∙∙ Retrieving maintenance window...
Cluster: blue-dog
Window Start: Tuesday 02:00 UTC
Window Duration: 6h

To set a maintenance window using --day and --hour:

ccloud cluster maintenance set blue-dog --day tuesday --hour 2 --duration 6h

∙∙∙ Setting maintenance window...
Success! Set maintenance window
Cluster: blue-dog
Window Start: Tuesday 02:00 UTC
Window Duration: 6h

Alternatively, you can specify the window start time as a raw offset from Monday 00:00 UTC using --offset:

ccloud cluster maintenance set blue-dog --offset 26h --duration 6h

To delete (reset) the maintenance window:

ccloud cluster maintenance delete blue-dog

∙∙∙ Deleting maintenance window...
Success! Deleted maintenance window for cluster blue-dog

Simulate cluster disruptions using `ccloud cluster disruption`

Use the ccloud cluster disruption commands to simulate cluster disruptions for disaster recovery testing on a CockroachDB Advanced cluster. Disruptions allow you to test how your applications behave when parts of your cluster become unavailable.

To get the current disruption status:

ccloud cluster disruption get blue-dog

∙∙∙ Retrieving disruption status...
No disruptions active

To disrupt an entire region:

ccloud cluster disruption set blue-dog --region us-east-1 --whole-region

∙∙∙ Setting disruption...
Successfully set disruption for region us-east-1

To disrupt specific availability zones within a region:

ccloud cluster disruption set blue-dog --region us-east-1 --azs us-east-1a,us-east-1b

To clear all disruptions and restore normal operation:

ccloud cluster disruption clear blue-dog

∙∙∙ Clearing disruptions...
Successfully cleared all disruptions

View CMEK configuration using `ccloud cluster cmek`

Use the ccloud cluster cmek get command to view the Customer-Managed Encryption Keys (CMEK) configuration for a CockroachDB Advanced cluster.

ccloud cluster cmek get blue-dog

∙∙∙ Retrieving CMEK configuration...
STATUS    KEY                                                              REGION
ENABLED   arn:aws:kms:us-east-1:123456789:key/a1b2c3d4-e5f6-7890-abcd-ef  us-east-1

Configure log export using `ccloud cluster log-export`

Use the ccloud cluster log-export commands to configure log export for a CockroachDB Advanced cluster. You can export logs to AWS CloudWatch, GCP Cloud Logging, or Azure Log Analytics.

To get the current log export configuration:

ccloud cluster log-export get blue-dog

∙∙∙ Retrieving log export configuration...
Cluster: blue-dog
Log Export Status: ENABLED
Type: AWS_CLOUDWATCH
Log Name: cockroach-logs
Auth Principal: arn:aws:iam::123456789:role/CockroachCloudLogExport

To enable log export to AWS CloudWatch:

ccloud cluster log-export enable blue-dog --type AWS_CLOUDWATCH --auth-principal arn:aws:iam::123456789:role/CockroachCloudLogExport --log-name cockroach-logs

∙∙∙ Enabling log export...
Success! Enabled log export
Cluster: blue-dog
Type: AWS_CLOUDWATCH
Status: ENABLING

To disable log export:

ccloud cluster log-export disable blue-dog

∙∙∙ Disabling log export...
Success! Disabled log export for cluster blue-dog

Configure metric export using `ccloud cluster metric-export`

Use the ccloud cluster metric-export commands to configure metric export for a CockroachDB Advanced cluster. You can export metrics to AWS CloudWatch, Datadog, or Prometheus.

Export metrics to AWS CloudWatch

ccloud cluster metric-export cloudwatch enable blue-dog --role-arn arn:aws:iam::123456789:role/metrics-role --target-region us-east-1

∙∙∙ Enabling CloudWatch metric export...
Success! Enabled CloudWatch metric export

To get the current CloudWatch configuration:

ccloud cluster metric-export cloudwatch get blue-dog

To disable CloudWatch metric export:

ccloud cluster metric-export cloudwatch disable blue-dog

Export metrics to Datadog

ccloud cluster metric-export datadog enable blue-dog --site us5 --api-key your-datadog-api-key

∙∙∙ Enabling Datadog metric export...
Success! Enabled Datadog metric export

To get the current Datadog configuration:

ccloud cluster metric-export datadog get blue-dog

To disable Datadog metric export:

ccloud cluster metric-export datadog disable blue-dog

Export metrics to Prometheus

ccloud cluster metric-export prometheus enable blue-dog

∙∙∙ Enabling Prometheus metric export...
Success! Enabled Prometheus metric export

To get the Prometheus scrape endpoint:

ccloud cluster metric-export prometheus get blue-dog

To disable the Prometheus endpoint:

ccloud cluster metric-export prometheus disable blue-dog

Manage egress rules using `ccloud cluster networking egress-rule`

Use the ccloud cluster networking egress-rule commands to manage egress traffic rules for a CockroachDB Advanced cluster. Egress rules control which external destinations your cluster can connect to.

To list egress rules:

ccloud cluster networking egress-rule list blue-dog

∙∙∙ Retrieving egress rules...
ID                                    NAME           TYPE  DESTINATION        DESCRIPTION
f6a7b8c9-d0e1-2345-fab0-456789012345  allow-s3       FQDN  s3.amazonaws.com   Allow S3 access
a7b8c9d0-e1f2-3456-ab01-567890123456  allow-subnet   CIDR  10.0.0.0/8         Internal network

To create an egress rule:

ccloud cluster networking egress-rule create blue-dog --name allow-s3 --type FQDN --destination s3.amazonaws.com --description "Allow S3 access"

∙∙∙ Creating egress rule...
Successfully created egress rule
ID: f6a7b8c9-d0e1-2345-fab0-456789012345
Name: allow-s3
Type: FQDN
Destination: s3.amazonaws.com

To delete an egress rule:

ccloud cluster networking egress-rule delete blue-dog f6a7b8c9-d0e1-2345-fab0-456789012345

∙∙∙ Deleting egress rule...
Successfully deleted egress rule 'f6a7b8c9-d0e1-2345-fab0-456789012345'

Manage egress private endpoints using `ccloud cluster networking egress-private-endpoint`

Use the ccloud cluster networking egress-private-endpoint commands to manage egress private endpoint connections from a CockroachDB Advanced cluster. Egress private endpoints allow your cluster to connect to external services using private network connectivity.

To list egress private endpoints:

ccloud cluster networking egress-private-endpoint list blue-dog

∙∙∙ Retrieving egress private endpoints...
ID                                    REGION       STATE    TARGET SERVICE
b8c9d0e1-f2a3-4567-b012-678901234567  us-east-1    ACTIVE   com.amazonaws.vpce.us-east-1.vpce-svc-012345abcdef

To get details of an egress private endpoint:

ccloud cluster networking egress-private-endpoint get blue-dog b8c9d0e1-f2a3-4567-b012-678901234567

∙∙∙ Retrieving egress private endpoint...
ID: b8c9d0e1-f2a3-4567-b012-678901234567
Region: us-east-1
State: ACTIVE
Target Service Type: PRIVATE_SERVICE
Target Service Identifier: com.amazonaws.vpce.us-east-1.vpce-svc-012345abcdef
Endpoint Address: 10.0.1.5
Endpoint Connection ID: vpce-0abc123def456789

To create an egress private endpoint:

ccloud cluster networking egress-private-endpoint create blue-dog --region us-east-1 --target-service-identifier com.amazonaws.vpce.us-east-1.vpce-svc-012345abcdef --target-service-type PRIVATE_SERVICE

∙∙∙ Creating egress private endpoint...
Successfully created egress private endpoint
ID: b8c9d0e1-f2a3-4567-b012-678901234567
Region: us-east-1
State: CREATING

Valid target service types are PRIVATE_SERVICE, MSK_SASL_SCRAM, MSK_SASL_IAM, and MSK_TLS.

To delete an egress private endpoint:

ccloud cluster networking egress-private-endpoint delete blue-dog b8c9d0e1-f2a3-4567-b012-678901234567

∙∙∙ Deleting egress private endpoint...
Successfully deleted egress private endpoint 'b8c9d0e1-f2a3-4567-b012-678901234567'

Manage client CA certificates using `ccloud cluster networking client-ca-cert`

Use the ccloud cluster networking client-ca-cert commands to manage client CA certificates for a CockroachDB Advanced cluster. Client CA certificates allow clients to authenticate using TLS certificates signed by your own certificate authority.

To get the current client CA certificate:

ccloud cluster networking client-ca-cert get blue-dog

∙∙∙ Retrieving client CA certificate...
STATUS   X509 CERTIFICATE
ACTIVE   -----BEGIN CERTIFICATE-----
         MIIBxTCCAWugAwIBAgIRAJ...
         -----END CERTIFICATE-----

To set a client CA certificate from a PEM-encoded file:

ccloud cluster networking client-ca-cert set blue-dog --cert-file /path/to/ca.crt

∙∙∙ Setting client CA certificate...
Success! Set client CA certificate

To update the client CA certificate:

ccloud cluster networking client-ca-cert update blue-dog --cert-file /path/to/new-ca.crt

∙∙∙ Updating client CA certificate...
Success! Updated client CA certificate

To delete the client CA certificate:

ccloud cluster networking client-ca-cert delete blue-dog

∙∙∙ Deleting client CA certificate...
Success! Deleted client CA certificate

Manage private endpoints using `ccloud cluster networking private-endpoint`

Use the ccloud cluster networking private-endpoint commands to manage private endpoint connectivity for a CockroachDB Advanced cluster. Private endpoints provide private connectivity using AWS PrivateLink, GCP Private Service Connect, or Azure Private Link.

Manage private endpoint services

To list available private endpoint services for a cluster:

ccloud cluster networking private-endpoint service list blue-dog

∙∙∙ Retrieving private endpoint services...
REGION       SERVICE ID                                                     CLOUD  STATUS      AVAILABILITY ZONES
us-east-1    com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef         AWS    AVAILABLE   us-east-1a,us-east-1b,us-east-1c

To create private endpoint services for all regions in a cluster:

ccloud cluster networking private-endpoint service create blue-dog

∙∙∙ Creating private endpoint services...
Success! Created private endpoint services:

REGION       SERVICE ID                                                     CLOUD  STATUS
us-east-1    com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef         AWS    CREATING

Manage private endpoint connections

To list connections:

ccloud cluster networking private-endpoint connection list blue-dog

∙∙∙ Retrieving private endpoint connections...
ENDPOINT ID                  SERVICE ID                                                     REGION       CLOUD  STATUS
vpce-0123456789abcdef0       com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef         us-east-1    AWS    AVAILABLE

To add a connection using your cloud provider's private endpoint identifier:

ccloud cluster networking private-endpoint connection add blue-dog vpce-0123456789abcdef0

∙∙∙ Adding private endpoint connection...
Success! Added private endpoint connection
 Endpoint ID: vpce-0123456789abcdef0
 Service ID: com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef
 Status: PENDING

To remove a connection:

ccloud cluster networking private-endpoint connection remove blue-dog vpce-0123456789abcdef0

∙∙∙ Removing private endpoint connection...
Success! Removed private endpoint connection vpce-0123456789abcdef0

Manage trusted owners

Trusted owners control which cloud provider accounts are allowed to establish private endpoint connections to your cluster.

To list trusted owners:

ccloud cluster networking private-endpoint trusted-owner list blue-dog

∙∙∙ Retrieving trusted owners...
ID                                    EXTERNAL OWNER ID  TYPE
a1b2c3d4-e5f6-7890-abcd-ef1234567890  123456789012       AWS_ACCOUNT_ID

To add a trusted owner:

ccloud cluster networking private-endpoint trusted-owner add blue-dog 123456789012 --type AWS_ACCOUNT_ID

∙∙∙ Adding trusted owner...
Success! Added trusted owner
 ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
 External Owner ID: 123456789012
 Type: AWS_ACCOUNT_ID

To remove a trusted owner:

ccloud cluster networking private-endpoint trusted-owner remove blue-dog a1b2c3d4-e5f6-7890-abcd-ef1234567890

∙∙∙ Removing trusted owner...
Success! Removed trusted owner a1b2c3d4-e5f6-7890-abcd-ef1234567890

Delete a cluster using `ccloud cluster delete`

Use the ccloud cluster delete command to delete the specified cluster using the cluster name.

ccloud cluster delete blue-dog

∙∙∙ Deleting cluster...
Success! Deleted cluster
 id: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d

Note:

If the cluster state is CLUSTER_STATE_CREATING you cannot delete the cluster. You must wait until the cluster has been provisioned and started, with a status of CLUSTER_STATE_CREATED, before you can delete the cluster. CockroachDB Serverless clusters are created in less than a minute. CockroachDB Advanced clusters can take an hour or more to provision and start.

View organization information using `ccloud organization get`

Use the ccloud organization get command (or its alias ccloud org get) to view information about your CockroachDB Cloud organization.

ccloud organization get

∙∙∙ Retrieving organization...
Organization info
 name: my-organization
 id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
 created at: 2024-01-15 10:30:00Z

View audit logs using `ccloud audit list`

Use the ccloud audit list command to view audit log entries for your organization. Audit logs record actions taken on your CockroachDB Cloud resources, including who performed the action, when, and what was changed.

ccloud audit list

∙∙∙ Retrieving audit logs...
TIME                  ACTION                CLUSTER     USER
2026-03-01 12:00:00Z  CLUSTER_CREATED       blue-dog    user@example.com
2026-03-01 11:30:00Z  SQL_USER_CREATED      blue-dog    user@example.com
2026-03-01 10:00:00Z  ALLOWLIST_CREATED     blue-dog    user@example.com

Use the --limit flag to control the number of entries returned, and --starting-from to filter by start time:

ccloud audit list --limit 10 --starting-from 2026-03-01T00:00:00Z

Manage billing using `ccloud billing`

Use the ccloud billing invoice commands to view invoices and billing information for your organization.

To list invoices:

ccloud billing invoice list

∙∙∙ Retrieving invoices...
INVOICE ID                            PERIOD START          PERIOD END            AMOUNT     STATUS
d0e1f2a3-b4c5-6789-0123-456789abcdef  2026-02-01 00:00:00Z  2026-02-28 23:59:59Z  $1,234.56  PAID
e1f2a3b4-c5d6-7890-1234-567890abcdef  2026-01-01 00:00:00Z  2026-01-31 23:59:59Z  $1,100.00  PAID

To get details of a specific invoice:

ccloud billing invoice get d0e1f2a3-b4c5-6789-0123-456789abcdef

Manage folders using `ccloud folder`

Use the ccloud folder commands to manage folders for organizing clusters within your organization.

To list folders:

ccloud folder list

∙∙∙ Retrieving folders...
ID                                    NAME          PARENT PATH  TYPE
f2a3b4c5-d6e7-8901-2345-678901abcdef  Production                 FOLDER
a3b4c5d6-e7f8-9012-3456-789012abcdef  Staging       /Production  FOLDER

To get details of a specific folder:

ccloud folder get f2a3b4c5-d6e7-8901-2345-678901abcdef

To create a folder:

ccloud folder create --name Production

∙∙∙ Creating folder...
Success! Created folder
 id: f2a3b4c5-d6e7-8901-2345-678901abcdef
 name: Production

To create a subfolder, use the --parent-id flag:

ccloud folder create --name Staging --parent-id f2a3b4c5-d6e7-8901-2345-678901abcdef

To update a folder name:

ccloud folder update f2a3b4c5-d6e7-8901-2345-678901abcdef --name "Prod Environment"

∙∙∙ Updating folder...
Success! Updated folder

To delete a folder:

ccloud folder delete f2a3b4c5-d6e7-8901-2345-678901abcdef

∙∙∙ Deleting folder...
Success! Deleted folder
 id: f2a3b4c5-d6e7-8901-2345-678901abcdef

To list the contents of a folder:

ccloud folder contents f2a3b4c5-d6e7-8901-2345-678901abcdef

∙∙∙ Retrieving folder contents...
RESOURCE ID                           RESOURCE TYPE
041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d  CLUSTER
a3b4c5d6-e7f8-9012-3456-789012abcdef  FOLDER

Manage service accounts using `ccloud service-account`

Use the ccloud service-account commands to manage service accounts for programmatic access to CockroachDB Cloud.

To list service accounts:

ccloud service-account list

∙∙∙ Retrieving service accounts...
ID                                    NAME          DESCRIPTION        CREATOR              CREATED AT
b4c5d6e7-f8a9-0123-4567-890123abcdef  ci-pipeline   CI/CD automation   user@example.com     2026-01-15 10:30:00Z

To get details of a specific service account:

ccloud service-account get b4c5d6e7-f8a9-0123-4567-890123abcdef

To create a service account:

ccloud service-account create --name ci-pipeline --description "CI/CD automation"

∙∙∙ Creating service account...
Success! Created service account
 id: b4c5d6e7-f8a9-0123-4567-890123abcdef
 name: ci-pipeline

To delete a service account:

ccloud service-account delete b4c5d6e7-f8a9-0123-4567-890123abcdef

∙∙∙ Deleting service account...
Success! Deleted service account
 id: b4c5d6e7-f8a9-0123-4567-890123abcdef

Manage API keys for service accounts

Use the ccloud service-account api-key commands to manage API keys for a service account.

To list API keys:

ccloud service-account api-key list b4c5d6e7-f8a9-0123-4567-890123abcdef

∙∙∙ Retrieving API keys...
ID                                    NAME          CREATED AT
c5d6e7f8-a9b0-1234-5678-901234abcdef  deploy-key    2026-01-15 10:30:00Z

To create an API key:

ccloud service-account api-key create b4c5d6e7-f8a9-0123-4567-890123abcdef --name deploy-key

∙∙∙ Creating API key...
Success! Created API key
 id: c5d6e7f8-a9b0-1234-5678-901234abcdef
 name: deploy-key
 secret: CCDB1_ABCDEFghijklmnopqrstuvwxyz0123456789...

Note:

The API key secret is only shown once when the key is created. Store it securely.

To delete an API key:

ccloud service-account api-key delete b4c5d6e7-f8a9-0123-4567-890123abcdef c5d6e7f8-a9b0-1234-5678-901234abcdef

∙∙∙ Deleting API key...
Success! Deleted API key
 id: c5d6e7f8-a9b0-1234-5678-901234abcdef

Manage JWT issuers using `ccloud jwt-issuer`

Use the ccloud jwt-issuer commands to manage JWT/OIDC identity providers for cluster authentication. JWT issuers allow your clusters to authenticate users via external identity providers.

To list JWT issuers:

ccloud jwt-issuer list

∙∙∙ Retrieving JWT issuers...
ID                                    ISSUER URL                              AUDIENCE       CLAIM
d6e7f8a9-b0c1-2345-6789-012345abcdef  https://accounts.google.com             my-app         email
e7f8a9b0-c1d2-3456-7890-123456abcdef  https://login.microsoftonline.com/...   my-app-azure   preferred_username

To get details of a JWT issuer:

ccloud jwt-issuer get d6e7f8a9-b0c1-2345-6789-012345abcdef

To create a JWT issuer:

ccloud jwt-issuer create --issuer-url https://accounts.google.com --audience my-app --claim email

∙∙∙ Creating JWT issuer...
Success! Created JWT issuer
 id: d6e7f8a9-b0c1-2345-6789-012345abcdef

To update a JWT issuer:

ccloud jwt-issuer update d6e7f8a9-b0c1-2345-6789-012345abcdef --audience my-app-v2

∙∙∙ Updating JWT issuer...
Success! Updated JWT issuer

To delete a JWT issuer:

ccloud jwt-issuer delete d6e7f8a9-b0c1-2345-6789-012345abcdef

∙∙∙ Deleting JWT issuer...
Success! Deleted JWT issuer
 id: d6e7f8a9-b0c1-2345-6789-012345abcdef

Manage physical cluster replication using `ccloud replication`

Use the ccloud replication commands to manage physical cluster replication (PCR) between CockroachDB Cloud clusters.

To list replication streams for a cluster:

ccloud replication list prod-east

∙∙∙ Retrieving replication streams...
ID                                    PRIMARY CLUSTER                       STANDBY CLUSTER                       STATUS
f8a9b0c1-d2e3-4567-8901-234567abcdef  a1b2c3d4-e5f6-7890-abcd-ef1234567890  b2c3d4e5-f6a7-8901-bcde-f12345678901  REPLICATING

To get details of a replication stream:

ccloud replication get f8a9b0c1-d2e3-4567-8901-234567abcdef

∙∙∙ Retrieving replication stream...
ID: f8a9b0c1-d2e3-4567-8901-234567abcdef
Primary Cluster: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Standby Cluster: b2c3d4e5-f6a7-8901-bcde-f12345678901
Status: REPLICATING
Created At: 2026-02-15 10:30:00Z
Replicated Time: 2026-03-04 12:00:00Z
Replication Lag: 5 seconds

To create a replication stream:

ccloud replication create --primary-cluster prod-east --standby-cluster dr-west

∙∙∙ Creating replication stream...
Successfully created replication stream
ID: f8a9b0c1-d2e3-4567-8901-234567abcdef
Primary Cluster: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Standby Cluster: b2c3d4e5-f6a7-8901-bcde-f12345678901
Status: INITIALIZING

To initiate a failover to the standby cluster:

ccloud replication update f8a9b0c1-d2e3-4567-8901-234567abcdef --status FAILING_OVER

∙∙∙ Updating replication stream...
Successfully updated replication stream
ID: f8a9b0c1-d2e3-4567-8901-234567abcdef
Status: FAILING_OVER

To schedule a failover for a specific time:

ccloud replication update f8a9b0c1-d2e3-4567-8901-234567abcdef --status FAILING_OVER --failover-at 2026-03-05T00:00:00Z

To cancel a replication stream:

ccloud replication update f8a9b0c1-d2e3-4567-8901-234567abcdef --status CANCELED

Turn off telemetry events for `ccloud`

Cockroach Labs collects anonymized telemetry events to improve the usability of ccloud. Use the ccloud settings set command and disable sending telemetry events to Cockroach Labs.

ccloud settings set --disable-telemetry=true

Limitations

- It is not possible to use the ccloud command to view the folder structure, move a cluster or folder into or out of a folder, or assign the FOLDER_ADMIN or FOLDER_MOVER roles.

Get Started with the ccloud CLI

Install ccloud

Use Homebrew

Download the binary

Use ccloud quickstart

Log in to CockroachDB Cloud using ccloud auth

Log in to CockroachDB Cloud on a headless server

Create a new cluster using ccloud cluster create

Create and manage IP allowlists using ccloud cluster networking allowlist

Get a list of all the clusters in your organization using ccloud cluster list

Get information about your cluster using ccloud cluster info

Use a SQL client with a cluster using ccloud cluster sql

Connect to your cluster using SSO

Skip the IP allowlist check when connecting to your cluster

Get the connection information for your cluster using ccloud cluster sql

Get a connection string using ccloud cluster connection-string

Create a SQL user using ccloud cluster user create

Manage databases using ccloud cluster database

Manage backups using ccloud cluster backup

Restore from a backup using ccloud cluster restore

List available CockroachDB versions using ccloud cluster versions

Manage version deferral using ccloud cluster version-deferral

Manage blackout windows using ccloud cluster blackout-window

Manage maintenance windows using ccloud cluster maintenance

Simulate cluster disruptions using ccloud cluster disruption

View CMEK configuration using ccloud cluster cmek

Configure log export using ccloud cluster log-export

Configure metric export using ccloud cluster metric-export

Export metrics to AWS CloudWatch

Export metrics to Datadog

Export metrics to Prometheus

Manage egress rules using ccloud cluster networking egress-rule

Manage egress private endpoints using ccloud cluster networking egress-private-endpoint

Manage client CA certificates using ccloud cluster networking client-ca-cert

Manage private endpoints using ccloud cluster networking private-endpoint

Manage private endpoint services

Manage private endpoint connections

Manage trusted owners

Delete a cluster using ccloud cluster delete

View organization information using ccloud organization get

View audit logs using ccloud audit list

Manage billing using ccloud billing

Manage folders using ccloud folder

Manage service accounts using ccloud service-account

Manage API keys for service accounts

Manage JWT issuers using ccloud jwt-issuer

Manage physical cluster replication using ccloud replication

Turn off telemetry events for ccloud

Limitations

Tell us about your experience

Select the problem area

Thank you for your feedback!

Explore More Documentation:

Install `ccloud`

Use `ccloud quickstart`

Log in to CockroachDB Cloud using `ccloud auth`

Create a new cluster using `ccloud cluster create`

Create and manage IP allowlists using `ccloud cluster networking allowlist`

Get a list of all the clusters in your organization using `ccloud cluster list`

Get information about your cluster using `ccloud cluster info`

Use a SQL client with a cluster using `ccloud cluster sql`

Get the connection information for your cluster using `ccloud cluster sql`

Get a connection string using `ccloud cluster connection-string`

Create a SQL user using `ccloud cluster user create`

Manage databases using `ccloud cluster database`

Manage backups using `ccloud cluster backup`

Restore from a backup using `ccloud cluster restore`

List available CockroachDB versions using `ccloud cluster versions`

Manage version deferral using `ccloud cluster version-deferral`

Manage blackout windows using `ccloud cluster blackout-window`

Manage maintenance windows using `ccloud cluster maintenance`

Simulate cluster disruptions using `ccloud cluster disruption`

View CMEK configuration using `ccloud cluster cmek`

Configure log export using `ccloud cluster log-export`

Configure metric export using `ccloud cluster metric-export`

Manage egress rules using `ccloud cluster networking egress-rule`

Manage egress private endpoints using `ccloud cluster networking egress-private-endpoint`

Manage client CA certificates using `ccloud cluster networking client-ca-cert`

Manage private endpoints using `ccloud cluster networking private-endpoint`

Delete a cluster using `ccloud cluster delete`

View organization information using `ccloud organization get`

View audit logs using `ccloud audit list`

Manage billing using `ccloud billing`

Manage folders using `ccloud folder`

Manage service accounts using `ccloud service-account`

Manage JWT issuers using `ccloud jwt-issuer`

Manage physical cluster replication using `ccloud replication`

Turn off telemetry events for `ccloud`