catchotp CLI

Ephemeral inboxes for OTP, magic-link, and verification-link testing.

Install

npm / pnpm / yarn / bun

npm install -g catchotp
# or any compatible package manager
pnpm add -g catchotp
yarn global add catchotp
bun add -g catchotp

Homebrew (macOS, Linux)

brew install dvirben123/catchotp/catchotp

Docker (CI)

docker run --rm ghcr.io/dvirben123/catchotp:latest --help
# Pin to a release tag in CI (replaces :latest with e.g. :0.1.0-alpha.1)

Quick start

catchotp auth login --api-key tki_live_xxx
catchotp inbox create --ttl-seconds 600 --label demo
catchotp inbox list
catchotp inbox list --status active --limit 10 --json
catchotp inbox get inb_01HZABC...
catchotp inbox delete inb_01HZABC...
catchotp message list inb_01HZABC... --limit 20
catchotp message get inb_01HZABC... msg_01HZDEF...
catchotp message raw inb_01HZABC... msg_01HZDEF...
catchotp auth whoami
catchotp auth logout

--json is supported on inbox create/get/list and message list/get for scripting. Output fields are camelCase (inboxId, address, ttlSeconds, expiresAt, …) and match the API spec exactly. message raw streams the original RFC 5322 message bytes to stdout.

Configuration

Credentials are stored at ~/.config/catchotp/config.json with 0600 perms (respects $XDG_CONFIG_HOME). Env vars override the file:

| Variable | Purpose | | ----------------------- | ------------------------------------------------ | | CATCHOTP_API_KEY | Use this key instead of the one in the file. | | CATCHOTP_API_URL | Point at a non-default API (mock, staging, etc.) | | CATCHOTP_CONFIG_PATH | Override the config file location. |

Status

Implemented: auth login/logout/whoami, inbox create/list/get/delete, message list/get/raw. Remaining subcommands (wait, webhook) exit with code 2 and reference the Phase 1 task ID that unblocks them — tracked in docs/engineering/tasks.md.

Error format

catchotp surfaces nested error envelopes from the API as a single line on stderr, exit code 1:

catchotp: API error 400 validation_error: ttlSeconds must be between 60 and 2592000 (requestId=req_abc123)

Pass --json for scripted parsing of successful responses.

Development

pnpm install                        # repo root
pnpm --filter catchotp build
pnpm --filter catchotp test         # unit tests (node --test)
node packages/cli/dist/index.js --version

For an end-to-end loop against the real API with no AWS requirements, follow the in-memory smoke-test recipe in packages/api/README.md.

Using with AI agents

catchotp is built to be agent-native. Every command supports --json, the wait subcommand long-polls server-side (no polling loops in your agent), and the --extract otp / --extract magic-link flags return just the token on stdout — no regex on your side.

Drop-in resources:

• Claude Code — install the Anthropic Skill into ~/.claude/skills/catchotp/
• Cursor — copy the Cursor rule into your project's .cursor/rules/
• OpenAI Agents SDK / LangChain / CrewAI / browser agents — see the agent cookbook
• Generic LLMs with web access — point them at https://catchotp.com/llms.txt

License

Apache License 2.0. See LICENSE and NOTICE.

Issues & feedback

Bug reports and feature requests: https://github.com/dvirben123/catchotp/issues. Security disclosures: see the project SECURITY.md.