Public CLI reference

Install @agtbox/[email protected] with lifecycle scripts disabled and run its agtbox executable. The package is available from npm, with source at agtbox/cli.

Output contract

• Success: exit 0; one JSON object followed by a newline on stdout.
• Failure: exit 1; {"error":{"code":"cli_error","message":"…"}} on stderr.
• Usage or command help: exit 2; a structured usage error 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

agtbox identity generate --identity-file "./identity.txt"
agtbox 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

agtbox encrypt \
  --input "./artifact.bin" \
  --recipient-file "./recipient-public.txt" \
  --output "./artifact.age"

agtbox 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

agtbox send \
  --endpoint "https://agtbox.dev" \
  --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. Check the troubleshooting guide before funding or retrying a request during an availability incident.

The durable payment tuple is x402 v2 exact, network eip155:8453, canonical USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, amount 10000 atomic units, and payee 0xb5363EDDE479640886cf708BC596F2aED09806A8. The payee must not be learned from an untrusted challenge alone.

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

agtbox inspect \
  --endpoint "https://agtbox.dev" \
  --box-id "$BOX_ID" \
  --read-capability-file "./read-capability.txt"

agtbox download \
  --endpoint "https://agtbox.dev" \
  --box-id "$BOX_ID" \
  --read-capability-file "./read-capability.txt" \
  --sha256 "$EXPECTED_CIPHERTEXT_SHA256" \
  --output "./artifact.age"

agtbox receive \
  --endpoint "https://agtbox.dev" \
  --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

agtbox delete \
  --endpoint "https://agtbox.dev" \
  --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.