Reins

CLI reference

Every reins command a person runs, with its flags and defaults. Flags take one or two dashes and come after the command (and after the subcommand, where there is one).

Set up

reins setup

Takes a new machine from nothing to a pairing QR.

reins setup [--device NAME] [--no-service] [--qr-png PATH]

Runs three steps in order: installs the login service (as reins service install does), wires every supported agent it finds (as reins install-hooks does), then pairs a phone (as reins pair does). It creates the pairing token first, so the daemon and the QR read the same one.

Only the token and the pairing are fatal. If the service cannot be installed or one agent cannot be wired, setup still prints the QR, then lists the problems and points you at reins doctor.

Flag Default What it does
--no-service none Don't install the login service; run reins serve yourself. Use this if Homebrew already starts reins.
--device NAME none Name this phone (letters, digits, . _ -) so pairing a second one does not revoke the first.
--qr-png PATH none Also write the QR to this PNG file.

Example

reins setup --device pixel

reins pair

Prints a pairing QR for the app to scan.

reins pair [--device NAME] [--qr-png PATH] [--ssh-port N] [--no-authorize] [--remote | --remote-off]

The QR carries every route to this machine, your username, the SSH host-key fingerprints, the pairing token and an SSH key minted for this pairing, which pair adds to your authorized_keys. It never carries a password. Anyone who photographs it can reach the machine, so treat it like a key.

Flag Default What it does
--device NAME none Name this phone (letters, digits, . _ -) so pairing a second one does not revoke the first.
--qr-png PATH none Also write the QR to a PNG, for when the terminal QR won't render.
--ssh-port N Port in ~/.reins/sshd_config, else 22 The sshd port the phone should connect through.
--host-key-file PATH none An extra sshd host public key (.pub) to pin, beyond those in /etc/ssh.
--authorized-keys PATH sshd's AuthorizedKeysFile, else ~/.ssh/authorized_keys Where to add the phone's pairing key.
--no-authorize none Don't mint or authorise a phone key; the phone must already have an authorised SSH identity.
--token-file PATH ~/.reins/token Pairing token file.
--daemon-port N 7777 The daemon's port on this host's loopback.
--remote none Turn on remote pairing instead of printing a QR. Makes a new passphrase (five words, shown once) that a phone on this network or tailnet can pair with, away from this machine. Five wrong tries lock it for an hour. Running it again makes a new one.
--remote-off none Turn remote pairing off. Phones already paired keep working.

Example

reins pair --qr-png ~/reins-pair.png

reins install-hooks

Wires Reins into your coding agents.

reins install-hooks [--agent NAME|all] [--dry-run] [--approvals pre-tool-use|permission-request]

Hook entries name the reins binary by its absolute path, because a bare name would resolve against whatever PATH the agent inherited. Re-running is safe: entries that are already right are kept. Restart any running agent afterwards so it reloads its config.

With --agent all (the default), Claude Code, Codex, OpenCode and Pi are always written; the other agents are skipped when they do not look installed, and named so you can wire one later.

Flag Default What it does
--agent NAME all One of claude-code, codex, opencode, pi, devin, omo, qwen-code, qoder, factory-droid, grok-build, cursor, copilot, antigravity, kimi-code, jcode, hermes, amp, omp, or all. devin wires claude-code; omo wires opencode.
--dry-run none Print what would change without writing.
--approvals HOOK pre-tool-use Which Claude Code hook carries approvals. pre-tool-use works everywhere; permission-request skips a process per tool call but never fires for headless claude -p runs.
--claude-settings PATH ~/.claude/settings.json Claude Code settings file.
--codex-config PATH ~/.codex/config.toml Codex config file.
--opencode-plugin PATH ~/.config/opencode/plugins/reins.js OpenCode plugin file.
--pi-extension PATH ~/.pi/agent/extensions/reins.ts Pi extension file.

Example

reins install-hooks --agent cursor --dry-run

reins uninstall-hooks

Removes what install-hooks added, and nothing else.

reins uninstall-hooks [--agent NAME|all] [--dry-run]

Takes the same --agent names and file-path flags as install-hooks.

Flag Default What it does
--agent NAME all Which agent to unwire, or all.
--dry-run none Print what would change without writing.

Example

reins uninstall-hooks --agent codex

reins service

Starts reins at login, removes that, or says how it stands.

reins service [install|uninstall|status] [--force]

On macOS it installs a launchd agent (~/Library/LaunchAgents/com.enraio.reins.plist); on Linux and WSL2, a systemd user unit (~/.config/systemd/user/reins.service). The service writes its output to ~/.reins/daemon.out.

It refuses when reins came from Homebrew (use brew services start reins) or when a daemon is already running by hand. --force installs anyway.

status
The default. Whether the service is installed and running.
install
Install and start the login service.
uninstall
Stop and remove it.
Flag Default What it does
--force none Install even under Homebrew or with a daemon already running.

Example

reins service status

Run and inspect

reins serve

Runs the daemon in the foreground. The login service runs exactly this.

reins serve [flags]

Logs go to stderr and to ~/.reins/daemon.log, which reins logs reads.

