# shelbi merge

Merge a workspace's branch into the project's default branch, locally or via a GitHub PR.

```text
shelbi merge [OPTIONS] <ID>
```

`shelbi merge` bridges a task in `review` and a clean default branch. By
default it squash-merges the task's branch into the project's default branch
(typically `main`) using the workspace's commit message. Pass `--pr` to push
the branch and open a GitHub pull request instead, for teams that require a
code-review roundtrip before anything lands.

The command does not move the card. After a successful local merge, the
orchestrator's "merged → done" sweep (or you, manually) moves the task to
`done`. After a `--pr` merge, the card stays in `review` until the PR
itself lands.

## Arguments

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `<ID>` | string | — | Task id whose branch to merge (required). |

## Flags

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--pr` | flag | off | Push the branch and open a GitHub PR instead of a local squash-merge. |
| `-p, --project <PROJECT>` | string | env / cwd lookup | Project to operate on. |

## Examples

Squash-merge a reviewed task locally:

```bash
shelbi merge docs-write-cli-reference-pages
```

Open a GitHub PR for the branch instead of merging locally:

```bash
shelbi merge docs-write-cli-reference-pages --pr
```

## See also

- [Workflows](/docs/guides/getting-started/workflows#lifecycle-who-moves-a-task-between-the-default-statuses)
  — where `Review` and `Done` sit in the default workflow's lifecycle
  and what each transition signals.
- [Review workspaces](/docs/concepts/review-workspaces) — the upstream step
  that puts the branch in front of a reviewer before merge.