getaip CLI

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 families and 49 leaf commands implemented at source revision d7cce13d1d555644d04a4d73c66c95b113737635.

Use the generated --help output for the binary actually installed. Use this page to understand how its commands select transports, obtain credentials, validate files, print results, and divide authority.

Invocation

Invoke an installed binary directly:

getaip COMMAND --help

From the source repository, place CLI arguments after Cargo’s -- separator:

cargo run -p getaip-cli -- COMMAND --help

All native HTTP and NATS security options are global. The command parser accepts them before or after a subcommand. Examples on this page put them first so their scope is visible.

Command index

Global native HTTP options

The native HTTP client does not follow redirects. When native signing is enabled, a peer DID is mandatory. Signed envelope responses must match that DID and carry a valid signature and sender binding. They must also address the request sender, preserve session and correlation context, reference the exact request, and have a timestamp within five minutes of the local clock.

These envelope checks apply to commands that send native envelopes. Ordinary HTTP GET and ergonomic POST commands use bearer authentication and bounded response reading; configuring a signing seed does not convert every route into a signed-envelope exchange.

Global NATS options

The username and password file are a pair: providing only one is an error. Broker authentication and AIP envelope signing are separate. A signing seed must encode exactly 32 bytes as 64 hexadecimal characters.

Derive the DID to register for the configured signing key without printing the seed:

getaip --nats-signing-seed-file /run/secrets/getaip-nats-seed \
  nats signer-did

The command prints a JSON object containing did and principal_id.

Environment fallbacks and precedence

The environment-first behavior for native principal ID and maximum response bytes is intentional documentation of the current code, not a general CLI precedence rule. Clear those variables before trying to override them on the command line.

An inline native bearer token conflicts with any token-file source, including one supplied through the environment. Inline and file peer-DID sources have the same mutual-exclusion rule.

File inputs

JSON values

Action input, identity context, approval objects, approval lifecycle messages, and MCP tool arguments accept either inline JSON or @path:

getaip action call "$AIP_URL" cap:example:create --input @request.json

@path is a CLI convention, not part of the AIP wire format. The file must contain one complete JSON value. Registry and orchestration commands instead take explicit path options and decode the expected typed object.

Credential and trust files

Secret-file readers reject symlinks, non-regular files, empty files, oversized files, and, on Unix, any group or other permissions. They strip trailing line endings. Public peer-DID and CA files must also be regular non-symlink files and must not be group- or world-writable.

Registry and orchestration documents have separate bounded JSON readers. Their limits range from 1 MiB for trust policies to 32 MiB for admission packages, observations, and signed plans.

Native discovery and operations

Commands in this section print pretty JSON on success unless the output column says otherwise. URL is the daemon base URL.

--follow asks the native HTTP route for SSE. At this revision the shared GET helper buffers the bounded response rather than operating as a long-lived SSE client. Use the transport bindings and a streaming client when continuous consumption is required.

Shared action options

Both HTTP and NATS action calls accept:

Transaction mode values are execute, dry-run, plan, commit, compensate, and rollback-not-supported. The core protocol also defines reconcile, but this CLI enum does not expose it. Transaction detail options are serialized only when --transaction-mode is present.

These options construct claims; they do not grant identity, approval, transaction, or provider authority. The receiving deployment remains authoritative.

Native NATS commands

NATS commands use SERVER_URL plus --trust-domain local, --service getaip-server, and --version v1 defaults. They use Core NATS request/reply and print the response envelope. A peer Error envelope makes the command fail.

Schema, conformance, and local verification

Manifest validation applies the built-in manifest schema. Receipt verification checks every previous-hash link, every receipt hash, and the chain root. Core conformance checks either the supplied envelope or a built-in manifest-request message body. These local checks do not prove deployment conformance or live provider behavior.

MCP compatibility commands

For inspect, call-tool, and conformance, select exactly one client transport:

• --url URL for Streamable HTTP; the CLI preserves a URL ending in /mcp or /mcp/v1 and otherwise joins /mcp;
• --command PROGRAM plus repeatable --arg VALUE for a stdio subprocess.

MCP bearer authentication is independent of native HTTP authentication.

Connector qualification commands

connector test URL fetches the manifest, checks every repeatable --capability CAPABILITY, and optionally invokes every repeatable --invoke-capability CAPABILITY with common --input. Each invocation must return the --expect-status value, which defaults to completed.

The success JSON contains status, the manifest agent, the full capability list and count, and invoked capability statuses. This is a bounded interface check, not complete connector qualification.

connector registry-migrate installs or verifies immutable registry migrations:

getaip connector registry-migrate \
  --database-url-file /run/secrets/registry-admin-url

Its pool defaults are four control connections, one data connection, and a 5,000 ms acquisition timeout. All three bounds must be greater than zero. The success JSON reports the component and installed schema version.

Connector registry commands

These are short-lived operator commands. They do not belong in a long-running gateway or connector-host process.

Evidence kinds are oci-signature, sbom, provenance, conformance, vulnerability, license, and revocation. Evidence validity must be between 60 seconds and 30 days. Signer identities must contain 1 to 512 bytes.

Database options shared by apply, status, and revoke are --database-url-file, --control-max-connections 2, --data-max-connections 2, and --acquire-timeout-ms 5000. Each numeric bound must be greater than zero.

Connector orchestration commands

The CLI derives and verifies platform-neutral operation plans. It does not execute the operations on Kubernetes, Nomad, ECS, Docker, or another workload platform.

The signing DID must be trusted by the executor policy. Verification is an executor precondition, not execution itself. See the connector orchestration guide for the external executor’s responsibilities.

Output and exit behavior

The process returns status 0 only when the selected operation completes successfully. Clap parsing, file decoding, local validation, transport, authentication, authorization, protocol, registry, orchestration, and conformance failures print a diagnostic to standard error and return non-zero.

Most finite commands print pretty JSON to standard output. The documented exceptions are schema export, the concise manifest-validation line, the compact registry-migration JSON line, and long-running MCP proxies. Native ergonomic HTTP helpers wrap a successful non-JSON body as { "body": "..." } before printing it. Scripts should use exit status first and parse JSON only for a command whose output contract above is JSON.

Security boundaries

• Prefer owner-only credential files over inline secret arguments.
• Do not treat a bearer token, signed request, or NATS connection as tenant or policy authority by itself.
• Pin a peer DID when using signed native HTTP and protect the local clock used by freshness checks.
• Keep registry administrator database credentials in short-lived operator commands; hosts and gateways use narrower roles.
• Review signed admission and orchestration objects before passing them to an external executor.
• Treat command output as potentially sensitive operational evidence.

Related reference

• Environment variables
• Native HTTP API
• Connector registry and routing
• Connector admission and supply-chain trust
• Errors