maqpna for kubectl users

The kubectl verbs, flags and output formats in maqpna, maqpnactl and ma, for the MAQPNA resource types and the gateway's runtime records.

If you know kubectl, you know maqpna. The same verbs, the same argument forms (TYPE NAME, TYPE/NAME, TYPE1,TYPE2), the same flags (-n, -A, -l, --field-selector, -o, -w, --sort-by, --dry-run, ...) and the same output formats work on the 13 maqpna.com kinds and on the gateway's runtime records (approvals, audit records, runtime sessions, active revocations, usage).

Three names, one binary#

Name	What it is
`maqpna`	The CLI.
`maqpnactl`	The same binary under its kubectl-style name. The install scripts, the Linux packages and Homebrew link it; Scoop adds a shim.
`ma`	The short name, like kubectl's `k`. The install scripts link it only when no other `ma` is on your `PATH`; package managers never install it. Or define it (any name) as a shell function with completion: `maqpna alias install [--name ma]`.
`kubectl maqpna`	The kubectl plugin (`kubectl-maqpna`, krew).

Help and error messages use the name you typed (ma get -h shows ma get ...).

maqpna alias install            # adds ma() with tab completion to ~/.zshrc or ~/.bashrc
ma get ag -A

Resource types#

maqpna api-resources lists them. The short names are CRD short names, so kubectl get ag works too, and every kind is in the maqpna category (kubectl get maqpna, maqpna get maqpna, or maqpna get all).

