birch CLI overview

birch is the companion command line: create and remove worktrees, check out and open pull requests, run AI reviews, and query state — from any terminal, scriptable with --json. It talks to a running Birch app over a local pipe when one is there, and most commands work standalone when it isn’t.

Installing to PATH

The CLI ships inside the app. Install it from Settings → Claude Code (or Settings → Codex) with the Install birch CLI to PATH button:

Platform	What happens
macOS	Creates a symlink /usr/local/bin/birch pointing at the bundled CLI. Birch tries without privileges first; if that fails it re-runs the link through the system administrator prompt.
Windows	Appends the CLI’s folder to your user PATH (and to the current process, so the running app sees it immediately).

After installing, open a new terminal and verify:

terminal

birch --help

The same Settings pane shows the install status and warns when a different birch binary is first on your PATH and shadows the bundled one.

Command tree

Command	What it does	Reference
birch worktree new <ticket>	Create a worktree on a fresh branch	birch worktree
birch worktree ls	List worktrees across all registered repositories	birch worktree
birch worktree rm <name>	Remove a worktree (optionally its branch)	birch worktree
birch pr checkout <url-or-id>	Check a PR out into a worktree	birch pr
birch pr create	Open a PR for the current worktree’s branch	birch pr
birch pr merge <url-or-id>	Merge a PR	birch pr
birch pr list	List pull requests for a repository	birch pr
birch review run <pr-id>	Run an AI code review on a PR	birch review
birch status	Summarize repositories, worktrees, PRs, reviews	Utility commands
birch open	Continue the current agent session in the Birch app	Utility commands
birch agent-event	Plugin plumbing: relay an agent status event	Utility commands
birch statusline	Plugin plumbing: Claude Code statusLine command	Utility commands

Global flags

Both flags are accepted by every command:

Flag	Effect
--json	Emit machine-readable JSON output on stdout.
--verbose	Print diagnostic messages to stderr (e.g. IPC routing).

Plus the built-in --help and --version.

Errors always print to stderr as birch: <message>, and --verbose diagnostics go to stderr with the same prefix — stdout stays clean for --json pipelines. JSON output is indented, and fields with null values are omitted (for example, branch is absent for a detached worktree in worktree ls --json).

Exit codes

Code	Meaning
0	Success.
1	Not found or ambiguous (a repository, worktree, or PR the command couldn’t resolve). Also: birch open couldn’t launch the app or the app didn’t accept the request.
2	Invalid operation (e.g. no integration account configured) or any other error.
3	review run only — the review didn’t complete.
130	Cancelled (Ctrl+C).

agent-event and statusline are the exception: they always exit 0 — they run as agent hooks, and a failing hook would disturb the agent.

App integration: IPC vs standalone

birch looks for a running Birch app on a local named pipe. Commands fall into three groups:

Mode	Commands	Behavior
App first, local fallback	worktree new, worktree rm, pr checkout, review run	Relayed through the running app so the UI updates live; executed locally when the app isn’t running. --verbose prints which path was taken: GUI detected — relayed via IPC or GUI not running — executing locally.
Pipe only	agent-event, statusline, open	Talk only to the pipe and never touch the database. When the app isn’t running: open launches it, statusline still prints its status text to stdout (only the relay to the app is silently dropped), and agent-event silently does nothing.
Always local	worktree ls, pr create, pr merge, pr list, status	Run against Birch’s local state directly, app running or not.

Scripting with —json

terminal

# Every worktree path across all repositories
birch worktree ls --json | jq -r '.[].path'

# How many of my PRs are open?
birch status --json | jq '.openPullRequestsForMe'

# Open PRs as "id<TAB>title"
birch pr list --json | jq -r '.[] | "\(.externalId)\t\(.title)"'

# Create a worktree and cd into it
cd "$(birch worktree new ABC-123 --json | jq -r '.Path')"

Logs

CLI diagnostics are written to daily-rolling files under logs/ in Birch’s data folder (birch-cli-<date>.log). See Storage & data for the exact location and what to attach to a bug report.