akua pkg - Akua

akua pkg is the Package toolchain inside the akua CLI: it scaffolds, renders, tests, signs and publishes Packages. The same commands ship as the standalone akuapkg executable; akuapkg render and akua pkg render behave identically. Renders run inside a WebAssembly sandbox with no network, no shell and only the Package directory readable, so untrusted Packages are safe to render.

brew install akua-dev/tap/akua
akua pkg init hello && cd hello
akua pkg render --inputs inputs.example.yaml

Commands

Author and render

Command	Description
`init`	Scaffold a new Package
`render`	Execute a `package.k` against inputs and write manifests
`check`	Fast workspace check (parse + lint)
`lint`	Parse-only check of a `package.k` (KCL syntax + imports)
`fmt`	Format a `package.k` via KCL’s canonical formatter
`export`	Emit the Package’s `Input` schema (JSON Schema / OpenAPI)
`inspect`	Report a Package’s input surface or tarball metadata
`test`	Run KCL tests (`test_.k`, `_test.k`) and, with `--golden`, snapshot tests
`repl`	Interactive KCL shell (`.help` lists meta commands)
`diff`	Structural diff between two rendered-output directories

Dependencies

Command	Description
`add`	Add a dependency to akua.toml and lock it
`remove`	Remove a dependency from akua.toml
`tree`	Print the workspace’s declared deps and lockfile entries
`lock`	Regenerate akua.lock from akua.toml
`update`	Refresh akua.lock to what upstream serves now
`vendor`	Materialize and inspect the vendor tree at `.akua/vendor/`

Distribute

Command	Description
`pack`	Pack the workspace into a local .tar.gz
`pull`	Pull a published Package from an OCI registry
`push`	Upload a pre-packed tarball to an OCI registry
`sign`	Produce a cosign signature sidecar for a packed tarball
`publish`	Pack, push, sign and attest the workspace’s Package
`verify`	Check akua.lock against akua.toml, or a tarball against its signature

Toolchain

Command	Description
`cache`	Manage the on-disk OCI, git and Helm caches
`version`	Print the package toolchain version

Universal flags

Every command accepts these flags. Output is JSON by default when a coding agent runs the command; --json and --no-json decide explicitly.

Flag	Type	Description
`--json`	boolean	Emit structured JSON to stdout; default for agents, `--no-json` forces text
`--plan`	boolean	Compute the plan; do not write
`--timeout`	string	Wall-clock cap; renders are bounded by fuel instead
`--idempotency-key`	string	Retry-safe key for write operations
`--log`	choice	Structured log format to stderr (choices: text, json)
`--log-level`	choice	Log level (choices: debug, info, warn, error)
`--verbose`, `-v`	boolean	More detail in logs (does not change stdout format)
`--no-color`	boolean	Disable color codes
`--no-progress`	boolean	Disable progress output
`--no-interactive`	boolean	Never prompt
`--no-agent-mode`	boolean	Ignore agent-context detection

Exit codes

Code	Meaning
`0`	Success.
`1`	The input was wrong: a flag, a file, a Package, or a check that found a difference.
`2`	The system failed: a file could not be read or written.
`3`	A policy refused the operation.
`4`	A registry or service rate-limited the request.
`5`	The operation needs approval before it can run.
`6`	The command ran out of its time or CPU budget.

Errors

A failing command prints one JSON object on stderr with a stable code, a message, and a docs link to the error reference:

{
  "level": "error",
  "code": "E_MANIFEST_MISSING",
  "message": "akua.toml not found",
  "path": "./akua.toml",
  "docs": "https://cli.akua.dev/errors/E_MANIFEST_MISSING"
}

Error codes

What each structured error means and how to resolve it.

Package format

The package.k Input schema and UI annotations.

Packages on Akua

How Akua renders a Package for every installation.

​Commands

​Author and render

​Dependencies

​Distribute

​Toolchain

​Universal flags

​Exit codes

​Errors

​Related topics