akua lint-cli
Shipped
Validate that the current binary honors the CLI contract.
akua lint-cliUsed in CI to catch contract violations before release.
Environment variables
A minimal set. No hidden state.
akua-specific
| var | purpose |
|---|---|
AKUA_REGISTRY | default OCI registry for publish/pull |
AKUA_CACHE_DIR | override cache location (default: $XDG_CACHE_HOME/akua) |
AKUA_LOG_LEVEL | override --log-level |
AKUA_NO_TELEMETRY | force telemetry off (for CI) |
AKUA_TOKEN_FILE | path to a token file for non-interactive auth |
AKUA_API_TOKEN | hosted API bearer token for akua api |
AKUA_API_BASE_URL | hosted API base URL for akua api (default: https://api.akua.dev/v1/) |
AKUA_WORKSPACE_ID | workspace context sent by akua api as akua-context |
AKUA_AGENT | signal an agent context explicitly (value is the agent name) |
AKUA_NO_AGENT_DETECT | disable agent-context auto-detection |
All of these can be overridden by flags where a flag exists. Local package workflows typically need none of them. Hosted API calls need a bearer token from --token or AKUA_API_TOKEN.
Agent-context env vars (detected, never written)
These are set by agent runtimes, not by akua. akua reads them to determine whether it's running in an agent context.
| var | set by |
|---|---|
AGENT=<name> | Goose (goose), Amp (amp), Codex (codex), Cline (cline), OpenCode (opencode) — emerging standard |
CLAUDECODE=1 | Claude Code |
GEMINI_CLI=1 | Gemini CLI |
CURSOR_CLI=1 | Cursor CLI |
GOOSE_TERMINAL=1, AMP_THREAD_ID=<id>, CODEX_SANDBOX=<id>, CLINE_ACTIVE=true | secondary identifiers per agent — recorded as context |
See cli-contract.md §1.5 for detection rules and precedence.
Exit code reference (summary)
From cli-contract.md:
| code | meaning |
|---|---|
| 0 | success |
| 1 | user error |
| 2 | system error |
| 3 | policy deny |
| 4 | rate limited |
| 5 | needs approval |
| 6 | timeout |
Stability and versioning
- Pre-v1.0: breaking changes require a minor version bump + changelog entry.
- v1.0 onward: flag removal requires 6-month deprecation; exit code semantics never change.
- JSON output keys are part of the stability contract.
- New verbs can be added without bumping major.
What's not in this reference
- Implementation details (Rust crate structure, KCL plugin ABI).
- The TypeScript SDK (see sdk.md).
- The CLI contract (see cli-contract.md).
- Examples of usage (see examples/).
- Architecture (see architecture.md).
Spec cross-references
- Package format — package-format.md (KCL Package, four regions, engine callables)
- Policy format — policy-format.md (Rego as host, compile-resolved imports, custom builtins)
- Lockfile — lockfile-format.md (
akua.toml+akua.lock)