# `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:

```sh
aipctl --native-bearer-token TOKEN COMMAND
```

The repository command form is:

```sh
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:

```sh
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`:

```sh
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|close|resume` | Operate sessions |
| `approval list|records|get` | Read approval events or records over HTTP |
| `approval request|decide` | Submit approval lifecycle messages over HTTP |
| `approval list-nats|request-nats|decide-nats` | Use the approval lifecycle through NATS |
| `transaction get` | Read a transaction by one selector |
| `audit events` | Query or export audit evidence |
| `resource list|read` | Discover and read native resources |
| `receipt get|verify` | Fetch or verify receipt chains |
| `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`:

```sh
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|streaming` | Requested invocation mode |
| `--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](implementation-status.md).

## Useful Workflows

Discover, call, and inspect:

```sh
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:

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

Read one transaction using exactly one selector:

```sh
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.