the Akua packaging toolkit

What is akua?

akua is a cloud-native packaging toolkit, shipped as a single Rust binary. Packages are authored in KCL — a typed configuration language with real types, functions, and imports. Existing Helm charts, kro RGDs, and Kustomize bases will be callable KCL functions, so the whole ecosystem works unchanged.

akua render --inputs inputs.yaml      # render to raw YAML

Designed agent-first: auto-detects Claude Code, Cursor, Codex, Gemini CLI, Goose, Amp, OpenCode, Cline, and 20+ more, emitting structured JSON on every verb. Ships a skills library conforming to the Agent Skills Specification.

Warning

Pre-alpha. The tree is mid-pivot. Only the whoami, version, verify, and render verbs exist today; the full verb set landed in docs/cli.md is the target, not the current state. Don't build production workloads on this yet.

Install

# from source (primary path today)
cargo install --git https://github.com/cnap-tech/akua akua-cli

# into your AI agent (universal)
npx skills install github:cnap-tech/akua/skills

Prebuilt binaries live on GitHub Releases. Agent setup for Claude Code, Cursor, Codex, Gemini CLI, Goose, Amp, and 25+ others: docs/agent-usage.md.

Quick start

A Package.k is plain KCL with four regions — imports, schema, body, outputs:

schema Input:
    appName: str
    replicas: int = 2

input: Input = option("input") or Input {}

resources = [{
    apiVersion: "v1"
    kind: "ConfigMap"
    metadata.name: input.appName
    data.replicas: str(input.replicas)
}]

outputs = [{ kind: "RawManifests", target: "./" }]

Render it:

akua render --package ./Package.k --inputs inputs.yaml --out ./deploy

Full CLI reference: docs/cli.md. Universal contract: docs/cli-contract.md. Runnable examples: examples/.

Architecture

Two crates:

• akua-core — the Rust library: CLI contract primitives, akua.toml / akua.lock parsers, Package.k loader, render output writer.
• akua-cli — the akua binary. Every verb JSON-first, idempotent, typed exit codes — see docs/cli-contract.md.

KCL is the authoring language; in the target shape, Helm, kro RGDs, and Kustomize are callable KCL functions (helm.template(...), rgd.instantiate(...), kustomize.build(...)) — those engine callables arrive in Phase B.

Deep dives: docs/architecture.md · docs/cli.md · docs/cli-contract.md · docs/agent-usage.md · docs/package-format.md · docs/policy-format.md · docs/lockfile-format.md · docs/embedded-engines.md · skills/ · examples/ · docs/roadmap.md

Status

What's shipped on main:

• akua whoami / version / verify / render verbs wired to the binary.
• akua.toml + akua.lock parsers with round-trip tests against every example.
• Package.k loader with input injection via KCL's option() mechanism.
• RawManifests output emitter with deterministic filenames + sha256 hashes.

What's next: docs/roadmap.md.

Security

See SECURITY.md for the threat model and vulnerability-disclosure process.

Contributing

Pre-alpha means APIs churn. Small focused fixes (typos, doc clarity, test coverage, security findings) are always welcome; PRs against in-flight features may hit merge friction. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Naming

"Akua" — Hawaiian for divine spirit; echoes aqua, water. Fits the cloud-native tradition: Docker loads the cargo, Helm steers the ship, Harbor stores what's shipped, Kubernetes (Greek kubernḗtēs, "helmsman") pilots the fleet. Akua is the current underneath — the flow that carries your sources, transforms them in motion, and delivers a sealed package to the harbor.

License

Apache-2.0.