{
  "schemaVersion": "1.0",
  "title": "getaip CLI",
  "description": "getaip is the developer and operator client for native AIP, NATS, Model Context Protocol (MCP), schemas, connector qualification, connector admission, orchestration plans, and receipt verification. This reference covers all 15 command famil",
  "canonical": "https://getaip.org/docs/reference/cli",
  "route": "/docs/reference/cli",
  "source": "docs/reference/cli.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "API Reference",
  "documentType": "Reference",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/reference/cli.md",
    "txt": "/docs/download/reference/cli.txt",
    "json": "/docs/download/reference/cli.json",
    "pdf": "/docs/download/reference/cli.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: GetAIP CLI\ndescription: Look up every getaip command, option, credential source, and output contract\nkind: reference\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# `getaip` CLI\n\n`getaip` is the developer and operator client for native AIP, NATS, Model\nContext Protocol (MCP), schemas, connector qualification, connector admission,\norchestration plans, and receipt verification. This reference covers all 15\ncommand families and 49 leaf commands implemented at source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`.\n\nUse the generated `--help` output for the binary actually installed. Use this\npage to understand how its commands select transports, obtain credentials,\nvalidate files, print results, and divide authority.\n\n## Invocation\n\nInvoke an installed binary directly:\n\n```sh\ngetaip COMMAND --help\n```\n\nFrom the source repository, place CLI arguments after Cargo's `--` separator:\n\n```sh\ncargo run -p getaip-cli -- COMMAND --help\n```\n\nAll native HTTP and NATS security options are global. The command parser accepts\nthem before or after a subcommand. Examples on this page put them first so their\nscope is visible.\n\n## Command index\n\n| Family | Leaf commands | Count |\n|---|---|---:|\n| `schema` | `export` | 1 |\n| `nats` | `signer-did` | 1 |\n| `manifest` | `fetch`, `fetch-nats`, `validate` | 3 |\n| `capability` | `list` | 1 |\n| `action` | `call`, `call-nats`, `list`, `status`, `result`, `events`, `cancel` | 7 |\n| `approval` | `list`, `records`, `get`, `request`, `decide`, `list-nats`, `request-nats`, `decide-nats` | 8 |\n| `events` | `list` | 1 |\n| `session` | `list`, `get`, `close`, `resume` | 4 |\n| `transaction` | `get` | 1 |\n| `audit` | `events` | 1 |\n| `resource` | `list`, `read` | 2 |\n| `conformance` | `run` | 1 |\n| `mcp` | `inspect`, `call-tool`, `conformance`, `serve-stdio`, `bridge` | 5 |\n| `connector` | `test`, `registry-migrate`, six `registry` commands, three `orchestration` commands | 11 |\n| `receipt` | `get`, `verify` | 2 |\n| **Total** |  | **49** |\n\n## Global native HTTP options\n\n| Option | Default | Behavior |\n|---|---|---|\n| `--native-bearer-token TOKEN` | None | Adds one bearer token to native HTTP requests; conflicts with the token-file source |\n| `--native-bearer-token-file PATH` | None | Reads the bearer token from an owner-only file; conflicts with the inline source |\n| `--native-signing-seed-file PATH` | None | Signs native envelope requests with an Ed25519 key |\n| `--native-principal-id PRINCIPAL_ID` | `agent:getaip:cli` | Sets the principal carried by signed native requests |\n| `--native-trust-domain TRUST_DOMAIN` | None | Sets signed native trust-domain metadata; requires a signing seed |\n| `--native-tls-ca-file PATH` | Platform roots | Adds one PEM root certificate for private-PKI endpoints |\n| `--native-peer-did DID` | None | Pins the Ed25519 DID expected on signed native envelope responses |\n| `--native-peer-did-file PATH` | None | Reads the pinned peer DID from a public configuration file |\n| `--native-max-response-bytes BYTES` | `4194304` | Rejects a native HTTP response whose body exceeds this positive limit |\n\nThe native HTTP client does not follow redirects. When native signing is\nenabled, a peer DID is mandatory. Signed envelope responses must match that\nDID and carry a valid signature and sender binding. They must also address the\nrequest sender, preserve session and correlation context, reference the exact\nrequest, and have a timestamp within five minutes of the local clock.\n\nThese envelope checks apply to commands that send native envelopes. Ordinary\nHTTP `GET` and ergonomic `POST` commands use bearer authentication and bounded\nresponse reading; configuring a signing seed does not convert every route into\na signed-envelope exchange.\n\n## Global NATS options\n\n| Option | Default | Behavior |\n|---|---|---|\n| `--nats-username USERNAME` | None | Selects NATS username/password authentication |\n| `--nats-password-file PATH` | None | Reads the NATS password from an owner-only file |\n| `--nats-signing-seed-file PATH` | None | Signs AIP envelopes sent through NATS |\n\nThe username and password file are a pair: providing only one is an error.\nBroker authentication and AIP envelope signing are separate. A signing seed\nmust encode exactly 32 bytes as 64 hexadecimal characters.\n\nDerive the DID to register for the configured signing key without printing the\nseed:\n\n```sh\ngetaip --nats-signing-seed-file /run/secrets/getaip-nats-seed \\\n  nats signer-did\n```\n\nThe command prints a JSON object containing `did` and `principal_id`.\n\n## Environment fallbacks and precedence\n\n| Variable | Corresponding option | Precedence at this revision |\n|---|---|---|\n| `GETAIP_NATIVE_BEARER_TOKEN` | `--native-bearer-token` | Explicit inline option, then environment |\n| `GETAIP_NATIVE_BEARER_TOKEN_FILE` | `--native-bearer-token-file` | Explicit file option, then environment |\n| `GETAIP_NATIVE_SIGNING_SEED_FILE` | `--native-signing-seed-file` | Explicit option, then environment |\n| `GETAIP_NATIVE_PRINCIPAL_ID` | `--native-principal-id` | Environment, then option/default |\n| `GETAIP_NATIVE_TRUST_DOMAIN` | `--native-trust-domain` | Explicit option, then environment |\n| `GETAIP_NATIVE_TLS_CA_FILE` | `--native-tls-ca-file` | Explicit option, then environment |\n| `GETAIP_NATIVE_PEER_DID` | `--native-peer-did` | Explicit inline option, then environment |\n| `GETAIP_NATIVE_PEER_DID_FILE` | `--native-peer-did-file` | Explicit file option, then environment |\n| `GETAIP_NATIVE_MAX_RESPONSE_BYTES` | `--native-max-response-bytes` | Environment, then option/default |\n| `GETAIP_NATS_USERNAME` | `--nats-username` | Explicit option, then environment |\n| `GETAIP_NATS_PASSWORD_FILE` | `--nats-password-file` | Explicit option, then environment |\n| `GETAIP_NATS_SIGNING_SEED_FILE` | `--nats-signing-seed-file` | Explicit option, then environment |\n| `GETAIP_MCP_BEARER_TOKEN` | MCP `--bearer-token` | Explicit subcommand option, then environment |\n\nThe environment-first behavior for native principal ID and maximum response\nbytes is intentional documentation of the current code, not a general CLI\nprecedence rule. Clear those variables before trying to override them on the\ncommand line.\n\nAn inline native bearer token conflicts with any token-file source, including\none supplied through the environment. Inline and file peer-DID sources have\nthe same mutual-exclusion rule.\n\n## File inputs\n\n### JSON values\n\nAction input, identity context, approval objects, approval lifecycle messages,\nand MCP tool arguments accept either inline JSON or `@path`:\n\n```sh\ngetaip action call \"$AIP_URL\" cap:example:create --input @request.json\n```\n\n`@path` is a CLI convention, not part of the AIP wire format. The file must\ncontain one complete JSON value. Registry and orchestration commands instead\ntake explicit path options and decode the expected typed object.\n\n### Credential and trust files\n\nSecret-file readers reject symlinks, non-regular files, empty files, oversized\nfiles, and, on Unix, any group or other permissions. They strip trailing line\nendings. Public peer-DID and CA files must also be regular non-symlink files and\nmust not be group- or world-writable.\n\n| File purpose | Maximum size |\n|---|---:|\n| Native bearer token or NATS password | 16 KiB |\n| Native or NATS Ed25519 signing seed | 1 KiB |\n| Registry administrator database URL | 16 KiB |\n| Pinned native peer DID | 1 KiB |\n| Native TLS CA PEM | 1 MiB |\n\nRegistry and orchestration documents have separate bounded JSON readers. Their\nlimits range from 1 MiB for trust policies to 32 MiB for admission packages,\nobservations, and signed plans.\n\n## Native discovery and operations\n\nCommands in this section print pretty JSON on success unless the output column\nsays otherwise. `URL` is the daemon base URL.\n\n| Command syntax | Options and selectors | Result |\n|---|---|---|\n| `manifest fetch URL` | Global HTTP options | Fetches `GET /aip/v1/manifest`; prints a manifest |\n| `capability list URL` | `--capability-id`, `--text`, `--profile`, `--cursor`, `--limit`, `--signed-native` | Queries the tenant-scoped capability catalog; signed mode invokes `cap:aip:server:connector-capabilities-query` |\n| `action call URL CAPABILITY` | `--input` plus shared action options | Sends one native action envelope and prints the response envelope |\n| `action list URL` | `--state`, `--capability-id`, `--session-id`, `--principal-id`, `--approval-id`, `--transaction-id`, `--cursor`, `--limit`, `--include-results`, `--include-receipts` | Prints a durable action page |\n| `action status URL ACTION_ID` | `--include-result`, `--include-receipts`, `--include-chunks`, `--wait-ms` | Prints one action view |\n| `action result URL ACTION_ID` | `--wait-ms`, `--include-receipt`, `--include-terminal-events` | Prints the final-result view or the server's current response |\n| `action events URL ACTION_ID` | `--cursor`, `--limit`, repeatable `--kind`, `--include-chunks`, `--follow` | Prints an event page; follow mode is requested but buffered rather than emitted incrementally |\n| `action cancel URL ACTION_ID` | `--reason` | Posts a cancellation request and prints the response |\n| `events list URL` | `--cursor`, `--limit`, repeatable `--kind`, `--follow` | Reads the global event stream |\n| `session list URL` | `--principal-id`, `--status`, `--cursor`, `--limit` | Prints a session page |\n| `session get URL SESSION_ID` | None | Prints one session |\n| `session close URL SESSION_ID` | `--reason` | Closes one session and prints the response |\n| `session resume URL SESSION_ID` | `--resume-token`, `--last-event-cursor` | Submits reconnect state and prints the response |\n| `approval list URL` | `--cursor`, `--limit` default `100`, repeatable `--kind` | Reads approval lifecycle events; omitted kinds expand to the built-in approval set |\n| `approval records URL` | `--status`, `--approver`, `--requester`, `--tenant-id`, `--cursor`, `--limit`, `--include-action-status`, `--include-receipts` | Prints an approval-record page |\n| `approval get URL APPROVAL_ID` | `--include-action-status`, `--include-receipts` | Prints one approval record |\n| `approval request URL REQUEST` | Inline JSON or `@path` | Sends an `ApprovalRequest` envelope and prints the response envelope |\n| `approval decide URL DECISION` | Inline JSON or `@path` | Sends an `ApprovalDecision` envelope and prints the response envelope |\n| `transaction get URL` | Exactly one of `--transaction-id`, `--plan-id`, `--action-id`; optional `--include-result`, `--include-receipts` | Prints one transaction view |\n| `audit events URL` | `--action-id`, `--session-id`, `--principal-id`, `--transaction-id`, `--from`, `--to`, `--cursor`, `--limit`, `--include-receipts`, `--export` | Prints an audit page or authorized evidence export |\n| `resource list URL` | `--capability-id`, `--kind`, `--cursor`, `--limit` | Prints a resource page |\n| `resource read URL RESOURCE_ID` | `--version`, repeatable or comma-separated `--accept` | Prints one resource representation |\n| `receipt get URL` | Exactly one of `--chain-id` or `--receipt-id` | Prints one receipt chain |\n\n`--follow` asks the native HTTP route for SSE. At this revision the shared GET\nhelper buffers the bounded response rather than operating as a long-lived SSE\nclient. Use the [transport bindings](transport-bindings.md) and a streaming\nclient when continuous consumption is required.\n\n### Shared action options\n\nBoth HTTP and NATS action calls accept:\n\n| Option | Wire effect |\n|---|---|\n| `--action-id ACTION_ID` | Replaces the generated action ID |\n| `--idempotency-key KEY` | Sets the action idempotency key |\n| `--mode sync\\|async\\|streaming` | Sets the requested action mode |\n| `--identity JSON_OR_@FILE` | Decodes an `IdentityContext` into the action |\n| `--approval JSON_OR_@FILE` | Decodes an `ApprovalDecision` into the action |\n| `--transaction-mode MODE` | Creates the action transaction object |\n| `--transaction-id ID` | Adds a transaction ID when transaction mode is present |\n| `--plan-id ID` | Adds a plan ID when transaction mode is present |\n| `--compensation-for ACTION_ID` | Adds the compensated action when transaction mode is present |\n\nTransaction mode values are `execute`, `dry-run`, `plan`, `commit`,\n`compensate`, and `rollback-not-supported`. The core protocol also defines\n`reconcile`, but this CLI enum does not expose it. Transaction detail options\nare serialized only when `--transaction-mode` is present.\n\nThese options construct claims; they do not grant identity, approval,\ntransaction, or provider authority. The receiving deployment remains\nauthoritative.\n\n## Native NATS commands\n\nNATS commands use `SERVER_URL` plus `--trust-domain local`, `--service getaip-server`,\nand `--version v1` defaults. They use Core NATS request/reply and print the\nresponse envelope. A peer `Error` envelope makes the command fail.\n\n| Command syntax | Additional input |\n|---|---|\n| `manifest fetch-nats SERVER_URL` | Subject-routing options only |\n| `action call-nats SERVER_URL CAPABILITY` | `--input`, shared action options, subject-routing options |\n| `approval list-nats SERVER_URL` | `--cursor`, `--limit 100`, repeatable `--kind`, subject-routing options |\n| `approval request-nats SERVER_URL REQUEST` | Inline JSON or `@path`, subject-routing options |\n| `approval decide-nats SERVER_URL DECISION` | Inline JSON or `@path`, subject-routing options |\n\n## Schema, conformance, and local verification\n\n| Command syntax | Input | Success output |\n|---|---|---|\n| `schema export DIR` | Output directory | Writes every built-in schema as pretty JSON; otherwise silent |\n| `manifest validate FILE` | Manifest JSON | `manifest valid` |\n| `conformance run` | Optional `--envelope FILE` | JSON containing `name`, `passed`, and `detail` |\n| `receipt verify FILE` | Receipt-chain JSON | JSON containing `status`, `chain_id`, `receipt_count`, and recomputed `root_hash` |\n\nManifest validation applies the built-in manifest schema. Receipt verification\nchecks every previous-hash link, every receipt hash, and the chain root. Core\nconformance checks either the supplied envelope or a built-in manifest-request\nmessage body. These local checks do not prove deployment conformance or live\nprovider behavior.\n\n## MCP compatibility commands\n\nFor `inspect`, `call-tool`, and `conformance`, select exactly one client\ntransport:\n\n- `--url URL` for Streamable HTTP; the CLI preserves a URL ending in `/mcp` or\n  `/mcp/v1` and otherwise joins `/mcp`;\n- `--command PROGRAM` plus repeatable `--arg VALUE` for a stdio subprocess.\n\nMCP bearer authentication is independent of native HTTP authentication.\n\n| Command syntax | Options | Result |\n|---|---|---|\n| `mcp inspect` | Client transport and optional `--bearer-token` | Initializes the peer and prints its projected AIP manifest |\n| `mcp call-tool TOOL` | `--arguments JSON_OR_@FILE`, client transport, optional token | Initializes the peer, calls one tool, and prints the result |\n| `mcp conformance` | Client transport and optional token | Runs outbound MCP checks and prints the report |\n| `mcp serve-stdio --url URL` | Optional `--bearer-token` | Exposes the HTTP MCP endpoint as a stdio MCP server until stopped |\n| `mcp bridge --server stdio` | `--url URL`, optional token | Exposes an HTTP upstream over stdio until stopped |\n| `mcp bridge --server http` | `--command PROGRAM`, repeatable `--arg`, `--bind 127.0.0.1:18090` | Exposes a stdio subprocess over Streamable HTTP until stopped |\n\n## Connector qualification commands\n\n`connector test URL` fetches the manifest, checks every repeatable\n`--capability CAPABILITY`, and optionally invokes every repeatable\n`--invoke-capability CAPABILITY` with common `--input`. Each invocation must\nreturn the `--expect-status` value, which defaults to `completed`.\n\nThe success JSON contains `status`, the manifest agent, the full capability\nlist and count, and invoked capability statuses. This is a bounded interface\ncheck, not complete connector qualification.\n\n`connector registry-migrate` installs or verifies immutable registry\nmigrations:\n\n```sh\ngetaip connector registry-migrate \\\n  --database-url-file /run/secrets/registry-admin-url\n```\n\nIts pool defaults are four control connections, one data connection, and a\n5,000 ms acquisition timeout. All three bounds must be greater than zero. The\nsuccess JSON reports the component and installed schema version.\n\n## Connector registry commands\n\nThese are short-lived operator commands. They do not belong in a long-running\ngateway or connector-host process.\n\n| Command syntax | Required options | Result |\n|---|---|---|\n| `connector registry sign-evidence` | `--kind`, `--artifact-digest`, `--manifest-digest`, `--document`, `--signing-seed-file`, `--signer-identity`; optional `--valid-for-seconds 86400` | Prints signed release evidence |\n| `connector registry sign-package` | `--package`, `--signing-seed-file`, `--signer-identity` | Prints a signed admission package |\n| `connector registry plan` | `--package`, `--trust-policy` | Verifies without writing and prints package identity, digests, counts, and `write_performed: false` |\n| `connector registry apply` | `--package`, `--trust-policy`, database options | Applies or resumes the exact verified package and prints its durable operation |\n| `connector registry status` | `--package-id`, optional `--revision`, database options | Prints one durable admission operation; omitted revision selects the latest |\n| `connector registry revoke` | `--package-id`, `--revision`, `--reason`, database options | Stops new traffic for the applied package and prints the retained operation |\n\nEvidence kinds are `oci-signature`, `sbom`, `provenance`, `conformance`,\n`vulnerability`, `license`, and `revocation`. Evidence validity must be between\n60 seconds and 30 days. Signer identities must contain 1 to 512 bytes.\n\nDatabase options shared by `apply`, `status`, and `revoke` are\n`--database-url-file`, `--control-max-connections 2`,\n`--data-max-connections 2`, and `--acquire-timeout-ms 5000`. Each numeric bound\nmust be greater than zero.\n\n## Connector orchestration commands\n\nThe CLI derives and verifies platform-neutral operation plans. It does not\nexecute the operations on Kubernetes, Nomad, ECS, Docker, or another workload\nplatform.\n\n| Command syntax | Required options | Result |\n|---|---|---|\n| `connector orchestration plan` | `--package`, `--admission-trust-policy`, `--intent`, `--observed`, `--orchestration-policy` | Prints the next deterministic unsigned plan; performs no write |\n| `connector orchestration sign` | Plan inputs plus `--signing-seed-file` and `--signer-identity` | Re-derives, signs, verifies, and prints the exact plan |\n| `connector orchestration verify` | `--plan`, `--current-observed`, `--orchestration-policy` | Verifies signature, limits, semantics, and the fresh observation fence; prints operation IDs and `write_performed: false` |\n\nThe signing DID must be trusted by the executor policy. Verification is an\nexecutor precondition, not execution itself. See the\n[connector orchestration guide](../guides/connector-orchestration.md) for the\nexternal executor's responsibilities.\n\n## Output and exit behavior\n\nThe process returns status 0 only when the selected operation completes\nsuccessfully. Clap parsing, file decoding, local validation, transport,\nauthentication, authorization, protocol, registry, orchestration, and\nconformance failures print a diagnostic to standard error and return non-zero.\n\nMost finite commands print pretty JSON to standard output. The documented\nexceptions are schema export, the concise manifest-validation line, the compact\nregistry-migration JSON line, and long-running MCP proxies. Native ergonomic\nHTTP helpers wrap a successful non-JSON body as `{ \"body\": \"...\" }` before\nprinting it. Scripts should use exit status first and parse JSON only for a\ncommand whose output contract above is JSON.\n\n## Security boundaries\n\n- Prefer owner-only credential files over inline secret arguments.\n- Do not treat a bearer token, signed request, or NATS connection as tenant or\n  policy authority by itself.\n- Pin a peer DID when using signed native HTTP and protect the local clock used\n  by freshness checks.\n- Keep registry administrator database credentials in short-lived operator\n  commands; hosts and gateways use narrower roles.\n- Review signed admission and orchestration objects before passing them to an\n  external executor.\n- Treat command output as potentially sensitive operational evidence.\n\n## Related reference\n\n- [Environment variables](environment-variables.md)\n- [Native HTTP API](http-api.md)\n- [Connector registry and routing](../architecture/connector-registry-and-routing.md)\n- [Connector admission and supply-chain trust](../architecture/connector-admission.md)\n- [Errors](errors.md)\n",
    "text": "getaip CLI\n\ngetaip is the developer and operator client for native AIP, NATS, Model\nContext Protocol (MCP), schemas, connector qualification, connector admission,\norchestration plans, and receipt verification. This reference covers all 15\ncommand families and 49 leaf commands implemented at source revision\nd7cce13d1d555644d04a4d73c66c95b113737635.\n\nUse the generated --help output for the binary actually installed. Use this\npage to understand how its commands select transports, obtain credentials,\nvalidate files, print results, and divide authority.\n\nInvocation\n\nInvoke an installed binary directly:\n\ngetaip COMMAND --help\n\nFrom the source repository, place CLI arguments after Cargo's -- separator:\n\ncargo run -p getaip-cli -- COMMAND --help\n\nAll native HTTP and NATS security options are global. The command parser accepts\nthem before or after a subcommand. Examples on this page put them first so their\nscope is visible.\n\nCommand index\n\n| Family | Leaf commands | Count |\n\n| schema | export | 1 |\n| nats | signer-did | 1 |\n| manifest | fetch, fetch-nats, validate | 3 |\n| capability | list | 1 |\n| action | call, call-nats, list, status, result, events, cancel | 7 |\n| approval | list, records, get, request, decide, list-nats, request-nats, decide-nats | 8 |\n| events | list | 1 |\n| session | list, get, close, resume | 4 |\n| transaction | get | 1 |\n| audit | events | 1 |\n| resource | list, read | 2 |\n| conformance | run | 1 |\n| mcp | inspect, call-tool, conformance, serve-stdio, bridge | 5 |\n| connector | test, registry-migrate, six registry commands, three orchestration commands | 11 |\n| receipt | get, verify | 2 |\n| Total |  | 49 |\n\nGlobal native HTTP options\n\n| Option | Default | Behavior |\n\n| --native-bearer-token TOKEN | None | Adds one bearer token to native HTTP requests; conflicts with the token-file source |\n| --native-bearer-token-file PATH | None | Reads the bearer token from an owner-only file; conflicts with the inline source |\n| --native-signing-seed-file PATH | None | Signs native envelope requests with an Ed25519 key |\n| --native-principal-id PRINCIPALID | agent:getaip:cli | Sets the principal carried by signed native requests |\n| --native-trust-domain TRUSTDOMAIN | None | Sets signed native trust-domain metadata; requires a signing seed |\n| --native-tls-ca-file PATH | Platform roots | Adds one PEM root certificate for private-PKI endpoints |\n| --native-peer-did DID | None | Pins the Ed25519 DID expected on signed native envelope responses |\n| --native-peer-did-file PATH | None | Reads the pinned peer DID from a public configuration file |\n| --native-max-response-bytes BYTES | 4194304 | Rejects a native HTTP response whose body exceeds this positive limit |\n\nThe native HTTP client does not follow redirects. When native signing is\nenabled, a peer DID is mandatory. Signed envelope responses must match that\nDID and carry a valid signature and sender binding. They must also address the\nrequest sender, preserve session and correlation context, reference the exact\nrequest, and have a timestamp within five minutes of the local clock.\n\nThese envelope checks apply to commands that send native envelopes. Ordinary\nHTTP GET and ergonomic POST commands use bearer authentication and bounded\nresponse reading; configuring a signing seed does not convert every route into\na signed-envelope exchange.\n\nGlobal NATS options\n\n| Option | Default | Behavior |\n\n| --nats-username USERNAME | None | Selects NATS username/password authentication |\n| --nats-password-file PATH | None | Reads the NATS password from an owner-only file |\n| --nats-signing-seed-file PATH | None | Signs AIP envelopes sent through NATS |\n\nThe username and password file are a pair: providing only one is an error.\nBroker authentication and AIP envelope signing are separate. A signing seed\nmust encode exactly 32 bytes as 64 hexadecimal characters.\n\nDerive the DID to register for the configured signing key without printing the\nseed:\n\ngetaip --nats-signing-seed-file /run/secrets/getaip-nats-seed \\\n  nats signer-did\n\nThe command prints a JSON object containing did and principalid.\n\nEnvironment fallbacks and precedence\n\n| Variable | Corresponding option | Precedence at this revision |\n\n| GETAIPNATIVEBEARERTOKEN | --native-bearer-token | Explicit inline option, then environment |\n| GETAIPNATIVEBEARERTOKENFILE | --native-bearer-token-file | Explicit file option, then environment |\n| GETAIPNATIVESIGNINGSEEDFILE | --native-signing-seed-file | Explicit option, then environment |\n| GETAIPNATIVEPRINCIPALID | --native-principal-id | Environment, then option/default |\n| GETAIPNATIVETRUSTDOMAIN | --native-trust-domain | Explicit option, then environment |\n| GETAIPNATIVETLSCAFILE | --native-tls-ca-file | Explicit option, then environment |\n| GETAIPNATIVEPEERDID | --native-peer-did | Explicit inline option, then environment |\n| GETAIPNATIVEPEERDIDFILE | --native-peer-did-file | Explicit file option, then environment |\n| GETAIPNATIVEMAXRESPONSEBYTES | --native-max-response-bytes | Environment, then option/default |\n| GETAIPNATSUSERNAME | --nats-username | Explicit option, then environment |\n| GETAIPNATSPASSWORDFILE | --nats-password-file | Explicit option, then environment |\n| GETAIPNATSSIGNINGSEEDFILE | --nats-signing-seed-file | Explicit option, then environment |\n| GETAIPMCPBEARERTOKEN | MCP --bearer-token | Explicit subcommand option, then environment |\n\nThe environment-first behavior for native principal ID and maximum response\nbytes is intentional documentation of the current code, not a general CLI\nprecedence rule. Clear those variables before trying to override them on the\ncommand line.\n\nAn inline native bearer token conflicts with any token-file source, including\none supplied through the environment. Inline and file peer-DID sources have\nthe same mutual-exclusion rule.\n\nFile inputs\n\nJSON values\n\nAction input, identity context, approval objects, approval lifecycle messages,\nand MCP tool arguments accept either inline JSON or @path:\n\ngetaip action call \"$AIPURL\" cap:example:create --input @request.json\n\n@path is a CLI convention, not part of the AIP wire format. The file must\ncontain one complete JSON value. Registry and orchestration commands instead\ntake explicit path options and decode the expected typed object.\n\nCredential and trust files\n\nSecret-file readers reject symlinks, non-regular files, empty files, oversized\nfiles, and, on Unix, any group or other permissions. They strip trailing line\nendings. Public peer-DID and CA files must also be regular non-symlink files and\nmust not be group- or world-writable.\n\n| File purpose | Maximum size |\n\n| Native bearer token or NATS password | 16 KiB |\n| Native or NATS Ed25519 signing seed | 1 KiB |\n| Registry administrator database URL | 16 KiB |\n| Pinned native peer DID | 1 KiB |\n| Native TLS CA PEM | 1 MiB |\n\nRegistry and orchestration documents have separate bounded JSON readers. Their\nlimits range from 1 MiB for trust policies to 32 MiB for admission packages,\nobservations, and signed plans.\n\nNative discovery and operations\n\nCommands in this section print pretty JSON on success unless the output column\nsays otherwise. URL is the daemon base URL.\n\n| Command syntax | Options and selectors | Result |\n\n| manifest fetch URL | Global HTTP options | Fetches GET /aip/v1/manifest; prints a manifest |\n| capability list URL | --capability-id, --text, --profile, --cursor, --limit, --signed-native | Queries the tenant-scoped capability catalog; signed mode invokes cap:aip:server:connector-capabilities-query |\n| action call URL CAPABILITY | --input plus shared action options | Sends one native action envelope and prints the response envelope |\n| action list URL | --state, --capability-id, --session-id, --principal-id, --approval-id, --transaction-id, --cursor, --limit, --include-results, --include-receipts | Prints a durable action page |\n| action status URL ACTIONID | --include-result, --include-receipts, --include-chunks, --wait-ms | Prints one action view |\n| action result URL ACTIONID | --wait-ms, --include-receipt, --include-terminal-events | Prints the final-result view or the server's current response |\n| action events URL ACTIONID | --cursor, --limit, repeatable --kind, --include-chunks, --follow | Prints an event page; follow mode is requested but buffered rather than emitted incrementally |\n| action cancel URL ACTIONID | --reason | Posts a cancellation request and prints the response |\n| events list URL | --cursor, --limit, repeatable --kind, --follow | Reads the global event stream |\n| session list URL | --principal-id, --status, --cursor, --limit | Prints a session page |\n| session get URL SESSIONID | None | Prints one session |\n| session close URL SESSIONID | --reason | Closes one session and prints the response |\n| session resume URL SESSIONID | --resume-token, --last-event-cursor | Submits reconnect state and prints the response |\n| approval list URL | --cursor, --limit default 100, repeatable --kind | Reads approval lifecycle events; omitted kinds expand to the built-in approval set |\n| approval records URL | --status, --approver, --requester, --tenant-id, --cursor, --limit, --include-action-status, --include-receipts | Prints an approval-record page |\n| approval get URL APPROVALID | --include-action-status, --include-receipts | Prints one approval record |\n| approval request URL REQUEST | Inline JSON or @path | Sends an ApprovalRequest envelope and prints the response envelope |\n| approval decide URL DECISION | Inline JSON or @path | Sends an ApprovalDecision envelope and prints the response envelope |\n| transaction get URL | Exactly one of --transaction-id, --plan-id, --action-id; optional --include-result, --include-receipts | Prints one transaction view |\n| audit events URL | --action-id, --session-id, --principal-id, --transaction-id, --from, --to, --cursor, --limit, --include-receipts, --export | Prints an audit page or authorized evidence export |\n| resource list URL | --capability-id, --kind, --cursor, --limit | Prints a resource page |\n| resource read URL RESOURCEID | --version, repeatable or comma-separated --accept | Prints one resource representation |\n| receipt get URL | Exactly one of --chain-id or --receipt-id | Prints one receipt chain |\n\n--follow asks the native HTTP route for SSE. At this revision the shared GET\nhelper buffers the bounded response rather than operating as a long-lived SSE\nclient. Use the transport bindings (transport-bindings.md) and a streaming\nclient when continuous consumption is required.\n\nShared action options\n\nBoth HTTP and NATS action calls accept:\n\n| Option | Wire effect |\n\n| --action-id ACTIONID | Replaces the generated action ID |\n| --idempotency-key KEY | Sets the action idempotency key |\n| --mode sync\\|async\\|streaming | Sets the requested action mode |\n| --identity JSONOR@FILE | Decodes an IdentityContext into the action |\n| --approval JSONOR@FILE | Decodes an ApprovalDecision into the action |\n| --transaction-mode MODE | Creates the action transaction object |\n| --transaction-id ID | Adds a transaction ID when transaction mode is present |\n| --plan-id ID | Adds a plan ID when transaction mode is present |\n| --compensation-for ACTIONID | Adds the compensated action when transaction mode is present |\n\nTransaction mode values are execute, dry-run, plan, commit,\ncompensate, and rollback-not-supported. The core protocol also defines\nreconcile, but this CLI enum does not expose it. Transaction detail options\nare serialized only when --transaction-mode is present.\n\nThese options construct claims; they do not grant identity, approval,\ntransaction, or provider authority. The receiving deployment remains\nauthoritative.\n\nNative NATS commands\n\nNATS commands use SERVERURL plus --trust-domain local, --service getaip-server,\nand --version v1 defaults. They use Core NATS request/reply and print the\nresponse envelope. A peer Error envelope makes the command fail.\n\n| Command syntax | Additional input |\n\n| manifest fetch-nats SERVERURL | Subject-routing options only |\n| action call-nats SERVERURL CAPABILITY | --input, shared action options, subject-routing options |\n| approval list-nats SERVERURL | --cursor, --limit 100, repeatable --kind, subject-routing options |\n| approval request-nats SERVERURL REQUEST | Inline JSON or @path, subject-routing options |\n| approval decide-nats SERVERURL DECISION | Inline JSON or @path, subject-routing options |\n\nSchema, conformance, and local verification\n\n| Command syntax | Input | Success output |\n\n| schema export DIR | Output directory | Writes every built-in schema as pretty JSON; otherwise silent |\n| manifest validate FILE | Manifest JSON | manifest valid |\n| conformance run | Optional --envelope FILE | JSON containing name, passed, and detail |\n| receipt verify FILE | Receipt-chain JSON | JSON containing status, chainid, receiptcount, and recomputed roothash |\n\nManifest validation applies the built-in manifest schema. Receipt verification\nchecks every previous-hash link, every receipt hash, and the chain root. Core\nconformance checks either the supplied envelope or a built-in manifest-request\nmessage body. These local checks do not prove deployment conformance or live\nprovider behavior.\n\nMCP compatibility commands\n\nFor inspect, call-tool, and conformance, select exactly one client\ntransport:\n• --url URL for Streamable HTTP; the CLI preserves a URL ending in /mcp or\n  /mcp/v1 and otherwise joins /mcp;\n• --command PROGRAM plus repeatable --arg VALUE for a stdio subprocess.\n\nMCP bearer authentication is independent of native HTTP authentication.\n\n| Command syntax | Options | Result |\n\n| mcp inspect | Client transport and optional --bearer-token | Initializes the peer and prints its projected AIP manifest |\n| mcp call-tool TOOL | --arguments JSONOR@FILE, client transport, optional token | Initializes the peer, calls one tool, and prints the result |\n| mcp conformance | Client transport and optional token | Runs outbound MCP checks and prints the report |\n| mcp serve-stdio --url URL | Optional --bearer-token | Exposes the HTTP MCP endpoint as a stdio MCP server until stopped |\n| mcp bridge --server stdio | --url URL, optional token | Exposes an HTTP upstream over stdio until stopped |\n| mcp bridge --server http | --command PROGRAM, repeatable --arg, --bind 127.0.0.1:18090 | Exposes a stdio subprocess over Streamable HTTP until stopped |\n\nConnector qualification commands\n\nconnector test URL fetches the manifest, checks every repeatable\n--capability CAPABILITY, and optionally invokes every repeatable\n--invoke-capability CAPABILITY with common --input. Each invocation must\nreturn the --expect-status value, which defaults to completed.\n\nThe success JSON contains status, the manifest agent, the full capability\nlist and count, and invoked capability statuses. This is a bounded interface\ncheck, not complete connector qualification.\n\nconnector registry-migrate installs or verifies immutable registry\nmigrations:\n\ngetaip connector registry-migrate \\\n  --database-url-file /run/secrets/registry-admin-url\n\nIts pool defaults are four control connections, one data connection, and a\n5,000 ms acquisition timeout. All three bounds must be greater than zero. The\nsuccess JSON reports the component and installed schema version.\n\nConnector registry commands\n\nThese are short-lived operator commands. They do not belong in a long-running\ngateway or connector-host process.\n\n| Command syntax | Required options | Result |\n\n| connector registry sign-evidence | --kind, --artifact-digest, --manifest-digest, --document, --signing-seed-file, --signer-identity; optional --valid-for-seconds 86400 | Prints signed release evidence |\n| connector registry sign-package | --package, --signing-seed-file, --signer-identity | Prints a signed admission package |\n| connector registry plan | --package, --trust-policy | Verifies without writing and prints package identity, digests, counts, and writeperformed: false |\n| connector registry apply | --package, --trust-policy, database options | Applies or resumes the exact verified package and prints its durable operation |\n| connector registry status | --package-id, optional --revision, database options | Prints one durable admission operation; omitted revision selects the latest |\n| connector registry revoke | --package-id, --revision, --reason, database options | Stops new traffic for the applied package and prints the retained operation |\n\nEvidence kinds are oci-signature, sbom, provenance, conformance,\nvulnerability, license, and revocation. Evidence validity must be between\n60 seconds and 30 days. Signer identities must contain 1 to 512 bytes.\n\nDatabase options shared by apply, status, and revoke are\n--database-url-file, --control-max-connections 2,\n--data-max-connections 2, and --acquire-timeout-ms 5000. Each numeric bound\nmust be greater than zero.\n\nConnector orchestration commands\n\nThe CLI derives and verifies platform-neutral operation plans. It does not\nexecute the operations on Kubernetes, Nomad, ECS, Docker, or another workload\nplatform.\n\n| Command syntax | Required options | Result |\n\n| connector orchestration plan | --package, --admission-trust-policy, --intent, --observed, --orchestration-policy | Prints the next deterministic unsigned plan; performs no write |\n| connector orchestration sign | Plan inputs plus --signing-seed-file and --signer-identity | Re-derives, signs, verifies, and prints the exact plan |\n| connector orchestration verify | --plan, --current-observed, --orchestration-policy | Verifies signature, limits, semantics, and the fresh observation fence; prints operation IDs and writeperformed: false |\n\nThe signing DID must be trusted by the executor policy. Verification is an\nexecutor precondition, not execution itself. See the\nconnector orchestration guide (../guides/connector-orchestration.md) for the\nexternal executor's responsibilities.\n\nOutput and exit behavior\n\nThe process returns status 0 only when the selected operation completes\nsuccessfully. Clap parsing, file decoding, local validation, transport,\nauthentication, authorization, protocol, registry, orchestration, and\nconformance failures print a diagnostic to standard error and return non-zero.\n\nMost finite commands print pretty JSON to standard output. The documented\nexceptions are schema export, the concise manifest-validation line, the compact\nregistry-migration JSON line, and long-running MCP proxies. Native ergonomic\nHTTP helpers wrap a successful non-JSON body as { \"body\": \"...\" } before\nprinting it. Scripts should use exit status first and parse JSON only for a\ncommand whose output contract above is JSON.\n\nSecurity boundaries\n• Prefer owner-only credential files over inline secret arguments.\n• Do not treat a bearer token, signed request, or NATS connection as tenant or\n  policy authority by itself.\n• Pin a peer DID when using signed native HTTP and protect the local clock used\n  by freshness checks.\n• Keep registry administrator database credentials in short-lived operator\n  commands; hosts and gateways use narrower roles.\n• Review signed admission and orchestration objects before passing them to an\n  external executor.\n• Treat command output as potentially sensitive operational evidence.\n\nRelated reference\n• Environment variables (environment-variables.md)\n• Native HTTP API (http-api.md)\n• Connector registry and routing (../architecture/connector-registry-and-routing.md)\n• Connector admission and supply-chain trust (../architecture/connector-admission.md)\n• Errors (errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "c4387a662e08462e86b17935f5694fc86368c1319b9e7cf20645891e52f3de42"
  }
}