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 Dedicated 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 Dedicated 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: v24.3
 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: v24.3
 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

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...

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 Dedicated clusters can take an hour or more to provision and start.

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.

Was this helpful?

Pricing

Contact us

Sign In

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`

Create a SQL user using `ccloud cluster user create`

Delete a cluster using `ccloud cluster delete`

Turn off telemetry events for `ccloud`

Limitations

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

Create a SQL user using ccloud cluster user create

Delete a cluster using ccloud cluster delete

Turn off telemetry events for ccloud

Limitations

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`

Create a SQL user using `ccloud cluster user create`

Delete a cluster using `ccloud cluster delete`

Turn off telemetry events for `ccloud`