> ## Documentation Index
> Fetch the complete documentation index at: https://controlplanecorporation-jakob-ess-2-0-0.mintlify.site/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/2708952122-4bc72557/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/2708952122-4bc72557/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/2708952122-4bc72557/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/2708952122-4bc72557/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/2708952122-4bc72557/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/2708952122-4bc72557/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/2708952122-4bc72557/cpln-linux.tgz
                  ```

                  ```bash wget theme={null}
                  wget https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2708952122-4bc72557/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/2708952122-4bc72557/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/2708952122-4bc72557/cpln-linux.tgz
                  ```

                  ```bash wget theme={null}
                  wget https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2708952122-4bc72557/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>

            <Note>
              **Logging in from WSL2:** No browser is needed inside WSL2. `cpln login` prints a login URL and a confirmation code, so you can paste the URL into your Windows browser, sign in, and enter the code. The CLI running in WSL2 picks up the credentials on its own.
            </Note>
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    <Accordion title="Verify checksums">
      | OS            | File                 | SHA256                                                           |
      | ------------- | -------------------- | ---------------------------------------------------------------- |
      | macOS-arm64   | cpln-macos-arm64.dmg | 14d84014fe0cf18fc6242bc50dc2e6c0aea67792d4ac9daef791a9363b8c0965 |
      | macOS-x64     | cpln-macos-x64.dmg   | f1ddf131bad43aab2d66304476ebf09b945e73fbed022bc717f45dab46aaa6e3 |
      | Linux         | cpln-linux.tgz       | c3dbe36a03f118d4f085cf5523eb1a94ac9db54080e9ddd31f4ba150101f9fe2 |
      | Windows 10/11 | cpln-win.zip         | 83596906d67c1236060f2851e4f71601ef8aa676392c4320f0ad742d6aa088e2 |
    </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`.

`cpln version` and `cpln -v` are aliases for `cpln --version`.

## Keep the CLI up to date

Run `cpln upgrade` to upgrade the CLI to the latest version.

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