Command line (npx agentboxd)

The agentboxd npm package includes a command line. It uses the same API key and sees the same inboxes as the SDKs and the MCP server, prints tables for people and JSON for scripts, and needs nothing but Node.js 20 or newer.

npx agentboxd login                        # paste your key at the hidden prompt
npx agentboxd inboxes create --username support-agent --client-id support-agent
npx agentboxd send support-agent@agents.agentboxd.com \
  --to someone@example.com --subject "Hello" --text "Reply to this and my agent will see it."
npx agentboxd messages list support-agent@agents.agentboxd.com --unread

#Install and log in

Run it with npx agentboxd … without installing, or install it once with npm install -g agentboxd. Then log in with a key from API keys:

npx agentboxd login              # prompts for the key without echoing it
echo "$KEY" | npx agentboxd login   # or pipe it (CI, scripts)
npx agentboxd whoami             # workspace, plan and where the key came from

• login checks the key against the API and saves it in ~/.config/agentboxd/config.json ($XDG_CONFIG_HOME if set) on macOS and Linux, or %APPDATA%\agentboxd\config.json on Windows. The file is readable by your user only (mode 0600). logout deletes it.
• AGENTBOXD_API_KEY in the environment always wins over the saved key, so CI and agents never need login.
• The key is never taken as a command-line flag, so it doesn’t end up in your shell history.
• API keys are created and revoked in the dashboard, not from the command line.

#Commands

<inbox> is an inbox id or its address. Every command takes --json (print the API response) and --base-url; npx agentboxd <command> --help shows its options.

#Scripts and sign-up codes

wait-code prints just the code (or the link when there is no code) on stdout and the details on stderr, so it drops into a shell variable. Take the time before you trigger the email and pass it as --since; a duration such as --since 5m works too. It waits up to --timeout seconds and exits with status 3 if nothing arrived.

inbox=$(npx agentboxd inboxes create --temporary --ttl 900 --json | jq -r .id)
since=$(date -u +%Y-%m-%dT%H:%M:%SZ)
# … submit the sign-up form with the inbox's address …
code=$(npx agentboxd wait-code "$inbox" --since "$since" --from acme.com --timeout 120) || exit 1
echo "code: $code"

With --json every command prints the API’s response unchanged (the same objects as the API reference), and errors as { "error": { "status", "code", "message", "details" } }.

#Watch events live

tail opens the realtime stream with a single-use token, reconnects on its own and resumes where it left off. --json prints one event per line, ready for jq. It needs Node.js 22 or newer, or the ws package installed next to it.

npx agentboxd tail --inbox support-agent@agents.agentboxd.com --event message.received
2026-09-26 10:04  message.received        Dana <dana@example.com>  Opening hours  7c1e…

npx agentboxd tail --json | jq -c 'select(.type == "message.bounced")'

#For agents

Coding agents with a shell (Claude Code, Codex, Cursor and others) can use the CLI directly: give them AGENTBOXD_API_KEY and they can create an inbox, read a code with wait-code and answer mail. messages get starts the email text with an UNTRUSTED EMAIL CONTENT line and shows a warning: line for mail that failed authentication or looks like phishing or prompt injection, like the MCP server does. The agent skill teaches them when to use which command.

#Other servers

Point the CLI at a dedicated deployment or a local development server with --base-url http://localhost:3000 or AGENTBOXD_BASE_URL. login --base-url … saves the URL with the key. The order is: --base-url, then AGENTBOXD_BASE_URL, then the saved URL, then https://api.agentboxd.com.