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

# Quickstart

> Get started with the Control Plane CLI in minutes.

Follow these steps to install, authenticate, and start using the Control Plane CLI.

<Steps>
  <Step title="Install the CLI">
    Choose your preferred installation method:

    <Tabs>
      <Tab title="npm">
        Install via npm if you have Node.js **version 18** or later installed.

        ```bash theme={null}
        npm install -g @controlplane/cli
        ```

        <Note>
          Requires [Node.js](https://nodejs.org/en/download/) version 18+ (an active LTS release is recommended).
        </Note>

        For detailed instructions, see [Installation](/cli-reference/installation).
      </Tab>

      <Tab title="Homebrew">
        Install via Homebrew on macOS or Linux.

        ```bash theme={null}
        brew tap controlplane-com/cpln && brew install cpln
        ```

        <Note>
          If you don't have Homebrew installed, follow the [installation instructions](https://brew.sh/).
        </Note>

        For detailed instructions, see [Installation](/cli-reference/installation).
      </Tab>

      <Tab title="Binary">
        Download from the [Installation page](/cli-reference/installation#binary).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify the installation">
    Confirm the CLI is installed and accessible:

    ```bash theme={null}
    cpln --version
    ```

    You should see the CLI version number.
  </Step>

  <Step title="Authenticate">
    Log in to Control Plane using your browser:

    ```bash theme={null}
    cpln login
    ```

    This opens your browser for authentication and creates a default profile.

    <Info>
      If you can't use a browser, see the [browser-less login guide](/guides/browser-less-cli-login).
    </Info>

    <Accordion title="Using WSL2? Browser login requires extra setup">
      When you run `cpln login` in WSL2, the localhost URL won't work in your Windows browser because it points to the WSL2 instance, not Windows.

      **Solution:** Install a browser in WSL2 (requires [WSLg](https://github.com/microsoft/wslg)):

      ```bash theme={null}
      cd /tmp
      sudo wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
      sudo dpkg -i google-chrome-stable_current_amd64.deb
      sudo apt install --fix-broken -y
      sudo dpkg -i google-chrome-stable_current_amd64.deb
      ```

      After installation, Chrome appears in your Windows Start menu under the distro name (e.g., **Ubuntu → Google Chrome**). Run `cpln login`, copy the localhost URL from the terminal, and paste it into your WSL2 Chrome.

      **Alternative:** Use [browser-less login](/guides/browser-less-cli-login) with a service account token.
    </Accordion>
  </Step>

  <Step title="Explore available commands">
    Use the built-in help to discover commands:

    ```bash theme={null}
    cpln --help
    cpln <command> --help
    ```

    Start with read-only commands like `cpln gvc get` or `cpln workload get`.
  </Step>
</Steps>

## Try your first commands

Once authenticated, try these safe, read-only commands:

<CodeGroup>
  ```bash List GVCs theme={null}
  cpln gvc get
  ```

  ```bash List workloads in a GVC theme={null}
  cpln workload get --gvc <gvc-name>
  ```

  ```bash List all configured profiles theme={null}
  cpln profile get
  ```
</CodeGroup>

## Deploy your first app

Build and deploy a local application to Control Plane:

<Steps>
  <Step title="Create a GVC">
    Create a Global Virtual Cloud to host your workload:

    ```bash theme={null}
    cpln gvc create --name my-app-gvc --location aws-us-east-1
    ```
  </Step>

  <Step title="Build and push your image">
    From your project directory, build and push to your org's private registry:

    ```bash theme={null}
    cpln image build --name my-app:v1 --push
    ```

    <Tip>
      No Dockerfile? The CLI can auto-detect your language and build with buildpacks.
    </Tip>
  </Step>

  <Step title="Create a workload">
    Deploy your image as a workload:

    ```bash theme={null}
    cpln workload create --name my-app --gvc my-app-gvc \
      --image //image/my-app:v1 --port 8080 --public
    ```

    <Note>
      Replace `8080` with the port your application listens on. Use `--public` to make it accessible from the internet.
    </Note>
  </Step>

  <Step title="Check your deployment">
    View your workload status:

    ```bash theme={null}
    cpln workload get my-app --gvc my-app-gvc
    ```

    Once ready, access your app at the endpoint shown in the output.
  </Step>
</Steps>

<Info>
  For more image operations, see the [Images guide](/cli-reference/get-started/images).
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Images" href="/cli-reference/get-started/images" icon="docker">
    Build, push, and manage container images
  </Card>

  <Card title="Profiles" href="/cli-reference/get-started/profiles" icon="user">
    Manage authentication and context
  </Card>

  <Card title="Common Options" href="/cli-reference/using-cli/common-options" icon="sliders">
    Learn about shared CLI flags
  </Card>

  <Card title="CI/CD" href="/cli-reference/ci-cd-development/ci-cd" icon="code">
    Use the CLI in automation
  </Card>
</CardGroup>