CLI reference

Every sailfork command, the flags they all share, output formats, exit codes and environment variables.

Start

curl -fsSL https://sailfork.com/install | sh
sailfork auth login
sailfork status

The binary is sailfork, with the alias sf. Install the CLI covers every platform, sign-in and updates. Each command below prints its own help with --help, and sailfork commands lists them all with what they change.

Commands

CommandWhat it does
sailfork authSign in and out, and connect git
sailfork onboardSee what is set up for a new person and what to do next; an agent can drive it
sailfork orgCreate organizations, invite people and answer invitations
sailfork migrateMove repositories over from GitHub
sailfork repoCreate, inspect and clone repositories
sailfork prWork with pull requests
sailfork queueSee and leave a repository's merge queue
sailfork issueWork with issues
sailfork searchSearch code, issues and pull requests
sailfork commitShow a commit, or the pull requests that contain it
sailfork branchList and delete a repository's branches
sailfork attachmentDownload files attached to issues and pull requests
sailfork releasePublish a tag with notes and downloadable files, and list or edit releases
sailfork caissonEdit a repository's worktree on the server: write files or apply a diff (cs apply --patch), commit, open a pull request
sailfork ciInspect and control CI runs
sailfork sandboxRun code in isolated sandboxes on the organization's Drydock machines
sailfork keyManage SSH keys
sailfork tokenManage access tokens
sailfork inboxWhat reached you while you were away: failed checks on your pull requests, held writes waiting for you, stopped caissons, issue news; mark entries read
sailfork undoTake back your most recent action: a comment, a label or status change, a close, a merge, a deleted branch or file
sailfork whoamiShow who you are signed in as and what the token may do
sailfork doctorCheck sign-in, token, git, the server and this clone in one pass, with the command that fixes each problem
sailfork statusWhat needs you: your open pull requests and their checks, reviews waiting on you, issues assigned to you; with -R, only that repository's
sailfork briefEverything to start on an issue or pull request in one call: body, comments, threads with code, failed checks
sailfork eventsPrint what happens on your repositories (reviews, comments, CI, merges, pushes) as it happens, or since a time
sailfork labelList the labels a repository's issues use
sailfork milestoneList the milestones a repository's issues use
sailfork noteKeep short facts about the repository for the agents and people who work it next
sailfork usageShow metered usage for a month
sailfork apiMake an authenticated request to the API
sailfork mcpServe sailfork's tools to a coding agent over MCP (stdio), signed in as you
sailfork skillInstall the agent skills that ship with this binary
sailfork hookCommands for coding agents' hooks, such as Claude Code's SessionStart and SessionEnd
sailfork browseOpen the repository, a pull request or an issue in the browser
sailfork waitWait until a pull request, CI run, caisson or issue reaches a state
sailfork changelogWhat changed in each sailfork release newer than the one you run: update available or not, and the release notes
sailfork upgradeUpdate sailfork to the latest release
sailfork uninstallRemove sailfork and, with --purge, its saved sign-in and git setup
sailfork completionPrint a shell completion script, or install it with --install
sailfork helpShow help for a command, or a topic: exit-codes, environment, formatting
sailfork commandsList every command and whether it changes anything; with a command path, its flags, examples and the global flags too
sailfork schemaPrint the JSON Schema of what a command prints under --json

Flags every command takes

