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
| Command | What it does |
|---|---|
sailfork auth | Sign in and out, and connect git |
sailfork onboard | See what is set up for a new person and what to do next; an agent can drive it |
sailfork org | Create organizations, invite people and answer invitations |
sailfork migrate | Move repositories over from GitHub |
sailfork repo | Create, inspect and clone repositories |
sailfork pr | Work with pull requests |
sailfork queue | See and leave a repository's merge queue |
sailfork issue | Work with issues |
sailfork search | Search code, issues and pull requests |
sailfork commit | Show a commit, or the pull requests that contain it |
sailfork branch | List and delete a repository's branches |
sailfork attachment | Download files attached to issues and pull requests |
sailfork release | Publish a tag with notes and downloadable files, and list or edit releases |
sailfork caisson | Edit a repository's worktree on the server: write files or apply a diff (cs apply --patch), commit, open a pull request |
sailfork ci | Inspect and control CI runs |
sailfork sandbox | Run code in isolated sandboxes on the organization's Drydock machines |
sailfork key | Manage SSH keys |
sailfork token | Manage access tokens |
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 |
sailfork undo | Take back your most recent action: a comment, a label or status change, a close, a merge, a deleted branch or file |
sailfork whoami | Show who you are signed in as and what the token may do |
sailfork doctor | Check sign-in, token, git, the server and this clone in one pass, with the command that fixes each problem |
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 |
sailfork brief | Everything to start on an issue or pull request in one call: body, comments, threads with code, failed checks |
sailfork events | Print what happens on your repositories (reviews, comments, CI, merges, pushes) as it happens, or since a time |
sailfork label | List the labels a repository's issues use |
sailfork milestone | List the milestones a repository's issues use |
sailfork note | Keep short facts about the repository for the agents and people who work it next |
sailfork usage | Show metered usage for a month |
sailfork api | Make an authenticated request to the API |
sailfork mcp | Serve sailfork's tools to a coding agent over MCP (stdio), signed in as you |
sailfork skill | Install the agent skills that ship with this binary |
sailfork hook | Commands for coding agents' hooks, such as Claude Code's SessionStart and SessionEnd |
sailfork browse | Open the repository, a pull request or an issue in the browser |
sailfork wait | Wait until a pull request, CI run, caisson or issue reaches a state |
sailfork changelog | What changed in each sailfork release newer than the one you run: update available or not, and the release notes |
sailfork upgrade | Update sailfork to the latest release |
sailfork uninstall | Remove sailfork and, with --purge, its saved sign-in and git setup |
sailfork completion | Print a shell completion script, or install it with --install |
sailfork help | Show help for a command, or a topic: exit-codes, environment, formatting |
sailfork commands | List every command and whether it changes anything; with a command path, its flags, examples and the global flags too |
sailfork schema | Print the JSON Schema of what a command prints under --json |
Flags every command takes
| Flag | What 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-output | Accepted 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-color | Never 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. |
--summary | Print 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.
| Flag | Prints |
|---|---|
--json | The result as JSON, every field |
--json=number,title | Only those top-level fields |
--jq EXPR | The JSON filtered by a jq expression: strings raw, anything else as compact JSON, one result per line |
--format table|tsv|json|ndjson | That format. SAILFORK_FORMAT sets the default |
JSON has the same shape on every command:
| Result | Shape |
|---|---|
| A list | {"schemaVersion": 1, "items": [...], "nextCursor": "..." | null, "hasMore": true | false}. Pass nextCursor to --cursor, or use --all |
| One thing | The 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
| Code | Meaning |
|---|---|
0 | Success |
1 | Other failure |
2 | Usage error: a bad or missing flag, or a prompt that cannot be answered |
3 | Not signed in, or the token was rejected |
4 | Not found. For a private repository this also means you cannot see it |
5 | Forbidden: signed in, but not allowed |
6 | Conflict: the file or branch changed, a merge is refused, or it already exists |
7 | Network failure: the server could not be reached |
8 | Validation: the server rejected the input (HTTP 400 or 422) |
9 | Unavailable, retry later (HTTP 429, 502, 503, 504) |
10 | Precondition failed (HTTP 412, or --match-head-commit did not match) |
11 | Needs approval: a person must approve the held write in the browser |
12 | Pending: pr checks found checks still running, or wait timed out |
20 | upgrade --check found a newer release |
130, 143 | Interrupted (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.
| Variable | What it sets |
|---|---|
SAILFORK_HOST | Site origin, the same as --host. SAILFORK_URL means the same |
SAILFORK_REPO | Default repository as owner/repo, the same as -R |
SAILFORK_REMOTE | Git remote to read the repository from and push to |
SAILFORK_TOKEN | Access token to use instead of the stored one. It is sent only to SAILFORK_HOST, else to the default host |
SAILFORK_NO_KEYRING | Keep the token in hosts.toml (mode 0600) instead of the OS keychain |
SAILFORK_AGENT | Name of the coding agent driving the CLI, so its pull requests and comments read as agent work. none turns it off |
SAILFORK_SESSION | Id of this run of the agent, so two sessions sharing one token cannot both hold an issue lease |
SAILFORK_CONFIG_DIR | Directory for hosts.toml (default ~/.config/sailfork) |
SAILFORK_NO_PROMPT | Never prompt or open an editor. CI=true does the same |
SAILFORK_EDITOR | Editor command to use when there is no terminal |
SAILFORK_FORMAT | Default output format: table, tsv, json or ndjson |
SAILFORK_MAX_BYTES | Cap stdout at this many bytes, the same as --max-bytes |
SAILFORK_TIMEOUT | Seconds before one request gives up (default 120, and 60 for sailfork mcp) |
SAILFORK_RETRY_SECONDS | Seconds to keep retrying a server that cannot be reached (default 60, and 0 turns it off) |
SAILFORK_NO_UPDATE | Set to 1 to stop the background update |
NO_COLOR, FORCE_COLOR | Turn colors off, or keep them in a pipe |