# Install the CLI

Install the sailfork command line, sign in, connect git, switch accounts, keep it current, and script it with JSON output, environment variables and exit codes.

## Install and sign in

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

The first line installs the binary. The second signs you in through the browser and also makes `sailfork` git's credential helper, so `git push` and `git pull` work with no password. The third shows who you are and what your token may do.

## Install

### macOS and Linux

The script copies one binary to `~/.local/bin`. It supports x86_64 and arm64, needs no sudo, and installs only after the download's SHA-256 matches the one in the release manifest, which the server serves only after checking it against the release signature.

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

The script also links `git-remote-sailfork` next to the binary. It never creates `sf`, because Salesforce's CLI uses that name. It only refreshes an `sf` that already points at sailfork. Read the script first with `curl -fsSL https://status.sailfork.com/install`: a browser sees the install page at that address, but `curl` and `wget` get the script.

If `~/.local/bin` is not on your `PATH`, the script prints the line to add for your shell (fish, zsh or bash). If another `sailfork` earlier on your `PATH` shadows the new one, it warns you.

| Variable | Effect |
| --- | --- |
| `SAILFORK_INSTALL_DIR` | Install into this folder instead of `~/.local/bin`. |
| `SAILFORK_VERSION` | Install this version, such as `0.3.0`, instead of the latest. |

### Windows

Run this in PowerShell. No administrator rights are needed.

```sh
irm https://status.sailfork.com/install.ps1 | iex
```

It installs `sailfork.exe` and `git-remote-sailfork.exe` into `%LOCALAPPDATA%\Programs\sailfork` and adds that folder to your user `PATH`. Open a new terminal afterwards. The build is x86_64. Arm64 Windows runs it under emulation, from an x64 PowerShell. `SAILFORK_INSTALL_DIR` and `SAILFORK_VERSION` work here too.

### Homebrew

```sh
brew tap sailfork/tap https://status.sailfork.com/sailfork/homebrew-tap.git && brew install sailfork/tap/sailfork
```

