CLI

Complete reference for the ninka command-line interface. Each command is documented with its syntax, arguments, behavior, output, and exit codes.

Overview

• Package: ninka-authz — npm install ninka-authz. The package bundles the CLI and the runtime.
• Binary: ninka — typically run as npx ninka <command>.
• Node.js: 20 or later.

usage: ninka <command>

  init [--bare]        Set up authz/ and the agent rules (AGENTS.md); --bare omits the sample policy
  compile [files...]   Sekisho + Rego + manifest + types + WASM (pinned opa, fetched once)
  build                compile, but fail when the pinned opa toolchain is unavailable (CI use)
  verify               Recompile and require byte-identity with authz/out/ (CI gate)
  explain <policy>     Human-readable summary of a policy

There is no --help or --version flag.

Exit codes

Situation	Output	Exit code
Success	command output	0
Unknown or missing command	USAGE on stderr	2
Any thrown error	error: <message>	1

---

ninka init [--bare]

Scaffolds a project for Ninka. Idempotent — existing files are skipped, never overwritten.

Flag	Description
--bare	Omit the sample policy (authz/invoice-access.tegata.json).

What it does

Creates the following, skipping any that already exist:

Path	Contents
authz/tegata-0.1.schema.json	The Tegata JSON Schema.
authz/invoice-access.tegata.json	Sample policy. Omitted with --bare.
authz/vocabulary.json	Starter vocabulary: {"roles":["employee"],"actions":["view"],"resource_types":["invoice"],"attributes":{}}.
lib/authz.ts	Typed check() boundary.
AGENTS.md	Agent rules for working with AI coding assistants.

For AGENTS.md: if the file exists without a ## Ninka Authorization Rules heading, the rules are appended; if the heading is already present it is left untouched. Other agent files are never edited.

After scaffolding, if any authz/*.tegata.json exists, init immediately runs compile so that authz/out/ is present.

---

ninka compile [files...]

Compiles Tegata policies to Rego, types, and (when the OPA toolchain is available) WASM.

Argument	Description
[files...]	Specific Tegata files to compile. When omitted, compiles all authz/*.tegata.json.

What it does

Runs the semantic checker (Sekisho (関所)) per file, then across the whole set, then emits artifacts to authz/out/. If a semantic problem is found it rejects with a one-line, prescriptive error.

What it writes

To authz/out/:

File	Always written
<id>.rego	Yes
<id>.manifest.json	Yes
input-contract.json	Yes
types.gen.ts	Yes
<id>.wasm	Only when the OPA toolchain is available
<id>.build.json	Only when the OPA toolchain is available
<id>.validation.json	Only when the OPA toolchain is available

On a machine without the OPA toolchain, WASM is skipped with a note: — Sekisho, Rego, and types still succeed. See Generated Files for the contents of each file.

Exit codes

Exit 1 on a Sekisho rejection or a validation mismatch; otherwise 0.

---

ninka build

The same as compile, but hard-fails when the pinned OPA toolchain cannot be resolved. Use it in CI, where the WASM artifact must be produced.

Exit codes

Exit 1 if the OPA toolchain is unavailable, on a Sekisho rejection, or on a validation mismatch; otherwise 0.

---

ninka verify

The CI gate. Recompiles in memory and requires byte-identity with the committed authz/out/.

What it does

• Recompiles and compares the Rego, types.gen.ts, and the validation table byte-for-byte against the committed files.
• Re-checks the WASM hashes.
• Re-runs every validation vector against the committed WASM.

Exit codes

Exit 1 on any mismatch; otherwise 0.

---

ninka explain <policy>

Prints a human-readable summary of a policy. Writes no files.

Argument	Description
<policy>	A policy id or a Tegata file path.

What it does

Prints each rule as [effect] id: roles → actions on resource — description, plus any interpretation reports.

---

OPA toolchain

Ninka emits WASM that runs on OPA. The OPA version is pinned so that the same Tegata always produces byte-identical WASM.

• Pinned OPA version: 0.65.0. Because WASM bytes depend on the OPA version, bumping it is an explicit new ninka-authz release.
• Ninka never uses a PATH opa; a stray system or Homebrew opa cannot leak into the build.

Resolution order

1. NINKA_OPA_PATH — path to an OPA binary. An escape hatch for air-gapped or proxied machines.
2. Cache: ~/.cache/ninka/opa-v0.65.0-<platform>-<arch>.
3. One-time download from openpolicyagent.org (SHA-256 verified).

Environment variables

Variable	Effect
NINKA_OPA_PATH	Use this OPA binary directly, skipping the cache and download.
NINKA_CACHE_DIR	Override the cache directory.

Supported platforms

darwin-x64, darwin-arm64, linux-x64, linux-arm64, win32-x64. On any other platform, set NINKA_OPA_PATH.

---

See also

• Generated Files — everything compile writes to authz/out/.
• Runtime API — loading and calling the compiled policies.