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

1. Install

   macOS (Homebrew)

   brew install cnap-tech/tap/cnap
   

   Go install

   go install github.com/cnap-tech/cli/cmd/cnap@latest
   

   From source

   git clone https://github.com/cnap-tech/cli.git
   cd cli
   go build -o cnap ./cmd/cnap
   
2. Log in

   cnap auth login
   

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

   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.

3. Run your first command

   cnap clusters list
   

Authentication

# 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

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

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

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:

cnap --debug installs list

This shows HTTP request/response details for troubleshooting.

Related

API Reference

REST API conventions, pagination, and error codes

AI & Agents

Manage CNAP through AI agents and MCP servers