Kind	Short names	CLI-only aliases
Agent	`ag`, `mqagent`
AgentSession	`as`, `sess`, `asess`	`session(s)`
AgentSessionSnapshot	`snap`, `asnap`	`snapshot(s)`
ToolPolicy	`tp`	`policy`, `policies`
MCPServer	`mcp`, `mcps`	`server(s)`
TrustTier	`tt`, `tier`	`tiers`
Tenant	`tn`
BudgetPolicy	`bp`
SovereigntyPolicy	`sp`, `sovpol`
MemoryStore	`ms`, `mem`	`store(s)`
A2APeer	`peer`, `a2ap`	`peers`
ConnectedAccount	`ca`, `conn`	`account(s)`
AgentRevocation	`arev`	`rev`, `revocation(s)` (`rev` is Knative's Revision in kubectl)
Approval (gateway)	`apr`
AuditRecord (gateway)	`audit`, `ar`
RuntimeSession (gateway)	`rsess`
ActiveRevocation (gateway)	`arv`, `killswitches`
Usage (gateway)	`costs`, `cost`

The gateway kinds (APIVERSION gateway/v1) come from the gateway admin API: pass --gateway URL (or set it in a context with maqpna login). kubectl cannot read them.

Verb by verb#

kubectl	maqpna	Notes
`get`	`maqpna get`	Columns are the CRDs' printer columns; `-o wide` adds the priority ones. `-w` uses the watch API (gateway kinds are polled).
`describe`	`maqpna describe`	Agents and sessions add tier, policies, budget, sandbox, pods, cost, taint and approvals; every kind lists the objects that use it and its events.
`create -f`	`maqpna create -f`	`create session --agent A` runs `maqpna session start`; `create snapshot S` runs `maqpna session snapshot`.
`apply`, `diff`	`maqpna apply`, `maqpna diff`	Always server-side apply; `--dry-run=client\\|server`; runs the offline `maqpna validate` checks first. `-k`: pipe `kubectl kustomize DIR` into `-f -`. `diff` exits 3 on differences.
`replace`, `patch`, `edit`	same	Custom resources take merge (the default) and JSON patches, not strategic merge. `edit` uses `$KUBE_EDITOR`, `$EDITOR`.
`delete`	`maqpna delete`	Named objects: as kubectl. `-l`, `--all` or a category: asks first, `--yes` in scripts. `--cascade`, `--grace-period`, `--now`, `--force`, `--wait`.
`label`, `annotate`	same	`KEY=VALUE`, `KEY-`, `--overwrite`, `--list`, `-l`, `--all`.
`logs`	`maqpna logs`	`SESSION`, `sess/NAME` or `ag/AGENT` (newest running session); `-f`, `--tail`, `--since`, `-c`, `-p`.
`exec`, `attach`, `cp`	same	Into the session's sandbox pod. Privileged: checked with a SelfSubjectAccessReview and recorded as a `PrivilegedAccess` Warning event on the session. `exec --governed` runs through the gateway instead (policy-checked, in the audit ledger). Need `kubectl` on `PATH`.
`port-forward`	`maqpna port-forward`	To a session (`sess/NAME`), or to `gateway` / `console`.
`top`	`maqpna top sessions\\|agents`	CPU and memory from metrics-server; model calls, tokens and cost from the gateway.
`wait`	`maqpna wait`	`--for condition=Ready`, `delete`, `create`, `jsonpath='{.status.phase}'=Running`.
`rollout status\\|history\\|restart`	same, for agents	Agents keep no revisions: `status` follows the generation and Ready, `history` shows the current generation, `restart` restarts the sandbox pods of the agent's running sessions (asks first). `undo`, `pause`, `resume` do not apply.
`scale`	`maqpna scale tt/NAME --replicas N`	A trust tier's warm pool is the only replica count.
`events`	`maqpna events`	MAQPNA objects' events; `--for TYPE/NAME`; `-w`; `--audit` merges the gateway's audit records.
`explain`	`maqpna explain`	From the CRD schemas built into the CLI (no cluster needed); `--recursive`.
`api-resources`, `api-versions`	same	From the built-in CRDs plus the gateway kinds.
`auth can-i`, `auth whoami`	same	`can-i` takes MAQPNA short names (`can-i create sess`); `whoami` adds the gateway's view of your login.
`config get-contexts\\|use-context\\|current-context\\|set-context\\|view`	same	Map onto `maqpna context` (MAQPNA contexts: gateway, kube context, namespace).
`cluster-info`	same	API server, gateway, identity, attest, operator: URL, version, health. `cluster-info dump` is `maqpna support-bundle`.
`version`	`maqpna version`	`maqpna version --check` compares every component and enforces the skew policy.
`completion`	same	bash, zsh, fish, PowerShell; completes types, names and namespaces from the cluster.
`plugin list`	same	Executables `maqpna-NAME` on `PATH` run as `maqpna NAME`.
`proxy`, `debug`, `run`, `expose`, `set`, `taint`, `cordon`, `drain`, `certificate`, `kustomize`	none	Not about MAQPNA objects: use kubectl.

Flags and output#

Flag	Where
`-n`, `--namespace`, `-A`, `--all-namespaces`	Every verb that reads namespaced objects.
`--context`, `--kubeconfig`	Global (before or after the verb). `--context` names a MAQPNA context, which holds the kube context.
`-o json\\|yaml\\|wide\\|name\\|jsonpath=\\|jsonpath-file=\\|go-template=\\|go-template-file=\\|custom-columns=\\|custom-columns-file=`	Global: every command that prints data, not only `get`. `--jq` filters JSON too.
`-l`, `--field-selector`, `--sort-by`, `--show-labels`, `-L`, `--no-headers`, `--show-kind`, `--ignore-not-found`	`get`; `-l`/`--field-selector` also on `describe`, `delete`, `label`, `annotate`, `wait`, `top`. Field selectors work on any field and on the gateway kinds (the CLI evaluates them).
`-w`, `--watch`, `--watch-only`	`get`, `events`.
`-f` (files, directories, URLs, `-`), `-R`	`apply`, `diff`, `create`, `replace`, `delete`, `label`, `annotate`, `wait`.
`--dry-run=none\\|client\\|server`	`apply`, `create`, `replace`, `delete`, `patch`, `label`, `annotate`, `scale`.
`--server-side`	`apply` (always on).
`--force`, `--grace-period`, `--cascade`	`delete` (`--force` also on `replace`).
`-v=N`	Global: `-v=6` logs every Kubernetes and gateway request.

Examples#

ma get sess -A --field-selector status.phase=Running --sort-by .metadata.creationTimestamp
ma get ag coder -n team-a -o jsonpath='{.spec.tier}'
ma get approvals --field-selector status=pending -o custom-columns=ID:.id,TOOL:.tool -w
ma describe tt gvisor
ma logs ag/coder -n team-a -f
ma wait --for condition=Ready ag/coder -n team-a --timeout 2m
ma auth can-i create pods/exec -n team-a
ma top sessions -n team-a --sort-by cost