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

# CLI

> Manage CNAP resources from your terminal

The CNAP CLI provides terminal-based access to all API operations with interactive pickers, streaming logs, and shell access to running pods.

## Quick Start

<Steps>
  <Step title="Install">
    <Tabs>
      <Tab title="macOS (Homebrew)">
        ```bash theme={null}
        brew install cnap-tech/tap/cnap
        ```
      </Tab>

      <Tab title="Go install">
        ```bash theme={null}
        go install github.com/cnap-tech/cli/cmd/cnap@latest
        ```
      </Tab>

      <Tab title="From source">
        ```bash theme={null}
        git clone https://github.com/cnap-tech/cli.git
        cd cli
        go build -o cnap ./cmd/cnap
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Log in">
    ```bash theme={null}
    cnap auth login
    ```

    This opens your browser for approval, then stores a session token in `~/.cnap/config.yaml`.

    <Tip>
      For CI/CD, use `cnap auth login --token cnap_pat_...` with a Personal Access Token. You can also set the `CNAP_API_TOKEN` environment variable.
    </Tip>
  </Step>

  <Step title="Run your first command">
    ```bash theme={null}
    cnap clusters list
    ```
  </Step>
</Steps>

## Authentication

```bash theme={null}
# Log in via browser (device flow) — stores a session token
cnap auth login

# Log in with a Personal Access Token (for CI/CD)
cnap auth login --token cnap_pat_...

# Check authentication status (shows token type and expiry)
cnap auth status

# Remove stored credentials (revokes session server-side)
cnap auth logout
```

Sessions are long-lived and auto-refresh on use.

## Output Formats

```bash theme={null}
# Table output (default)
cnap installs list

# JSON output
cnap installs list -o json

# Quiet mode (IDs only)
cnap installs list -o quiet

# Set default format in config
cnap config set output.format json
```

The `-o` / `--output` flag is available on all commands.

## Pagination

List commands accept `--limit` and `--cursor` flags for pagination:

```bash theme={null}
# First page (10 items)
cnap clusters list --limit 10

# Next page using cursor from previous response
cnap clusters list --limit 10 --cursor <cursor>
```

Default limit is 50, maximum is 100.

## Configuration

The CLI stores configuration in `~/.cnap/config.yaml`:

```yaml theme={null}
api_url: https://api.cnap.tech
auth_url: https://cnap.tech
active_workspace: j575xyz789ghi012
auth:
  token: a1b2c3d4e5f6...  # session token from device flow (or cnap_pat_... for PATs)
output:
  format: table
```

### Environment Variables

| Variable         | Description                      | Overrides              |
| ---------------- | -------------------------------- | ---------------------- |
| `CNAP_API_TOKEN` | API token (PAT or session token) | `auth.token` in config |
| `CNAP_API_URL`   | API base URL                     | `api_url` in config    |
| `CNAP_AUTH_URL`  | Auth/dashboard URL               | `auth_url` in config   |
| `CNAP_DEBUG`     | Enable debug logging             | —                      |

## Debugging

Enable verbose output with the `--debug` flag or `CNAP_DEBUG=1`:

```bash theme={null}
cnap --debug installs list
```

This shows HTTP request/response details for troubleshooting.

## Related

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/apis/introduction">
    REST API conventions, pagination, and error codes
  </Card>

  <Card title="AI & Agents" icon="robot" href="/ai/index">
    Manage CNAP through AI agents and MCP servers
  </Card>
</CardGroup>