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:

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

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

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

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

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

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

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

Next steps

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