Skip to navigation

Command Reference

View as MarkdownOpen in Claude

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

CommandPurposeGuide
claude, codex, piLaunch the selected coding agent through Relay.Claude Code, Codex, pi
runLaunch an explicitly selected agent or command.Run Syntax
configRun setup or edit CLI configuration.Configuration
pluginsEdit configuration and manage discoverable plugins.Configure, Manage
install, uninstallManage persistent coding-agent integrations.Manage Persistent Integrations
integrations refreshRefresh Relay-managed integrations after upgrading.Refresh Installed Integrations
authSign in, obtain a token, or remove an OIDC sign-in.Provider Authentication
doctorCheck configuration, integrations, and configured destinations.Troubleshoot the CLI
agentsList supported and detected coding agents.Support Matrix
gatewayStart or stop a standalone gateway.Gateway Lifecycle
mcpKeep the shared gateway available for an MCP connection.Shared Gateway Lifecycle
diagnosticsInspect diagnostics from an existing gateway or daemon.CLI and Daemon Diagnostics
daemonRun or connect to the managed daemon.Daemon Reference
model-pricingValidate catalogs, manage sources, and resolve prices.Model Pricing
completionsGenerate or install shell completions.Shell Completions

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 --:

nemo-relay run -- codex

When --agent or a shortcut selects the agent, provide only that agent’s arguments after --:

nemo-relay run --agent claude -- -p "Review this change"

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

OptionBehavior
--agent claude|codex|piSelect the agent when a custom executable or configured command hides its identity. claude-code is also accepted.
--config PATHSelect an explicit base configuration and its sibling plugins.toml; system configuration still applies.
--openai-base-url URLOverride the OpenAI-compatible upstream.
--anthropic-base-url URLOverride the Anthropic-compatible upstream.
--chatgpt-codex-base-url URLOverride the ChatGPT Codex backend. This backend receives the caller’s ChatGPT credential.
--session-metadata JSONAttach structured metadata to the session.
--dry-runValidate and print the launch plan without setup, gateway startup, or agent execution.
--printInclude generated launch configuration in the printed plan. Combine with --dry-run to inspect it without launching.

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 --:

nemo-relay run --agent claude --dry-run -- claude
nemo-relay claude --dry-run -- claude

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:

nemo-relay run --dry-run --print -- codex

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:

nemo-relay gateway start

Stop that gateway with:

nemo-relay gateway stop

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:

nemo-relay completions 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.