Issues

File, triage, assign and close issues, and filter them by status, label and milestone, from the web app or the CLI.

File an issue

sailfork issue create --title "Login loops on Safari" --label bug --priority high
sailfork issue list --status ready --priority high
sailfork issue close 7 --comment "Fixed in the last release."

sailfork issue works on issues only. Given a pull request's number it fails with #7 is a pull request, not an issue.

Create an issue

In the web app

Open the repository's Issues page and choose New issue. The composer asks for a Title and a Description (Markdown, with a Preview tab) and offers these properties: Status, Priority, Assignee, Labels, Milestone, Estimate, Parent issue and Blocked by. Open More properties for the ones not shown. Attach files uploads files into the text. Choose File issue to save.

While you type the title, the composer lists up to three issues under Maybe already filed, open ones first, so you can open one before filing a copy. An issue is listed when its title shares at least two words with yours (short and common words do not count) and more than half of yours. Each links to the issue in a new tab.

Issue templates

A repository keeps issue templates as Markdown files in .sailfork/ISSUE_TEMPLATE/, or in .github/ISSUE_TEMPLATE/ as GitHub reads them. If the first folder has Markdown files, only it is read. Templates are read from the default branch.

---
name: Bug report
about: Something broke or behaves wrong
title: "Bug: "
labels: [bug]
---

## What happened

## What you expected

## Steps to reproduce
Front matterWhat it does
nameThe button's name. Default: the file name, with dashes and underscores as spaces.
aboutThe line shown when you hover the button.
titleThe starting title. A prefix such as Bug: keeps its trailing space.
labelsLabels to add. A list, or one comma-separated string.

The text after the front matter is the starting description. GitHub's YAML issue forms are not read.

When a repository has templates and the composer is empty, Start from lists them. Choosing one fills in the title and description and adds its labels to the ones already chosen. Once you have typed anything, the list goes away, so a template never overwrites a draft.

To make one from the composer, write a title or description, choose Save as template and give it a name and an optional "When to use it". It commits <name>.md to the default branch, or to a new branch with a link to open a pull request when the branch's rules keep a direct commit out. People with push access see this button. Pull requests have no template.

From the CLI

Flag of sailfork issue createWhat it does
-t, --title <TITLE>Required.
-b, --body <TEXT>, --body-file <FILE>The description. --body-file - reads stdin.
-l, --label <LABEL>Add a label. Repeat for several.
--priority <urgent|high|medium|low|none>The priority.
--estimate <1|2|3|5|8>Size in points.
--due <YYYY-MM-DD>Due date.
--milestone <NAME>Milestone name.
--parent <N>Make it a sub-issue of issue N.
--blocked-by <N>An issue that must finish first. Repeat for several.
--assignee <HANDLE>The one person who answers for it.
--stage <reported|triaged|fixing|review>The starting stage.
--attach <PATH>Upload a file and link it in the text. Repeat for several.
--idempotency-key <KEY>Retrying with the same key returns the issue already created.

The issue page

The page has the title and description, a Properties panel, Sub-issues, the Activity timeline of comments and changes, and a Following control. A repository's pull requests that close the issue show as a card on it. Use Edit title and description to change the text, and the comment box ("Leave a comment, @ to mention") to talk. Reactions are on the issue and on each comment.

The title, description and state can be changed by the issue's author. Everything else (status, assignee, labels, priority and the rest) needs push access. Locking the issue leaves only people with write access able to comment.

sailfork issue view 7 prints the issue with its relations, comments and timeline.

Statuses

An issue has one status, derived from its stage, whether it is open and why it closed:

StatusStageMeaning
TriageReportedWaiting for someone to triage it.
ReadyTriagedReady to be picked up.
In progressFixingSomeone is working on it. Reads as Ready once an agent's lease on it lapses.
In reviewReviewA pull request says it fixes this.
DoneclosedClosed as done.
CanceledclosedClosed as won't do.
DuplicateclosedClosed as a duplicate of another issue.

