CLI and plugin#

The CLI (maqpna) is one static Go binary. Developers run a local MAQPNA and their agent with it, approvers decide approvals, auditors verify the ledger, and platform teams apply manifests, check posture, back up and rotate keys. The Helm lifecycle commands (preflight, install, upgrade, rollback, uninstall) live in a separate executable, maqpna-install, because the Helm v3 SDK would more than double the size of the CLI.

Code: cmd/maqpna, cmd/maqpna-install, cmd/internal/cliutil, cmd/internal/lifecycle, cmd/internal/desk.

How the CLI reaches things#

flowchart LR
    U["You"] --> CLI["maqpna"]
    CLI -- "exec, same arguments,<br/>stdio and exit code passed through" --> PL["maqpna-install<br/>(Helm v3 SDK)"]
    PL --> K
    CLI -- "admin API over HTTP<br/>Bearer access token" --> GW["Gateway /v1/*"]
    CLI -- "controller-runtime client<br/>maqpna.com/v1alpha1" --> K[("Kubernetes API")]
    CLI -- "kubectl port-forward<br/>(console, desk)" --> GW
    CLI -- "POST /v1/token<br/>(dev run, token mint)" --> IB["Identity broker"]
    CLI -- "starts local processes" --> DEV["maqpna dev up:<br/>gateway, broker, mcp-echo"]
    CLI -- "reads files offline" --> F[("ledger, manifests,<br/>policies, bundles")]

