> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with the ccloud CLI

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

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`](#install-ccloud) and use the [`ccloud quickstart` command](#use-ccloud-quickstart) to interactively log in and create a new CockroachDB Serverless cluster.

## Install `ccloud`

Choose your OS:

<Tabs>
  <Tab title="Mac">
    You can install `ccloud` using either Homebrew or by downloading the binary.

    ### Use Homebrew

    1. [Install Homebrew](http://brew.sh/).
    2. Install using the `ccloud` tap:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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`:

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    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:

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    curl https://binaries.cockroachdb.com/ccloud/ccloud_darwin-arm64_0.6.12.tar.gz | tar -xJ && cp -i ccloud /usr/local/bin/
    ```
  </Tab>

  <Tab title="Linux">
    In a terminal, enter the following command to download and extract the `ccloud` binary and add it to your `PATH`:

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    curl https://binaries.cockroachdb.com/ccloud/ccloud_linux-amd64_0.6.12.tar.gz | tar -xz && cp -i ccloud /usr/local/bin/
    ```
  </Tab>

  <Tab title="Windows">
    In a PowerShell window, enter the following command to download and extract the `ccloud` binary and add it to your `PATH`:

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    $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.
    ```
  </Tab>
</Tabs>

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

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   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.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ccloud auth login --vanity-name {custom-organization-name}
```

Replace <code>{'{custom-organization-name}'}</code> 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.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ccloud auth login --no-redirect
```

## Next steps

Refer to the <InternalLink path="ccloud-reference">`ccloud` reference documentation</InternalLink> to learn how to use the `ccloud` CLI tool to create and manage CockroachDB Cloud clusters.