# Sign-in and setup commands

Sign in, check what a token may do, manage tokens and SSH keys, and keep the CLI up to date.

How to install and sign in step by step is in [Install the CLI](https://status.sailfork.com/docs/install). Tokens and their scopes are in [Access tokens](https://status.sailfork.com/docs/tokens).

## sailfork auth

Sign in and out, and connect git.

### sailfork auth login

Sign in with the browser, a device code, or a token on stdin. Changes something.

```sh
sailfork auth login [flags]
```

| Flag | What it does |
| --- | --- |
| `--name <NAME>` | Name for the token (default: CLI on <hostname>); signing in again under a name replaces that token. |
| `--device` | Skip the browser and use a device code (implied by --json) |
| `--with-token` | Read a personal access token from stdin. |
| `--scopes <SCOPES>` | Scopes to request, comma separated: repo:read, repo:write, repo:admin, user, org:read, org:admin, sandbox. Repeatable. One of `repo:read`, `repo:write`, `repo:admin`, `user`, `org:read`, `org:admin`, `sandbox`. |
| `--timeout <SECS>` | Give up after this many seconds without approval (default: when the code expires); with --resume the code stays valid and the command exits 12 so it can be run again. |
| `--no-wait` | Print the device code and approval address, remember the sign-in, and exit at once; finish it with --resume. |
| `--resume` | Wait for the sign-in a --no-wait started, then store the token. |
| `--no-git` | Leave git's credential helpers alone (by default login makes sailfork the helper for the host's git origin when no other helper is set there) |

Examples:

```sh
sailfork auth login
sailfork auth login --device --json
sailfork auth login --device --no-wait --json
sailfork auth login --resume --timeout 120 --json
sailfork auth login --device --name "ci-runner-7"
```

### sailfork auth logout

Revoke this machine's token and forget it. Changes something.

```sh
sailfork auth logout
```

Examples:

```sh
sailfork auth logout
sailfork auth logout --host http://localhost:5173
```

### sailfork auth status

Show who you are signed in as on each host. Read-only.

```sh
sailfork auth status
```

Examples:

```sh
sailfork auth status
sailfork auth status --json --jq '.[] | select(.valid | not) | .host'
```

### sailfork auth token

Print the token for the current host. Read-only.

```sh
sailfork auth token
```

### sailfork auth setup-git

Use sailfork as git's credential helper for the host's git origin. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork auth setup-git [flags]
```

| Flag | What it does |
| --- | --- |
| `--git-origin <GIT_ORIGIN>` | Origin of the git server when it cannot be read from a repository, e.g. https://git.sailfork.com. |
| `--local` | Write the helper to this clone's .git/config instead of your global git config; needs no --yes. |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork auth setup-git --dry-run
sailfork auth setup-git --yes
sailfork auth setup-git --local
sailfork auth setup-git --git-origin https://git.sailfork.com --yes
```

### sailfork auth list

List the hosts you are signed in to; the default is marked. Also `auth ls`. Read-only.

```sh
sailfork auth list
```

Examples:

```sh
sailfork auth list
sailfork auth list --json --jq '.items[] | select(.default) | .host'
```

### sailfork auth switch

Make a host the default. Changes something.

```sh
sailfork auth switch <HOST>
```

| Argument | What it is |
| --- | --- |
| `<HOST>` | Host to make the default, e.g. https://sailfork.com |

Examples:

```sh
sailfork auth switch https://sailfork.com
```

## sailfork whoami

Show who you are signed in as and what the token may do. Read-only.

```sh
sailfork whoami
```

Examples:

```sh
sailfork whoami
sailfork whoami --json --jq '.token.scopes | index("repo:write") != null'
```

## sailfork doctor

Check sign-in, token, git, the server and this clone in one pass, with the command that fixes each problem. Read-only.

```sh
sailfork doctor
```

Examples:

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

## sailfork onboard

See what is set up for a new person and what to do next; an agent can drive it.

### sailfork onboard status

Every setup step as done, todo or needs_human, with the exact next command. Read-only.

```sh
sailfork onboard status [flags]
```

| Flag | What it does |
| --- | --- |
| `--import` | Plan to bring repositories over from GitHub: check that GitHub is connected and say what a person must do if not. |

Examples:

```sh
sailfork onboard status --json
sailfork onboard status --json --jq .next.command
sailfork onboard status --import --json
```

## sailfork token

Manage access tokens.

### sailfork token list

List your access tokens. Also `token ls`. Read-only.

```sh
sailfork token list [flags]
```

| Flag | What it does |
| --- | --- |
| `--scope <SCOPE>` | Only tokens that carry this scope. One of `repo:read`, `repo:write`, `repo:admin`, `user`, `org:read`, `org:admin`, `sandbox`. |
| `--limit <LIMIT>` | Most rows to print. Default `30`. |

Examples:

```sh
sailfork token list
sailfork token list --scope repo:admin --limit 100
sailfork token list --json=id,name,expires
```

