ankra CLI keeps a contract for scripts, CI jobs and coding agents: where it takes its credential from, what it prints on stdout, and what each exit code means. This page lists those values. For installing the CLI and its command families, see Ankra CLI; for every command and flag, see the CLI reference.
Credentials, organisation and project
Each value is taken from the first place in the row that sets it.
A saved login wins over
ANKRA_API_TOKEN. When both are set and differ, the CLI uses the login and prints on stderr:
ankra logout to clear the saved login, or pass --token. With no credential at all, every command exits 6 and says:
logged_in, base_url, token_source (flag, config or env), token_name and the organisation the token acts in. ankra login status exits 6 when no credential is configured or the platform rejects it.
Structured output
- A command takes
-owhen its reference lists-o,--output. - With
-o jsonor-o yaml, stdout carries only the document. Hints, notes and errors go to stderr. - On most commands
-otakes onlyjsonoryaml, and any other value is refused with exit 2 before the command sends anything. A few commands declare their own-owith other values, such astable(ankra cluster helm getalso takesvalues, andankra cluster helm historytakes onlytableorjson),raw, or a file path. The reference’s description of-olists what each command takes. ankra pipeline get --watch -o jsonprints one JSON object per line, one for each state change.ankra tokens rotateprints only the new token on stdout when stdout is not a terminal, soTOKEN=$(ankra tokens rotate <token_id>)works. With-o jsonit prints the whole response.
Exit codes
Exit code 9
Code 9 is not a failure. The command stopped because the next step is not its own:
The same
ship run exits 8 with state setup_pull_request_blocked when the pipeline’s gate blocks the setup pull request’s run.
Waiting for long operations
A command that starts work on the platform returns as soon as the platform accepts it, unless you pass--wait.
- Exit 5 means the CLI stopped waiting, not that the work stopped. Without
--waitthe CLI says: “Avoid submitting the same change again while it may still be running (duplicate node groups can double cost).” - Follow the selected cluster’s operations with
ankra cluster operations list --watch, or read one withankra cluster operations list <execution-id>. - Wait for a pipeline run by what a job knows about it, such as its commit:
ankra pipeline get --head-sha "$(git rev-parse HEAD)" --trigger pull_request --latest --wait --timeout 45m. It exits 0 when the run succeeded, 1 when it concluded any other way, 2 when several runs match and--latestwas not given, 3 when nothing matches and 5 when--timeoutran out. - Some commands wait in their own way.
--waitonankra org access-policy setwaits for an owner or admin to decide the proposal: 0 applied, 4 dismissed, 1 expired or replaced, 5 still pending.
Confirmation prompts
Commands that delete, uninstall or deprovision ask before they act. Declining exits 4, and so does a prompt in a job with no terminal, because it reads no answer. Pass--yes on the commands that offer it (the reference lists it under Flags).
Shell completion
install detects your shell; --shell bash|zsh|fish|powershell names it.
Restart the shell afterwards. To print a script instead of installing it, run
ankra completion bash, zsh, fish or powershell.
Running in CI
A CI job runs where noankra login is saved, so the CLI reads ANKRA_API_TOKEN.
- Make a service token with Full API access and the lowest role the job needs. It belongs to the organisation, so it keeps working when the person who made it leaves.
- Store it in your CI system’s secret store and expose it to the job as
ANKRA_API_TOKEN. - Start the job with
ankra login status, so a missing or rejected token fails the job at once with exit 6.
env. Without ANKRA_BASE_URL the CLI also prints on stderr which default base URL it uses.
A GitHub Actions job can sign in with no stored token. An organisation admin first creates a trust policy for the repository with ankra org oidc-trust create; the job, with permissions: id-token: write, then runs:
Environment variables
Every request names the CLI, its version and the command path, never its arguments or flags. Under a coding agent the CLI also names the agent and a digest of its session, so the audit log shows which agent ran what.
Related
- Ankra CLI - install, sign in and the command families
- Service tokens - organisation tokens for CI
- Give a coding agent least privilege - limit what an agent’s CLI and MCP calls can do
- CLI, MCP, API or Terraform - which way to automate Ankra