Skip to main content
The 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:
Run ankra logout to clear the saved login, or pass --token. With no credential at all, every command exits 6 and says:
Check which credential a job is using before its first real command:
The document carries 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 -o when its reference lists -o, --output.
  • With -o json or -o yaml, stdout carries only the document. Hints, notes and errors go to stderr.
  • On most commands -o takes only json or yaml, and any other value is refused with exit 2 before the command sends anything. A few commands declare their own -o with other values, such as table (ankra cluster helm get also takes values, and ankra cluster helm history takes only table or json), raw, or a file path. The reference’s description of -o lists what each command takes.
  • ankra pipeline get --watch -o json prints one JSON object per line, one for each state change.
  • ankra tokens rotate prints only the new token on stdout when stdout is not a terminal, so TOKEN=$(ankra tokens rotate <token_id>) works. With -o json it 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 --wait the 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 with ankra 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 --latest was not given, 3 when nothing matches and 5 when --timeout ran out.
  • Some commands wait in their own way. --wait on ankra org access-policy set waits 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 no ankra login is saved, so the CLI reads ANKRA_API_TOKEN.
  1. 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.
  2. Store it in your CI system’s secret store and expose it to the job as ANKRA_API_TOKEN.
  3. Start the job with ankra login status, so a missing or rejected token fails the job at once with exit 6.
The command prints 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:
It exchanges the job’s GitHub ID token for a short-lived Ankra token, masks both in the log and saves the token for the rest of the job.

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.