CLI reference

The ctrlrelay console script is a Typer app defined at src/ctrlrelay/cli.py. This page is generated by hand from that source — when in doubt, read the file.

Run any command with no arguments (or --help) to see Typer’s auto-generated help.

ctrlrelay [--version] <command> ...
Top-level Purpose
ctrlrelay --version / -v Print the package version and exit.
ctrlrelay version Same, as a subcommand.
ctrlrelay status Show active locks and the 5 most-recent sessions.
ctrlrelay config ... Configuration helpers.
ctrlrelay skills ... Skill discovery / audit.
ctrlrelay bridge ... Manage the chat bridge daemon (Telegram or Mattermost).
ctrlrelay run ... Run a pipeline interactively.
ctrlrelay ci ... CI helpers used by the dev pipeline prompt.
ctrlrelay poller ... Manage the issue-poller daemon.
ctrlrelay setup Interactive first-run setup: writes orchestrator.yaml.
ctrlrelay install ... Generate launchd / systemd unit files.
ctrlrelay web ... Read-only status page and JSON API.
ctrlrelay node ... Check this machine’s setup.
ctrlrelay repos ... Bulk repo operations across the configured repos.
ctrlrelay personalization ... Cross-machine sync of operator state.

setup, personalization, status and version are described below; install and web in Operations, node in Adding a machine. For repos, see ctrlrelay repos --help.

Every command that reads config accepts --config / -c to point at a non-default orchestrator.yaml (default: config/orchestrator.yaml).

ctrlrelay setup

ctrlrelay setup [OPTIONS]

First-run onboarding: detect GitHub orgs, enumerate their non-fork non-archived repos, write a fresh ~/.config/ctrlrelay/orchestrator.yaml, clone every repo to ~/Projects/<owner.lower()>/<repo>, and (optionally) configure the personalization sync block plus install launchd/systemd unit files. Composes the building blocks operators previously had to wire by hand.

The interactive flow asks one question at a time. --yes skips prompts and accepts every default. Repeat --owner to lock the owner list non-interactively.

Key flags:

Flag Default Notes
--owner OWNER (interactive prompt) Repeatable. When omitted, prompts to pick from accessible owners.
--repo-root PATH ~/Projects Where repos land — ~/Projects/<owner.lower()>/<repo>.
--config-out PATH ~/.config/ctrlrelay/orchestrator.yaml Where to write the generated config.
--timezone TZ UTC IANA zone for cron schedules.
--transport TRANSPORT file_mock file_mock, telegram or mattermost. Exactly one is active; there is no fallback between them.
--telegram-chat-id ID none Required for --transport=telegram.
--mattermost-url URL none Server URL, e.g. https://chat.example.com. Required for --transport=mattermost.
--mattermost-channel-id ID none The channel’s 26-character ID, not its name. Required for --transport=mattermost.
--personalization-repo OWNER/REPO none Adds a personalization block.
--no-personalization off Skip the personalization prompt entirely.
--install-daemons (prompted) Render and write launchd/systemd unit files. Reads the token variable the chosen transport names ($CTRLRELAY_TELEGRAM_TOKEN, $CTRLRELAY_MATTERMOST_TOKEN) so the rendered unit isn’t a placeholder.
--skip-archived/--include-archived skip gh repo list filter.
--skip-forks/--include-forks skip gh repo list filter.
--yes / -y off Accept every default; never prompt.
--force off Overwrite an existing orchestrator.yaml (and existing daemon plists when --install-daemons).

Refuses to overwrite an existing config or daemon plist without --force. Refuses to proceed if gh auth status fails — run gh auth login first.

After setup completes, the next manual steps are:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.ctrlrelay.ctrlrelay-poller.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.ctrlrelay.ctrlrelay-bridge.plist

(Or the systemd equivalents on Linux.)

ctrlrelay config

config validate

ctrlrelay config validate [-c PATH]

Loads config/orchestrator.yaml, validates the pydantic schema, prints the parsed node_id, timezone, transport type, and repo count. Exits non-zero on validation errors.

config repos

ctrlrelay config repos [-c PATH]

Lists configured repositories in a table (name, local path, deploy provider).

ctrlrelay skills

skills audit

ctrlrelay skills audit [-p SKILLS_DIR] [-c PATH]

