CLI reference

Every command accepts --help for the full list of flags. Session, request and task IDs can be shortened to any unique prefix (s_4k2m, r_9x, t_2b).

Getting started

Command	What it does
pilothouse setup	Install hooks for Claude Code and Codex, install and start the user service, and run the checks from doctor.
pilothouse doctor	Check your setup (daemon, hooks, service, remote access) and print what to fix.

Everyday

Command	What it does
pilothouse	Open the terminal inbox (same as pilothouse inbox).
pilothouse inbox	Live view of sessions and pending requests; approve or deny from the keyboard.
pilothouse ls	List sessions and their states. Wrapped sessions you can attach to are marked.
pilothouse approve <request>	Allow a pending request.
pilothouse deny <request>	Deny a pending request.
pilothouse log	Recent events: tool calls, policy decisions, approvals.
pilothouse explain <session>	Why a session is in its current state: the evidence and the rule that decided it.
pilothouse here	Treat me as at the desk.
pilothouse away	Treat me as away: hold requests for my devices.
pilothouse auto	Go back to idle detection.

Policy

Command	What it does
pilothouse policy init	Write a starter ~/.pilothouse/policy.yaml with examples.
pilothouse policy check [file]	Validate a policy file.
pilothouse policy test --tool … [--command …] [--path …] [--agent …] [--cwd …]	Evaluate a hypothetical tool call and show the outcome and matching rules.
pilothouse policy replay [--since 7d]	Re-evaluate logged tool calls against the current rules and show what would change.
pilothouse policy trust [repo]	Trust a repository’s .pilothouse/policy.yaml (allows its allow rules).
pilothouse policy untrust [repo]	Stop trusting it.
pilothouse policy status	Loaded files, rule counts, ignored rules and errors.

See Policies.

Running agents

Command	What it does
pilothouse run [-n name] [-d] [--] <cmd> [args…]	Run an agent in wrap mode. Detach with ctrl+\.
pilothouse attach <session>	Re-attach to a wrapped session.
pilothouse task new [--agent …] [--base …] [--name …] [-a] "<prompt>"	New task: worktree + branch + agent.
pilothouse task ls	List tasks and their status.
pilothouse task diff <task>	Show git diff base...branch.
pilothouse task done <task> [--pr] [--keep]	Finish: optionally push and open a PR; remove the worktree unless --keep.
pilothouse task abandon <task>	Discard a task.

Phone and remote

Command	What it does
pilothouse remote tailscale	Serve the web app over HTTPS on your tailnet with Tailscale Serve.
pilothouse remote status	Show the current remote address.
pilothouse remote off	Stop serving.
pilothouse pair	Show a QR code and one-time link to pair a phone or browser.
pilothouse devices	List paired devices; rename or revoke them.
pilothouse open	Open the web app in this machine’s browser, signed in.

See Phone setup.

Daemon and setup

Command	What it does
pilothouse start / stop / status	Control the daemon.
pilothouse daemon	Run the daemon in the foreground (logs to stderr).
pilothouse service	Install, remove or inspect the launchd / systemd user service.
pilothouse hooks install / uninstall / status	Manage the agent hooks.
pilothouse notify test	Send a test notification to every configured channel.
pilothouse version	Print the version.

pilothouse hook <agent> is the hook shim the agents call; you don’t run it yourself.

Exit codes and errors

Errors say what to do next, for example daemon not running — run pilothouse start. Commands exit non-zero on failure.