DOCS / REFERENCE / CLI

birch pr

birch pr drives pull requests without the GUI: check one out into a fresh worktree by number or URL, open a PR for the current worktree’s branch with smart prefill, merge with your chosen strategy, and list what’s open.

All four subcommands require a connected git-host account (GitHub, GitLab, or Azure DevOps) — see Integrations overview. Without one, pr create exits 2 with No integration account configured. Add one in the GUI before opening a PR., and the others have no PRs to resolve.

birch pr checkout

birch pr checkout <url-or-id>

<url-or-id> is the PR’s external id (e.g. 1234) or its full URL as your provider prints it. The PR must already be known to Birch (it appears in birch pr list); an unknown or ambiguous id exits 1.

Checkout creates a dedicated worktree for the PR’s branch — the worktree-first model, with the usual file carryover — or reuses the existing one when the PR was checked out before.

Text output starts with checked out (new worktree) or exists (reused):

checked out  feature/abc-123  /Users/you/dev/my-repo-feature-abc-123

--json output:

{
  "pullRequestId": "9f1e4a3b-…",
  "externalId": "1234",
  "worktreeId": "0b6f2c1e-…",
  "path": "/Users/you/dev/my-repo-feature-abc-123",
  "branch": "feature/abc-123",
  "alreadyExisted": false
}

birch pr create

birch pr create [--title <text>] [--body <text>] [--base <branch>] [--draft]

Runs against the current directory: run it from inside a registered repository’s worktree with a checked-out branch — that branch becomes the PR’s source. From a repository root with no checked-out branch it exits 2 with Current directory is a repository root with no checked-out branch. Run from inside a worktree.

Option	Meaning
`--title <text>`	PR title. When omitted, prefilled (see below).
`--body <text>`	PR description. When omitted, prefilled with the branch’s own commits as a bullet list.
`--base <branch>`	Target branch to merge into. Defaults to the repository’s default branch; when neither exists the command asks you to pass `--base`.
`--draft`	Open the PR as a draft.

Prefill. The title falls back through: the source Task’s title (when the worktree was launched from an Inbox task) → the branch’s oldest own commit → a humanized branch name. This is the same chain the GUI dialog uses, minus the agent-session title (reading agent transcripts is the app’s job, not the CLI’s). If nothing usable is found, the command exits 2 with Could not derive a PR title from this branch. Pass --title.

Account resolution. The command needs exactly one usable integration account (verified accounts are preferred). With several candidates it refuses to guess and exits 2 naming them.

Text output is the new PR’s URL. --json output:

{
  "externalId": "1234",
  "url": "https://github.com/org/repo/pull/1234"
}

birch pr merge

birch pr merge <url-or-id> [--strategy merge|squash|rebase] [--delete-source]

Argument / option	Meaning
`<url-or-id>`	Required. PR external id or full URL.
`--strategy`	Merge strategy: `merge` (default), `squash`, or `rebase`.
`--delete-source`	Delete the source branch after a successful merge.

Text output:

merged  #1234  (squash)  source branch deleted

--json output:

{
  "pullRequestId": "9f1e4a3b-…",
  "externalId": "1234",
  "strategy": "Squash",
  "deleteSourceBranch": true,
  "merged": true
}

birch pr list

birch pr list [--repo <name>] [--all]

Option	Meaning
`--repo <name>`	Repository name. Defaults to the repository of the current directory.
`--all`	Include merged/closed PRs, not just open ones (open includes drafts).

Text output is a table with columns #, STATE, and TITLE, each row ending with the branch flow (source -> target). Empty result prints (no open pull requests) (or (no pull requests) with --all).

--json returns an array of objects: pullRequestId, externalId, url, title, state, sourceBranch, targetBranch.

Examples

# Review a colleague's PR in an isolated worktree
birch pr checkout 1234
cd "$(birch pr checkout 1234 --json | jq -r '.path')"

# Open a draft PR against a release branch
birch pr create --base release/2.4 --draft

# Squash-merge and clean up
birch pr merge 1234 --strategy squash --delete-source