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

# Authentication

> Authenticate with the Control Plane CLI using interactive login or token-based flows.

The CLI supports multiple authentication methods for different environments and use cases.

## Interactive login

The default authentication method opens your browser for a secure login flow.

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

This command:

1. Opens your default browser
2. Prompts you to authenticate via Control Plane
3. Creates a `default` profile with your credentials

<Check>
  After successful authentication, the CLI is ready to use with your default profile.
</Check>

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

## Browser-less authentication

For environments without browser access (SSH sessions, CI/CD, containers), use a service account token.

<Steps>
  <Step title="Create a service account">
    <Tabs>
      <Tab title="Console">
        1. Click **Service Accounts** in the left menu and click **New** (or use the **Create** dropdown in the upper right corner)
        2. Enter a unique name and optional description
        3. Click **Next (Tags)**, add any optional tags, then click **Create**
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        cpln serviceaccount create --name pipeline-automation --description "CI/CD automation"
        ```
      </Tab>
    </Tabs>

    See the [Create a Service Account](/guides/create-service-account) guide for details.
  </Step>

  <Step title="Generate a key">
    <Tabs>
      <Tab title="Console">
        1. Open the service account you created
        2. Click the **Keys** link
        3. Enter a key description and click **Add**
        4. Copy and download the generated key securely
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        cpln serviceaccount add-key pipeline-automation --description github-workflow
        ```

        Save the returned key securely.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Authenticate with the token">
    Use the token directly or create a profile:

    <Tabs>
      <Tab title="Create a profile (recommended)">
        ```bash theme={null}
        cpln profile create <profile-name> --token <your-token> --org <org-name> --gvc <gvc-name>
        ```

        <Note>
          When using `--token`, always include `--gvc` if your commands require a default GVC context.
        </Note>

        Set as default (optional):

        ```bash theme={null}
        cpln profile set-default <profile-name>
        ```
      </Tab>

      <Tab title="Use token directly">
        Pass the token with each command:

        ```bash theme={null}
        cpln gvc get --token <your-token> --org <org-name>
        ```
      </Tab>

      <Tab title="Use environment variable">
        Set the `CPLN_TOKEN` environment variable:

        ```bash theme={null}
        export CPLN_TOKEN=<your-token>
        cpln gvc get --org <org-name>
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Info>
  For detailed browser-less setup, see the [Browser-less CLI Login](/guides/browser-less-cli-login) guide.
</Info>

## Token management

### View your current token

Display the token for a profile:

```bash theme={null}
cpln profile token <profile-name>
```

### Override token for a single command

Use a different token without changing your profile:

```bash theme={null}
cpln gvc get <gvc-name> --token <your-token>
```

### Token precedence

The CLI uses tokens in this order:

1. `--token` flag (highest priority)
2. `CPLN_TOKEN` environment variable
3. Profile token (default)

## Authentication for CI/CD

For automated environments:

1. Create a service account with appropriate permissions
2. Generate a key and store it securely (e.g., `CPLN_TOKEN` in secrets manager)
3. Create a profile in your CI/CD pipeline

```bash theme={null}
cpln profile update ci --org <org-name> --default
```

See [CI/CD usage](/cli-reference/ci-cd-development/ci-cd) for complete automation setup.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Login command doesn't open a browser">
    If the browser doesn't open automatically, copy the URL displayed in the terminal and paste it into your browser manually. Complete the login flow in the browser to authenticate.
  </Accordion>

  <Accordion title="Login command opens wrong browser">
    The CLI uses your system's default browser. Change your default browser in your OS settings, or copy the URL from the terminal and paste it into your preferred browser.
  </Accordion>

  <Accordion title="Authentication failed or 403 Forbidden error">
    A 403 error typically means one of the following:

    * **Wrong org**: You're trying to access an org you don't have access to, or there's a typo in the org name. Verify with `cpln profile get`.
    * **Missing token**: No token is provided. Ensure `CPLN_TOKEN` is set or you're using a profile with a valid token.
    * **Insufficient permissions**: Your token doesn't have the required permissions. Generate a new key or re-login to refresh your token:
      ```bash theme={null}
      cpln login
      ```
      Or for service accounts:
      ```bash theme={null}
      cpln serviceaccount add-key <name> --description <key-description>
      ```
  </Accordion>
</AccordionGroup>

<Info>
  For more troubleshooting help, see the [Troubleshooting](/cli-reference/using-cli/troubleshooting) page.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Profiles" href="/cli-reference/get-started/profiles" icon="user">
    Manage multiple authentication contexts
  </Card>

  <Card title="CI/CD Setup" href="/cli-reference/ci-cd-development/ci-cd" icon="code">
    Automate with service accounts
  </Card>
</CardGroup>