### sailfork token create

Create an access token and print its secret once. Changes something.

```sh
sailfork token create <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Name to list the token under |

| Flag | What it does |
| --- | --- |
| `--scopes <SCOPES>` | Scopes, comma separated: repo:read, repo:write, repo:admin, user, org:read, org:admin, sandbox. Repeatable. One of `repo:read`, `repo:write`, `repo:admin`, `user`, `org:read`, `org:admin`, `sandbox`. Default `repo:read,repo:write`. |
| `--expires <EXPIRES>` | Expiry as a duration from now (8h, 30d), an RFC 3339 instant or YYYY-MM-DD (default: none) |
| `--repos <OWNER/REPO>` | Limit the token to these repositories, as owner/repo, comma separated (default: every repository you can reach) Repeatable. |

Examples:

```sh
sailfork token create ci-readonly --scopes repo:read
sailfork token create agent-7 --repos acme/app,acme/docs --expires 8h
sailfork token create release --expires 2027-01-01 --json --jq .secret
```

### sailfork token delete

Revoke an access token. Also `token revoke`, `token rm`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork token delete <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Token id, from `token list` |

| Flag | What it does |
| --- | --- |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork token delete t_1 --dry-run
sailfork token delete t_1 --yes
```

## sailfork key

Manage SSH keys.

### sailfork key list

List your SSH keys. Also `key ls`. Read-only.

```sh
sailfork key list [flags]
```

| Flag | What it does |
| --- | --- |
| `--kind <KIND>` | Only keys used to sign in over SSH, or only keys that sign commits. One of `auth`, `signing`. |
| `--limit <LIMIT>` | Most rows to print. Default `30`. |

Examples:

```sh
sailfork key list
sailfork key list --kind signing
sailfork key list --json=id,title,kind
```

### sailfork key add

Add a public key from a file, or `-` for stdin. Changes something.

```sh
sailfork key add <FILE> [flags]
```

| Argument | What it is |
| --- | --- |
| `<FILE>` | Public key file (such as ~/.ssh/id_ed25519.pub), or `-` for stdin |

| Flag | What it does |
| --- | --- |
| `-t`, `--title <TITLE>` | Name for the key (default: the key comment) |
| `--signing` | Use the key to sign commits instead of to authenticate. |

Examples:

```sh
sailfork key add ~/.ssh/id_ed25519.pub
sailfork key add ~/.ssh/id_ed25519.pub --title "work laptop"
sailfork key add ~/.ssh/signing.pub --signing
```

### sailfork key delete

Remove an SSH key. Also `key rm`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork key delete <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Key id, from `key list` |

| Flag | What it does |
| --- | --- |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork key delete k_1 --dry-run
sailfork key delete k_1 --yes
```

## sailfork upgrade

Update sailfork to the latest release. Changes something. Supports `--dry-run`.

```sh
sailfork upgrade [flags]
```

| Flag | What it does |
| --- | --- |
| `--check` | Report whether a newer release exists without installing it; exits 20 when one does. |
| `--dry-run` | Show which release and file would be installed without changing anything. |
| `--rollback` | Put back the binary the last upgrade replaced. |

Examples:

```sh
sailfork upgrade
sailfork upgrade --check
sailfork upgrade --version 0.2.4
```

## sailfork changelog

What changed in each sailfork release newer than the one you run: update available or not, and the release notes. Read-only.

```sh
sailfork changelog [flags]
```

| Flag | What it does |
| --- | --- |
| `--since <VERSION>` | List the releases after this version instead of after the one you run. |
| `--all` | List every release the server keeps, newest first. |
| `--limit <LIMIT>` | Most releases to list. Default `10`. |

Examples:

```sh
sailfork changelog
sailfork changelog --since 0.2.10 --json --jq '.releases[] | {version, notes}'
sailfork changelog --json --jq .updateAvailable
```

## sailfork uninstall

Remove sailfork and, with --purge, its saved sign-in and git setup. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork uninstall [flags]
```

| Flag | What it does |
| --- | --- |
| `--purge` | Also delete the saved sign-in (keychain token, revoked on the server when reachable), the config directory and the git credential helper that `auth setup-git` wrote. |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

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

## sailfork completion

Print a shell completion script, or install it with --install. Changes something.

```sh
sailfork completion [SHELL] [flags]
```

| Argument | What it is |
| --- | --- |
| `[SHELL]` | Shell to generate the script for (with --install, default: the shell in $SHELL) |

| Flag | What it does |
| --- | --- |
| `--install` | Add the completions to the shell's startup files (idempotent) |

Examples:

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

## sailfork help

Show help for a command, or a topic: exit-codes, environment, formatting. Read-only.

```sh
sailfork help [WORDS...]
```

| Argument | What it is |
| --- | --- |
| `[WORDS...]` | A command path such as `pr create`, or a topic name |

Examples:

```sh
sailfork help pr create
sailfork help exit-codes
sailfork help environment
sailfork help formatting
```

---

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