Get Started with the ccloud CLI

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:

Mac
Linux
Windows

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

Next steps

Refer to the to learn how to use the ccloud CLI tool to create and manage CockroachDB Cloud clusters.

​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

​Next steps