JSON output

Every command that prints data accepts --json and emits a stable, documented schema. This page is the contract.

`birch worktree list --json`

{
  "repo": "/Users/me/projects/my-app",
  "worktrees": [
    {
      "path": "/Users/me/projects/my-app/main",
      "branch": "main",
      "head": "a1b2c3d4",
      "isCurrent": false,
      "isClean": true
    },
    {
      "path": "/Users/me/projects/my-app/feature-auth",
      "branch": "feature/auth",
      "head": "e5f6a7b8",
      "isCurrent": true,
      "isClean": false,
      "uncommittedFiles": 3
    }
  ]
}

`birch worktree new --json`

{
  "ok": true,
  "worktree": {
    "path": "/Users/me/projects/my-app/feature-42",
    "branch": "feature/issue-42",
    "head": "1234abcd"
  }
}

On failure:

{
  "ok": false,
  "error": "worktree-exists",
  "message": "A worktree for feature/issue-42 already exists at …"
}

`birch commit suggest --json`

{
  "model": "claude-sonnet-4-6",
  "tokensUsed": 1820,
  "message": "feat(auth): add device-trust check to login flow\n\n…"
}

Stability guarantees

Once the CLI hits 1.0, JSON keys and types follow semver:

New keys can be added in minor releases.
Existing keys keep their type and meaning until the next major.
Field removal happens only at major version bumps, with at least one minor of deprecation warnings.