Path	Used by
Gateway admin API (`--gateway`, `$MAQPNA_GATEWAY_URL` or the context's gateway)	`approvals`, `audit verify --gateway`, `audit export --gateway`, `kill`, `revocations`, `policy test --gateway`, `session describe`, `dev timeline`, `taint`, `mcp`, `budgets`, `costs summary`, `evidence`, `whoami`, `doctor`
Kubernetes API (`--kubeconfig`, the context's kube context)	`apply`, `diff`, `session` (start, list, get, suspend, resume, fork, snapshot, delete), `agent`, `tier`, `status`, `logs`, `events`, `backup`, `restore`
Identity broker	`dev run`, `token mint`
Offline files	`validate`, `policy test --policy`, `sovereignty check`, `audit verify FILE`, `audit export FILE`, `replay`, `eval`, `config validate`, `values validate`, `airgap verify`, `verify`, `license verify`
Helm (through `maqpna-install`)	`preflight`, `install`, `upgrade`, `upgrade check`, `rollback`, `uninstall`

Commands#

The command tree, grouped as maqpna help prints it (cmd/maqpna/testdata/help.golden, verbatim):

MAQPNA - The sovereign runtime for AI agents.

Quickstart:
  maqpna dev up                        Start a local MAQPNA: gateway, identity broker, test MCP server
  maqpna dev run -- python agent.py    Run your agent under it, with its own session identity
  maqpna dev timeline --last           See each tool call it made and the decision on it

Usage:
  maqpna <command> [subcommand] [flags]

Get started:
  install         Install MAQPNA in a cluster with Helm
  dev             Run a local MAQPNA (identity broker, gateway, test MCP server) and your agent under it
  init            Print a starter manifest for a MAQPNA resource
  explain         Document a MAQPNA resource or field
  login           Log in to a gateway's admin API (browser or device flow) and store the access token
  logout          Delete the context's stored access token
  whoami          Show the identity and roles the gateway sees for you

Run agents:
  apply           Validate manifests, then server-side apply them (agents, policies, trust tiers, ...)
  diff            Show what apply would change (server-side dry run)
  validate        Validate MAQPNA manifests offline (schemas, policies, sovereignty, references)
  session         Start, inspect, control and observe sessions
  agent           List and inspect agents
  tier            List and inspect trust tiers
  call            Make one tool call through the gateway with a session token (debugging)
  console         Open the console of an installation
  token           Mint, inspect and verify session tokens
  keygen          Generate an Ed25519 signing key pair for session identities (dev and CI)

Govern:
  policy          Test a tool call against policies, offline or on the live gateway
  eval            Score the policy decisions of an evaluation suite
  replay          Replay the audit ledger against a candidate policy
  sovereignty     Check Agent manifests against a sovereignty policy offline
  approvals       List pending approvals, and approve or deny them
  desk            Open the approvals inbox and dev window in your browser (what MAQPNA Desk shows)
  kill            Kill switch: revoke sessions, agents, users or tokens at the gateway (break-glass)
  revocations     List or delete revocations (deleting one lifts it)
  mcp             List MCP servers, their tools and pins (tool pinning)
  a2a             List the gateway's agent-to-agent (A2A) routes
  accounts        List or revoke users' connected accounts
  memory          List memory stores, or erase a user's memory with a signed certificate (GDPR Art. 17)
  taint           List, inspect and clear session taint

Observe:
  status          One-screen status of an installation: release, workloads, sessions, approvals, audit ledger
  logs            Print the logs of a session's sandbox
  events          Print the Kubernetes events of a session, its sandbox and snapshots
  audit           Verify, export, stream and tail the audit ledger
  usage           Hourly usage per tenant: sandbox seconds, governed calls, model tokens, approvals
  costs           Export costs in FOCUS, the FinOps cost-export format
  budgets         Show budgets and the spend against them
  evidence        Export the third-party register (DORA Art. 28) from the audit ledger

Operate:
  doctor          Check the health and security posture of an installation
  preflight       Check a cluster before installing MAQPNA (read-only; exit 3 when a check fails)
  upgrade         Upgrade MAQPNA; 'upgrade check' says whether it is safe
  rollback        Roll the Helm release back to an earlier revision
  uninstall       Uninstall MAQPNA (resources, keys and agent namespaces are kept unless --purge)
  smoke           Smoke-test a running installation end to end (exit 3 when a step fails)
  support-bundle  Collect a redacted diagnostics archive for support
  backup          Back up the audit ledger, MAQPNA resources, sealed signing keys and PostgreSQL state
  restore         Restore a backup (signing keys, MAQPNA resources, PostgreSQL state, audit ledger)
  dr              Disaster-recovery drill: prove a backup restores, and report recovery time and data-loss window
  keys            Rotate signing and encryption keys without downtime
  license         Install, show, verify or issue MAQPNA licences (offline EdDSA or ES256 JWS)
  verify          Verify signatures, SBOM attestations and checksums of MAQPNA releases
  airgap          Build, verify and mirror offline (air-gap) install bundles
  config          Validate a gateway configuration file offline
  values          Validate Helm values for the MAQPNA chart offline
  tenants         List tenants with their trust domain, signing key and ledger head

Configure the CLI:
  context         Manage named contexts: gateway URL, cluster and namespace
  completion      Print a shell completion script (bash, zsh, fish, PowerShell)
  version         Print the CLI version, or every component's version with the skew check
  help            Show help for maqpna or one command

Global flags:
  --context NAME       Use this context from the config file (env MAQPNA_CONTEXT)
  --kubeconfig FILE    Kubeconfig for Kubernetes-backed commands (default $KUBECONFIG)
  -o, --output FORMAT  table, json or yaml, for commands that print data
  --jq EXPR            Filter the JSON output with a jq expression
  --no-color           Plain output without colour (also NO_COLOR=1)
  --gateway URL        Gateway base URL (before the command; commands also take --gateway)
  -n, --namespace NS   Default namespace (before the command)

Learn more:
  maqpna <command> -h    Flags and examples for one command
  maqpna help --all      Every command's synopsis, and the environment variables
  maqpna completion -h   Tab completion for bash, zsh, fish and PowerShell
  Docs: https://maqpna.com/docs

How commands are built:

Each command registers itself from init() with register(&Command{...}); the help group and order come from one layout table, so help, completion and the reference stay in sync.
Subcommands added from other files use registerSub. A When predicate lets one take over an existing name only for some arguments: audit verify --gateway and audit verify --postgres are handled by the admin path, audit verify FILE by the offline verifier.
Global flags (--context, --kubeconfig, -o, --jq, --no-color, --gateway, -n) are taken out before the command is parsed. -o and --jq are refused for commands that print no data.
Unknown commands, subcommands and flags get a "did you mean" suggestion.

The `maqpna-install` plugin#

The lifecycle commands are registered in maqpna as stubs (so help and completion list them) and executed by maqpna-install:

maqpna looks for the plugin in $MAQPNA_INSTALL_PLUGIN, then next to its own executable (also next to the symlink target, as Homebrew installs it), then on PATH.
It runs the plugin with all original arguments, global flags included, passes stdin, stdout, stderr and the exit code through, forwards SIGTERM and sets MAQPNA_PROG_NAME.
When the plugin is missing, maqpna prints how to install it.

maqpna-install uses the Helm v3 SDK, server-side-applies CRDs before helm install and helm upgrade (Helm never upgrades crds/), and maps --profile dev|prod|sovereign-eu to the chart's values files. See install and upgrade flow.

There is no general plugin mechanism: maqpna-install is the only plugin. Separately, the binary installed as kubectl-maqpna works as a kubectl plugin and rewrites its usage text to kubectl maqpna.

Contexts and tokens#

Contexts (gateway URL, identity and attestation URLs, kube context, kubeconfig, namespaces, OIDC token file) live in $MAQPNA_CONFIG, default $XDG_CONFIG_HOME/maqpna/config.yaml or ~/.config/maqpna/config.yaml. The config file holds no secrets.
maqpna login (browser PKCE flow, or --device) stores the access token per context in tokens/<NAME>.json beside the config file, mode 0600, and refreshes it.
Token precedence for admin calls: --oidc-token-file ($MAQPNA_OIDC_TOKEN_FILE), then --token ($MAQPNA_ADMIN_TOKEN, the static break-glass token), then the token stored by maqpna login.
Select a context per call with --context NAME or $MAQPNA_CONTEXT.

Exit codes#

Code	Meaning
0	OK
1	Error: the action did not happen
2	Usage error: unknown command or flag, missing argument
3	Mismatch or failed check: `policy test` decision differs from `--expect`, `audit verify` found tampering, `doctor`, `preflight`, `upgrade check`, `smoke`, `airgap verify` or `sovereignty check` failed

Code 3 is designed for CI: a policy test suite or a ledger verification fails the pipeline without parsing output.

Failure modes#

Failure	Behaviour
No gateway URL	Commands that need one exit 2 with the three ways to set it
Gateway unreachable, wrong role, expired token	The error names the cause and the next step (`maqpna whoami`, `maqpna login`)
Plugin missing	Install instructions for `maqpna-install`
Cedar policy evaluated by a build without Cedar	`policy test` refuses to report a verdict and exits 3

What you see#

Errors follow the voice guide: what happened, why, and the next step (cmd/maqpna/testdata/errors.golden):

$ maqpna stauts
✗ unknown command "stauts"
  Did you mean status?
  → maqpna help
[exit 2]

$ maqpna approvals list
✗ --gateway is required
  Pass --gateway URL, set MAQPNA_GATEWAY_URL, or save it in a context once:
  → maqpna context set NAME --gateway URL --use

Usage:
  maqpna approvals list    --gateway URL [--status pending] [--oidc-token-file F]

Run 'maqpna approvals -h' for flags and examples.
[exit 2]

Every command also has a reference page generated from its real flags, for example maqpna dev up, maqpna kill, maqpna audit verify, maqpna context and maqpna install.