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.
ReplyLayer provides safe email infrastructure for AI agents: mailboxes, sending, inbox workflows, scanning, quarantine, and approval flows designed for automated systems.
Command names: rly and replylayer (identical) — examples below use the shorter rly.
Install
npm
The official npm package is rly — the same name as on PyPI. It installs both the rly and replylayer commands. (The package was previously published as replylayer; that name is deprecated.)
npm i -g rly
rly --help
Requires Node.js 22 or higher. The npm package is the JavaScript CLI — it runs on your host Node runtime, so both installing and running it need Node 22+.
PyPI
The PyPI package is rly. Use pipx for a global CLI install. On supported
platforms the wheel ships a bundled native binary — it needs Python 3.10+
but no Node toolchain to install or run.
pipx install rly
rly --help
On Debian and Ubuntu systems that enforce PEP 668, plain pip install rly may fail with externally-managed-environment. Use pipx install rly, or install inside a virtual environment.
winget (Windows x64)
The winget package is ReplyLayer.CLI. It needs no Node or Python toolchain.
winget install --id ReplyLayer.CLI -e
rly --help
Windows x64 only — there is no arm64 package — and it installs the rly
command alone, not the replylayer alias. The installer is the Windows x64
binary published on this repository's releases, and its hash is pinned in the
winget manifest from the same GPG-signed SHA256SUMS described below.
Submitting to the winget community source is a manual step in our release
process, so this package can trail the newest npm/PyPI release — sometimes by
more than one version. npm i -g rly is always the first channel to carry a new
release; use it if you need the latest immediately.
To update or remove:
winget upgrade --id ReplyLayer.CLI -e
winget uninstall --id ReplyLayer.CLI -e
Install-channel collisions
npm, pipx, and winget can each put an rly on your PATH. Your shell runs
whichever comes first, so a fresh winget install can look like it did nothing
or installed an old version when an earlier npm or pipx install is actually
winning.
Keep one global install channel active at a time. To see which executable is live:
Get-Command rly -All # Windows PowerShell (or: where.exe rly)
which -a rly # macOS / Linux
In PowerShell, bare where is an alias for Where-Object, not the where.exe
program — use one of the two forms above.
Then remove the channels you are not using:
winget uninstall --id ReplyLayer.CLI -e
npm uninstall -g rly
pipx uninstall rly
rly --version reports the version of whichever executable actually ran —
compare it against the channel you expect before filing an issue.
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] (ReplyLayer's own first-party simulator) is the
zero-setup first-send target — the send is accepted immediately and a genuine
message.delivered webhook fires a few seconds later. The send flag is
--from <mailbox> (mailbox name or ID). See "Simulator" below for the full scenario
list and rly simulate inbound (synthetic inbound testing).
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 on protected product routes until a human completes both
signup checks: the emailed 6-digit code (rly auth verify --code <code>) and the
6-digit SMS code (rly auth verify-phone --code <code>). EMAIL_NOT_VERIFIED or
PHONE_NOT_VERIFIED means that bootstrap is incomplete. If the SMS was not sent,
run rly auth resend-phone; before verification, add --phone +<country-code>...
to correct a typo and resend.
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.
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.
Simulator
Test send, provider-style outcomes, webhook signatures, and inbound receive/quarantine without a real recipient or another provider's simulator:
rly send --from <mailbox> --to [email protected] --subject hi --body hi
rly simulate inbound --mailbox <mailbox> --scenario clean
rly simulate inbound --mailbox <mailbox> --scenario prompt_injection_quarantined
rly webhook test <id> --event message.delivered
Outbound scenarios: delivered@, bounced@, complained@, suppressed@ at
simulator.replylayer.net (append +label for your own correlation, e.g.
[email protected]). complained@/suppressed@ prove webhook
delivery only — no real suppression row is written. One Sandbox account can run all
four scenarios in the same day; the exact simulator addresses bypass the
recipient-domain cap but still consume daily and cumulative send allowances. Full
detail is in CLI_GUIDE.md;
the canonical outcome, accounting, and inbound-response contract is the
email simulator guide.
Package Links
- npm: https://www.npmjs.com/package/rly
- PyPI: https://pypi.org/project/rly/
- winget: https://github.com/microsoft/winget-pkgs/tree/master/manifests/r/ReplyLayer/CLI
Verifying a release
Every CLI release publishes a GPG-signed checksum manifest so you can verify a
download. The signing key is in KEYS.txt in this repository.
What the manifest covers: the PyPI wheels and sdist (byte-identical to
the files on PyPI) and the platform binaries. The npm package is not
covered by this manifest; verify npm registry signatures separately with npm audit signatures.
-
Download the manifest, its signature, and the signing key:
base=https://github.com/replylayer/rly/releases/latest/download curl -fsSLO "$base/SHA256SUMS" curl -fsSLO "$base/SHA256SUMS.sig" curl -fsSL https://raw.githubusercontent.com/replylayer/rly/main/KEYS.txt | gpg --import -
Verify the manifest signature — expect
Good signature from "ReplyLayer CLI Releases <[email protected]>":gpg --verify SHA256SUMS.sig SHA256SUMS -
Verify the file you actually downloaded. The manifest lists every release artifact — including binaries not attached to this repo — so check only your file with a filtered match. A bare
sha256sum -c SHA256SUMSwould fail on the absent entries.# GNU/Linux: verify every listed file you actually have, skip the rest sha256sum --ignore-missing -c SHA256SUMS # any platform: verify one file by name (replace with your download) grep '<your-downloaded-file>' SHA256SUMS | sha256sum -cOn macOS use
shasum -a 256 -cin place ofsha256sum -c(thegrepform).
Security
Please report security issues privately to [email protected].
Source
This repository contains the CLI source (src/ with its manifest, lockfile,
and build config). From cli-v0.7.13 onward, each release tag identifies the
exact commit the published npm package was built and attested from — see the
From source section of CLI_GUIDE.md for build
instructions (Node.js 22+). main may briefly carry the next prepared,
unreleased version between a source merge and its stable publication; use the
immutable cli-vX.Y.Z tags for released source. Tags before cli-v0.7.13
predate source publication and do not contain the CLI source. Public source
covers the JavaScript npm package only — native binaries in the PyPI wheels
and the winget package remain privately built and are verified via the signed
checksums above, not by this source tree.
langchain-python/ — LangChain adapter source mirror
langchain-python/ is a read-only source mirror of the langchain-replylayer PyPI package, updated automatically at each release and proven byte-identical to the released sdist. File issues here; pull requests against this directory cannot be merged directly — it is regenerated from the upstream source at every release.
