> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI
> Install, authenticate, and operate Akua from a terminal or coding agent
`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:
```bash theme={null}
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](https://github.com/akua-dev/akua/tree/main/cli#install) for the exact
commands for your operating system and architecture.
## Authenticate
Start browser/device sign-in:
```bash theme={null}
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.
## Choose a workspace
Browser-approved credentials can access more than one workspace. List your
workspaces, then save the one later commands should run in:
```bash theme={null}
akua workspaces list
akua workspaces use my-team
```
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:
```bash theme={null}
akua workspaces current
```
To run one command in another workspace, pass `--workspace` (short form `-w`).
For a whole shell session or a CI job, set `AKUA_WORKSPACE`:
```bash theme={null}
akua clusters list --workspace other-team
AKUA_WORKSPACE=ws_j572abc123def456 akua clusters list
```
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](#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:
```bash theme={null}
akua regions list
akua clusters create --name demo --region-id REGION_ID
akua clusters get CLUSTER_ID
akua installs get-logs INSTALL_ID --tail 100
```
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](https://jqlang.org) to pick out fields:
```bash theme={null}
akua clusters list --json | jq -r '.data.data[].id'
```
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 `---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:
```bash theme={null}
akua secrets create --name db-password --kind generic --value-file -
```
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:
```bash theme={null}
printf '%s' '{"query":{"limit":5}}' | akua workspaces list --input - --json
akua clusters create --input cluster.json --json
```
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:
```bash theme={null}
akua commands --resource clusters --json
akua commands --operation-id clusters.create --json
```
`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](/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:
```text theme={null}
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:
```bash theme={null}
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. See the [`akua pkg` command reference](/akua/cli) 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.
## Related topics
Start from one prompt and choose a supported route.
Give a coding agent its CLI operating instructions.
Review REST conventions, pagination, and errors.
Compare device sessions and workspace API tokens.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.