Audits each skill under paths.skills (or --path) for orchestrator readiness — checks shape, required metadata, common pitfalls. Exits non-zero if any skill fails.

skills list

ctrlrelay skills list [-p SKILLS_DIR] [-c PATH]

Lists discovered skills as a table (name, path).

ctrlrelay bridge

See Chat bridge for the full setup walkthrough.

bridge start

ctrlrelay bridge start [-c PATH] [-F|--foreground]

Starts the bridge for the active transport (transport.type, Telegram or Mattermost), listening on that block’s socket_path. Reads the bot token from the env var named in that block’s bot_token_env (default CTRLRELAY_TELEGRAM_TOKEN or CTRLRELAY_MATTERMOST_TOKEN). Daemonizes by default — forks a detached process, writes a PID file alongside the socket, and returns to the shell. Pass --foreground / -F under launchd/systemd or when debugging interactively; the process runs in the foreground and still writes its PID file so ctrlrelay bridge status works.

Fails if transport.type is not telegram or mattermost, the token env var is unset, the chat handler cannot be built from the config, or a PID file already exists for a live process. On Mattermost it also refuses to start until the bot is a member of the configured channel.

bridge stop

ctrlrelay bridge stop [-c PATH]

Reads the PID file and sends SIGTERM.

bridge status

ctrlrelay bridge status [-c PATH]

Reports running / not-running by consulting the PID file. If the PID file is missing but the socket exists (e.g. the bridge was started by an older launchd plist that pre-dates the PID-file change), exits non-zero with a hint to restart the bridge — a restart on the new version will regenerate the PID file and let status work.

bridge test

ctrlrelay bridge test [-m "MESSAGE"] [-c PATH]

Connects to the bridge socket as a client and sends a one-off message. Useful for confirming end-to-end delivery to your chat (Telegram or Mattermost) without waiting for a real pipeline run.

ctrlrelay run

run dev

ctrlrelay run dev -i ISSUE [-r REPO] [-c PATH] [--from-step STEP]
Flag Required Default Description
--issue / -i yes — GitHub issue number.
--repo / -r when more than one repo is configured — Limit to a single owner/repo.
--config / -c no config/orchestrator.yaml Config path.
--from-step no — Start again from plan, code or publish, taking the earlier steps from the issue’s newest run that saved them and moving the branch back. See A run whose process died.

Acquires the per-repo lock, creates the worktree, spawns the repo’s agent (Claude Code, OpenCode, Copilot, Codex or a plugin, per agent.type / repos[].agent_type) with the issue’s title/body in the prompt, and reports the result. If the agent blocks and a chat transport (Telegram or Mattermost) is configured, posts the question to your chat and waits for a reply (up to DEFAULT_MAX_BLOCKED_ROUNDS rounds).

run secops

ctrlrelay run secops [-r REPO] [-c PATH]

Runs the secops pipeline across configured repos (or one repo with --repo). Each repo’s run is serialised by the per-repo lock; the overall sweep runs in parallel across repos. Reports per-repo success/failure and exits non-zero if any repo failed.

ctrlrelay ci

ci wait

ctrlrelay ci wait --pr N --repo OWNER/REPO [--timeout 600] [--interval 15]
Flag Default Description
--pr / -p — (required) PR number to wait on.
--repo / -r — (required) Repository as owner/name.
--timeout / -t 600 Hard timeout in seconds.
--interval / -i 15 Seconds between polls.

Polls gh pr checks until every check has left the pending bucket (or the hard timeout is hit), then exits with:

  • 0 — all checks passed (or the repo has no CI configured)
  • 1 — at least one check failed / cancelled / timed_out
  • 2 — hard timeout while checks were still pending

