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
curl -fsSL https://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.
curl -fsSL https://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://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.
irm https://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
brew tap sailfork/tap https://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, which is where you pick an older version.
Sign in
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://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:
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:
| 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:
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 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:
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 for how git authenticates.
More than one host or account
The CLI keeps one sign-in per host and one default host.
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
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.
sailfork doctor --json --jq '.checks[] | select(.status != "ok") | "\(.id): \(.fix // .summary)"' Keep it current
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
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
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://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). |
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, or
sailfork <command> --help. - Calling routes directly: REST API.
- Connecting an assistant: MCP server.