Flag Default What it does
--listen ADDR 127.0.0.1:7777 Loopback listener for the local hook shims. Leave it on loopback.
--transport-listen ADDR :7778 The resumable transport the paired phone dials. Each connection is authenticated and encrypted with a per-session key handed over SSH. Empty disables it.
--socket PATH ~/.reins/hook.sock Unix socket the hook shims use.
--token-file PATH ~/.reins/token Pairing token file, created on first run with mode 0600.
--allow-chat-send BOOL true Let paired phones type into agent terminals. --allow-chat-send=false keeps approvals and the live feed and removes typing.
--pair-listen ADDR :7779 The pairing service: a phone on the local network or tailnet can pair without a QR, by confirming a code on this machine (a dialog, on macOS) or with the reins pair --remote passphrase. Empty disables it.
--advertise BOOL true Announce this host on the LAN over mDNS (_reins._tcp). --advertise=false turns it off.
--ssh-port N Port in ~/.reins/sshd_config, else 22 sshd port to advertise over mDNS.
--max-decision-wait DURATION 5m Upper bound on how long any hook waits for a phone decision.
--transport-session-ttl DURATION 90s How long a dropped phone session is held for resume. Lower restores fail-open sooner; higher tolerates longer backgrounding.
--push-relay URL https://reins-push.enraio.com Relay used to wake phones that registered through it. Empty turns relay push off.
--fcm-service-account PATH ~/.reins/fcm-service-account.json Your own Firebase service account, for push without the relay. A missing file means this path is off.
--push-wake-wait DURATION 45s How long an approval is held for a woken phone to reconnect before it passes through.
--terminal-keep DURATION 12h How long a shell opened from the phone keeps running with no phone attached.
--log-file PATH ~/.reins/daemon.log The log reins logs reads. Empty writes to stderr only.
--webhooks PATH ~/.reins/webhooks.json Outbound webhooks (HMAC-SHA256 signed). A missing file means none.
--sessions-file PATH ~/.reins/sessions.json Where the session list is kept across restarts. Empty keeps it in memory.

Example

reins serve --allow-chat-send=false --advertise=false

reins doctor

Checks what is wired and what is not.

reins doctor [--claude-settings PATH] [--codex-config PATH]

Reports the reins binary and version, whether the daemon answers, sshd, the Claude Code hooks, the Codex notify line, every other agent, and which multiplexers (herdr, tmux, zellij) are available. Each line is a tick, a warning or a problem, with a summary at the end.

Flag Default What it does
--listen ADDR 127.0.0.1:7777 Daemon address to probe.
--socket PATH ~/.reins/hook.sock Hook socket to probe.
--claude-settings PATH ~/.claude/settings.json Claude Code settings file to check.
--codex-config PATH ~/.codex/config.toml Codex config file to check.

Example

reins doctor

reins logs

Prints the daemon's log.

reins logs [-f] [-n N] [--path PATH] [--print-path]

Reads ~/.reins/daemon.log, the file reins serve writes.

Flag Default What it does
-f, --follow none Keep printing as new lines arrive.
-n N 50 Recent lines to print first (0 for none).
--path PATH ~/.reins/daemon.log Log file to read.
--print-path none Print the log file path and exit.

Example

reins logs -f

Agents, network and push

reins agents

Lists the agents this build speaks, with their hook events and capabilities.

reins agents

Capabilities are approvals, sessions, notifications and transcript. Codex has no approvals; only Claude Code has a transcript.

Example

reins agents

reins tailnet

Lists the machines on this host's tailnet, with address, OS and online status.

reins tailnet [--json]

Useful when the pairing screen is not offering a machine you expect. The app reads the --json form.

Flag Default What it does
--json none Print the status as JSON.

Example

reins tailnet

reins routes

Lists the addresses a phone can use to reach this machine now.

reins routes [--json] [--ssh-port N]

LAN addresses first, then Tailscale, without duplicates: the same list reins pair puts in the QR. The app asks for it each time it connects and merges the answer into what it already has, so a machine that gains Tailscale after pairing becomes reachable away from home without pairing again.

Flag Default What it does
--json none Print the routes as JSON (ssh_port and hosts). The app reads this form.
--ssh-port N Port in ~/.reins/sshd_config, else 22 The sshd port to report.

Example

reins routes

reins push

Shows and tests the wake-up push.

reins push [list|test]

list shows each phone registered for push and whether it is reached through the relay or your own Firebase project. test sends the wake notification now, so you can check push without waiting for an agent.

register and unregister also exist; the app calls them over SSH, and you do not run them yourself.

list
The default. Registered phones and their route.
test
Send the wake notification to every registered phone.
Flag Default What it does
--file PATH ~/.reins/push_devices.json Where registered phones are kept.
--push-relay URL https://reins-push.enraio.com Relay to send through.
--fcm-service-account PATH ~/.reins/fcm-service-account.json Your own Firebase service account.

Example

reins push test

reins settings

Shows the preferences your phones have synced through this machine.

reins settings [list]

The host is the sync point; settings live in ~/.reins/settings.json and nowhere else. The app reads and writes them with get and put.

Flag Default What it does
--file PATH ~/.reins/settings.json Where settings are kept.

Example

reins settings

reins version

Prints the version.

reins version

Example

reins version

Called for you

These exist in the binary but are run by your agents or by the app over SSH. You should not need to type them; they are listed so nothing in ps or a hook file is a surprise.

reins hook <kind>
The shim your agent runs on each hook event. Blocking hooks wait up to --timeout (the installed hooks pass 180s; the default is 60s).
reins transport-bootstrap
The app runs this over SSH to get the per-session key for the encrypted transport.
reins file <stat|read> PATH
Hands a file the agent mentioned to the phone over the paired connection. No hosting, no URL.
reins repo <status|diff|ls|show|log>
Answers the app's questions about the repository an agent works in, as JSON.
reins push register|unregister
The app registers and withdraws a phone for push.
reins settings get|put
The app reads and writes synced settings.