agtbox CLI

@agtbox/cli is the agent-oriented command-line and JavaScript client for encrypted, capability-based agtbox handoffs. The current public-beta version is 0.1.5; it supports Node.js 22 or newer and Bun 1.3 or newer. The package has no install lifecycle scripts.

The package is published at npmjs.com/package/@agtbox/cli. Install it inertly and exactly with npm install --ignore-scripts --save-exact @agtbox/[email protected]. Review its changelog before replacing the lockfile entry.

Live service

The public beta runs at https://agtbox.dev; its OpenAPI is the canonical machine contract. Check the troubleshooting guide before retrying an availability failure. The legal policy manifest identifies the effective policy text and digest. Send only non-secret request IDs, timestamps, and error codes to [email protected].

One box accepts one client-encrypted ciphertext from 1 byte through 10 MiB and expires after 24 hours without renewal. Creation returns independent write, read, and delete bearer capabilities; possession authorizes only that operation until deletion or expiry. Production creation costs exactly 10000 atomic canonical USDC ($0.01) through x402 v2 exact on network eip155:8453, paid only to the pinned 0xb5363EDDE479640886cf708BC596F2aED09806A8 recipient. Creation can be stopped independently while existing authorized reads and deletes remain available.

Machine contract

Every command writes exactly one JSON object plus a newline to stdout on success. Operational failures write one JSON error object to stderr and exit 1; usage failures exit 2. Recovery events are newline-delimited JSON on stderr. Keep the streams separate.

The executable is agtbox. Use agtbox --version --json to obtain package identity. Supported commands are:

agtbox identity generate --identity-file PATH
agtbox identity import --identity-file PATH
agtbox encrypt --input PATH_OR_- --recipient-file PATH --output PATH
agtbox decrypt --input PATH_OR_- --sha256 HEX --identity-file PATH --output PATH
agtbox send --endpoint HTTPS_URL --input PATH --recipient-file PATH --payer-key-file PATH --capabilities-file PATH [--idempotency-key VALUE] [--ciphertext-file PATH] [--max-price-atomic VALUE]
agtbox inspect --endpoint HTTPS_URL --box-id VALUE --read-capability-file PATH
agtbox download --endpoint HTTPS_URL --box-id VALUE --read-capability-file PATH --sha256 HEX --output PATH
agtbox receive --endpoint HTTPS_URL --box-id VALUE --read-capability-file PATH --identity-file PATH --output PATH
agtbox delete --endpoint HTTPS_URL --box-id VALUE --delete-capability-file PATH

AGTBOX_ENDPOINT, AGTBOX_IDEMPOTENCY_KEY, and AGTBOX_MAX_PRICE_ATOMIC may provide their corresponding non-secret options. Private identities, payer keys, payment authorizations, and capabilities are accepted only through protected regular files and never through command arguments or normal stdout. encrypt and decrypt accept - for stdin. Paid send requires a stable file input so an identical retry remains possible.

Output files are create-only, mode 0600, and never replace existing files or symbolic links. A paid send keeps its ciphertext and a protected adjacent payment-recovery file until the result becomes definitive. Reuse the same endpoint, input, ciphertext, idempotency key, payer, and price ceiling after an ambiguous failure; never create a second authorization for a changed request.

The JavaScript export provides the encryption, commitment, create/upload, inspect, download/verify, delete, and CLI functions. Its HTTP behavior follows the production OpenAPI contract for the same release. Retryable create failures retain the service error code and HTTP status in the CLI JSON error; reuse the same ciphertext, idempotency key, and protected payment recovery rather than creating another authorization. A contract-breaking HTTP change requires a CLI major version; additive compatible fields require a minor version, and fixes that preserve the public contract use a patch version. The client rejects non-HTTPS endpoints, cross-origin capability URLs, incompatible payment challenges, oversized responses, and ciphertext integrity mismatches.

Security

Report vulnerabilities as described in SECURITY.md. Do not paste secret files or payment/capability values into a report.

Contributing

Open a GitHub Issue for bugs or feature requests. Pull requests are not accepted; this project is maintained by its project team.

License

Source-available under the PolyForm Shield License 1.0.0. This is not an OSI-approved open-source license.