# CLI reference

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

## Start

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

The binary is `sailfork`, with the alias `sf`. [Install the CLI](https://sailfork.com/docs/install) 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`](https://sailfork.com/docs/cli-setup#sailfork-auth) | Sign in and out, and connect git |
| [`sailfork onboard`](https://sailfork.com/docs/cli-setup#sailfork-onboard) | See what is set up for a new person and what to do next; an agent can drive it |
| [`sailfork org`](https://sailfork.com/docs/cli-organizations#sailfork-org) | Create organizations, invite people and answer invitations |
| [`sailfork migrate`](https://sailfork.com/docs/cli-repositories#sailfork-migrate) | Move repositories over from GitHub |
| [`sailfork repo`](https://sailfork.com/docs/cli-repositories#sailfork-repo) | Create, inspect and clone repositories |
| [`sailfork pr`](https://sailfork.com/docs/cli-collaboration#sailfork-pr) | Work with pull requests |
| [`sailfork queue`](https://sailfork.com/docs/cli-collaboration#sailfork-queue) | See and leave a repository's merge queue |
| [`sailfork issue`](https://sailfork.com/docs/cli-collaboration#sailfork-issue) | Work with issues |
| [`sailfork search`](https://sailfork.com/docs/cli-repositories#sailfork-search) | Search code, issues and pull requests |
| [`sailfork commit`](https://sailfork.com/docs/cli-repositories#sailfork-commit) | Show a commit, or the pull requests that contain it |
| [`sailfork branch`](https://sailfork.com/docs/cli-repositories#sailfork-branch) | List and delete a repository's branches |
| [`sailfork attachment`](https://sailfork.com/docs/cli-collaboration#sailfork-attachment) | Download files attached to issues and pull requests |
| [`sailfork release`](https://sailfork.com/docs/cli-repositories#sailfork-release) | Publish a tag with notes and downloadable files, and list or edit releases |
| [`sailfork caisson`](https://sailfork.com/docs/cli-agents#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`](https://sailfork.com/docs/cli-compute#sailfork-ci) | Inspect and control CI runs |
| [`sailfork sandbox`](https://sailfork.com/docs/cli-compute#sailfork-sandbox) | Run code in isolated sandboxes on the organization's Drydock machines |
| [`sailfork key`](https://sailfork.com/docs/cli-setup#sailfork-key) | Manage SSH keys |
| [`sailfork token`](https://sailfork.com/docs/cli-setup#sailfork-token) | Manage access tokens |
| [`sailfork inbox`](https://sailfork.com/docs/cli-collaboration#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`](https://sailfork.com/docs/cli-collaboration#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`](https://sailfork.com/docs/cli-setup#sailfork-whoami) | Show who you are signed in as and what the token may do |
| [`sailfork doctor`](https://sailfork.com/docs/cli-setup#sailfork-doctor) | Check sign-in, token, git, the server and this clone in one pass, with the command that fixes each problem |
| [`sailfork status`](https://sailfork.com/docs/cli-collaboration#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`](https://sailfork.com/docs/cli-collaboration#sailfork-brief) | Everything to start on an issue or pull request in one call: body, comments, threads with code, failed checks |
| [`sailfork events`](https://sailfork.com/docs/cli-collaboration#sailfork-events) | Print what happens on your repositories (reviews, comments, CI, merges, pushes) as it happens, or since a time |
| [`sailfork label`](https://sailfork.com/docs/cli-collaboration#sailfork-label) | List the labels a repository's issues use |
| [`sailfork milestone`](https://sailfork.com/docs/cli-collaboration#sailfork-milestone) | List the milestones a repository's issues use |
| [`sailfork note`](https://sailfork.com/docs/cli-collaboration#sailfork-note) | Keep short facts about the repository for the agents and people who work it next |
| [`sailfork usage`](https://sailfork.com/docs/cli-compute#sailfork-usage) | Show metered usage for a month |
| [`sailfork api`](https://sailfork.com/docs/cli-agents#sailfork-api) | Make an authenticated request to the API |
| [`sailfork mcp`](https://sailfork.com/docs/cli-agents#sailfork-mcp) | Serve sailfork's tools to a coding agent over MCP (stdio), signed in as you |
| [`sailfork skill`](https://sailfork.com/docs/cli-agents#sailfork-skill) | Install the agent skills that ship with this binary |
| [`sailfork hook`](https://sailfork.com/docs/cli-agents#sailfork-hook) | Commands for coding agents' hooks, such as Claude Code's SessionStart and SessionEnd |
| [`sailfork browse`](https://sailfork.com/docs/cli-repositories#sailfork-browse) | Open the repository, a pull request or an issue in the browser |
| [`sailfork wait`](https://sailfork.com/docs/cli-collaboration#sailfork-wait) | Wait until a pull request, CI run, caisson or issue reaches a state |
| [`sailfork changelog`](https://sailfork.com/docs/cli-setup#sailfork-changelog) | What changed in each sailfork release newer than the one you run: update available or not, and the release notes |
| [`sailfork upgrade`](https://sailfork.com/docs/cli-setup#sailfork-upgrade) | Update sailfork to the latest release |
| [`sailfork uninstall`](https://sailfork.com/docs/cli-setup#sailfork-uninstall) | Remove sailfork and, with --purge, its saved sign-in and git setup |
| [`sailfork completion`](https://sailfork.com/docs/cli-setup#sailfork-completion) | Print a shell completion script, or install it with --install |
| [`sailfork help`](https://sailfork.com/docs/cli-setup#sailfork-help) | Show help for a command, or a topic: exit-codes, environment, formatting |
| [`sailfork commands`](https://sailfork.com/docs/cli-agents#sailfork-commands) | List every command and whether it changes anything; with a command path, its flags, examples and the global flags too |
| [`sailfork schema`](https://sailfork.com/docs/cli-agents#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:

```json
{"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 |

---

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