Repository CLI reference

Run the CLI from the repository root as bun run cli -- …. Public @agtbox/cli publication is separately gated, so this guide documents the implemented checkout command interface without claiming package availability or public paid writes.

Output contract

• Success: exit 0; one JSON object followed by a newline on stdout.
• Failure: exit 1; {"error":{"code":"cli_error","message":"…"}} on stderr.
• Recovery events: newline-delimited JSON on stderr. Keep stderr separate from stdout.
• Secrets: identity, payer key, and capability values are read from or written to files, not process arguments or normal stdout.

Identity commands

bun run cli -- identity generate --identity-file "./identity.txt"
bun run cli -- identity import --identity-file "./identity.txt"

generate writes a new age-compatible X25519 identity with mode 0600 and returns its public recipient key. import derives the public key from an existing identity. Neither command prints the private identity.

Local encryption commands

bun run cli -- encrypt \
  --input "./artifact.bin" \
  --recipient-file "./recipient-public.txt" \
  --output "./artifact.age"

bun run cli -- decrypt \
  --input "./artifact.age" \
  --sha256 "$EXPECTED_CIPHERTEXT_SHA256" \
  --identity-file "./identity.txt" \
  --output "./artifact.bin"

encrypt returns ciphertextSize and ciphertextSha256. decrypt verifies the exact ciphertext digest before local decryption.

Paid send

bun run cli -- send \
  --endpoint "https://agentbox.link" \
  --input "./artifact.bin" \
  --recipient-file "./recipient-public.txt" \
  --payer-key-file "./payer-key.txt" \
  --capabilities-file "./box-capabilities.json" \
  --idempotency-key "$IDEMPOTENCY_KEY" \
  --ciphertext-file "./artifact.age" \
  --max-price-atomic "10000"

send requires the HTTPS endpoint, plaintext input, recipient public-key file, payer private-key file, and a new capabilities-file path. Supplying an idempotency key, ciphertext file, and explicit maximum price makes recovery deterministic. Do not fund or send until an approved release pins the production tuple and payee; public paid writes remain separately gated.

The durable payment tuple is x402 v2 exact, Base Mainnet eip155:8453, canonical Base USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, and amount 10000 atomic units. The production payee is a release-pinned value; it must not be learned from an untrusted challenge alone. Public production availability and that payee are not announced by these docs.

On success, send contains boxId, createdAt, expiresAt, capabilitiesFile, and idempotencyKey. The protected capabilities file contains the upload, download, and delete URLs and bearer capabilities.

Inspect, download, and receive

bun run cli -- inspect \
  --endpoint "https://agentbox.link" \
  --box-id "$BOX_ID" \
  --read-capability-file "./read-capability.txt"

bun run cli -- download \
  --endpoint "https://agentbox.link" \
  --box-id "$BOX_ID" \
  --read-capability-file "./read-capability.txt" \
  --sha256 "$EXPECTED_CIPHERTEXT_SHA256" \
  --output "./artifact.age"

bun run cli -- receive \
  --endpoint "https://agentbox.link" \
  --box-id "$BOX_ID" \
  --read-capability-file "./read-capability.txt" \
  --identity-file "./identity.txt" \
  --output "./artifact.bin"

inspect returns ciphertextSha256, ciphertextSize, createdAt, and expiresAt. download verifies a caller-supplied digest and writes ciphertext. receive obtains the trusted digest and size with HEAD, downloads and verifies the exact bytes, then decrypts locally.

Delete

bun run cli -- delete \
  --endpoint "https://agentbox.link" \
  --box-id "$BOX_ID" \
  --delete-capability-file "./delete-capability.txt"

On success, delete returns {"deleted":true}. Keep the delete capability separate from the recipient handoff.

Retries and recovery

For a retry, keep all of these identical: endpoint origin, input bytes, encrypted ciphertext bytes, idempotency key, payer, and price policy.

If --idempotency-key is omitted, the CLI emits an idempotency_key event to stderr before the network request. Record it and reuse it. The generated ciphertext filename includes that key. Once a payment authorization is produced, the CLI writes an adjacent protected *.payment.json file so an ambiguous timeout can retry the same signed authorization instead of signing another payment.

Do not edit recovery files. A retry fails if endpoint, idempotency key, or ciphertext digest differs. Definitively rejected payment data is removed; ambiguous payment data is retained. An identical paid retry converges on the existing box, while changed input with the same key fails with idempotency_conflict.

Capacity reclamation responses marked retryable are retried within the client’s bounded budget. Other HTTP failures surface as errors so the caller can inspect service state before deciding whether another identical retry is safe.