rly

rly is 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 an agent loop. Not a bulk or marketing tool.

This package is the PyPI launcher: it ships a bundled native binary, so no Node toolchain is required.

Looking for the Python library? This package is the CLI. For the importable SDK (import replylayer), install replylayer instead: pip install replylayer.

pipx install rly
rly --help

Installing the rly package exposes both the rly and replylayer commands — they are aliases for the same launcher, mirroring the npm package. Examples use the short form:

rly --help   # the `replylayer` command is an identical legacy alias

On Debian and Ubuntu systems that enforce PEP 668, plain pip install rly may fail with externally-managed-environment. Use pipx install rly for a global CLI install, or install inside a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
pip install rly

On the supported binary-wheel install, the rly command execs a bundled native replylayer binary directly — no Node toolchain is involved. The npx rly@<pinned> path is reached only when you explicitly set RLY_FORCE_NPX=1 (the launcher's emergency fallback). If the bundled binary is absent (a source/sdist install on an unsupported platform), rly exits with an actionable error pointing at RLY_FORCE_NPX=1 — it does not fall back to npx automatically. The version-pin contract still holds for that npx fallback — the PyPI rly@X.Y.Z resolves the npm rly@X.Y.Z exactly (see Strict pin policy below).

Requirements

• Python 3.10+
• pipx for the recommended global install path

Optional (fallback only): Node 22+ with npx on PATH is required only when you opt into the emergency RLY_FORCE_NPX=1 fallback — which is also how you run a source/sdist install on an unsupported platform (set RLY_FORCE_NPX=1 with Node on PATH; the launcher does not switch to npx on its own). The binary wheel needs neither Node nor npx.

Examples

rly auth login
rly mailbox list
rly inbox list --mailbox support-bot

For the full command reference, run rly --help. The complete CLI_GUIDE.md is also bundled in the npm rly package and readable on GitHub. Public CLI source and package-trust material (signed SHA256SUMS, GPG key, SLSA provenance) live at: https://github.com/replylayer/rly

Environment variables

RLY_TIMEOUT_SECONDS

Opt-in subprocess timeout, in seconds. When set, every rly invocation is bounded by subprocess.run(..., timeout=RLY_TIMEOUT_SECONDS); if the underlying CLI subprocess does not exit in time the launcher prints a diagnostic to stderr and exits with code 124. This bounds the bundled-binary exec on the supported path (and the npx process under RLY_FORCE_NPX=1).

By default there is no timeout, with one narrow exception: the help and version short-circuits (--help, -h, --version, -V) carry a built-in 10-second timeout. Those commands should never need to touch the network beyond an initial registry resolve; bounding them lets you diagnose a restricted-network sandbox without affecting legitimate long-poll commands like rly inbox wait --timeout 60.

RLY_TIMEOUT_SECONDS=30 rly inbox list --mailbox support-bot

Set the value high enough to cover the slowest command you reasonably expect. Setting it to a non-integer string is treated as "no timeout" (graceful fallback rather than a launcher crash).

RLY_OFFLINE

RLY_OFFLINE is a no-op on the default bundled-binary path — it applies only under the RLY_FORCE_NPX=1 fallback (the only path that invokes npx).

Set RLY_OFFLINE=1 to force npx to resolve rly from the local cache only. The launcher passes both --offline on the command line and npm_config_offline=true in the subprocess environment (belt-and-suspenders; --prefer-offline is NOT a no-network guarantee).

If the pinned rly version isn't cached locally, npx exits fast with its own non-zero exit code (typically 1 with ENOTCACHED); the wrapper passes that exit code through verbatim — it does NOT normalize it to 124. Exit code 124 is reserved for the wrapper's own timeout branch.

# RLY_OFFLINE only applies under the RLY_FORCE_NPX=1 fallback. Warm the npx
# cache once, online:
RLY_FORCE_NPX=1 rly --version
# Subsequent fallback calls can then run offline:
RLY_FORCE_NPX=1 RLY_OFFLINE=1 rly --version

RLY_OFFLINE=1 is useful in network-restricted CI sandboxes, air-gapped deployments, or any environment where you want a hard guarantee that the launcher will not reach out to the npm registry.

Strict pin policy

The PyPI rly@X.Y.Z always resolves the npm rly@X.Y.Z exactly — there is no @latest resolution and no semver range. The launcher computes the pinned package string at runtime via importlib.metadata.version('rly'), so the two artifacts always move together.

This means:

• A published PyPI rly@X.Y.Z cannot ride a later patch-level npm release; both packages must be republished together by ReplyLayer.
• Source installs from the repository between a launcher-only PR and the paired version bump are intentionally unsupported. Use pipx install rly (PyPI) or npm install -g rly (npm) as the supported install paths.