Upgrade with `brew upgrade sailfork`. Every archive, its checksums and the release notes are also on the [releases page](https://status.sailfork.com/sailfork/cli/releases), which is where you pick an older version.

## Sign in

```sh
sailfork auth login
```

This opens the browser. Approve once and the terminal is signed in. The token is named `CLI on <hostname>`, and signing in again under the same name replaces it. It lives in the OS keychain. When the keychain is not available, the CLI says so and keeps the token in `hosts.toml` with mode 0600.

| Flag | Effect |
| --- | --- |
| `--device` | Skip the browser. Prints a code to approve at the address it shows (`https://status.sailfork.com/device`). Implied by `--json`. |
| `--name <name>` | Name the token, for example `ci-runner-7`. |
| `--scopes <list>` | Ask for these scopes, comma separated. |
| `--with-token` | Read a personal access token from stdin instead of signing in. |
| `--no-wait` | Print the device code and address, remember the sign-in, and exit at once. |
| `--resume` | Wait for a sign-in that `--no-wait` started, then store the token. |
| `--timeout <secs>` | Give up after this long. With `--resume` the code stays valid and the command exits 12, so you can run it again. |
| `--no-git` | Leave git's credential helpers alone. |

On a machine with no browser, use the device code. `--no-wait` and `--resume` split it in two, which suits a script or an agent that has to show you the code and come back:

```sh
sailfork auth login --device --no-wait --json
sailfork auth login --resume --timeout 120 --json
```

Without `--scopes`, the sign-in asks for every scope. Ask for fewer on a machine that does not need them. The scopes are the same as for [access tokens](https://status.sailfork.com/docs/tokens):

| Scope | Allows |
| --- | --- |
| `repo:read` | Clone, fetch and read issues, pull requests and CI runs |
| `repo:write` | Push, open and merge pull requests, edit issues, rerun CI |
| `repo:admin` | Create and delete repositories, change branch protection and CI secrets |
| `user` | Read and update your profile, SSH keys and tokens |
| `org:read` | See your organizations, members and teams |
| `org:admin` | Create organizations; manage members, teams, rules, domains, CI providers and Drydock hosts |
| `sandbox` | Start sandboxes and run commands on your organizations' Drydock hosts |

### Tokens for scripts and CI

For a machine that will not sign in, make a token (Settings, Keys and tokens, or `sailfork token create`) and either export it or pipe it in:

```sh
export SAILFORK_TOKEN=<token>
printf %s "$TOKEN" | sailfork auth login --with-token
```

`SAILFORK_TOKEN` is sent only to the host named by `SAILFORK_HOST` (or `SAILFORK_URL`), else to the default host. A `--host` or a clone's origin elsewhere never gets it. See [Access tokens](https://status.sailfork.com/docs/tokens) for scopes and expiry.

## Connect git

`sailfork auth login` already does this when no other credential helper answers for the host's git address. Run the command yourself to redo it, or to take over from another helper:

```sh
sailfork auth setup-git
```

It asks first, then writes two entries to your global git config: `credential.<git address>.helper` pointing at sailfork, and `http.<git address>.proactiveAuth` set to `basic`, so git sends the credentials on its first request. Other options:

| Flag | Effect |
| --- | --- |
| `--local` | Write to this clone's `.git/config` instead of the global config. Needs no `--yes`. |
| `--dry-run` | Print what would change and change nothing. |
| `-y`, `--yes` | Confirm. Required when there is no terminal to ask on. |
| `--git-origin <url>` | The origin git clones from, when it cannot be read from a repository, such as `https://git.sailfork.com`. |

`sailfork auth logout` removes the helper again. See [Git over HTTPS and SSH](https://status.sailfork.com/docs/git-access) for how git authenticates.

## More than one host or account

The CLI keeps one sign-in per host and one default host.

```sh
sailfork auth list
sailfork auth switch http://localhost:5173
sailfork auth status
sailfork auth logout
```

`auth list` shows the hosts you are signed in to and marks the default. `auth switch <host>` makes another host the default. `auth status` shows who you are on each host and whether each token is still valid. `auth logout` revokes this machine's token and forgets it.

Any command takes `--host <origin>` (or `SAILFORK_HOST`) to talk to a host other than the default, and `auth login --host <origin>` signs in there. Inside a clone, the CLI reads the repository from the git remote on a Sailfork host. `-R owner/repo` overrides that, as does `SAILFORK_REPO`.

> [!NOTE]
> The CLI has one sign-in per host. To use two accounts on the same host, sign in as one and give the other's token to `SAILFORK_TOKEN` for the commands that need it.

## Check your setup

```sh
sailfork whoami
sailfork doctor
```

`whoami` shows who you are signed in as and what the token may do. `doctor` checks sign-in, the token's expiry and scopes, whether git is installed and its credential helper answers, whether the SSH port is reachable, the server and its version, and the clone you are in. Each problem comes with the command that fixes it. It exits 1 when a check fails, so an agent can run it before it starts work.

```sh
sailfork doctor --json --jq '.checks[] | select(.status != "ok") | "\(.id): \(.fix // .summary)"'
```

## Keep it current

```sh
sailfork upgrade --check
sailfork upgrade
sailfork upgrade --rollback
```

`upgrade` installs the latest release. `--check` only reports, and exits 20 when a newer release exists. `--version <v>` installs a specific version, downgrades included. `--dry-run` shows which release and file it would install. `--rollback` puts back the binary the last upgrade replaced.

An install that sailfork owns also updates itself. Once a day, after a command's own work, a detached process checks the release manifest and installs a newer release that passes the release-key signature, for the next run. A terminal sees `sailfork updated A -> B` once. Some installs are left alone:

- Homebrew, cargo, Nix, Scoop, winget and Snap installs, and folders sailfork cannot write. A line says how to update, once per release.
- Windows does not update itself in the background. Run `sailfork upgrade`.
- CI never updates.

Set `SAILFORK_NO_UPDATE=1`, or `auto_update = false` in `config.toml` in the config directory, to stop the check and the update. `SAILFORK_NO_UPDATE_NOTIFIER` prints no update line and makes no background check.

## Completions

```sh
sailfork completion --install
```

This adds completions for the shell in `$SHELL` to its startup files, and is safe to run twice. Name a shell (`bash`, `elvish`, `fish`, `powershell` or `zsh`) to pick another one. Without `--install`, the script prints to stdout.

## Uninstall

```sh
sailfork uninstall --dry-run
sailfork uninstall --purge --yes
```

`uninstall` removes sailfork. `--purge` also deletes the saved sign-in (the keychain token, revoked on the server when it can be reached), the config directory and the git credential helper that `auth setup-git` wrote. The install script does the same: `curl -fsSL https://status.sailfork.com/install | sh -s -- --uninstall --purge`. On Windows, set `$env:SAILFORK_UNINSTALL = 'purge'` (or `'1'` to keep the sign-in) and run the install command again.

## Output for scripts

Every command prints a padded table on a terminal and tab-separated rows in a pipe. Pick another shape with a flag:

| Flag | Prints |
| --- | --- |
| `--json` | All fields as JSON. |
| `--json=number,title` | Only those top-level fields. |
| `--jq '<expr>'` | Runs a jq expression on the JSON. Strings print raw, anything else as compact JSON lines. |
| `--format <f>` | `table`, `tsv`, `json` or `ndjson` (one compact line per list item). |

```sh
sailfork pr list --json=number,title --jq '.items[] | "\(.number) \(.title)"'
sailfork repo view acme/app --jq .defaultBranch
```

Lists come back as `{"schemaVersion": 1, "items": [...], "nextCursor": ..., "hasMore": ...}`. Pass `nextCursor` to `--cursor`, or use `--all`. Counts and notices go to stderr, so stdout stays clean for pipes. `sailfork schema <command>` prints the JSON Schema of a command's output, and `sailfork help formatting` has the rest.

A coding agent gets stdout capped at 65536 bytes unless it sets `--max-bytes` (`0` lifts the cap). `--summary` prints the compact form of `pr view`, `issue view`, `ci view`, `ci logs` and `pr diff`.

## Environment variables

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

| Variable | Effect |
| --- | --- |
| `SAILFORK_HOST`, `SAILFORK_URL` | Site origin, the same as `--host`. |
| `SAILFORK_REPO` | Default repository as `owner/repo`, the same as `-R`. |
| `SAILFORK_REMOTE` | The git remote to read the repository from and push to. |
| `SAILFORK_TOKEN` | Access token to use instead of the stored one. |
| `SAILFORK_NO_KEYRING` | Keep the token in `hosts.toml` 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. Claude Code, Codex, Cursor, Gemini CLI and others are detected by default. |
| `SAILFORK_SESSION` | Id of this agent run, so two sessions sharing one token cannot both hold an issue lease. |
| `SAILFORK_CONFIG_DIR` | Where `hosts.toml` lives. Default `$XDG_CONFIG_HOME/sailfork`, else `~/.config/sailfork`. |
| `SAILFORK_NO_PROMPT`, `CI=true` | Never prompt or open an editor. A command that needs an answer fails and names the flag. |
| `SAILFORK_EDITOR` | Editor command to use when there is no terminal. |
| `SAILFORK_FORMAT` | Default output format. |
| `SAILFORK_MAX_BYTES` | Cap stdout at this many 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, `0` turns it off. |
| `NO_COLOR`, `FORCE_COLOR` | Turn colors off, or force them on in a pipe. |

## Exit codes

A script can tell a missing pull request from a rejected token without reading the message.

| 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 a `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, and 124 when it timed out. Under `--json` a failure prints one JSON object on stderr, with a `code`, the `exitCode`, a `message`, `retryable` and a `hint` when there is one.

## Where to go next

- Every command and flag: [the CLI guide](https://status.sailfork.com/cli), or `sailfork <command> --help`.
- Calling routes directly: [REST API](https://status.sailfork.com/docs/api).
- Connecting an assistant: [MCP server](https://status.sailfork.com/docs/mcp).

---

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