CLI - Akua | Docs

akua is Akua’s public command-line interface for people, automation, and coding agents. Browser/device authentication handles interactive sign-in. The generated resource commands stay aligned with the public OpenAPI contract.

Install

Install the supported Homebrew formula on macOS or Linux:

brew install akua-dev/tap/akua
akua --version
akua --help

GitHub Release archives are the alternative distribution channel. Each archive includes the akua executable and its adjacent runtime files, plus a checksum for verification. Preserve the extracted directory layout when installing it. See the CLI repository for the exact commands for your operating system and architecture.

Authenticate

Start browser/device sign-in:

akua auth login
akua auth status --json

akua auth login opens the device page and waits for you to approve the displayed code. On a remote terminal, use akua auth login --no-browser and open the displayed URL yourself. The CLI saves the resulting credential only after approval. For noninteractive automation, set AKUA_API_TOKEN to a workspace API token. The environment variable takes precedence over the locally stored credential.

Select a workspace

Browser-approved credentials can access more than one workspace. List them before calling a workspace-scoped operation:

akua workspaces list --json

After selecting a workspace, pass its ID through the generated request object’s headers.akua-context field:

printf '%s' '{"headers":{"akua-context":"WORKSPACE_ID"}}' \
    | akua clusters list --input - --json

Replace WORKSPACE_ID with the confirmed ws_... value. A workspace-owned API token already implies its workspace, so the header is optional for that token. An Akua-Context value that conflicts with a token’s scope is rejected.

Discover commands

Inspect the generated registry before constructing a request:

akua commands --json
akua commands --resource clusters --json
akua commands --operation-id clusters.create --json
akua clusters create --help

An OpenAPI operationId such as workspaces.list becomes akua workspaces list. akua commands reports the operation ID, method, path, summary, and executable resource/action pair. Every generated API command accepts one JSON request object from stdin or a file through --input. The object’s possible partitions are path, query, headers, and body. The CLI validates the input against the public API contract before sending a request and rejects unknown fields. A rejected request returns a structured error that names the missing or invalid fields and includes a runnable example, so an agent can correct the input without guessing. For example, list five workspaces:

printf '{"query":{"limit":5}}' | akua workspaces list --input - --json

Mutating operations can accept an idempotency-key under headers. Reuse the same key only when retrying the same intended change. When an API returns an Operation, poll it with akua operations get, passing both path.id and headers.akua-context, instead of repeating the mutation. Repeat until done is true; continue only for state: SUCCEEDED, and stop and report state: FAILED or state: CANCELLED. The generated operations wait request doesn’t currently expose workspace context, so a browser-approved credential can’t use that long-poll command yet. The CLI has no provider-specific setup commands. Provider configuration belongs to generated Secrets and Compute Configs operations, which take validated JSON request objects and keep credentials out of command arguments.

Use the CLI with a coding agent

When stdout isn’t an interactive terminal, or when a known coding-agent environment is present, the CLI uses compact agent-oriented output. --json makes the output mode explicit. An agent should fetch the agent setup prompt, ask for your goal, consult https://docs.akua.dev/llms.txt, confirm Akua-Context, and request approval before consequential actions. Start that flow with one prompt:

Fetch https://docs.akua.dev/agent-setup/prompt and complete the Akua CLI
quickstart with me.

Author Packages

akua pkg provides Package authoring, validation, rendering, publishing, and inspection commands through the same installed CLI:

akua pkg --help
akua pkg version --json

Package commands operate on local Package files. Generated akua packages ... commands manage Package resources through the Akua API; the two namespaces have different roles.

Add MCP later if useful

MCP is optional. It can add documentation search or another authenticated workspace tool surface, but it doesn’t replace CLI authentication or generated commands. Configure MCP after the CLI works. Continue through the CLI if the agent host needs a restart or a new conversation to load it.

Quickstart

Start from one prompt and choose a supported route.

Agent setup

Give a coding agent its CLI operating instructions.

API reference

Review REST conventions, pagination, and errors.

Authentication

Compare device sessions and workspace API tokens.

​Install

​Authenticate

​Select a workspace

​Discover commands

​Use the CLI with a coding agent

​Author Packages

​Add MCP later if useful

​Related topics