> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# akua pkg

> Author, render, test and publish Packages from the command line

`akua pkg` is the Package toolchain inside the `akua` CLI: it scaffolds, renders, tests, signs and publishes [Packages](/akua). 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.

```sh theme={null}
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`](/akua/cli/init) | Scaffold a new Package |
| [`render`](/akua/cli/render) | Execute a `package.k` against inputs and write manifests |
| [`check`](/akua/cli/check) | Fast workspace check (parse + lint) |
| [`lint`](/akua/cli/lint) | Parse-only check of a `package.k` (KCL syntax + imports) |
| [`fmt`](/akua/cli/fmt) | Format a `package.k` via KCL's canonical formatter |
| [`export`](/akua/cli/export) | Emit the Package's `Input` schema (JSON Schema / OpenAPI) |
| [`inspect`](/akua/cli/inspect) | Report a Package's input surface or tarball metadata |
| [`test`](/akua/cli/test) | Run KCL tests (`test_*.k`, `*_test.k`) and, with `--golden`, snapshot tests |
| [`repl`](/akua/cli/repl) | Interactive KCL shell (`.help` lists meta commands) |
| [`diff`](/akua/cli/diff) | Structural diff between two rendered-output directories |

### Dependencies

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

### Distribute

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

### Toolchain

| Command | Description |
| - | - |
| [`cache`](/akua/cli/cache) | Manage the on-disk OCI, git and Helm caches |
| [`version`](/akua/cli/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](/akua/errors):

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

## Related topics

<CardGroup cols={2}>
  <Card title="Error codes" icon="triangle-exclamation" href="/akua/errors">
    What each structured error means and how to resolve it.
  </Card>

  <Card title="Package format" icon="cube" href="/akua/package-format">
    The `package.k` Input schema and UI annotations.
  </Card>

  <Card title="Packages on Akua" icon="box" href="/akua">
    How Akua renders a Package for every installation.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.