Cairn CLI

Cairn (cairn) is Backpac's agent-native command-line tool, built in Rust for autonomous settlement workflows within the Agentic Economy.

Designed to be lightweight, deterministic, and machine-readable, Cairn serves as the primary gateway for AI Agents to interact with the Backpac Settlement Layer.

Core Principles

• Agent-Native: Outputs are heavily structured (JSON by default), making it trivial for agents to instrument.
• Deterministic: Exactly 16 exit codes map HTTP responses to system boundaries.
• Native OpenWallet Standard (OWS): Integrated OWS support directly into the CLI. Effortlessly manage storage, encryption, and signatures for multiple disparate wallets natively, bypassing third-party wallet applications.
• Stateless Operation: Employs Ed25519 DID signatures and EIP-4361 standard auth, storing only minimal session configurations locally.
• Agent Policy Engine: Locally govern, gate, and simulate transaction execution bounds via programmable Agentic Guardrails (the policy command).
• Real-Time Visibility: Natively supports SSE streams for live intent tracking and agent notifications.
• Built for Scale: A single static binary with no runtime dependencies.

Installation

Cairn is distributed via multiple package managers and as a pre-compiled binary for maximum cross-platform compatibility.

1. Via Cargo (Rust Package Manager)

If you have Rust installed, you can install Cairn directly from crates.io:

cargo install cairn-cli

2. Via Homebrew (macOS / Linux)

Add the Backpac tap and install the CLI:

brew tap backpac-inc/cairn
brew install cairn-cli

3. Pre-compiled Binaries

Download the latest static binary for your operating system from the official releases.

Quick Start

1. Configure the Environment

Set up your execution chain and network environments.

cairn config set chain solana
cairn config set network mainnet

2. Initialize a Named Wallet (OWS)

Cairn natively supports the OpenWallet Standard. Before authenticating, create a named wallet profile. This name (--name) is used to resolve the wallet and perform cryptographic signatures during the challenge response.

cairn wallet create --name Agent1 --length 12

3. Login via Wallet (EIP-4361)

Agents connect their wallet identities using Sign-in with Ethereum (EIP-4361), tying a decentralized identifier (DID) to a concrete financial actor.

You can authenticate explicitly using the --wallet flag, or automatically resolve your identity using a named OWS profile via --ows:

# Option A: Explicit Wallet Address
NONCE=$(cairn auth challenge \
  --wallet 0xAGENT_WALLET \
  --chain eip155:1 \
  --did did:key:z6MkAGENT | jq -r .nonce)

cairn auth connect \
  --wallet 0xAGENT_WALLET \
  --chain eip155:1 \
  --did did:key:z6MkAGENT \
  --nonce $NONCE \
  --key-file ~/.backpac/agent_key.pem

# Option B: Native OWS Resolution (recommended)
NONCE=$(cairn auth challenge \
  --ows Agent1 \
  --chain eip155:1 \
  --did did:key:z6MkAGENT | jq -r .nonce)

cairn auth connect \
  --ows Agent1 \
  --chain eip155:1 \
  --did did:key:z6MkAGENT \
  --nonce $NONCE

Your successful login JWT is securely encrypted and stored at ~/.backpac/credentials.json.

Credential Encryption

Because Cairn handles sensitive authentication data, it requires an encryption key for local storage. This encryption key is derived using a multi-stage fallback strategy:

1. Environment Variable (CAIRN_STORAGE_KEY): Useful for CI/CD environments.
2. Interactive TTY Prompt: By default, Cairn will interactively prompt for a secure passphrase.
3. Machine UID Fallback: If CAIRN_NON_INTERACTIVE=1 is set, or if running headless, Cairn will derive a deterministic fallback key based on the host machine's unique hardware signature.

3. Check Balance via OWS

Ensure your agent has sufficient funds across its wallets. The built-in OWS abstraction lets you securely track network balances natively across any chain.

cairn balance

4. Create Proof of Intent (PoI)

Before broadcasting a transaction, generate a tracking ID (PoI) that binds the impending on-chain intent to off-chain business logic.

cairn poi create --ttl 600 > poi.json

5. Send the Execution Intent

Send the raw RPC payload wrapped inside the Intent context.

cairn intent send \
  --method eth_sendRawTransaction \
  --params '["0x..."]' \
  --poi-id $(jq -r .id poi.json)

6. Watch & Verify Cryptographic Proof

Wait for Backpac to finalize the transaction, stream its progress, then verify the cryptographic Proof of Transport (PoT) locally using the issuer's Ed25519 JWKS.

# Block execution until resolution
cairn intent wait <INTENT_ID> --timeout 60

# Or stream live status updates via SSE
cairn watch intent <INTENT_ID>

# And verify cryptographically
cairn proof verify <INTENT_ID>

7. Automated Payments (x402)

The Cairn CLI automatically detects HTTP 402 Payment Required L402 challenges when your SLA volume is depleted. Set the CAIRN_AUTO_PAY=1 environment variable to instruct the CLI to automatically intercept the challenge, perform an EIP-712 wallet signature, and replay the transaction seamlessly.

For more details on cryptographic proofs, see Proof of Intents.