Command Reference
Find a CLI command here, then follow its linked guide for prerequisites,
setup, and expected results. Run nemo-relay <command> --help for the complete
options accepted by your installed version.
Command Index
With no subcommand or server-specific options, nemo-relay opens first-time
setup when no configuration exists. Once configured, it runs a health check.
Use nemo-relay config to reopen setup.
Run Syntax
Use an explicit executable after --:
When --agent or a shortcut selects the agent, provide only that agent’s
arguments after --:
Relay forwards those arguments unchanged. Use the Claude Code, Codex, or pi guide for launch instructions and prerequisites. pi requires an installed Relay extension even for a transparent run.
Run Options
For provider defaults, timeout settings, and endpoint-change credential rules, refer to Provider Connections. For file precedence, custom commands, and session metadata, refer to Configuration.
Inspect a Launch Plan
Add --dry-run before -- to validate and inspect the resolved launch plan
without running setup, starting the gateway, or launching the agent. During
dry-run validation, Relay logs a warning when the selected executable is
repeated after --:
Live launches do not perform this diagnostic or rewrite forwarded arguments. The selected agent receives the arguments exactly as provided.
Dry-run output includes forwarded arguments. Do not share it when those arguments contain prompts, credentials, or other sensitive values.
Use run --dry-run --print to inspect the generated hook configuration,
gateway environment, gateway URL, and final command:
The claude, codex, and pi shortcuts accept --dry-run. Use run for
--print.
Launch Lifecycle
Use the agent shortcuts for local observability. The wrapper starts a gateway on
a dynamic 127.0.0.1 port, injects the resolved hook and gateway configuration
into the launched coding agent, and stops the gateway when the
agent exits. Relay owns the launched wrapper and its descendants as one process
tree, so a gateway failure cannot leave an agent running without its private
gateway and hook configuration. Interactive Unix launches transfer foreground
terminal ownership and preserve Ctrl-C and Ctrl-Z job control. Non-interactive
Unix launches forward termination signals to the complete agent process tree
before Relay removes the injected configuration.
For Claude Code and Codex, transparent mode leaves the caller’s source settings, selected profile, and installed plugin state unchanged. A process marker makes any installed Relay MCP borrow the wrapper-owned dynamic gateway. Claude’s persistent hooks exit without forwarding; Codex disables the known Relay plugin hook identities in its process-local CLI state. Only the injected wrapper hooks deliver events.
Gateway Lifecycle
Start a standalone gateway at the default 127.0.0.1:4040 endpoint:
Stop that gateway with:
Pass the same top-level --bind value to both commands for a custom endpoint.
On Unix, gateway stop --force terminates the process immediately instead of
requesting graceful shutdown. Windows always terminates the gateway process
tree. The command stops only a verified Relay process at a local loopback
endpoint.
The persistent shared gateway uses 127.0.0.1:47632 by default. See
Shared Gateway Lifecycle
to stop it, or
Refresh Installed Integrations
to update its installation. For a multi-user deployment, use the
separate Daemon commands.
Shell Completions
Print a completion script for a shell, for example Zsh:
Use nemo-relay completions --install to install completions for the shell
identified by SHELL, or specify the shell explicitly with
nemo-relay completions zsh --install. The command prints the installed file
path.