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

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

### Use Homebrew

1. Install Homebrew.

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

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

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

1. Connect to the cluster using the `--sso` flag.

       ccloud cluster sql --sso blue-dog

2. Log in to your organization when prompted by `ccloud`.

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

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

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

1. Log out of the current organization.

       ccloud auth logout

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