FlagWhat it does
--host <HOST>Site origin to talk to, e.g. https://sailfork.com or http://localhost:5173. Reads SAILFORK_HOST.
--json <FIELDS>Print JSON instead of text; --json=number,title or --json number,title keeps only those fields (sailfork help formatting)
--jq <EXPR>Filter the JSON output with a jq expression; strings print raw, other results as compact JSON lines.
-r, --raw-outputAccepted for jq habit: --jq already prints string results raw, as jq -r does.
--format <FORMAT>Output format: table, tsv, json or ndjson (default: SAILFORK_FORMAT, else table on a terminal, tsv in a pipe) One of table, tsv, json, ndjson.
--no-colorNever color the output (NO_COLOR does the same; FORCE_COLOR and CLICOLOR_FORCE color a pipe)
-R, --repo <OWNER/REPO>Repository to act on, as owner/repo (default: the clone's remote on a Sailfork host) Reads SAILFORK_REPO.
--remote <NAME>Git remote of the current clone to read the repository from and push to (default: the one on a Sailfork host, origin first) Reads SAILFORK_REMOTE.
--max-bytes <BYTES>Cap stdout at this many bytes, cut at a line, ending with what was cut and how to get the rest; 0 lifts the cap (default: no cap, 65536 when a coding agent runs sailfork) Reads SAILFORK_MAX_BYTES.
--summaryPrint the compact form: pr view and issue view without bodies and comments, ci view and ci logs only the failed steps, pr diff as a per-file stat (other commands print as usual)

Output

On a terminal a command prints a padded table with colors. In a pipe it prints tab-separated rows without a header. Counts, notices and empty-list messages go to stderr, so stdout stays clean.

FlagPrints
--jsonThe result as JSON, every field
--json=number,titleOnly those top-level fields
--jq EXPRThe JSON filtered by a jq expression: strings raw, anything else as compact JSON, one result per line
--format table|tsv|json|ndjsonThat format. SAILFORK_FORMAT sets the default

JSON has the same shape on every command:

ResultShape
A list{"schemaVersion": 1, "items": [...], "nextCursor": "..." | null, "hasMore": true | false}. Pass nextCursor to --cursor, or use --all
One thingThe object itself
A change{"schemaVersion": 1, "ok": true, ...ids}
A dry run{"dryRun": true, "action": "..."}
A failure{"error": {...}, "schemaVersion": 1} on stderr

sailfork schema <command> prints the JSON Schema of a command's output. Within a schema version, changes only add fields.

--max-bytes N caps stdout. A coding agent gets 65536 bytes unless it says otherwise, and 0 lifts the cap. A JSON document is shortened so it still parses, and says what was cut under truncated.

Exit codes

CodeMeaning
0Success
1Other failure
2Usage error: a bad or missing flag, or a prompt that cannot be answered
3Not signed in, or the token was rejected
4Not found. For a private repository this also means you cannot see it
5Forbidden: signed in, but not allowed
6Conflict: the file or branch changed, a merge is refused, or it already exists
7Network failure: the server could not be reached
8Validation: the server rejected the input (HTTP 400 or 422)
9Unavailable, retry later (HTTP 429, 502, 503, 504)
10Precondition failed (HTTP 412, or --match-head-commit did not match)
11Needs approval: a person must approve the held write in the browser
12Pending: pr checks found checks still running, or wait timed out
20upgrade --check found a newer release
130, 143Interrupted (Ctrl-C) or terminated (SIGTERM)

sandbox exec and caisson test exit with the code of the command they ran, or 124 when it timed out. caisson grep and caisson find exit 1 when nothing matched, as grep does.

Under --json a failure prints one object on stderr:

{"error":{"code":"not_found","exitCode":4,"message":"pull request #9 not found in acme/app","retryable":false,"subject":"pull request #9","hint":"..."}}

retryable is true for codes 7 and 9, and retryAfter (seconds) appears when the server asked for a wait.

Environment variables

A flag always wins over its variable. sailfork help environment prints the full list.

VariableWhat it sets
SAILFORK_HOSTSite origin, the same as --host. SAILFORK_URL means the same
SAILFORK_REPODefault repository as owner/repo, the same as -R
SAILFORK_REMOTEGit remote to read the repository from and push to
SAILFORK_TOKENAccess token to use instead of the stored one. It is sent only to SAILFORK_HOST, else to the default host
SAILFORK_NO_KEYRINGKeep the token in hosts.toml (mode 0600) instead of the OS keychain
SAILFORK_AGENTName of the coding agent driving the CLI, so its pull requests and comments read as agent work. none turns it off
SAILFORK_SESSIONId of this run of the agent, so two sessions sharing one token cannot both hold an issue lease
SAILFORK_CONFIG_DIRDirectory for hosts.toml (default ~/.config/sailfork)
SAILFORK_NO_PROMPTNever prompt or open an editor. CI=true does the same
SAILFORK_EDITOREditor command to use when there is no terminal
SAILFORK_FORMATDefault output format: table, tsv, json or ndjson
SAILFORK_MAX_BYTESCap stdout at this many bytes, the same as --max-bytes
SAILFORK_TIMEOUTSeconds before one request gives up (default 120, and 60 for sailfork mcp)
SAILFORK_RETRY_SECONDSSeconds to keep retrying a server that cannot be reached (default 60, and 0 turns it off)
SAILFORK_NO_UPDATESet to 1 to stop the background update
NO_COLOR, FORCE_COLORTurn colors off, or keep them in a pipe

Loading Sailfork