# Pull request and issue commands

Open, review and merge pull requests, work issues, and see what needs you from the terminal.

The guides are [Pull requests](https://status.sailfork.com/docs/pull-requests), [Code review](https://status.sailfork.com/docs/code-review), [Issues](https://status.sailfork.com/docs/issues) and [Notifications and activity](https://status.sailfork.com/docs/notifications).

## sailfork pr

Work with pull requests.

### sailfork pr list

List pull requests. Also `pr ls`. Read-only.

```sh
sailfork pr list [flags]
```

| Flag | What it does |
| --- | --- |
| `--state <STATE>` | Which pull requests to list. One of `open`, `draft`, `merged`, `closed`, `all`. Default `open`. |
| `--author <AUTHOR>` | Only pull requests by this handle, or `@me` |
| `--head <HEAD>` | Only pull requests from this branch. |
| `--base <BASE>` | Only pull requests into this branch. |
| `--file <PATH>` | Only pull requests that change this file (a folder when it ends in `/`) |
| `--search <TEXT>` | Only pull requests whose title or description contains this. |
| `--limit <LIMIT>` | Most rows to print. Default `30`. |
| `--all` | Keep fetching pages until there are no more. |
| `--cursor <CURSOR>` | Continue after the `nextCursor` of an earlier run. |

Examples:

```sh
sailfork pr list
sailfork pr list --state merged --limit 10 --json=number,title,url
sailfork pr list --author @me --base main
sailfork pr list --head feat/login --state all --json=number,state
sailfork pr list --file crates/server/src/ci/ --state all
sailfork pr list --search "login redirect"
sailfork pr list --all --json --jq '.items[] | select(.checks == "fail") | .number'
```

### sailfork pr view

Show a pull request. Also `pr show`. Read-only.

```sh
sailfork pr view [NUMBER]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

Examples:

```sh
sailfork pr view 12
sailfork pr view --json=number,state,headSha,url
sailfork pr view 12 --json title,body,threads
sailfork pr view 12 --summary
```

### sailfork pr create

Open a pull request from the current branch. Changes something.

```sh
sailfork pr create [flags]
```

| Flag | What it does |
| --- | --- |
| `-t`, `--title <TITLE>` | Pull request title (default: taken from the commits) |
| `-b`, `--body <BODY>` | Description text (default: taken from the commits) |
| `--body-file <FILE>` | Read the description from a file, or `-` for stdin. |
| `--fill` | Take the title and description from the commits and never open an editor. |
| `--no-push` | Do not push the branch first; fail if it is not on the server. |
| `--base <BASE>` | Branch to merge into (default: the repository's default branch) |
| `--onto <NUMBER>` | Stack on this open or draft pull request: its branch becomes the base. |
| `--head <HEAD>` | Branch with the changes (default: the current branch) |
| `--draft` | Open it as a draft; `pr ready` publishes it. |
| `--reviewer <HANDLE>` | Ask this person (a handle that can read the repository) to review it. |
| `--issue <N>` | Issue this pull request closes (repeatable): adds `Closes #N`, moves the issue to in review, and merging closes it. A branch named issue/N-... links issue N without it. Repeatable. |

Examples:

```sh
sailfork pr create --fill
sailfork pr create --title "Fix the login redirect" --body "Sends users back to the page they came from."
sailfork pr create --fill --base release --json --jq .url
sailfork pr create --fill --draft --reviewer ada
sailfork pr create --fill --onto 12
```

### sailfork pr checkout

Check out a pull request's branch. Changes something.

```sh
sailfork pr checkout <NUMBER>
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Pull request number |

Examples:

```sh
sailfork pr checkout 12
sailfork pr checkout 12 --remote upstream
```

### sailfork pr diff

Show a pull request's diff. Read-only.

```sh
sailfork pr diff [NUMBER]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

Examples:

```sh
sailfork pr diff 12
sailfork pr diff 12 | diffstat
sailfork pr diff --json --jq '.files[].path'
```

### sailfork pr merge

Merge a pull request; `--stack` merges the ones it is stacked on first. Changes something. Supports `--dry-run`.

```sh
sailfork pr merge [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

| Flag | What it does |
| --- | --- |
| `--dry-run` | Check that the pull request can merge and change nothing. |
| `--method <METHOD>` | How the commits land (default: fast-forward when the base has not moved, else a merge commit) One of `merge`, `squash`, `rebase`, `fast-forward`. |
| `--match-head-commit <SHA>` | Merge only if the head branch is still at this commit (a sha or its start); else exit 10 and merge nothing. |
| `--keep-branch` | Keep the head branch (by default the server deletes it unless a branch protection keeps it) |
| `--bypass-queue <REASON>` | Merge straight into a branch that takes merges through its merge queue, past the queue (repository admins only; the reason is recorded in the audit log as merge_queue.bypass) |
| `--auto` | Merge once the checks pass: the server waits and merges as you, only if the branch is still at the head you reviewed (--match-head-commit, else the head now), and this command returns at once. With --stack the command itself waits for each level. |
| `--cancel-auto` | Turn auto-merge off for this pull request. |
| `--stack` | Merge the open pull requests this one is stacked on first, bottom-up, then this one, each into the bottom one's base; stops at the first failure. Each level follows the one below onto that base only when the branch below is deleted, so not with --keep-branch. |

Examples:

```sh
sailfork pr merge 12
sailfork pr merge 12 --method squash
sailfork pr merge 12 --match-head-commit 3f2a9c1
sailfork pr merge 12 --dry-run
sailfork pr merge 12 --auto --method squash
sailfork pr merge 12 --stack --method squash
```

### sailfork pr stack

Show the stack of pull requests a pull request belongs to. Read-only.

```sh
sailfork pr stack [NUMBER]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

Examples:

```sh
sailfork pr stack
sailfork pr stack 12
sailfork pr stack 12 --json --jq '.items[] | "\(.depth) #\(.number)"'
```

### sailfork pr update-branch

Merge the base branch into a pull request's branch on the server, for a merge refused as behind. Changes something.

```sh
sailfork pr update-branch [NUMBER]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

### sailfork pr conflicts

List the files that keep a pull request's branch from taking its base, or print one with conflict markers. Read-only.

```sh
sailfork pr conflicts [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

| Flag | What it does |
| --- | --- |
| `--path <PATH>` | Only this file. |
| `--merged` | With --path, print only that file with its conflict markers, to edit and send back with `pr resolve --file` |

Examples:

```sh
sailfork pr conflicts 12
sailfork pr conflicts 12 --json --jq '.files[] | select(.merged != null) | .path'
sailfork pr conflicts 12 --path src/lib.rs --merged > lib.rs
```

### sailfork pr resolve

Resolve a pull request's conflicts on the server: take a side or send edited files, in one merge commit. Changes something. Supports `--dry-run`.

```sh
sailfork pr resolve [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

| Flag | What it does |
| --- | --- |
| `--take <SIDE>` | Take this side's version of every conflicting file not given a --file, or with --path of those files only. One of `head`, `base`. |
| `--path <PATH>` | A file --take applies to (repeat for several) Repeatable. |
| `--file <PATH=LOCALFILE>` | Send LOCALFILE's content as the resolution of PATH (repeat for several) Repeatable. |
| `--dry-run` | Print what would be sent for each file and change nothing. |

Examples:

```sh
sailfork pr resolve 12 --file src/lib.rs=lib.rs
sailfork pr resolve 12 --file src/lib.rs=lib.rs --take base --dry-run
sailfork pr resolve 12 --take head
```

### sailfork pr ready

Mark a draft pull request ready for review. Changes something.

```sh
sailfork pr ready [NUMBER]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

Examples:

```sh
sailfork pr ready 12
```

### sailfork pr draft

Turn an open pull request back into a draft. Changes something.

```sh
sailfork pr draft [NUMBER]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

Examples:

```sh
sailfork pr draft 12
```

### sailfork pr close

Close a pull request; `pr reopen` undoes it. Changes something. Supports `--dry-run`.

```sh
sailfork pr close [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

| Flag | What it does |
| --- | --- |
| `--dry-run` | Say which pull request would close and change nothing. |

Examples:

```sh
sailfork pr close 12
sailfork pr close 12 --dry-run
```

### sailfork pr reopen

Reopen a pull request. Changes something.

```sh
sailfork pr reopen [NUMBER]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

Examples:

```sh
sailfork pr reopen 12
```

### sailfork pr review

Approve or request changes on a pull request, with comments on lines of the diff. Changes something.

```sh
sailfork pr review [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

| Flag | What it does |
| --- | --- |
| `--approve` | Approve the pull request. |
| `--request-changes` | Ask for changes; needs --body. |
| `-b`, `--body <BODY>` | Review text; required with --request-changes. |
| `--body-file <FILE>` | Read the body from a file, or `-` for stdin. |
| `--inline <PATH:LINE:TEXT>` | A comment on a line of the diff, posted before the verdict: `PATH:LINE:TEXT` (LINE is `12` or a range `12-18`), or `PATH:LINE@old:TEXT` for the old side (repeat for several) Repeatable. |

Examples:

```sh
sailfork pr review 12 --approve
sailfork pr review 12 --request-changes --body "The migration drops a column that is still read."
sailfork pr review 12 --request-changes --body "Two problems." --inline "src/db.rs:41:This drops the column." --inline "src/db.rs:7@old:Still read here."
```

### sailfork pr comment

Add a comment to a pull request. Changes something.

```sh
sailfork pr comment [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

| Flag | What it does |
| --- | --- |
| `-b`, `--body <BODY>` | Comment text. |
| `--body-file <FILE>` | Read the comment from a file, or `-` for stdin. |
| `--attach <PATH>` | Upload a file and link it in the comment (repeat for several); images and videos show inline. Repeatable. |
| `--path <PATH>` | Comment on this file of the diff (with --line) |
| `--line <LINE>` | Comment on this line of the diff (with --path) |
| `--start-line <START_LINE>` | Start a multi-line comment here, ending at --line (same side) |
| `--side <SIDE>` | Which side of the diff the line counts on. One of `old`, `new`. Default `new`. |
| `--reply-to <THREAD>` | Reply in this review thread, by id from `pr threads` |

Examples:

```sh
sailfork pr comment 12 --body "Rebased on main."
sailfork pr comment 12 --attach after.png
sailfork pr comment 12 --path src/db.rs --line 41 --body "Add an index here."
sailfork pr comment 12 --reply-to t-1a2b --body "Fixed in the last commit."
```

### sailfork pr edit

Edit a pull request's title or description. Changes something.

```sh
sailfork pr edit [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

| Flag | What it does |
| --- | --- |
| `-t`, `--title <TITLE>` | New title. |
| `-b`, `--body <BODY>` | New description, replacing the old one. |
| `--body-file <FILE>` | Read the description from a file, or `-` for stdin. |
| `--attach <PATH>` | Upload a file and link it at the end of the description (repeat for several); without --body the current description is kept. Repeatable. |
| `--reviewer <HANDLE>` | Ask this person (a handle that can read the repository) to review it. |
| `--base <BRANCH>` | Retarget an open or draft pull request onto this branch. |
| `--onto <NUMBER>` | Retarget onto this open or draft pull request's branch, stacking on it. |

Examples:

```sh
sailfork pr edit 12 --title "Fix the login redirect on Safari"
sailfork pr edit 12 --body-file notes.md
sailfork pr edit 12 --attach screenshot.png
sailfork pr edit 12 --reviewer ada
sailfork pr edit 12 --base release
sailfork pr edit 12 --onto 11
```

### sailfork pr checks

Show a pull request's CI checks; `--watch` or `sailfork wait pr N --checks` waits for them. Read-only.

```sh
sailfork pr checks [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

| Flag | What it does |
| --- | --- |
| `--watch` | Poll until no check is pending; exit 1 if any failed. |
| `--fail-fast` | With --watch, stop at the first failed check. |
| `--interval <SECS>` | Seconds between polls with --watch. Default `5`. |

Examples:

```sh
sailfork pr checks 12
sailfork pr checks 12 --watch
sailfork pr checks 12 --watch --fail-fast
sailfork pr checks --json --jq '.checks[] | select(.state == "fail") | .run'
```

### sailfork pr threads

List a pull request's review threads and conversation comments. Also `pr comments`. Read-only.

```sh
sailfork pr threads [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

| Flag | What it does |
| --- | --- |
| `--unresolved` | Only threads that are not resolved. |

Examples:

```sh
sailfork pr threads 12
sailfork pr threads 12 --unresolved --json
sailfork pr comments 12
```

### sailfork pr feedback

Unresolved review threads with the code each points at and any suggested change, by file. Read-only.

```sh
sailfork pr feedback [NUMBER]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Pull request number (default: the open pull request for the current branch) |

Examples:

```sh
sailfork pr feedback 12
sailfork pr feedback 12 --json --jq '.threads[] | "\(.path):\(.line) \(.id)"'
```

### sailfork pr thread resolve

Mark a review thread resolved, or every one of yours (--mine) or all of them (--all). Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork pr thread resolve [ID] [flags]
```

| Argument | What it is |
| --- | --- |
| `[ID]` | Thread id, from `pr threads` or `pr feedback` |

| Flag | What it does |
| --- | --- |
| `-n`, `--number <NUMBER>` | Pull request number (default: the open pull request for the current branch) |
| `--mine` | Resolve every unresolved thread whose last comment is yours. |
| `--all` | Resolve every unresolved thread (needs --yes without a terminal) |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork pr thread resolve t-1a2b -n 12
sailfork pr thread resolve --mine -n 12
sailfork pr thread resolve --all --yes -n 12
```

### sailfork pr thread unresolve

Reopen a resolved review thread. Changes something.

```sh
sailfork pr thread unresolve <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Thread id, from `pr threads` |

| Flag | What it does |
| --- | --- |
| `-n`, `--number <NUMBER>` | Pull request number (default: the open pull request for the current branch) |

Examples:

```sh
sailfork pr thread unresolve t-1a2b -n 12
```

A pull request set to merge automatically waits in the repository's merge queue. `queue status` shows what is waiting and `queue leave` takes one out.

## sailfork queue

See and leave a repository's merge queue.

### sailfork queue status

Show whether the queue is on, the pull requests waiting (next first), the batches being tested and what left the queue lately with why. Read-only.

```sh
sailfork queue status
```

### sailfork queue leave

Take a pull request out of the queue (the same as `pr merge --cancel-auto`). Changes something.

```sh
sailfork queue leave <NUMBER>
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Pull request number |

## sailfork issue

Work with issues.

### sailfork issue list

List issues (open ones by default). Also `issue ls`. Read-only.

```sh
sailfork issue list [flags]
```

| Flag | What it does |
| --- | --- |
| `--state <STATE>` | Open, closed or all issues. One of `open`, `closed`, `all`. Default `open`. |
| `--stage <STAGE>` | Only issues at this stage. One of `reported`, `triaged`, `fixing`, `review`. |
| `--status <STATUS>` | Triage, ready, in-progress, in-review, done, canceled, duplicate or all. |
| `--label <LABEL>` | Only issues with this label. |
| `--assignee <ASSIGNEE>` | A handle, or `none` for unassigned issues. |
| `--author <AUTHOR>` | Only issues opened by this handle, or `@me` |
| `--mentions <HANDLE>` | Only issues whose title or description @mentions this handle, or `@me` |
| `--priority <PRIORITY>` | Only issues with this priority. One of `urgent`, `high`, `medium`, `low`, `none`. |
| `--milestone <MILESTONE>` | Only issues in this milestone. |
| `--parent <PARENT>` | Only sub-issues of this issue. |
| `-q`, `--query <QUERY>` | Search titles and bodies. |
| `--sort <SORT>` | Order of the rows. One of `newest`, `oldest`, `priority`, `updated`. |
| `--limit <LIMIT>` | Most rows to print. Default `30`. |
| `--all` | Keep fetching pages until there are no more. |
| `--cursor <CURSOR>` | Continue after the `nextCursor` of an earlier run. |

Examples:

```sh
sailfork issue list
sailfork issue list --status ready --priority high
sailfork issue list --assignee none --label bug --json=number,title,status
sailfork issue list --query 'login loop' --all
sailfork issue list --author @me --mentions ada
```

### sailfork issue view

Show an issue with its relations, comments and timeline. Also `issue show`. Read-only.

```sh
sailfork issue view <NUMBER>
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

Examples:

```sh
sailfork issue view 7
sailfork issue view 7 --json --jq '.comments[-1].body'
sailfork issue view 7 --json title,state,labels
```

### sailfork issue create

Create an issue. Also `issue open`. Changes something.

```sh
sailfork issue create [flags]
```

| Flag | What it does |
| --- | --- |
| `-t`, `--title <TITLE>` | Issue title. Required. |
| `-b`, `--body <BODY>` | Description text. |
| `--body-file <FILE>` | Read the body from a file, or `-` for stdin. |
| `-l`, `--label <LABELS>` | Label to add (repeat or comma-separate for several) Repeatable. |
| `--priority <PRIORITY>` | Urgent, high, medium, low or none. One of `urgent`, `high`, `medium`, `low`, `none`. |
| `--estimate <ESTIMATE>` | Size: 1, 2, 3, 5 or 8. |
| `--due <DUE>` | Due date, YYYY-MM-DD. |
| `--milestone <MILESTONE>` | Milestone name. |
| `--parent <PARENT>` | Make this a sub-issue of that issue number. |
| `--blocked-by <BLOCKED_BY>` | Issue number that must finish first (repeat for several) Repeatable. |
| `--assignee <ASSIGNEE>` | The one person who answers for the issue. |
| `--stage <STAGE>` | Starting stage: reported, triaged, fixing or review. One of `reported`, `triaged`, `fixing`, `review`. |
| `--attach <PATH>` | Upload a file and link it in the text (repeat for several) Repeatable. |
| `--idempotency-key <IDEMPOTENCY_KEY>` | Retrying with the same key returns the issue already created. |

Examples:

```sh
sailfork issue create --title "Login loops on Safari" --label bug --priority high
sailfork issue create -t "Retry safely" --idempotency-key retry-7 --json --jq .number
```

### sailfork issue edit

Change any field of an issue. Changes something.

```sh
sailfork issue edit <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

| Flag | What it does |
| --- | --- |
| `-t`, `--title <TITLE>` | New title. |
| `-b`, `--body <BODY>` | New description, replacing the old one. |
| `--body-file <FILE>` | Read the body from a file, or `-` for stdin. |
| `--stage <STAGE>` | Move to this stage. One of `reported`, `triaged`, `fixing`, `review`. |
| `--status <STATUS>` | Set the status: triage, ready, in-progress, in-review, done, canceled or duplicate (sets stage and state together) |
| `--assignee <ASSIGNEE>` | The one person who answers for the issue. |
| `--no-assignee` | Leave the issue without an assignee. |
| `--assign-agent <TOKEN>` | Ask one of your agent tokens (a name or id from `sailfork token list`) to take the issue. |
| `--no-agent` | Withdraw the request to your agent. |
| `-l`, `--label <LABELS>` | Replace the labels (repeat or comma-separate for several) Repeatable. |
| `--clear-labels` | Remove every label. |
| `--add-label <ADD_LABEL>` | Add this label (repeat or comma-separate for several) Repeatable. |
| `--remove-label <REMOVE_LABEL>` | Remove this label (repeat or comma-separate for several) Repeatable. |
| `--priority <PRIORITY>` | Urgent, high, medium, low or none. One of `urgent`, `high`, `medium`, `low`, `none`. |
| `--estimate <ESTIMATE>` | Size: 1, 2, 3, 5 or 8. |
| `--no-estimate` | Clear the estimate. |
| `--due <DUE>` | Due date, YYYY-MM-DD. |
| `--no-due` | Clear the due date. |
| `--milestone <MILESTONE>` | Move to this milestone. |
| `--no-milestone` | Take it out of its milestone. |
| `--parent <PARENT>` | Make this a sub-issue of that issue number. |
| `--no-parent` | Make it a top-level issue again. |
| `--blocked-by <BLOCKED_BY>` | Replace the blockers (repeat for several) Repeatable. |
| `--clear-blockers` | Remove every blocker. |

Examples:

```sh
sailfork issue edit 7 --priority urgent --add-label regression
sailfork issue edit 7 --status ready
sailfork issue edit 7 --no-assignee --no-due --clear-blockers
sailfork issue edit 7 --title 'Login loops on Safari 17'
sailfork issue edit 7 --assign-agent claude-laptop
sailfork issue edit 7 --no-agent
```

### sailfork issue comment

Comment on an issue, or post a progress update. Changes something.

```sh
sailfork issue comment <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

| Flag | What it does |
| --- | --- |
| `-b`, `--body <BODY>` | Comment text. |
| `--body-file <FILE>` | Read the comment from a file, or `-` for stdin. |
| `--update` | Mark it as a progress update: what is done, what is next. |
| `--attach <PATH>` | Upload a file and link it in the text (repeat for several) Repeatable. |

Examples:

```sh
sailfork issue comment 7 --body "Reproduced on Safari 17.2."
sailfork issue comment 7 --update --body "Parser done; tests next."
```

### sailfork issue close

Close an issue. Changes something.

```sh
sailfork issue close <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

| Flag | What it does |
| --- | --- |
| `--reason <REASON>` | Why it closes (default: done) One of `done`, `wont-do`, `duplicate`. |
| `--duplicate-of <DUPLICATE_OF>` | The issue this one duplicates (implies --reason duplicate) |
| `-c`, `--comment <COMMENT>` | Leave a comment with the close. |
| `--comment-file <FILE>` | Read the close comment from a file, or `-` for stdin. |

Examples:

```sh
sailfork issue close 7
sailfork issue close 7 --reason wont-do --comment "Out of scope for this quarter."
sailfork issue close 7 --duplicate-of 3
```

### sailfork issue reopen

Reopen a closed issue. Changes something.

```sh
sailfork issue reopen <NUMBER>
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

Examples:

```sh
sailfork issue reopen 7
```

### sailfork issue claim

Delegate an issue to yourself or your agent for a lease, or renew the lease. Changes something.

```sh
sailfork issue claim <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

| Flag | What it does |
| --- | --- |
| `--minutes <MINUTES>` | Lease length; the issue returns to Ready if it lapses, and delegating again before it ends renews it. |

Examples:

```sh
sailfork issue claim 7
sailfork issue claim 7 --minutes 120
```

### sailfork issue release

Hand a delegated issue back, optionally leaving a handoff note. Changes something.

```sh
sailfork issue release <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

| Flag | What it does |
| --- | --- |
| `--note <NOTE>` | What was done and what is left, for whoever picks it up. |
| `--note-file <FILE>` | Read the note from a file, or `-` for stdin. |

Examples:

```sh
sailfork issue release 7 --note "Parser done; the tests are left."
```

### sailfork issue context

Show the working context left on an issue, or write it for whoever picks the issue up next. Read-only.

```sh
sailfork issue context <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

| Flag | What it does |
| --- | --- |
| `--state <STATE>` | Where the work stands, in a few sentences (an empty string clears it) |
| `--tried <TEXT>` | An approach tried and how it went; repeat for each. Replaces the list. Repeatable. |
| `--file <PATH>` | A repository path that matters; repeat for each. Replaces the list. Repeatable. |
| `--next <TEXT>` | A step that is left; repeat for each. Replaces the list. Repeatable. |
| `--question <TEXT>` | An open question for a person; repeat for each. Replaces the list and marks the issue as needing input. Repeatable. |
| `--answered` | Mark the questions answered: empties that list. |
| `--branch <BRANCH>` | The branch the work is on. |
| `--clear` | Remove the whole context. |

### sailfork issue next

Get the most important ready issue, optionally delegating it to you. Changes something.

```sh
sailfork issue next [flags]
```

| Flag | What it does |
| --- | --- |
| `--status <STATUS>` | Status to pull from, as `issue list --status` takes it (default: ready, which includes issues whose lease lapsed) |
| `--stage <STAGE>` | Stage to pull from instead of a status: reported, triaged, fixing or review. One of `reported`, `triaged`, `fixing`, `review`. |
| `--label <LABEL>` | Only issues with this label. |
| `--milestone <MILESTONE>` | Only issues in this milestone. |
| `--claim` | Delegate the issue to you in the same call. |
| `--minutes <MINUTES>` | Lease length when claiming. |

Examples:

```sh
sailfork issue next
sailfork issue next --status triage
sailfork issue next --label bug --claim --json --jq .number
```

### sailfork issue start

Claim an issue and open a caisson (or a local branch) for it, ready to edit. Changes something.

```sh
sailfork issue start <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

| Flag | What it does |
| --- | --- |
| `--minutes <MINUTES>` | Lease length when the claim takes one. |
| `--local` | Create and check out the branch in the current clone instead of opening a caisson. |

Examples:

```sh
sailfork issue start 7
sailfork issue start 7 --json --jq .caisson.id
sailfork issue start 7 --local
```

### sailfork issue ship

Commit, open the pull request that closes the issue, optionally merge it, and hand the issue back. Changes something. Supports `--dry-run`.

```sh
sailfork issue ship [NUMBER] [flags]
```

| Argument | What it is |
| --- | --- |
| `[NUMBER]` | Issue number (default: the one the current branch issue/<n>-... works on) |

| Flag | What it does |
| --- | --- |
| `-m`, `--message <MESSAGE>` | Commit message for pending changes (default: `fix: <issue title> (#n)`) |
| `--wait` | Wait for the pull request's checks to pass; exit 1 if one fails or was cancelled. |
| `--merge` | Merge once the checks pass (waits for them) |
| `--method <METHOD>` | How --merge lands the commits. One of `merge`, `squash`, `rebase`, `fast-forward`. |
| `--keep-branch` | Keep the head branch after --merge. |
| `--local` | Ship the branch checked out in the current clone instead of the issue's caisson. |
| `--note <NOTE>` | Handoff note left when the lease is released (default: says where it shipped) |
| `--dry-run` | Show each step without doing it. |

Examples:

```sh
sailfork issue ship 7 --merge --method squash
sailfork issue ship 7 -m "fix(parser): accept empty config" --wait
sailfork issue ship 7 --merge --dry-run
sailfork issue ship --local --merge
```

### sailfork issue subscribe

Follow an issue to be notified of its activity. Changes something.

```sh
sailfork issue subscribe <NUMBER>
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

Examples:

```sh
sailfork issue subscribe 7
```

### sailfork issue react

Add or take back your reaction on an issue or one of its comments. Changes something.

```sh
sailfork issue react <NUMBER> <REACTION> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` |  |
| `<REACTION>` | +1, -1, laugh, hooray, confused, heart, rocket or eyes |

| Flag | What it does |
| --- | --- |
| `--comment <COMMENT>` | React to this comment id instead of the issue. |
| `--remove` | Take the reaction back. |

Examples:

```sh
sailfork issue react 12 rocket
sailfork issue react 12 +1 --comment c-abc123
sailfork issue react 12 heart --remove
```

### sailfork issue unsubscribe

Stop following an issue. Changes something.

```sh
sailfork issue unsubscribe <NUMBER>
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

Examples:

```sh
sailfork issue unsubscribe 7
```

## sailfork label

List the labels a repository's issues use.

### sailfork label list

List the repository's labels and the ones issues carry, most used first. Also `label ls`. Read-only.

```sh
sailfork label list
```

Examples:

```sh
sailfork label list
sailfork label list -R acme/app --json --jq '.items[].name'
```

### sailfork label create

Create a label. Changes something.

```sh
sailfork label create <NAME> [flags]
```

| Flag | What it does |
| --- | --- |
| `-d`, `--description <DESCRIPTION>` |  |

Examples:

```sh
sailfork label create bug --description "Something is broken"
```

### sailfork label edit

Rename a label or change its description; a new name reaches every issue that carries it. Changes something.

```sh
sailfork label edit <NAME> [flags]
```

| Flag | What it does |
| --- | --- |
| `--name-to <NAME_TO>` | The new name. |
| `-d`, `--description <DESCRIPTION>` |  |

Examples:

```sh
sailfork label edit bug --name-to defect
```

### sailfork label delete

Delete a label and remove it from every issue that carries it. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork label delete <NAME> [flags]
```

| Flag | What it does |
| --- | --- |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork label delete wontfix --yes
```

## sailfork milestone

List the milestones a repository's issues use.

### sailfork milestone list

List the repository's milestones and the ones issues are in, most used first. Also `milestone ls`. Read-only.

```sh
sailfork milestone list
```

Examples:

```sh
sailfork milestone list
sailfork milestone list --json --jq '.items[] | select(.open > 0) | .name'
```

### sailfork milestone create

Create a milestone. Changes something.

```sh
sailfork milestone create <TITLE> [flags]
```

| Flag | What it does |
| --- | --- |
| `-d`, `--description <DESCRIPTION>` |  |
| `--due <DUE>` | Due date, YYYY-MM-DD. |

Examples:

```sh
sailfork milestone create "v1.0" --due 2026-12-15 --description "First release"
```

### sailfork milestone edit

Retitle a milestone or change its description or due date. Changes something.

```sh
sailfork milestone edit <TITLE> [flags]
```

| Flag | What it does |
| --- | --- |
| `--title-to <TITLE_TO>` | The new title. |
| `-d`, `--description <DESCRIPTION>` |  |
| `--due <DUE>` | Due date, YYYY-MM-DD. |
| `--no-due` | Clear the due date. |

Examples:

```sh
sailfork milestone edit "v1.0" --due 2027-01-15
sailfork milestone edit "v1.0" --no-due
```

### sailfork milestone close

Close a milestone; its issues stay as they are. Changes something.

```sh
sailfork milestone close <TITLE>
```

Examples:

```sh
sailfork milestone close "v1.0"
```

### sailfork milestone reopen

Reopen a closed milestone. Changes something.

```sh
sailfork milestone reopen <TITLE>
```

Examples:

```sh
sailfork milestone reopen "v1.0"
```

### sailfork milestone delete

Delete a milestone and clear it from every issue in it. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork milestone delete <TITLE> [flags]
```

| Flag | What it does |
| --- | --- |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork milestone delete "v1.0" --yes
```

## sailfork attachment

Download files attached to issues and pull requests.

### sailfork attachment download

Download an attachment by the link a comment shows. Changes something.

```sh
sailfork attachment download <TARGET> [flags]
```

| Argument | What it is |
| --- | --- |
| `<TARGET>` | The attachment's link or path from a comment, or `<id>/<name>` (the repository comes from -R) |

| Flag | What it does |
| --- | --- |
| `-o`, `--output <FILE>` | File to write, or `-` for stdout (default: the attachment's name in the current directory) |
| `--force` | Overwrite the file if it exists. |

Examples:

```sh
sailfork attachment download /api/repos/acme/app/attachments/3f2a9c1e/after.png
sailfork attachment download 3f2a9c1e/after.png -R acme/app --output shots/after.png
sailfork attachment download 3f2a9c1e/report.pdf -R acme/app -o - | pdftotext - -
```

### sailfork attachment upload

Upload files to the repository and print a Markdown link for each, to place anywhere in a description or comment. Changes something.

```sh
sailfork attachment upload <PATH...>
```

| Argument | What it is |
| --- | --- |
| `<PATH...>` | Files to upload (up to 100 MB each); images and videos print as `![name](url)` so they show inline |

Examples:

```sh
sailfork attachment upload before.png after.png
sailfork attachment upload demo.gif -R acme/app --json --jq '.items[].markdown'
```

## sailfork status

What needs you: your open pull requests and their checks, reviews waiting on you, issues assigned to you; with -R, only that repository's. Read-only.

```sh
sailfork status
```

Examples:

```sh
sailfork status
sailfork status --json --jq '.authored[] | select(.checks == "failing") | .url'
```

## sailfork brief

Everything to start on an issue or pull request in one call: body, comments, threads with code, failed checks. Read-only.

```sh
sailfork brief <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue or pull request number |

| Flag | What it does |
| --- | --- |
| `--comments <N\|all>` | How many of the newest comments to show, or `all` Default `10`. |

Examples:

```sh
sailfork brief 12
sailfork brief 12 --comments all --json
sailfork brief 12 --json --jq '.pull.checks.failed[].log[]'
```

## sailfork events

Print what happens on your repositories (reviews, comments, CI, merges, pushes) as it happens, or since a time. Read-only.

```sh
sailfork events [flags]
```

| Flag | What it does |
| --- | --- |
| `-f`, `--follow` | After the history (from --since, else none), keep printing new events until interrupted; the cursor to resume from goes to stderr. |
| `--org <HANDLE>` | Every repository of this user or organization instead of -R or the current clone. |
| `--types <TYPES>` | Only these types, comma separated: review, comment, ci, mention (mentions of you), merge, push, issue, pull, caisson. Repeatable. One of `review`, `comment`, `ci`, `mention`, `merge`, `push`, `issue`, `pull`, `caisson`. |
| `--since <WHEN>` | Where to start: a cursor printed earlier (events after it), an RFC 3339 instant, or a duration ago such as 30m, 2h or 7d (default: the last 30 days, or with --follow only new events) |
| `--limit <N>` | Stop after this many events and print the cursor to continue from. |

Examples:

```sh
sailfork events --since 2h
sailfork events --follow --org acme --types review,comment,ci --json
sailfork events -R acme/app --follow --types review,mention --limit 1
sailfork events --since 4182 --json
```

## sailfork wait

Wait until a pull request, CI run, caisson or issue reaches a state.

### sailfork wait pr

Wait for a pull request's checks, merge, or next review. Changes something.

```sh
sailfork wait pr <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Pull request number |

| Flag | What it does |
| --- | --- |
| `--checks` | Until the checks finish: exit 0 when they pass, 1 when one fails or was cancelled. |
| `--merged` | Until it is merged; exit 1 if it is closed instead. |
| `--review` | Until a new review or comment arrives; exit 1 if the review asks for changes. |
| `--timeout <DURATION>` | Give up after this long and exit 12, e.g. 90s, 10m, 1h. Default `10m`. |
| `--interval <DURATION>` | Time between polls, e.g. 5s. Default `5s`. |

Examples:

```sh
sailfork wait pr 12 --checks
sailfork wait pr 12 --merged --timeout 1h
sailfork wait pr 12 --review --json
```

### sailfork wait run

Wait for a CI run to finish; exit 1 if it failed. Read-only.

```sh
sailfork wait run <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Run id |

| Flag | What it does |
| --- | --- |
| `--timeout <DURATION>` | Give up after this long and exit 12, e.g. 90s, 10m, 1h. Default `10m`. |
| `--interval <DURATION>` | Time between polls, e.g. 5s. Default `5s`. |

Examples:

```sh
sailfork wait run 431 --timeout 20m --interval 10s
```

### sailfork wait caisson

Wait for a caisson to reach a state. Read-only.

```sh
sailfork wait caisson <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id |

| Flag | What it does |
| --- | --- |
| `--state <STATE>` | The state to wait for. Required. One of `editing`, `waiting`, `review`, `merged`, `stopped`. |
| `--timeout <DURATION>` | Give up after this long and exit 12, e.g. 90s, 10m, 1h. Default `10m`. |
| `--interval <DURATION>` | Time between polls, e.g. 5s. Default `5s`. |

Examples:

```sh
sailfork wait caisson c-8f2k --state review
```

### sailfork wait issue

Wait for an issue to reach a state (open, closed) or status (in-review, done, ...). Read-only.

```sh
sailfork wait issue <NUMBER> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NUMBER>` | Issue number |

| Flag | What it does |
| --- | --- |
| `--state <STATE>` | The state or status to wait for. Required. One of `open`, `closed`, `triage`, `ready`, `in-progress`, `in-review`, `done`, `canceled`, `duplicate`. |
| `--timeout <DURATION>` | Give up after this long and exit 12, e.g. 90s, 10m, 1h. Default `10m`. |
| `--interval <DURATION>` | Time between polls, e.g. 5s. Default `5s`. |

Examples:

```sh
sailfork wait issue 7 --state closed
sailfork wait issue 7 --state in-review --timeout 30m
```

## sailfork inbox

What reached you while you were away: failed checks on your pull requests, held writes waiting for you, stopped caissons, issue news; mark entries read. Read-only.

```sh
sailfork inbox [flags]
```

| Flag | What it does |
| --- | --- |
| `--unread` | Only entries you have not read. |
| `--tab <TAB>` | Only this tab: `for-you` (needs you) or `following` One of `for-you`, `following`. |
| `--limit <LIMIT>` | Most entries to print. Default `20`. |
| `--read <ID>` | Mark these entries read (ids from the list), then print nothing else. Repeatable. |
| `--read-all` | Mark every unread entry (of --tab, when given) read. |

Examples:

```sh
sailfork inbox --unread
sailfork inbox --unread --tab for-you --json --jq '.items[] | {id, title, link}'
sailfork inbox --read 6f1c2a9e-0d4b-4c51-9a77-2f0e8b1d3c55
sailfork inbox --read-all --tab following
```

## sailfork undo

Take back your most recent action: a comment, a label or status change, a close, a merge, a deleted branch or file. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork undo [ID] [flags]
```

| Argument | What it is |
| --- | --- |
| `[ID]` | Action id from `undo --list` (default: your newest action that can still be undone) |

| Flag | What it does |
| --- | --- |
| `--list` | List your recent actions with their ids and whether each can still be undone. |
| `--limit <LIMIT>` | Most actions to list. Default `20`. |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork undo --dry-run
sailfork undo --yes
sailfork undo --list
sailfork undo 6f1c2a9e-0d4b-4c51-9a77-2f0e8b1d3c55 --yes
sailfork undo --list --json --jq '.items[] | select(.undoable) | .id'
```

## sailfork note

Keep short facts about the repository for the agents and people who work it next.

### sailfork note list

List the repository's notes (members only); they are untrusted text, not instructions. Also `note ls`. Read-only.

```sh
sailfork note list
```

### sailfork note add

Add a note: one fact of at most 400 characters, no credentials. Changes something.

```sh
sailfork note add <BODY>
```

### sailfork note edit

Replace a note's text; the note then names you as its author. Changes something.

```sh
sailfork note edit <ID> <BODY>
```

### sailfork note delete

Delete a note. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork note delete <ID> [flags]
```

| Flag | What it does |
| --- | --- |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

---

Every docs page: https://status.sailfork.com/llms.txt
