Skip to main content

CLI

Reference for the ninka-authz command-line interface.

Overview​

  • Package: ninka-authz — install with npm install ninka-authz.
  • Binary: ninka-authz — normally run as npx ninka-authz <command>.
  • Node.js: 20 or later.

The CLI's current usage text is:

usage: ninka-authz <command>

  init [--bare]        Set up ninka/ 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 ninka/out/ and the
                       Consumer Projections (CI gate)
  explain <policy>     Human-readable summary of a policy
  docs                 Serve the Authorization Reference for this project (local, read-only)
       [--port N]      Listen on a different port (default 4173)
       [--no-open]     Do not open a browser
       [-o <dir>]      Export a static snapshot into <dir> instead of serving

  --workspace <dir>    Use <dir> instead of ninka/ (global; every command above accepts it)
  --out <file>         Write the Consumer Projection to <file>, instead of <source root>/generated/ninka.ts
                       (init, compile, build; verify checks that file — not remembered, so a
                       later run, verify included, resolves again)
  --out-csharp <file>  Also write the C# Consumer Projection to <file> (compile and build;
                       verify checks that file). C# has no source-root convention to resolve,
                       so this names the file

--help or -h prints usage and exits 0 without running a command. There is no --version flag.

Workspace resolution​

--workspace <dir> selects the authoring workspace. Every command accepts it.

Without the flag, Ninka looks for ninka/ in the current directory. If it does not exist, the command fails; there is no silent fallback to the old authz/ location. init is the exception that may create the selected workspace.

The workspace contains the *.tegata.json files, optional vocabulary.json, schema copy, and generated out/.

TypeScript Consumer Projection output​

init, compile, and build resolve the TypeScript Consumer Projection on every invocation in this order:

  1. --out <file> — exactly that .ts file;
  2. <compilerOptions.rootDir>/generated/ninka.ts when tsconfig.json defines rootDir;
  3. src/generated/ninka.ts or lib/generated/ninka.ts when exactly one of src/ and lib/ exists;
  4. an error when both src/ and lib/ exist with no rootDir and no --out;
  5. no TypeScript projection when neither source root exists.

init creates src/ when necessary, so a normally scaffolded TypeScript project gets src/generated/ninka.ts.

Output-path flags are not remembered. A later verify resolves the path again, so a project that compiles with --out must pass the same path to verify.

--out-csharp <file> names the C# Consumer Projection explicitly. C# has no source-root convention in Ninka from which to derive this path.

Exit-code classes​

SituationExit code
Success0
Unknown or missing command2
CLI syntax / invalid argument2
Schema/Sekisho, validation, I/O, toolchain, export, or other operational failure1

Individual commands below add the command-specific details.

ninka-authz init [--bare] [--out <file>]​

Scaffolds a Ninka workspace. Existing files are skipped rather than overwritten.

FlagMeaning
--bareDo not create the sample ninka/invoice-access.tegata.json.
--out <file>Use the named TypeScript Consumer Projection path.

The default scaffold includes:

PathPurpose
ninka/tegata-0.1.schema.jsonTegata JSON Schema for editor/agent use.
ninka/invoice-access.tegata.jsonSample policy unless --bare is used.
ninka/vocabulary.jsonStarter closed-world project vocabulary.
src/Created only when the project has no TypeScript source root.
AGENTS.mdNinka rules for coding agents.
.gitignoreAdds the default raw-WASM ignore rule for ninka/out/bundles/*.wasm.

Ninka does not scaffold an application wrapper such as lib/authz.ts. The generated Consumer Projection is the Ninka-owned integration output; an application may build its own composition root around it if desired.

If AGENTS.md exists without a ## Ninka Authorization Rules section, init appends the section. If that section already exists, Ninka leaves it untouched. The same principle applies to the Ninka .gitignore block: init adds its own missing block but does not use the command as a general file rewriter.

When at least one Tegata exists after scaffolding, init runs the compile pipeline. If OPA is unavailable, the source-derived outputs that do not require WASM can still be written, just as with compile.

ninka-authz compile [files...] [--out <file>] [--out-csharp <file>]​

Compiles Tegata policies.

Argument / flagMeaning
[files...]Compile the named Tegata files. With no file arguments, compile the policies in the workspace.
--out <file>TypeScript Consumer Projection path.
--out-csharp <file>Also write the C# Consumer Projection to this path.

The pipeline performs JSON Schema validation, per-policy Sekisho checks, and set-level checks across the policy set and vocabulary. A rejected check stops compilation.

After those checks, Ninka writes source-derived files such as Rego, manifests, and the input contract under ninka/out/. When the OPA toolchain is available and the WASM build and generated validation succeed, it also publishes the execution bundle, validation files, and requested Consumer Projections.

If OPA cannot be resolved, compile takes the recoverable path: it reports that the WASM build was skipped and still writes the outputs that do not require the execution bundle. It does not publish a new projection without a new bundle to embed.

See Generated Files for the precise output set and fields.

Exit codes​

  • 0 when the compile command completes successfully, including the documented OPA-unavailable soft path;
  • 1 for schema/Sekisho rejection, validation failure, I/O failure, OPA refusing the generated policy set, or another operational failure;
  • 2 for invalid CLI syntax.

ninka-authz build [--out <file>] [--out-csharp <file>]​

Runs the compile pipeline with one stricter requirement: the command must publish an execution bundle.

If the pinned/default OPA toolchain cannot be resolved or run, or if OPA runs and no valid bundle can be produced, build fails instead of taking compile's soft path.

Use build in CI, packaging, or any workflow where a complete executable authorization bundle is required.

Exit codes​

  • 0 only when the build completes with the required bundle;
  • 1 when the bundle cannot be produced or another operational/validation failure occurs;
  • 2 for invalid CLI syntax.

ninka-authz verify [--out <file>] [--out-csharp <file>]​

verify checks the generated state on disk against what the current workspace and toolchain contract derive.

It does not read Git. File presence and byte identity are filesystem facts; whether a repository tracks those files is a separate repository policy.

FlagMeaning
--out <file>Check the TypeScript Consumer Projection at this path instead of the resolved default.
--out-csharp <file>Check the C# Consumer Projection at this path. Without it, no C# projection is checked.

Source-derived artifact checks​

For each policy, verify regenerates the Rego in memory and requires byte identity with the .rego file in the artifact tree. It recomputes the manifest fields that are derived from source and compares them while treating generated_by separately as provenance.

Across the workspace, it also re-derives input-contract.json and compares the source-derived contract content.

Bundle and validation checks​

When the pinned OPA toolchain is available, verify checks the policy-to-bundle bindings, entrypoints, Rego lineage, module hash, build metadata, generated validation file, and validation replay against the WASM. It also rebuilds as required to establish reproducibility rather than merely checking that existing files agree with each other.

An artifact set that is internally consistent but cannot be reproduced from the current Tegata/toolchain state fails verification.

A generated state produced by a different Ninka release is also reported as stale by upgrade where the provenance contract requires that finding. Rebuild with the current release rather than treating provenance as a substitute for byte reproducibility.

Consumer Projection checks​

verify resolves the same TypeScript output location as compile, or uses the supplied --out. It regenerates the Consumer Projection from the verified artifacts and requires byte identity with the file at that path.

A C# projection is checked only when --out-csharp is supplied.

verify does not write either projection. A projection mismatch is reported separately from artifact drift.

not checked​

A full WASM reproducibility check needs the pinned OPA toolchain. If that toolchain cannot be obtained at all, the WASM/build/validation obligations can be reported as explicit not checked skips instead of matches. This is the non-failing toolchain-unavailable skip path.

The same words can also appear downstream of a fatal finding — for example, a required bundle failed earlier, so a per-policy WASM obligation cannot be evaluated. In that case the overall run still fails.

Read not checked as “this obligation was not established,” never as “matched.”

Missing bundle versus Git tracking​

If the required bundle is missing from ninka/out/bundles/ while the environment can build it, that is a verification failure.

Whether bundles/*.wasm is tracked by Git is unrelated to that check. The default init scaffold ignores raw WASM, and that is a valid repository configuration as long as the bundle is present when verify needs to inspect it.

Exit codes​

Exit 1 when a required verification obligation fails. Otherwise exit 0; an exit-0 run may still contain the explicit non-failing not checked skips described above, so inspect the output when those obligations matter to your release process.

ninka-authz explain <policy>​

Prints a human-readable summary of one policy and writes no files.

<policy> may be a policy id or a Tegata file path. The output summarizes the rules and includes interpretation reports when present.

ninka-authz docs [--port N] [--no-open] [-o <dir>]​

Serves or exports the read-only Authorization Reference.

ninka-authz docs
ninka-authz docs -o ./reference
FlagMeaning
--port N / --port=NListen on port N (1–65535) instead of 4173.
--no-openDo not open a browser automatically.
-o <dir> / --output <dir> / --output=<dir>Export a static snapshot under the named parent directory instead of serving. Empty values are rejected; use -o . to name the project root explicitly.

LIVE serving​

The server binds to 127.0.0.1. LIVE reads the project but does not modify Tegata, write ninka/out/, or run compile for you.

If the specification changes after the last compile, the policy remains readable but the compiled state is marked stale and interactive evaluation is unavailable until the artifacts correspond again.

SNAPSHOT export​

-o names a parent directory. Each successful export creates a timestamped directory beneath it. Export never compiles the project and refuses an artifact state that does not satisfy the snapshot publication requirements.

See Authorization Reference for the user-facing behavior and security considerations.

OPA toolchain​

Ninka uses OPA to build WASM from emitted Rego. The default path pins both the OPA version and the expected distribution binary.

  • Pinned OPA version: 0.65.0.
  • The normal resolution path does not use an arbitrary opa from PATH.

Resolution order​

  1. NINKA_OPA_PATH — explicit caller-supplied binary override.
  2. Ninka cache under ~/.cache/ninka/ (or NINKA_CACHE_DIR).
  3. Download the configured platform asset and verify the configured SHA-256 before caching it.

NINKA_OPA_PATH is an escape hatch, not the pinned distribution path. Ninka does not checksum that caller-supplied binary as though it were the pinned one; responsibility for the override belongs to the caller.

Environment variables​

VariableEffect
NINKA_OPA_PATHUse the named OPA binary instead of resolving the pinned distribution.
NINKA_CACHE_DIROverride the default Ninka cache directory.

Supported automatic platforms​

Automatic pinned-binary resolution supports:

  • darwin-x64
  • darwin-arm64
  • linux-x64
  • linux-arm64
  • win32-x64

On another platform, use an explicit NINKA_OPA_PATH if you have a compatible toolchain.

See also​