Exists specifically so the dev pipeline’s prompt could point the agent at one correct command instead of asking it to improvise a bash until / while loop — every attempt at improvising those has been inverted-semantics or pipe-swallowed the exit code (see issue #85).

ctrlrelay poller

poller start

ctrlrelay poller start [-c PATH] [-F|--foreground] [-i SECONDS]
Flag Default Description
--interval / -i 300 Seconds between polls.
--foreground / -F off Run in the foreground. Default is to daemonize (fork + return to shell). Pass this under launchd/systemd.
--config / -c config/orchestrator.yaml Config path.

Polls each configured repo for issues assigned to your GitHub user (resolved via gh api user --jq .login), by you or by an account in allowed_accounts, plus issues carrying a trigger label one of those accounts added. On the first run, seeds the seen-issue set with current assignments so it does not replay your existing backlog.

For each newly assigned issue, runs run_dev_issue(...) (i.e. the dev pipeline) in-process. If a chat transport (telegram or mattermost) is configured and the bridge socket exists, sends notifications: 🔔 New issue on detection, ⏸️ Blocked on question, ✅ PR ready on success, ❌ Failed otherwise.

State is persisted to <state_db_dir>/poller_state.json.

poller stop

ctrlrelay poller stop [-c PATH]

Sends SIGTERM to the daemon PID.

poller status

ctrlrelay poller status [-c PATH]

Reports running / not-running.

ctrlrelay personalization

See Personalization sync for the conceptual walkthrough. All subcommands require a personalization: block in orchestrator.yaml and operate on the checkout at personalization.checkout_path (default ~/.ctrlrelay/personalization).

personalization init

ctrlrelay personalization init [-c PATH] [--no-adopt]

Clones the personalization repo into checkout_path, creates the per-machine working branch (personalization/<node_id>), and lays down the symlinks declared in personalization.paths.

By default, adopt-flow is on: a target that exists as a real file or directory while its corresponding source slot in the repo is empty is moved into the repo and replaced with a symlink. Your existing content is preserved and immediately under sync. Run personalization push after init to send the adopted content to GitHub.

Pass --no-adopt to opt out of adoption — pre-existing real targets surface as skipped-real-file-at-target instead, and you back them up

  • remove them manually before re-running.

If both the repo source and the on-disk target have real content, init refuses with skipped-conflict-both-exist regardless of --no-adopt. Reconcile manually before re-running.

personalization status

ctrlrelay personalization status [-c PATH]

Prints the working branch, repo URL, ahead/behind counts vs. origin, and per-symlink state — correct, wrong-target, missing, source-missing, etc. Read-only; doesn’t touch the filesystem.

personalization push

ctrlrelay personalization push [-c PATH] -m "MESSAGE"

Stages the entries declared in paths (allowlist — random files in the checkout are not committed), commits with MESSAGE, rebases the per-machine branch onto origin/<main_branch>, and pushes. Retries the fast-forward of origin/main up to three times if another machine’s push lands between fetch and push. Uses --force-with-lease on the per-machine branch only when the local working branch has diverged from the remote (after a rebase) — never on main.

Conflicts during the rebase abort and list the unmerged files for you to resolve.

personalization pull

ctrlrelay personalization pull [-c PATH]

Fetches, rebases the per-machine branch onto origin/<main_branch>, fast-forwards local main if it’s an ancestor of the remote, and re-wires symlinks (the config-as-code shipped in the repo may have changed). Uses adopt=True like init so newly-declared paths can adopt local content during a pull. Conflicts abort cleanly and list the unmerged files.

The daemon-driven auto-pull (under schedules.personalization_cron) calls the same code with two extra rails: skip when the working tree is dirty, and re-wire with adopt=False so a background sync never silently moves files.

ctrlrelay status

ctrlrelay status [-c PATH]

Opens the SQLite state DB at paths.state_db and prints:

  • Active locks — (repo → session_id) for each held repo lock.
  • Recent sessions — the 5 most-recent rows from the sessions table (id, pipeline, repo, status).

status values: running, done, blocked, failed.

If the DB doesn’t exist yet, prints a hint to run a pipeline first.

ctrlrelay self-update

ctrlrelay self-update [--version X] [--wait-minutes N] [--no-ack] [-c PATH]

Installs a version already on PyPI on this node once it is idle: holds new work, waits (up to --wait-minutes, default 60) for the run in flight, installs the wheel after checking its sha256 against PyPI’s JSON, restarts this node’s units and checks /api/status reports the new version. On any failure the old version stays or is put back, chat is told, and it exits non-zero. --no-ack is for updating from a poller too old to acknowledge the hold. See Operations: Updating a node.

ctrlrelay version

ctrlrelay version

Prints the package version (same as ctrlrelay --version).