aipctl Command Reference

aipctl is the developer and operator client for native AIP, MCP compatibility, schemas, connectors, and receipt verification.

Authentication

Pass a native HTTP bearer token globally:

aipctl --native-bearer-token TOKEN COMMAND

The repository command form is:

cargo run -p aipctl -- --native-bearer-token TOKEN COMMAND

MCP subcommands use their own --bearer-token because MCP authentication and native operational authentication are separate boundaries.

AIPCTL_NATIVE_BEARER_TOKEN and AIPCTL_MCP_BEARER_TOKEN provide process defaults. Explicit command options take precedence. Avoid placing long-lived tokens in shared shell profiles.

Native NATS uses separate broker credentials and an Ed25519 signing identity. Pass only secret-file references; do not put passwords or signing seeds in command arguments:

export AIPCTL_NATS_USERNAME=aipd
export AIPCTL_NATS_PASSWORD_FILE=/run/secrets/aipctl-nats-password
export AIPCTL_NATS_SIGNING_SEED_FILE=/run/secrets/aipctl-nats-signing-seed

The password and signing-seed files must be regular, non-symlink files with no group or other permissions. The signing-seed file contains exactly 32 bytes as 64 hexadecimal characters. Derive the public identifier without exposing the seed, then bind that DID to agent:aipctl in AIPD_TRUSTED_SIGNERS:

umask 077
openssl rand -hex 32 > /run/secrets/aipctl-nats-signing-seed
aipctl nats signer-did

Authenticated NATS does not replace AIP authentication. Production daemons also require the derived DID in their signer allowlist and agent:aipctl in the trusted identity directory. Peer Error envelopes make aipctl exit non-zero.

Command Map

Command	Purpose
schema export DIR	Export the built-in JSON Schema registry
nats signer-did	Derive the public DID for the configured NATS signing seed
manifest fetch URL	Fetch a native HTTP manifest
manifest fetch-nats URL	Fetch a manifest through NATS
manifest validate FILE	Validate a manifest file
action call URL CAPABILITY	Invoke through native HTTP
action call-nats URL CAPABILITY	Invoke through NATS
action list URL	List durable action views
action status URL ACTION_ID	Read one action
action result URL ACTION_ID	Read or briefly wait for final result
action events URL ACTION_ID	Read or follow action events
action cancel URL ACTION_ID	Request cancellation
events list URL	Read or follow the global event stream
`session list	get
`approval list	records
`approval request	decide`
`approval list-nats	request-nats
transaction get	Read a transaction by one selector
audit events	Query or export audit evidence
`resource list	read`
`receipt get	verify`
conformance run	Run native core conformance
connector test	Verify deployed connector capabilities and calls
mcp inspect	Project an MCP peer into an AIP manifest
mcp call-tool	Call an MCP tool
mcp conformance	Run outbound MCP compatibility checks
mcp serve-stdio	Expose an HTTP MCP server over stdio
mcp bridge	Bridge stdio and Streamable HTTP

Run aipctl COMMAND --help at each level for selector, pagination, and transport options. This table lists command families; it does not replace the installed binary’s generated help.

Input from Files

Commands that accept JSON allow either inline JSON or @path:

aipctl action call http://127.0.0.1:18080 cap:example:create \
  --input @request.json

File input avoids shell quoting errors and is preferable for approval, identity, and transaction objects. Protect files that contain sensitive business data even though they must not contain raw credentials.

Enterprise Action Options

action call and action call-nats accept:

Option	Meaning
--idempotency-key KEY	Stable deduplication key
`–mode sync	async
--identity JSON_OR_@FILE	Identity context claim, verified by the server
--approval JSON_OR_@FILE	Approved decision for the action
--transaction-mode MODE	Execute, dry-run, plan, commit, compensate, or rollback-not-supported
--transaction-id ID	Stable transaction id
--plan-id ID	Plan referenced by commit
--compensation-for ACTION_ID	Action being compensated

The server remains authoritative. CLI flags cannot grant identity, approval, or transaction rights.

The native protocol also defines transaction mode reconcile. The current 1.0.0 CLI value enum does not expose it; use a native envelope or the Rust SDK for explicit reconciliation. This limitation is tracked in Implementation Status.

Useful Workflows

Discover, call, and inspect:

aipctl --native-bearer-token "$AIP_TOKEN" manifest fetch "$AIP_URL"
aipctl --native-bearer-token "$AIP_TOKEN" action call "$AIP_URL" cap:aipd:health
aipctl --native-bearer-token "$AIP_TOKEN" action status "$AIP_URL" ACT_ID --include-result

Follow an async action:

aipctl --native-bearer-token "$AIP_TOKEN" action events "$AIP_URL" ACT_ID \
  --include-chunks --follow

Read one transaction using exactly one selector:

aipctl --native-bearer-token "$AIP_TOKEN" transaction get "$AIP_URL" \
  --plan-id PLAN_ID --include-result --include-receipts

Exit Behavior

Successful commands exit with status 0. Transport, validation, authorization, protocol, or conformance failures print a diagnostic to standard error and exit non-zero. Commands returning protocol records print pretty JSON. Validation-only commands may print a concise success line. Scripts should use the exit status and parse JSON only for commands whose output contract is JSON, rather than matching diagnostics.