Reference
Every maqpna command, generated from the binary, plus the resource, API and configuration reference.
Get started#
Install MAQPNA, run it on your laptop, and sign in.
Run agents#
Apply manifests, start sessions and make tool calls.
maqpna apply | Validate manifests, then server-side apply them (agents, policies, trust tiers, ...) |
|---|
maqpna diff | Show what apply would change (server-side dry run) |
|---|
maqpna validate | Validate MAQPNA manifests offline (schemas, policies, sovereignty, references) |
|---|
maqpna session | Start, inspect, control and observe sessionsstart list get describe wait suspend resume fork snapshot delete cost exec files liveview |
|---|
maqpna agent | List and inspect agentslist get describe |
|---|
maqpna tier | List and inspect trust tierslist get |
|---|
maqpna call | Make one tool call through the gateway with a session token (debugging) |
|---|
maqpna console | Open the console of an installation |
|---|
maqpna token | Mint, inspect and verify session tokensmint inspect verify |
|---|
maqpna keygen | Generate an Ed25519 signing key pair for session identities (dev and CI) |
|---|
Govern#
Policies, approvals, the kill switch and everything that decides what an agent may do.
Observe#
Status, logs, the audit ledger, usage and costs.
maqpna status | One-screen status of an installation: release, workloads, sessions, approvals, audit ledger |
|---|
maqpna logs | Print the logs of a session's sandbox |
|---|
maqpna events | Print the Kubernetes events of a session, its sandbox and snapshots |
|---|
maqpna audit | Verify, export, stream and tail the audit ledgerverify export stream tail fetch sinks |
|---|
maqpna usage | Hourly usage per tenant: sandbox seconds, governed calls, model tokens, approvalsbuckets report verify export |
|---|
maqpna costs | Export costs in FOCUS, the FinOps cost-export formatfocus summary |
|---|
maqpna budgets | Show budgets and the spend against themlist |
|---|
maqpna evidence | Build and verify compliance evidence packs; export the third-party registerregister frameworks generate verify |
|---|
Operate#
Install, upgrade, back up, verify and keep an installation healthy.
maqpna doctor | Check the health and security posture of an installation |
|---|
maqpna preflight | Check a cluster before installing MAQPNA (read-only; exit 3 when a check fails) |
|---|
maqpna upgrade | Upgrade MAQPNA; 'upgrade check' says whether it is safecheck |
|---|
maqpna rollback | Roll the Helm release back to an earlier revision |
|---|
maqpna uninstall | Uninstall MAQPNA (resources, keys and agent namespaces are kept unless --purge) |
|---|
maqpna smoke | Smoke-test a running installation end to end (exit 3 when a step fails) |
|---|
maqpna support-bundle | Collect a redacted diagnostics archive for support |
|---|
maqpna backup | Back up the audit ledger, MAQPNA resources, sealed signing keys and PostgreSQL statecreate verify |
|---|
maqpna restore | Restore a backup (signing keys, MAQPNA resources, PostgreSQL state, audit ledger) |
|---|
maqpna dr | Disaster-recovery drill: prove a backup restores, and report recovery time and data-loss windowdrill |
|---|
maqpna keys | Rotate signing and encryption keys without downtimerotate |
|---|
maqpna license | Install, show, verify or issue MAQPNA licences (offline EdDSA or ES256 JWS)install status verify issue |
|---|
maqpna verify | Verify signatures, SBOM attestations and checksums of MAQPNA releasesrelease image chart binary bundle |
|---|
maqpna airgap | Build, verify and mirror offline (air-gap) install bundlesbundle verify push |
|---|
maqpna config | Validate a gateway configuration file offlinevalidate |
|---|
maqpna values | Validate Helm values for the MAQPNA chart offlinevalidate |
|---|
maqpna tenants | List tenants with their trust domain, signing key and ledger headlist |
|---|
Contexts, shell completion and the CLI itself.
Server binaries#
Flags of the components the Helm chart runs. You rarely start these by hand.
maqpna-gateway | The MAQPNA gateway: every tool, model and egress call passes through it. |
|---|
maqpna-identity | The identity broker: mints the short-lived session tokens the gateway verifies. |
|---|
maqpna-operator | The Kubernetes operator: reconciles agents, sessions, trust tiers and policies. |
|---|
Global flags#
These go before or after the command name and work with every command.
| Flag | Description |
|---|
--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) |
Environment#
| Variable | Description |
|---|
MAQPNA_GATEWAY_URL | gateway base URL (default for --gateway; else the context's gateway) |
MAQPNA_CONTEXT | context name (default for --context) |
MAQPNA_CONFIG | config file (default $XDG_CONFIG_HOME/maqpna/config.yaml or ~/.config/maqpna/config.yaml) |
MAQPNA_BROKER_TOKEN | bearer token for the identity broker (token mint --broker) |
MAQPNA_ADMIN_TOKEN | static bearer token for the gateway admin API (adminAuth.mode token/both) |
MAQPNA_CAPTURE_KEY | key URI of the argument-capture key (replay --capture-key) |
NO_COLOR | any value: no colour (https://no-color.org) |
MAQPNA_ASCII | 1: ASCII symbols (+ x ! *) instead of ✓ ✗ ! • |
Exit codes#
| Code | Meaning |
|---|
0 | success |
1 | error (the message says what failed, with a hint when there is one) |
2 | usage error: unknown flag, missing argument or bad value; the synopsis is printed |
3 | a check failed, a change is blocked, or a result did not match (tamper, policy mismatch) |