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

# Installation

> Install the Control Plane CLI on macOS, Linux, or Windows.

The Control Plane CLI (`cpln`) is available via npm, Homebrew, or direct binary download for all major operating systems.

## Choose your installation method

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

    <CodeGroup>
      ```bash Install theme={null}
      npm install -g @controlplane/cli
      ```

      ```bash Update theme={null}
      npm update -g @controlplane/cli
      ```
    </CodeGroup>

    <Note>
      Requires [Node.js](https://nodejs.org/en/download/) version 16+.
    </Note>
  </Tab>

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

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

      ```bash Update theme={null}
      brew upgrade cpln
      ```
    </CodeGroup>

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

  <Tab title="Binary">
    Download and install the binary package for your operating system.

    <Steps>
      <Step title="Download the binary">
        <Tabs>
          <Tab title="Browser">
            <CardGroup cols={2}>
              <Card title="macOS (ARM64)" icon="apple" href="https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-macos-arm64.dmg">
                Download for Apple Silicon
              </Card>

              <Card title="macOS (x64)" icon="apple" href="https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-macos-x64.dmg">
                Download for Intel Macs
              </Card>

              <Card title="Linux / WSL2" icon="linux" href="https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-linux.tgz">
                Download for Linux (x64) or for Windows (WSL2)
              </Card>

              <Card title="Windows" icon="microsoft" href="https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-win.zip">
                Download for Windows 10/11
              </Card>
            </CardGroup>
          </Tab>

          <Tab title="Command line">
            <Tabs>
              <Tab title="macOS (ARM64)" icon="apple">
                ```bash theme={null}
                curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-macos-arm64.dmg
                ```
              </Tab>

              <Tab title="macOS (x64)" icon="apple">
                ```bash theme={null}
                curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-macos-x64.dmg
                ```
              </Tab>

              <Tab title="Linux" icon="linux">
                <CodeGroup>
                  ```bash curl theme={null}
                  curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-linux.tgz
                  ```

                  ```bash wget theme={null}
                  wget https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-linux.tgz
                  ```
                </CodeGroup>
              </Tab>

              <Tab title="Windows (PowerShell)" icon="microsoft">
                ```powershell theme={null}
                Invoke-WebRequest -Uri "https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-win.zip" -OutFile "cpln-win.zip"
                ```
              </Tab>

              <Tab title="Windows (WSL2)" icon="linux">
                <CodeGroup>
                  ```bash curl theme={null}
                  curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-linux.tgz
                  ```

                  ```bash wget theme={null}
                  wget https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-linux.tgz
                  ```
                </CodeGroup>

                <Note>
                  When using WSL2, download the Linux binary, not the Windows binary.
                </Note>
              </Tab>
            </Tabs>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Extract and add to PATH">
        <Tabs>
          <Tab title="macOS (ARM64)" icon="apple">
            ```bash theme={null}
            hdiutil attach cpln-macos-arm64.dmg && \
            cp -R /Volumes/cpln-macos-arm64/cpln /Volumes/cpln-macos-arm64/docker-credential-cpln . && \
            hdiutil detach /Volumes/cpln-macos-arm64 && \
            sudo mv cpln docker-credential-cpln /usr/local/bin/
            ```

            <Note>
              You'll be prompted to enter your password. The `sudo` command requires administrator privileges to move files to `/usr/local/bin`.
            </Note>
          </Tab>

          <Tab title="macOS (x64)" icon="apple">
            ```bash theme={null}
            hdiutil attach cpln-macos-x64.dmg && \
            cp -R /Volumes/cpln-macos-x64/cpln /Volumes/cpln-macos-x64/docker-credential-cpln . && \
            hdiutil detach /Volumes/cpln-macos-x64 && \
            sudo mv cpln docker-credential-cpln /usr/local/bin/
            ```

            <Note>
              You'll be prompted to enter your password. The `sudo` command requires administrator privileges to move files to `/usr/local/bin`.
            </Note>
          </Tab>

          <Tab title="Linux" icon="linux">
            ```bash theme={null}
            tar -xvf cpln-linux.tgz && \
            sudo mv cpln docker-credential-cpln /usr/local/bin/
            ```

            <Note>
              You'll be prompted to enter your password. The `sudo` command requires administrator privileges to move files to `/usr/local/bin`.
            </Note>
          </Tab>

          <Tab title="Windows" icon="microsoft">
            1. Right-click `cpln-win.zip` and select **Extract All**
            2. Choose a permanent location (e.g., `C:\Program Files\cpln`)
            3. Add to PATH:
               * Press `Win + R`, type `sysdm.cpl`, and press Enter
               * Click the **Advanced** tab → **Environment Variables**
               * Under "User variables", select **Path** and click **Edit**
               * Click **New** and add the directory containing `cpln.exe` (e.g., `C:\Program Files\cpln`)
               * Click **OK** to save all dialogs
            4. Open a **new** Command Prompt or PowerShell window to use `cpln`
          </Tab>

          <Tab title="Windows (WSL2)" icon="linux">
            ```bash theme={null}
            tar -xvf cpln-linux.tgz && \
            sudo mv cpln docker-credential-cpln /usr/local/bin/
            ```

            <Note>
              You'll be prompted to enter your password. The `sudo` command requires administrator privileges to move files to `/usr/local/bin`.
            </Note>

            <Warning>
              **Browser login in WSL2:** When you run `cpln login`, the CLI starts a local server and opens a localhost URL. This URL won't work in your Windows browser because it points to the WSL2 instance's localhost, not Windows.

              **Option 1:** Install Google Chrome in WSL2 (requires [WSLg](https://github.com/microsoft/wslg) for GUI support):

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

              **Option 2:** Use browser-less login with a service account token. See [Browser-less CLI Login](/guides/browser-less-cli-login).
            </Warning>
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    <Accordion title="Verify checksums">
      | OS            | File                 | SHA256                                                           |
      | ------------- | -------------------- | ---------------------------------------------------------------- |
      | macOS-arm64   | cpln-macos-arm64.dmg | 12b3caa3041ebdc9ab654658f84f940bb026fca710258300d0856e4197ba290e |
      | macOS-x64     | cpln-macos-x64.dmg   | 1e61b70db4fe2d0f6443321a9d704eacb15dfe238597435ad9dee1e304b29e0e |
      | Linux         | cpln-linux.tgz       | c3bdd81886430a4ca91f5ef86b902a47b916ed434713e785d054170ac04e31e4 |
      | Windows 10/11 | cpln-win.zip         | 96f99b190318893c8879bd11cc136751de45fbc90edf9e9e770ccedaba2024fc |
    </Accordion>

    <Info>
      The binary package includes two executables:

      * `cpln` - The Control Plane CLI
      * `docker-credential-cpln` - Enables Docker authentication to your org's private image registry
    </Info>
  </Tab>
</Tabs>

## Verify installation

After installing with any method, confirm the CLI is installed and accessible:

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

You should see the version number printed to the console. If you see `command not found`, ensure the installation directory is in your `PATH`.

## Enable shell completion (optional)

Enable tab completion for `cpln` commands, subcommands, and flags in your terminal:

```bash theme={null}
cpln misc install-completion
```

Restart your terminal after installation. For non-interactive setup and supported shells, see [Shell Completion](/cli-reference/using-cli/shell-completion).

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" href="/cli-reference/get-started/quickstart" icon="rocket">
    Get started with the CLI in minutes
  </Card>

  <Card title="Authentication" href="/cli-reference/get-started/authentication" icon="key">
    Learn how to authenticate
  </Card>
</CardGroup>