CLI Reference
This reference provides a comprehensive overview of the Cairn CLI command hierarchy, global flags, and system exit codes. It is designed for autonomous agent instrumentation, CI/CD pipes, and low-latency settlement workflows.
Global Flags
These flags can be applied to any command to override local configuration or environment variables.
| Flag | Env Var | Description |
|---|---|---|
--api-url | BACKPAC_API_URL | Base URL for the Backpac Identity/Admin API. |
--worker-url | BACKPAC_WORKER_URL | Base URL for RPC and Intent submission workers. |
--chain | CAIRN_CHAIN | Blockchain family (e.g., ethereum, solana). |
--network | CAIRN_NETWORK | Network within the chain (e.g., mainnet, sepolia, devnet). |
--jwt | BACKPAC_JWT | Bearer token to bypass saved credentials. |
--output | CAIRN_OUTPUT | Output format: json (default) or text (key=value). |
--quiet, -q | None | Suppress all stdout (exit code only). |
Command Categories
auth
Agent authentication and session management using EIP-4361 patterns.
| Command | Arguments | Description |
|---|---|---|
auth challenge | --wallet, --ows, --did, [--chain] | Request a cryptographic challenge for signing. |
auth connect | --wallet, --ows, --did, --nonce, [--signature], [--key-file] | Submit signature to receive a JWT. Auto-signs if --key-file or --ows provided. |
auth refresh | None | Mints a new JWT using the current session. |
auth status | None | Verify token health and expiry. |
balance
Query native token balances across one or multiple wallets.
| Command | Arguments | Description |
|---|---|---|
balance | [--address] | Check balance for a specific address or all OWS wallets. |
wallet (OWS)
Secure OpenWallet Standard (OWS) key management for agents.
| Command | Arguments | Description |
|---|---|---|
wallet create | --name, [--length], [--passphrase] | Generate a new encrypted OWS wallet. |
wallet list | None | List all locally configured OWS profiles. |
wallet delete | --name | Permanently remove a wallet profile. |
identity
Manage DID-anchored agent identities.
| Command | Arguments | Description |
|---|---|---|
identity register | --did, --wallet, --public-key, [--display-name] | Anchor a DID to a wallet. |
identity rotate | --did, --current-key, --new-key | Rotate Ed25519 signing keys. |
identity get | <did> | Look up state for a registered DID. |
poi (Proof of Intent)
Lifecycle management for structured settlement sessions.
| Command | Arguments | Description |
|---|---|---|
poi create | [--parent], [--max-depth], [--ttl], [--metadata], [--key-file] | Initialize a new signed PoI tracking record. |
poi get | <poi_id> | Retrieve PoI state. |
poi list | [--status], [--since], [--limit] | Filter authenticated agent's PoI history. |
intent
Dispatch and track individual execution intents.
| Command | Arguments | Description |
|---|---|---|
intent send | --method, [--params], [--params-file], [--poi-id], [--confidence] | Submit JSON-RPC payload as an intent. |
intent status | <intent_id> | Check state of a specific intent. |
intent wait | <intent_id>, [--interval], [--timeout] | Block until intent reaches a terminal state. |
intent history | <intent_id>, [--limit], [--status] | View state transition audit log. |
intent list | [--status], [--since], [--limit] | List agent's execution history. |
intent verify | <intent_id>, [--receiver-did], [--min-confidence] | Verify PoI and payment context for a receiver. |
proof (PoT)
Cryptographic verification of transaction finality.
| Command | Arguments | Description |
|---|---|---|
proof get | <id>, [--include-telemetry], [--verify-signature], [--raw] | Fetch PoT bundle for an Intent or PoI. |
proof verify | <id> | Perform local Ed25519 integrity check via JWKS. |
rpc
Direct protocol-level JSON-RPC operations (no intent wrapping).
| Command | Arguments | Description |
|---|---|---|
rpc health | None | Check worker connectivity and chain ID. |
rpc nonce | [--address] | Get the next valid transaction nonce. |
rpc quote | None | Request a gas/fee estimate from the network. |
policy
Administer Agentic Guardrails and Execution Policies locally.
| Command | Arguments | Description |
|---|---|---|
policy add | --file | Load an OWS policy from a JSON definition. |
policy list | None | List currently active guardrails. |
policy delete | --id | Remove a specific policy enforcement. |
Exit Codes
| Code | Condition / Meaning | HTTP Mapping |
|---|---|---|
0 | Success | 200, 201, 204 |
1 | General Error (IO, Serialization) | 500 |
2 | Value Mismatch | Intent context validation fail |
3 | Not Finalized | Terminal state required |
4 | Forbidden / Unauthorized | 401 / 403 |
5 | Not Found | 404 |
10 | Operation Timeout | Wait duration exceeded |
11 | Signature Error | Cryptographic match failure |
13 | Network Error | Unreachable endpoint |
16 | Insufficient Funds / x402 | 402 Payment Required |