CLI

Manage Akua resources from your terminal

The Akua CLI gives you 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 sk_akua_... with a workspace API token. You can also set the AKUA_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 workspace API token (for CI/CD)
cnap auth login --token sk_akua_...

# 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.akua.dev
auth_url: https://akua.dev
active_workspace: j575xyz789ghi012
auth:
  token: a1b2c3d4e5f6...  # session token from device flow (or sk_akua_... for workspace API tokens)
output:
  format: table

Environment variables

Variable	Description	Overrides
AKUA_API_TOKEN	API token (workspace token or session token)	auth.token in config
AKUA_API_URL	API base URL	api_url in config
AKUA_AUTH_URL	Auth/dashboard URL	auth_url in config
AKUA_DEBUG	Enable debug logging	(none)

Debugging

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

cnap --debug installs list

This shows HTTP request and response details for troubleshooting.

Resource commands

Workspaces

Switch active workspace and list all workspaces.

Clusters

List, update, delete clusters, and download kubeconfigs.

Products

List, inspect, and delete products.

Installs

Deploy products, stream logs, and open an interactive shell.

Regions

List available regions and create custom regions.

Registry

Manage container registry credentials.

Related topics

API reference

REST API conventions, pagination, and error codes.

Authentication

Mint API tokens for programmatic access.

AI and agents

Manage Akua through AI agents and MCP servers.

Workspaces

Organize products and clusters into workspaces.