The bridge

CLI reference

Every command the pagr CLI exposes, with its real flags and exit codes. This page is checked against the CLI source in the open-source bridge, so it cannot drift.

Global options#

These work on every command.

Global options
Flag	Effect
`--json`	machine-readable output where supported
`--home <dir>`	override PAGR_HOME (default ~/.pagr)
`-v, --version`	print the CLI version
`-h, --help`	usage for the program or any subcommand

--json prints a machine-readable object instead of the formatted output on the commands that support it, which is every read command plus the ones that report what they changed.

$pagr status --json | jq '.daemon.running'

Commands#

pagr connect#

pair this Mac with your Pagr account and install the background daemon.

$pagr connect [options]

Generates an Ed25519 device key (Keychain), sends only the public half, prints a short-lived pairing code, opens the browser, and waits for you to approve. On success it installs the launchd agent unless you pass --no-daemon. Refuses to run on an already-paired Mac unless you pass --force.

Options for pagr connect
Flag	Effect
`--api-url <url>`	Pagr API base URL (default: $PAGR_API_URL or https://api.pagr.dev)
`--gateway-url <url>`	override the gateway WebSocket URL returned by pairing
`--name <deviceName>`	device name shown in the dashboard (default: hostname)
`--no-daemon`	do not install the launchd agent
`--no-open`	print the pairing URL without opening a browser
`-f, --force`	re-pair even if this Mac is already paired
`--timeout <minutes>`	how long to wait for browser approval (default: 10)
`--wait <seconds>`	how long to wait for the gateway handshake, 0 to skip (default: 20)

JSON · supports --json

pagr status#

pairing, daemon, gateway, agents and project summary.

$pagr status

The one command to run when you want to know whether Pagr is working. Agent lines come from a cheap local probe (`claude --version`, `codex --version`), so they report `auth unknown` — only the daemon knows the real authentication state.

Daemon · talks to the running daemon over ~/.pagr/run/daemon.sock
JSON · supports --json

pagr doctor#

diagnose install, pairing, daemon, gateway and agent problems.

$pagr doctor [options]

Checks Node, the permissions on ~/.pagr, the secret store, pairing, the daemon socket, gateway TCP reachability, both agent CLIs and the launch agent — printing a fix for every failure.

Options for pagr doctor
Flag	Effect
`--fix`	tighten any file permissions that are too permissive
`--offline`	skip the network checks (API, clock, gateway)

JSON · supports --json
Exits · 5 when any check fails

pagr projects#

list registered projects.

$pagr projects

Reads through the daemon when it is running, and falls back to reading ~/.pagr/projects.json directly when it is not.

Daemon · talks to the running daemon over ~/.pagr/run/daemon.sock
JSON · supports --json

pagr project add#

$pagr project add [path] [options]

The folder must exist, be a directory, and be a git repository unless you pass --allow-non-git. Registration is refused for /, /System, /private/etc, /etc, /usr, /bin, /sbin, /Library, your home directory itself, and anything under ~/.pagr.

Options for pagr project add
Flag	Effect
`-n, --name <alias>`	display name (default: folder name)
`--alias <a,b>`	comma-separated extra aliases for iMessage
`--allow-non-git`	allow a folder without a .git directory

Daemon · talks to the running daemon over ~/.pagr/run/daemon.sock
JSON · supports --json
Exits · 5 on a duplicate, a non-git folder, or a refused root

pagr project scan#

find git repos under a few folders and register them in one go.

$pagr project scan [roots...] [options]

Walks a small set of conventional folders (~/code, ~/src, ~/Developer, ~/Projects, ~/work and the current directory when you name none), stopping at each repository rather than descending into it, and skipping node_modules, caches and hidden folders. It never walks your whole home directory, and refuses $HOME and / outright. Names come from the folder plus the GitHub repo name so either works over iMessage; a collision is qualified (two/app) instead of silently duplicated. Running it twice registers nothing new.

Options for pagr project scan
Flag	Effect
`--all`	register everything found, without asking
`--dry-run`	show what would be registered and change nothing
`--depth <n>`	how deep to walk each root (default 3)
`--limit <n>`	stop after this many repositories (default 500)

Daemon · talks to the running daemon over ~/.pagr/run/daemon.sock
JSON · supports --json

pagr project remove#

unregister a project by id, name or alias.

$pagr project remove <aliasOrId>

Aliased as `pagr project rm`. Forgets the id; it never deletes any files.

Daemon · talks to the running daemon over ~/.pagr/run/daemon.sock
JSON · supports --json
Exits · 5 when nothing matches

pagr sessions#

list agent sessions known to the daemon.

$pagr sessions [options]

Reads from the running daemon only — there is no offline fallback. The daemon already reconciles on startup, so a session that claimed to be working when it died is either re-attached or reported terminated; --reconcile forces that same pass by hand.

Options for pagr sessions
Flag	Effect
`--reconcile`	ask each provider what it still knows and clear any session that only claims to run

Daemon · talks to the running daemon over ~/.pagr/run/daemon.sock
JSON · supports --json
Exits · 3 when the daemon is not running

pagr daemon run#

run the daemon in the foreground (what the launch agent executes).

$pagr daemon run [options]

Useful for debugging: combine with PAGR_LOG_LEVEL=debug to see every decision. Refuses to start if another daemon already holds the lock for this PAGR_HOME.

Options for pagr daemon run
Flag	Effect
`--mock`	use mock agents (same as PAGR_MOCK_AGENTS=1)

Exits · 5 when a daemon is already running

pagr daemon install#

install + start the launchd agent.

$pagr daemon install

Writes the `dev.pagr.bridge` launch agent and bootstraps it. The plist captures the current PATH, so re-run this after installing Node or an agent CLI.

pagr daemon uninstall#

stop + remove the launchd agent.

$pagr daemon uninstall

pagr daemon stop#

alias for uninstall.

$pagr daemon stop

pagr daemon status#

launch agent + daemon process status.

$pagr daemon status

Distinguishes "installed but not loaded" from "not installed", and reports the lock pid and socket path when the daemon is holding the lock but not answering.

Daemon · talks to the running daemon over ~/.pagr/run/daemon.sock
JSON · supports --json

pagr daemon logs#

print the daemon log.

$pagr daemon logs [options]

Reads ~/.pagr/logs/daemon.log. Your home directory is rewritten to ~ in every line.

Options for pagr daemon logs
Flag	Effect
`-f, --follow`	follow (tail -f)
`-n, --lines <n>`	number of lines (default 50)

Exits · 5 when the daemon has never run

pagr billing#

open billing in the browser: status (default) | upgrade | portal.

$pagr billing [action] [options]

Browser-only by design: the CLI never sees card data, Stripe keys or portal credentials. Any action other than status, upgrade or portal is an error.

Options for pagr billing
Flag	Effect
`--web-url <url>`	dashboard base URL (default: $PAGR_WEB_URL)
`--no-open`	print the URL only

JSON · supports --json

pagr claude channel-setup#

wire the Pagr channel server into a project .mcp.json (research preview, dev flag only).

$pagr claude channel-setup [options]

Adds or removes only the `pagr` entry under `mcpServers`; every other server and top-level key in the file is preserved, and it refuses to overwrite a .mcp.json it cannot parse. See the Channels page — this is a flagged research-preview path.

Options for pagr claude channel-setup
Flag	Effect
`--project <path>`	project directory (default: cwd)
`--server <path>`	path to the built channel server.mjs
`--remove`	remove the pagr entry instead of adding it

JSON · supports --json
Exits · 5 on an unparseable .mcp.json, a missing directory, or a missing channel server

pagr logout#

stop the daemon, delete the device key and pairing config.

$pagr logout [options]

Removes the launch agent, deletes the private key from the Keychain, and removes config.json, sessions.json and replay.json. Projects are kept unless you pass --purge. Also prints a reminder to revoke the device in the dashboard.

Options for pagr logout
Flag	Effect
`--purge`	also remove the project registry

JSON · supports --json

pagr uninstall#

logout, remove the launch agent and delete ~/.pagr.

$pagr uninstall [options]

Prompts for confirmation unless you pass --yes, then does everything `logout --purge` does and removes the whole PAGR_HOME directory. Finish with `npm uninstall -g @pagr/cli`.

Options for pagr uninstall
Flag	Effect
`-y, --yes`	do not ask for confirmation

JSON · supports --json
Exits · 2 when you decline the prompt or stdin is not a TTY

Exit codes#

Exit codes
Code	Meaning	When
`0`	ok	the command succeeded — including `--help` and `--version`
`1`	error	an unexpected failure, or a network error during pairing
`2`	usage	a bad flag or argument, or a confirmation you declined
`3`	daemon not running	a command that needs the daemon could not reach the socket
`4`	not paired	this Mac has no device identity yet
`5`	precondition failed	doctor found a failure, or the project registry refused the request

Environment#

Environment variables read by the CLI and daemon
Variable	Value	Effect
`PAGR_HOME`	`path`	Where local state lives. Default ~/.pagr.
`PAGR_API_URL`	`url`	API base URL for pairing. Default https://api.pagr.dev.
`PAGR_WEB_URL`	`url`	Dashboard base URL used by `billing` and `logout`. Default https://app.pagr.dev.
`PAGR_LOG_LEVEL`	`debug`	Raises the daemon log level. Anything else is treated as info.
`PAGR_DEBUG`	`1`	Prints stack traces on unexpected CLI errors.
`PAGR_MOCK_AGENTS`	`1`	Runs scripted mock agents instead of real ones — same as `pagr daemon run --mock`.
`PAGR_MOCK_AGENT_DELAY_MS`	`ms`	Stretches the scripted mock turns. Used by the end-to-end tests.
`PAGR_INSECURE_FILE_STORE`	`1`	Stores the device private key in ~/.pagr/secrets.json instead of the Keychain. For CI and headless machines only; the daemon warns whenever it is set.
`PAGR_CLAUDE_CHANNEL`	`1`	Enables the flagged Claude Code channel path. Off by default.
`PAGR_CHANNEL_SERVER`	`path`	Overrides the resolved path to the Pagr channel server for `claude channel-setup`.

Full configuration, including the control-plane side, is in configuration.