Set the status from the Status property, or with sailfork issue edit 7 --status ready. The CLI takes triage, ready, in-progress, in-review, done, canceled and duplicate, and sets stage and state together. --stage moves only the stage.

Closing ends an issue wherever it stood:

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 7

--reason is done (the default), wont-do or duplicate. --duplicate-of implies duplicate. In the web app, closing as a duplicate asks which issue it duplicates.

Close it from a pull request

A pull request that says closes #7, fixes #7 or resolves #7, or that was opened with sailfork pr create --issue 7, or from a branch named issue/7-..., links the issue. Linking moves the issue to In review. Merging the pull request closes it. See Pull requests.

Assignees

An issue has at most one assignee, the one person who answers for it. Set it from Assignee, or:

sailfork issue edit 7 --assignee ada
sailfork issue edit 7 --no-assignee

In the web app, Claim this issue assigns it to you and moves it to In progress.

An agent takes an issue with a lease, which never changes the assignee. sailfork issue edit 7 --assign-agent <TOKEN> asks one of your agent tokens to take it, --no-agent withdraws the request, and a request not started within 30 minutes expires. sailfork issue claim, next, start and ship are the agent side. See Agents.

Labels and milestones

An issue carries at most 20 labels, each up to 50 characters, unique ignoring case. A milestone name is at most 80 characters. Issues name labels and milestones by text, so a name with no record still works. A record adds a description, and for a milestone a due date and an open or closed state.

In the web app, the Labels and Milestones pages of the repository list them, most used first, with the number of open and closed issues. They have New label, New milestone, rename, describe and delete. Renaming a label changes it on every issue that has it. Deleting a label or milestone removes it from every issue that carries it. Anyone with push access can change them.

sailfork label list
sailfork label create bug --description "Something is broken"
sailfork label edit bug --name-to defect
sailfork label delete defect --yes
sailfork milestone create "v1.0" --due 2026-12-01
sailfork milestone edit "v1.0" --title-to "1.0" --no-due
sailfork milestone close "1.0"
sailfork milestone reopen "1.0"
sailfork milestone delete "1.0" --yes

On an issue, --label replaces the labels, --add-label and --remove-label change one, and --clear-labels empties them. --milestone <NAME> moves it and --no-milestone takes it out. Closing a milestone leaves its issues as they are. --dry-run on a delete says what would go.

Views and filters

The issues list opens on All and keeps its query in the address, so a view can be saved and shared. The view tabs are My issues, Active (In progress and In review), Ready, Triage and All. A list across all of an owner's repositories adds Needs input, for issues where an agent left a question for a person.

  • Filter by assignee, agent, priority, label and milestone. Clear all removes them.
  • Find an issue matches the title and description, or a number such as #12.
  • Display options: Layout (list or board), Group by Status or Assignee, Order by Priority, Newest or Recently updated, and Show closed issues.
  • In Triage, you can snooze an issue for a week or until tomorrow. Snoozed issues stay out of the Triage view.

From the CLI:

sailfork issue list
sailfork issue list --status ready --priority high
sailfork issue list --assignee none --label bug --json=number,title,status
sailfork issue list --author @me --mentions ada
sailfork issue list --query "login loop" --all
Flag of sailfork issue listWhat it does
--state <open|closed|all>Default open.
--status <STATUS>, --stage <STAGE>Filter by status or stage.
--label, --milestone, --priority, --parent <N>Filter by that field.
--assignee <HANDLE|none>A handle, or none for unassigned issues.
--author <HANDLE|@me>, --mentions <HANDLE|@me>Who opened it, or whose @mention is in its title or description.
-q, --query <TEXT>Search titles and bodies.
--sort <newest|oldest|priority|updated>Order of the rows.
--limit <N> (default 30), --all, --cursor <CURSOR>Paging.

To search across a repository's issues with qualifiers, see Search.

Work graph

The graph draws one issue or pull request and what connects to it. Open it with Graph on an issue page, shown when the issue has a parent, sub-issues, blockers or issues it blocks, or with View graph in the Stack section of a pull request in a stack. The address is /<owner>/<repo>/graph?focus=issue-7 or focus=pull-12. Without a valid focus the page says "No item to graph".

