CLI Tools

<h1>ᚾ&nbsp;NornGate — CLI Tools</h1>

Scope note. Two commands are documented across these docs — audit replay and drill ragnarok (marked [documented] below). The rest is the coherent command surface implied by the control API; reconcile against norngate-cli --help on your build.

norngate-cli is the operator's interface to the control plane. Every command calls a gated control endpoint, so — like the API — every command is itself audited. There is no unobserved operator read of the ledger.

---

ᛏ Overview

• Auth — in-mesh via SPIFFE SVID, or a token (--token, NORNGATE_TOKEN). --context selects the cluster/realm.
• Output — --output table (default) or --output json for scripting.
• Everything is audited — reads and writes alike land in Urd.

norngate-cli version
norngate-cli --help

Global flags

Flag	Purpose
--context	Target cluster / realm
--output table|json	Human vs machine output
--token	Bearer token (external use)
--tenant	Scope to a tenant

References. Ed25519 / RFC 8032 and RFC 6962 (chain verification, per Urd Ledger); SPIFFE (CLI identity); RFC 3339 (timestamps). Naming doctrine: Prose Edda / Poetic Edda, per Norse Cosmology & Platform Design.

ᚾ NornGate — CLI Tools

Scope note. Two commands are documented across these docs — audit replay and drill ragnarok (marked [documented] below). The rest is the coherent command surface implied by the [control API](API-Reference); reconcile against norngate-cli --help on your build.

norngate-cli is the operator's interface to the control plane. Every command calls a gated control endpoint, so — like the API — every command is itself audited. There is no unobserved operator read of the ledger.

---

ᛏ Overview

• Auth — in-mesh via SPIFFE SVID, or a token (--token, NORNGATE_TOKEN). --context selects the cluster/realm.
• Output — --output table (default) or --output json for scripting.
• Everything is audited — reads and writes alike land in Urd.

norngate-cli version
norngate-cli --help

Global flags

Flag	Purpose
--context <name>	Target cluster / realm
--output table|json	Human vs machine output
--token <t>	Bearer token (external use)
--tenant <id>	Scope to a tenant

---

ᛈ audit

Query, fetch, replay, and verify the [Urd ledger](Urd-Ledger).

# query (mirrors GET /v1/audit)
norngate-cli audit query --gate policy --decision deny \
  --from 2026-07-06T00:00:00Z --to 2026-07-06T23:59:59Z

# one record
norngate-cli audit get audit_7f3a2b

# re-derive a historical verdict from its pinned snapshots      [documented]
norngate-cli audit replay req_abc123

# walk the hash chain and check signatures over a window
norngate-cli audit verify --from 2026-07-06T00:00:00Z --to 2026-07-07T00:00:00Z

Why replay: the verdict is a pure function of pinned inputs, so it reproduces exactly — the answer to "why was this denied?" in a dispute. Why verify: it validates the chain against a signed checkpoint, so tampering is detectable, not merely unlikely.

---

ᚷ receipts and keys

norngate-cli receipt get out_9a2
norngate-cli receipt verify out_9a2     # checks sig against the ledger public key
norngate-cli keys list                  # GET /v1/keys

Why: a tenant reconciles their per-outcome bill against receipts they verify themselves against the published key — trust neither side has to grant the other.

---

ᛗ approvals

The human side of G2.

norngate-cli approvals list --state pending
norngate-cli approvals decide apr_5c1 --approve
norngate-cli approvals decide apr_5c1 --deny --reason "out of policy window"

Why: each decision is recorded to Urd and debits the approval budget — the same budget that keeps human transits under ~5% ([Gates & Attributes](Gates-and-Attributes)).

---

ᛜ config

Validate, apply, and version declarative config ([Configuration](Configuration)).

norngate-cli config validate policy.yaml          # admission dry-run; fail-closed
norngate-cli config apply policy.yaml
norngate-cli config versions Policy/acme
norngate-cli config diff pol_20260705_02 pol_20260706_01

Why diff: it answers "why did this flip from allow to deny?" — take the two policy snapshot IDs off the differing decisions and diff them directly. Why validate: a bad config is rejected before apply, so fail-closed extends to configuration.

---

ᛟ realm and policy

Inspect realms; simulate a decision without deploying it.

norngate-cli realm list
norngate-cli realm describe jotunheim

# dry-run a policy decision against current policy
norngate-cli policy test \
  --subject retrieval-agent --resource pii:user-record --action write

Why policy test: because the decision is a pure function, you can evaluate it offline — CI can assert that a proposed policy still denies cross-tenant writes before it ships. [Deterministic Execution](Deterministic-Execution)

---

ᚺ drill

Disaster-recovery exercises ([Ragnarök drill](Disaster-Recovery-Ragnarok-Drill)).

# restore from a signed checkpoint, replay forward, verify the chain   [documented]
norngate-cli drill ragnarok --target staging --duration 30m
norngate-cli drill status

Why: the drill proves recovery-from-checkpoint works before a real outage needs it — Ragnarök is rehearsed, not discovered. The checkpoint it restores from is the same signed chain-head audit verify checks.

---

ᚱ Next steps

• [API Reference](API-Reference) — the endpoints these commands call.
• [Configuration](Configuration) — the resources config manages.
• [Urd Ledger](Urd-Ledger) — replay, verify, receipts, checkpoints.
• [Disaster Recovery (Ragnarök Drill)](Disaster-Recovery-Ragnarok-Drill) — the drill in full.

---

Iconography

Section glyphs are Elder Futhark runes (Unicode Runic block, U+16A0–U+16FF) — semantic, not emoji. Full set on [Home](Home#iconography):

Rune	Name	Gloss	Marks
ᚾ	Nauðiz	need, constraint	the platform mark
ᛏ	Tiwaz	Týr — order, the instrument	overview
ᛈ	Perthro	the well of Urd	audit
ᚷ	Gebo	the proof of exchange	receipts & keys
ᛗ	Mannaz	the self, the decider	approvals
ᛜ	Ingwaz	the structured whole	config
ᛟ	Othala	enclosed estate, boundary	realm & policy
ᚺ	Hagalaz	hail, Ragnarök	drill
ᚱ	Raidō	the ride, the road	next steps

References. [Ed25519 / RFC 8032](https://www.rfc-editor.org/rfc/rfc8032) and [RFC 6962](https://www.rfc-editor.org/rfc/rfc6962) (chain verification, per [Urd Ledger](Urd-Ledger)); [SPIFFE](https://spiffe.io/) (CLI identity); RFC 3339 (timestamps). Naming doctrine: Prose Edda / Poetic Edda, per [Norse Cosmology & Platform Design](Norse-Cosmology-and-Platform-Design).