rly

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.11.

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 [email protected] \
  --subject "hello" --body "first send" --json
# → branch on the JSON `status`: sent | quarantined | blocked | pending_review

[email protected] (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). |

send/reply with --strict add three outcome codes: 4 (blocked, terminal), 5 (infrastructure hold, retryable), and 6 (unrecognized outcome, fail-closed). Without --strict a non-delivered outcome stays exit 0.

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