For an issue, the graph shows its parents up the chain, its sub-issues, the issues it waits on and the issues that wait on it, and the pull requests that close any of them, with the pull requests they are stacked on. For a pull request, it shows the whole stack and the issues those pull requests close. An item with nothing connected reads "stands alone".

LineMeaning
SolidParent to sub-issue
Dashed, with an arrowBlocker to the issue it blocks
Dotted, with a dotAn issue to its pull request, and a pull request to the one stacked on it

Each node shows the number, title, status, a checks mark on an open pull request, and Ready now on an issue that is Ready with no open blocker and no open sub-issue. A summary line counts issues, pull requests and the ready ones. Choose a node to open it, or the crosshair on it to focus the graph there, which changes focus. A busy graph stops at 150 nodes and each node admits at most 8 neighbors on its own. A +N more node opens the rest, and the summary says how many are not shown. Zoom with the buttons.

Attachments

Drop or paste files into a description or comment, or choose Attach files. From the CLI, --attach <PATH> on issue create, issue comment and pr comment uploads a file and links it, and sailfork attachment handles files by hand:

sailfork attachment upload after.png report.pdf -R fenil/ocean-landing
sailfork attachment download <link-from-a-comment> -o after.png

upload prints a Markdown link for each file: ![name](url) for images and videos so they show inline, [name](url) for anything else. A file is up to 100 MB. Only png, jpeg, gif, webp, avif, mp4, webm, quicktime and pdf show inline, and every other type downloads. On a public repository anyone can fetch an attachment.

Mentions

Write @ada in a description or comment, outside a code block, to notify that person and make them follow the issue. They need read access to the repository. @acme/design mentions the members of that team of the organization, at most 50 people for one change. The editor suggests people and teams as you type. Who follows an issue is described under Notifications and activity.

sailfork issue subscribe 7 and sailfork issue unsubscribe 7 follow and unfollow from the terminal.

Commands

CommandWhat it does
sailfork issue list, view, createFind, read and file issues.
sailfork issue edit NChange any field: --title, --body, --status, --stage, --assignee, --priority, --estimate (or --no-estimate), --due (or --no-due), --parent (or --no-parent), --blocked-by (or --clear-blockers), and the label and milestone flags above.
sailfork issue comment NComment with --body, --body-file or --attach. --update posts it as a progress update.
sailfork issue close N, reopen NClose and reopen.
sailfork issue react N <REACTION>React with +1, -1, laugh, hooray, confused, heart, rocket or eyes. --comment <ID> reacts to a comment, --remove takes it back.
sailfork issue subscribe N, unsubscribe NFollow or stop following.
sailfork issue claim, release, context, next, start, shipThe agent workflow. See Agents.
sailfork label ..., sailfork milestone ...Manage labels and milestones.

sailfork brief 7 prints what you need to start on an issue in one call: the description, the newest comments (--comments <N|all>, default 10), its lease, parent, blockers, sub-issues and the pull requests that close it, plus repository notes. Add --json for an agent.

From a script

Create, list, update, comment on and claim issues over REST, with Idempotency-Key on writes: see the API reference. The issues toolset of the MCP server does the same for an agent.

Limits and common errors

  • A parent and its sub-issues are in the same repository, nested at most 32 deep. Blockers are in the same repository.
  • Issue lists return 1 to 100 rows a page, 30 by default.
  • Every issue write accepts an Idempotency-Key of 1 to 200 characters. A retry with the same key and body returns the first response, and the same key with a different request is 409. Keys last a day.
  • 403: the issue is locked and you lack write access, the owner of the repository blocked you, or the issue came over from GitHub into a pull mirror, where issues are read-only.
  • 409 on claim: another token holds the lease, the issue is closed or blocked, or it is an epic.
  • sailfork undo takes back a comment, a label or status change, a close and a few other actions within 24 hours. See Notifications and activity.

Loading Sailfork