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, Code review, Issues and Notifications and activity.
sailfork pr
Work with pull requests.
sailfork pr list
List pull requests. Also pr ls. Read-only.
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:
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.
sailfork pr view [NUMBER] | Argument | What it is |
|---|---|
[NUMBER] | Pull request number (default: the open pull request for the current branch) |
Examples:
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.
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:
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.
sailfork pr checkout <NUMBER> | Argument | What it is |
|---|---|
<NUMBER> | Pull request number |
Examples:
sailfork pr checkout 12
sailfork pr checkout 12 --remote upstream sailfork pr diff
Show a pull request's diff. Read-only.
sailfork pr diff [NUMBER] | Argument | What it is |
|---|---|
[NUMBER] | Pull request number (default: the open pull request for the current branch) |
Examples:
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.
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:
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.
sailfork pr stack [NUMBER] | Argument | What it is |
|---|---|
[NUMBER] | Pull request number (default: the open pull request for the current branch) |
Examples:
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.
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.
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:
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.
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:
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.
sailfork pr ready [NUMBER] | Argument | What it is |
|---|---|
[NUMBER] | Pull request number (default: the open pull request for the current branch) |
Examples:
sailfork pr ready 12 sailfork pr draft
Turn an open pull request back into a draft. Changes something.
sailfork pr draft [NUMBER] | Argument | What it is |
|---|---|
[NUMBER] | Pull request number (default: the open pull request for the current branch) |
Examples:
sailfork pr draft 12 sailfork pr close
Close a pull request; pr reopen undoes it. Changes something. Supports --dry-run.
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:
sailfork pr close 12
sailfork pr close 12 --dry-run sailfork pr reopen
Reopen a pull request. Changes something.
sailfork pr reopen [NUMBER] | Argument | What it is |
|---|---|
[NUMBER] | Pull request number (default: the open pull request for the current branch) |
Examples:
sailfork pr reopen 12 sailfork pr review
Approve or request changes on a pull request, with comments on lines of the diff. Changes something.
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:
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.
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:
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.
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:
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.
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:
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.
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:
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.
sailfork pr feedback [NUMBER] | Argument | What it is |
|---|---|
[NUMBER] | Pull request number (default: the open pull request for the current branch) |
Examples:
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.
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:
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.
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:
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.
sailfork queue status sailfork queue leave
Take a pull request out of the queue (the same as pr merge --cancel-auto). Changes something.
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.
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:
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.
sailfork issue view <NUMBER> | Argument | What it is |
|---|---|
<NUMBER> | Issue number |
Examples:
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.
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:
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.
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:
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.
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:
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.
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:
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.
sailfork issue reopen <NUMBER> | Argument | What it is |
|---|---|
<NUMBER> | Issue number |
Examples:
sailfork issue reopen 7 sailfork issue claim
Delegate an issue to yourself or your agent for a lease, or renew the lease. Changes something.
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:
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.
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:
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.
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.
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:
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.
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:
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.
sailfork issue ship [NUMBER] [flags] | Argument | What it is |
|---|---|
[NUMBER] | Issue number (default: the one the current branch issue/-... 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:
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.
sailfork issue subscribe <NUMBER> | Argument | What it is |
|---|---|
<NUMBER> | Issue number |
Examples:
sailfork issue subscribe 7 sailfork issue react
Add or take back your reaction on an issue or one of its comments. Changes something.
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:
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.
sailfork issue unsubscribe <NUMBER> | Argument | What it is |
|---|---|
<NUMBER> | Issue number |
Examples:
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.
sailfork label list Examples:
sailfork label list
sailfork label list -R acme/app --json --jq '.items[].name' sailfork label create
Create a label. Changes something.
sailfork label create <NAME> [flags] | Flag | What it does |
|---|---|
-d, --description <DESCRIPTION> |
Examples:
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.
sailfork label edit <NAME> [flags] | Flag | What it does |
|---|---|
--name-to <NAME_TO> | The new name. |
-d, --description <DESCRIPTION> |
Examples:
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.
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:
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.
sailfork milestone list Examples:
sailfork milestone list
sailfork milestone list --json --jq '.items[] | select(.open > 0) | .name' sailfork milestone create
Create a milestone. Changes something.
sailfork milestone create <TITLE> [flags] | Flag | What it does |
|---|---|
-d, --description <DESCRIPTION> | |
--due <DUE> | Due date, YYYY-MM-DD. |
Examples:
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.
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:
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.
sailfork milestone close <TITLE> Examples:
sailfork milestone close "v1.0" sailfork milestone reopen
Reopen a closed milestone. Changes something.
sailfork milestone reopen <TITLE> Examples:
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.
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:
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.
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:
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.
sailfork attachment upload <PATH...> | Argument | What it is |
|---|---|
<PATH...> | Files to upload (up to 100 MB each); images and videos print as  so they show inline |
Examples:
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.
sailfork status Examples:
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.
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:
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.
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:
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.
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:
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.
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:
sailfork wait run 431 --timeout 20m --interval 10s sailfork wait caisson
Wait for a caisson to reach a state. Read-only.
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:
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.
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:
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.
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:
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.
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:
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.
sailfork note list sailfork note add
Add a note: one fact of at most 400 characters, no credentials. Changes something.
sailfork note add <BODY> sailfork note edit
Replace a note's text; the note then names you as its author. Changes something.
sailfork note edit <ID> <BODY> sailfork note delete
Delete a note. Changes something. Asks before it acts unless you pass --yes. Supports --dry-run.
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. |