akua / cli

CLI reference

Every akua verb. Shipped verbs are wired and tested; planned verbs have a stable surface but no backing implementation yet.

akua CLI reference

Complete reference for the akua binary. Every verb, every subcommand, every flag.

For the universal contract every verb honors (JSON output, exit codes, idempotency, plan mode, timeouts), see cli-contract.md.

Status marker. Sections marked ✅ describe verbs available in the shipping binary. Sections marked 🚧 describe verbs from the target surface that aren't wired yet. If a verb isn't marked, assume 🚧. Shipped today (28 verbs): init · whoami · version · verify · render · add · vendor · dev · test · tree · pull · publish · sign · update · lock · push · repl · pack · remove · diff · check · inspect · lint · fmt · cache · auth · export · api Run akua --help at the command line for the authoritative live list.

Top-level flags

These flags are accepted by every verb:

flagdescription
--jsonemit structured JSON to stdout
--plancompute what the command would do; do not write
--timeout=<duration>max time before exit 6 (e.g. 30s, 5m)
--idempotency-key=<uuid>safe-retry key for write operations
`--log=<text\json>`stderr log format (default: text)
`--log-level=<debug\info\warn\error>`filter logs
--verbose / -vmore detail in logs
--help / -hhelp for this verb
--describe --jsonmachine-readable spec of this verb
--no-colordisable terminal colors (implicit under --json)
--no-interactivenever block on stdin; fail with exit 1 if input is missing (implicit in agent context)
--no-agent-modedisable agent-context auto-detection for this invocation

Agent-context auto-detection

When akua is run inside an AI-agent session, it detects this from env vars and auto-enables --json, --log=json, --no-color, --no-progress, and --no-interactive. Detection is keyed off AGENT=<name> (standard), CLAUDECODE, GEMINI_CLI, CURSOR_CLI, or AKUA_AGENT. Explicit flags always override detection.

# Human shell — text output
$ akua render
[pretty text output]

# Agent context — auto-JSON, no flag needed
$ CLAUDECODE=1 akua render
{"format":"raw-manifests","target":"./deploy","manifests":3,"hash":"sha256:…"}

See cli-contract.md §1.5 for the full detection rules, override semantics, and env-var reference.

Verb index

AUTHOR              PUBLISH             DEPLOY              OPERATE
------              -------             ------              -------
akua init           akua attest         akua deploy         akua secret
akua add            akua publish        akua rollout        akua policy
akua vendor         akua pull           akua dev            akua audit
akua render         akua inspect                            akua query
akua diff           akua export                              akua infra

DEVELOP             SESSION             META
-------             -------             ----
akua test           akua login          akua help
akua fmt            akua logout         akua version
akua lint           akua whoami         akua telemetry
akua check                              akua api
                                        akua lint-cli
akua bench
akua trace
akua cov
akua repl
akua eval

Thirty-five verbs. Grouped by purpose. Each covered below.

Quick disambiguation — render vs export vs inspect vs diff: | verb | takes | produces | invokes engines? | |---|---|---|---| | render | Package + inputs | deploy-ready manifests | yes | | export | any canonical artifact | format view (JSON Schema, YAML, OpenAPI, Rego bundle) | no | | inspect | a published package ref | audit report (schema, sources, signatures, attestation) | no | | diff | two package refs | structural diff between them | no | When in doubt: render = "run the program"; export = "convert the format"; inspect = "audit what's there"; diff = "compare two versions."

Shipped (16)

  • akua init
    Scaffold a new package or workspace.
  • akua add
    Insert a dependency into `akua.toml`. Pure manifest edit — the resolver best-effortly updates `akua.lock` immediately after.
  • akua vendor
    Materialize and inspect the workspace vendor tree at `.akua/vendor/`.
  • akua lint
    Parse-only check of a `package.k` — catches syntax errors and import- resolution failures without executing the program. Runtime errors (schema validation, unresolved options, engine failures) surface through `akua render --dry-run`.
  • akua render
    **Run the Package's program.** Evaluate the KCL, invoke every source engine (Helm, kro, Kustomize), compose results, produce deploy-ready manifests.
  • akua diff
    Structural diff between two package versions, or between a local package and a published version.
  • akua inspect
    Report a `package.k`'s input surface — every `option()` call-site with its name, declared type, required flag, default, and help text. Parse-only: the program is not executed.
  • akua export
    **Convert a Package's `Input` schema to a standard interchange format.** Emits JSON Schema 2020-12 (raw) or OpenAPI 3.1 (Input wrapped under `components.schemas`). Backed by KCL's resolver + AST walk; field docstrings become `description`,
  • akua api
    Call the hosted Akua API from the OSS CLI. This is an optional hosted extension: local package workflows such as `render`, `export`, `check`, `lint`, `test`, and `verify` do not require hosted API credentials or network access.
  • akua dev
    Start the hot-reload development loop.
  • akua whoami
    Display current identity, logged-in registries, and scopes.
  • akua fmt
    Format KCL and Rego sources in place.
  • akua check
    Syntax + type + dependency check. No execution, no rendering. Fast.
  • akua repl
    Interactive REPL for exploring policies and packages.
  • akua version
    ``` akua version # print version + git SHA akua version --json ```
  • akua lint-cli
    Validate that the current binary honors the CLI contract.

Planned (19)

  • akua attest
    Emit a SLSA v1 provenance predicate for the current package or a built artifact.
  • akua publish
    Push a signed package to an OCI registry.
  • akua pull
    Fetch a package from an OCI registry into the local cache.
  • akua deploy
    Deploy rendered output to a reconciler target.
  • akua rollout
    Cross-repo / cross-service staged rollout orchestration.
  • akua secret
    Typed secret operations. Secrets move as refs, never raw bytes.
  • akua policy
    Policy tier operations.
  • akua audit
    Causality spine. Trace changes, explain incidents, query the audit trail.
  • akua query
    Structured queries against observability stores.
  • akua infra
    Cluster, network, DNS, cert primitives. Wraps Crossplane or Terraform under the hood.
  • akua login
    Authenticate to OCI registries and signing providers.
  • akua logout
    Remove stored credentials.
  • akua test
    Run unit tests for packages, policies, or both. Unified test runner across engines — detects target types by file extension.
  • akua bench
    Benchmark policy evaluation and package render latency.
  • akua trace
    Explain the evaluation path of a policy query. Useful for debugging "why did this rule deny?" or "why didn't this rule fire?"
  • akua cov
    Generate a test coverage report across rules (Rego) and schemas (KCL).
  • akua eval
    One-shot evaluator — cheap, scriptable. For Rego queries and KCL expressions without entering the REPL.
  • akua help
    ``` akua help # list all verbs akua help # detailed help for one verb akua help --json # machine-readable command tree ```
  • akua telemetry
    Opt-in, anonymized usage data.