Skip to main content
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:
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 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.

​
Choose a workspace

Browser-approved credentials can access more than one workspace. List your workspaces, then save the one later commands should run in:
Replace my-team with the workspace’s slug, name, or ws_... ID from the list. akua workspaces use saves the choice in ~/.config/akua/config.json, and every workspace-scoped command sends it as the Akua-Context header for you. akua workspace switch is the same command. Run it without a name on a terminal to choose from a list of your active workspaces with the arrow keys. Check which workspace is active, and where the choice comes from:
To run one command in another workspace, pass --workspace (short form -w). For a whole shell session or a CI job, set AKUA_WORKSPACE:
The CLI picks the workspace in this order: the --workspace flag, then AKUA_WORKSPACE, then the saved workspace. A workspace-owned API token already implies its workspace, so it needs none of them. An Akua-Context value that conflicts with a token’s scope is rejected. Run akua workspaces use --clear to forget the saved workspace.
Check akua --help and each command’s --help for the features in your installed CLI. If --workspace isn’t listed, send workspace context through JSON input, as shown in Send a JSON request.

​
Run commands

Every public API operation is a command: an OpenAPI operationId such as clusters.create becomes akua clusters create. Path parameters are arguments, and request fields are flags generated from the API schema, so --help always matches the API:
Replace REGION_ID, CLUSTER_ID, and INSTALL_ID with IDs from the matching list command. On a terminal, lists print as tables and objects as aligned fields. Add --json for the full API response; pipe it to jq to pick out fields:
The CLI validates the request against the public API contract before sending it. A missing or invalid value names the flag or argument to fix, and the error lists the command’s --help and an example. Flags that take objects or lists, such as --initial-values, take a JSON value. When a command returns an Operation, the CLI prints the command that waits for it, for example akua operations wait OPERATION_ID. That command returns as soon as the Operation finishes, or after at most 60 seconds, so run it again until done is true. Continue only for state: SUCCEEDED, and stop for state: FAILED or state: CANCELLED. Don’t repeat the mutation.

​
Pass secret values

Fields that carry secret material, such as a Secret’s value or a Cloudflare api_token, also take a --<flag>-file form. It reads the value from a file, or from standard input with -, so the secret never appears in your shell history or the process list:
Paste or pipe the value in, then press Ctrl-D. One trailing newline is removed. Typing the secret as a plain flag, for example --value, still works, but the CLI prints a warning on stderr.

​
Send a JSON request

Scripts and agents can send the whole request as one JSON object from stdin or a file through --input. The object’s possible partitions are path, query, headers, and body; arguments and flags on the same command override its fields:
The CLI rejects unknown fields and returns a structured error that names each invalid field, so an agent can correct the input without guessing. Mutating operations accept an idempotency-key header, also as the --idempotency-key flag. Reuse the same key only when retrying the same intended change. Inspect the operation catalog before constructing a request:
akua commands reports each operation’s ID, method, path, summary, the human usage line, and the JSON request shape. The CLI has no provider-specific setup commands. Provider configuration belongs to generated Secrets and Compute Configs operations.

​
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 the workspace with you, and request approval before consequential actions. Start that flow with one prompt:

​
Author Packages

akua pkg provides Package authoring, validation, rendering, publishing, and inspection commands through the same installed CLI:
Package commands operate on local Package files. Generated akua packages ... commands manage Package resources through the Akua API; the two namespaces have different roles. See the akua pkg command reference for every Package command and its flags.

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