The command-line interface for ReplyLayer — safe email for AI agents. Send, receive, reply to, and security-scan transactional and operational email from the terminal or from an agent loop. Not a bulk or marketing tool.

Command names: rly and replylayer (identical) — examples below use the shorter rly. Version 0.7.5.

Install

npm install -g rly               # Node.js 22+; commands: rly, replylayer
# or
pipx install rly                 # bundled native launcher, no Node toolchain needed

Both packages expose both the rly and replylayer commands (same CLI).

One name, every registry. The package is rly on npm and on PyPI — npm install -g rly or pipx install rly. (This package was previously published on npm as replylayer; that name is deprecated — don't install it.)

Quickstart

export REPLYLAYER_API_KEY=rly_live_k3m9p2qx7vn4hjd0.uZ8Qb1vK3mN0pR7sT2wX9yA4cF6gH8jL1nP3rT5vW7z  # from app.replylayer.ai
rly doctor --json                                # confirm auth + connectivity (ok: true)
rly send --from <mailbox> --to success@simulator.mailgun.org \
  --subject "hello" --body "first send" --json
# → branch on the JSON `status`: sent | quarantined | blocked | pending_review

success@simulator.mailgun.org (the Mailgun success simulator) is the zero-setup first-send target. The send flag is --from <mailbox> (mailbox name or ID).

Auth

A single API key. REPLYLAYER_API_KEY (env var, wins over stored creds), or rly auth login, or --api-key. Production (https://api.replylayer.ai) is the default endpoint — set nothing else. REPLYLAYER_API_URL is a testing-only override.

A new key is inert until a human completes a one-time email-verification bootstrap (invite-gated signup + a 6-digit code: rly auth verify --code <code>). A EMAIL_NOT_VERIFIED response means that bootstrap is incomplete — a human must finish it.

For agents: `--json` and exit codes

Every command supports the global --json flag for machine-readable output (errors go to stderr as a single JSON object with a stable code).

Branch on the JSON status, not the exit code. A scanner block is exit 0 with status: "blocked" (the message was created and a policy decision recorded). A gate-reject (rate limit, allowlist, undeliverable recipient, draft rescan-reject) is exit 1 with a stable code and no message created.

Exit	Meaning
`0`	The request produced a message — read the JSON `status` (`sent` / `quarantined` / `blocked` / `pending_review`).
`1`	Remote / API / runtime failure, including every gate-reject — discriminate on the JSON `code`.
`2`	Local usage / configuration error (bad flags).
`3`	Auth required / invalid. Defaults to exit `1`; set `REPLYLAYER_AUTH_EXIT_CODE=1` to receive this distinct code.
`130`	Interrupted, or an interactive confirmation aborted (`USER_ABORTED`).

This table is the agent-facing exit-code contract; the full command reference is in the bundled CLI_GUIDE.md.

A typical agent monitoring loop anchors a --since cursor so it waits for the next arrival instead of reprocessing the backlog (reading does NOT mark a message read):

SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
MSG=$(rly --json inbox wait --mailbox support-bot --since "$SINCE" --timeout 30)
# exit 0 with .message=null means "polled cleanly, nothing arrived" — not an error.

Documentation & trust

CLI_GUIDE.md — the full command reference — is bundled in this package and is also readable at https://github.com/replylayer/rly.
Install verification, signed SHA256SUMS, GPG key, and SLSA provenance: https://github.com/replylayer/rly