# Caisson and agent commands

Edit a repository on the server through a caisson, serve MCP tools, install agent skills and call the API directly.

The guides are [Working with agents](https://status.sailfork.com/docs/agents), [Caissons](https://status.sailfork.com/docs/caissons) and [MCP server](https://status.sailfork.com/docs/mcp).

## sailfork caisson

Edit a repository's worktree on the server: write files or apply a diff (`cs apply --patch`), commit, open a pull request. Also `sailfork cs`.

### sailfork caisson open

Open a caisson scoped to some paths. Changes something.

```sh
sailfork caisson open [flags]
```

| Flag | What it does |
| --- | --- |
| `--title <TITLE>` | Short description of the change (4 to 200 characters) Required. |
| `--scope <PATH>` | Path the caisson may touch; repeat for more. A folder ends in /, "" or "." is the whole repository (default: the whole repository) Repeatable. |
| `--branch <BRANCH>` | Branch to work on (default a new caisson/<id>); an existing branch, such as a pull request's, is continued: new commits land on it. |
| `--base <BASE>` | Branch name or commit sha to start from (default the default branch) |
| `--carry-edits` | With an existing --branch: copy the uncommitted edits a stopped caisson left on it into the new caisson. |

Examples:

```sh
sailfork cs open --title "Fix the footer links" --scope web/src/lib/footer/
sailfork cs open --title "Rename the config loader" --scope ""
sailfork cs open --title "Touch two folders" --scope src/ --scope docs/
sailfork cs open --title "Bump the build image" --scope .github/ --json --jq .id
sailfork cs open --title "Hotfix on the release branch" --base release
sailfork cs open --title "Address the review" --branch feat/cart
```

### sailfork caisson list

List the repository's caissons. Read-only.

```sh
sailfork caisson list [flags]
```

| Flag | What it does |
| --- | --- |
| `--state <STATE>` | Only caissons in this state. One of `editing`, `waiting`, `review`, `merged`, `stopped`. |
| `--limit <LIMIT>` | Most rows to print. Default `30`. |
| `--all` | Keep fetching pages until there are no more. |
| `--cursor <CURSOR>` | Continue after the `nextCursor` of an earlier run. |

Examples:

```sh
sailfork cs list
sailfork cs list --state review --json=id,title,branch
sailfork cs list --all --json --jq '.items[].id'
sailfork cs list --org acme --all
```

### sailfork caisson view

Show a caisson: state, scope, commits, changed files, live sandboxes. Also `caisson show`. Read-only.

```sh
sailfork caisson view <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

| Flag | What it does |
| --- | --- |
| `--log` | Also print the session steps. |

Examples:

```sh
sailfork cs view c-ab12cd
sailfork cs view c-ab12cd --log
```

### sailfork caisson ls

List a folder of the caisson's working copy. Read-only.

```sh
sailfork caisson ls <ID> [PATH]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `[PATH]` | Folder to list (default the root) |

Examples:

```sh
sailfork cs ls c-ab12cd
sailfork cs ls c-ab12cd src/
```

### sailfork caisson cat

Print a file of the caisson's working copy. Read-only.

```sh
sailfork caisson cat <ID> <PATHS...> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATHS...>` | File paths in the repository; several are read in one request, each under a `==> path <==` line |

| Flag | What it does |
| --- | --- |
| `--etag` | Print the file's ETag (its blob oid) to stderr. |
| `--lines <RANGE>` | Print only these lines: N, START-END or START- (from 1) |
| `--head <N>` | Print only the first N lines. |
| `--tail <N>` | Print only the last N lines. |
| `-n`, `--number` | Number the lines, as cat -n does. |

Examples:

```sh
sailfork cs cat c-ab12cd src/main.rs
sailfork cs cat c-ab12cd src/main.rs --lines 20-40 -n
sailfork cs cat c-ab12cd Cargo.toml src/lib.rs --head 20
sailfork cs cat c-ab12cd README.md --etag
```

### sailfork caisson edit

Edit one file in your editor and write it back; a missing file is created. Changes something.

```sh
sailfork caisson edit <ID> <PATH>
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATH>` | File path in the repository |

Examples:

```sh
sailfork cs edit c-ab12cd src/lib.rs
```

### sailfork caisson write

Write one file from --file (`-` reads stdin). Changes something.

```sh
sailfork caisson write <ID> <PATH> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATH>` | File path in the repository |

| Flag | What it does |
| --- | --- |
| `--file <FILE>` | Read the content from this file, or `-` for stdin. Required. |
| `--if-match <OID>` | Only write if the file still has this blob oid (the ETag you read) |
| `--create` | Only write if the file does not exist yet. |

Examples:

```sh
sailfork cs write c-ab12cd site/index.html --file ./index.html --create
sailfork cs write c-ab12cd src/lib.rs --file ./lib.rs --if-match 8f3b2c1
```

### sailfork caisson replace

Replace exact text (or a regex) in one file on the server, without resending it. Changes something. Supports `--dry-run`.

```sh
sailfork caisson replace <ID> <PATH> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATH>` | File path in the repository |

| Flag | What it does |
| --- | --- |
| `--old <OLD>` | Exact text to find; repeat with --new for several edits, applied in order. Required. Repeatable. |
| `--new <NEW>` | Text to put in place of the matching --old. Required. Repeatable. |
| `--all` | Replace every occurrence of each --old instead of requiring exactly one. |
| `--regex` | Treat each --old as a regular expression; --new may use $1 and ${name}. |
| `--dry-run` | Print the diff the edits would make and change nothing. |
| `--if-match <OID>` | Only edit if the file still has this blob oid (the ETag you read) |

Examples:

```sh
sailfork cs replace c-ab12cd src/lib.rs --old "parse(" --new "parse_all("
sailfork cs replace c-ab12cd src/lib.rs --old foo --new bar --old baz --new qux --dry-run
sailfork cs replace c-ab12cd src/lib.rs --regex --old 'v(\d+)' --new 'version-$1' --all
```

### sailfork caisson insert

Insert lines into one file after a line number. Changes something. Supports `--dry-run`.

```sh
sailfork caisson insert <ID> <PATH> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATH>` | File path in the repository |

| Flag | What it does |
| --- | --- |
| `--after <LINE>` | Insert after this line; 0 inserts at the top. Required. |
| `--text <TEXT>` | Text to insert. |
| `--file <FILE>` | Read the text to insert from this file, or `-` for stdin. |
| `--dry-run` | Print the diff and change nothing. |

Examples:

```sh
sailfork cs insert c-ab12cd src/lib.rs --after 10 --text "// see the migration notes"
sailfork cs insert c-ab12cd README.md --after 0 --file header.md
```

### sailfork caisson mv

Move or rename a file or folder. Changes something. Supports `--dry-run`.

```sh
sailfork caisson mv <ID> <FROM> <TO> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<FROM>` | File or folder to move |
| `<TO>` | Where it goes |

| Flag | What it does |
| --- | --- |
| `-f`, `--force` | Replace a file already at the destination. |
| `--dry-run` | Print what would change and change nothing. |

Examples:

```sh
sailfork cs mv c-ab12cd src/old.rs src/new.rs
sailfork cs mv c-ab12cd docs/ guides/ --dry-run
```

### sailfork caisson restore

Undo uncommitted changes to files or folders, back to the branch's version. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork caisson restore <ID> <PATHS...> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATHS...>` | Files or folders to restore; "." restores everything |

| Flag | What it does |
| --- | --- |
| `--dry-run` | Print the diff it would apply and change nothing. |
| `-y`, `--yes` | Confirm restoring the whole repository ("."), which discards every uncommitted change. |

Examples:

```sh
sailfork cs restore c-ab12cd src/lib.rs
sailfork cs restore c-ab12cd . --yes
```

### sailfork caisson apply

Apply a unified diff (`--patch`, from `git diff`) or a JSON file of changes at once, all or nothing. Changes something. Supports `--dry-run`.

```sh
sailfork caisson apply <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

| Flag | What it does |
| --- | --- |
| `--file <FILE>` | JSON file with {"changes": [...]} or a bare array of changes, or `-` for stdin. |
| `--patch <FILE>` | Unified diff (`git diff` output: new, deleted and renamed files too), or `-` for stdin. |
| `--dry-run` | Print what would change and change nothing. |

Examples:

```sh
sailfork cs apply c-ab12cd --file changes.json --dry-run
sailfork cs apply c-ab12cd --file changes.json
sailfork cs apply c-ab12cd --patch fix.patch
```

### sailfork caisson grep

Search file contents of the caisson's working copy by regex. Read-only.

```sh
sailfork caisson grep <ID> <PATTERN> [PATH] [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATTERN>` | Regular expression (Rust regex syntax) matched against each line |
| `[PATH]` | Only search under this folder or file |

| Flag | What it does |
| --- | --- |
| `-F`, `--fixed-strings` | Treat the pattern as plain text. |
| `-i`, `--ignore-case` | Match regardless of case. |
| `--full` | Read every file instead of the search index, which leaves out vendored folders, generated files, binaries and files over 1 MiB. |
| `-n`, `--line-number` | Accepted for grep habit: matches always print their line numbers. |
| `-l`, `--files-with-matches` | Only print the paths of matching files. |
| `-c`, `--count` | Print the number of matching lines per file. |
| `-g`, `--glob <GLOB>` | Only search paths matching this glob, like *.rs or src/**/*.ts. |
| `-C`, `--context <N>` | Lines of context around each match (at most 20) |
| `-B`, `--before <N>` | Lines of context before each match. |
| `-A`, `--after <N>` | Lines of context after each match. |
| `--limit <N>` | Most results to return, 1 to 2000 (default 200) |

Examples:

```sh
sailfork cs grep c-ab12cd 'TODO|FIXME'
sailfork cs grep c-ab12cd parse_all src/ -g '*.rs' -C 2
sailfork cs grep c-ab12cd 'fn main' -l
```

### sailfork caisson find

List the caisson's files matching a glob. Read-only.

```sh
sailfork caisson find <ID> <PATTERN> [PATH] [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATTERN>` | Glob over paths: * within a folder, ** across folders; no / matches the name anywhere |
| `[PATH]` | Only look under this folder |

| Flag | What it does |
| --- | --- |
| `--limit <N>` | Most paths to return, 1 to 2000 (default 200) |

Examples:

```sh
sailfork cs find c-ab12cd '*.md'
sailfork cs find c-ab12cd 'src/**/*.rs' --limit 50
```

### sailfork caisson bash

Run a bash script over the caisson's files on the server, with no sandbox; simulated commands only. Changes something. Supports `--dry-run`.

```sh
sailfork caisson bash <ID> [SCRIPT] [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `[SCRIPT]` | The script; without it the script is read from --file or stdin |

| Flag | What it does |
| --- | --- |
| `--file <PATH>` | Read the script from this file. |
| `--save-on-failure` | Save what the script changed even after a nonzero exit or a limit. |
| `--dry-run` | Print the diff of what the script changed and save nothing. |

### sailfork caisson ast-grep

Search code by syntax with an ast-grep pattern, including uncommitted edits. Read-only.

```sh
sailfork caisson ast-grep <ID> <PATTERN> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATTERN>` | Code to match: $A captures one node, $$$A any number, $_ one uncaptured node |

| Flag | What it does |
| --- | --- |
| `--lang <LANG>` | rust, typescript, tsx, javascript, python or go. Required. |
| `--path <PATH>` | Only look under this folder or file. |
| `--glob <GLOB>` | Only files matching this glob. |
| `--limit <LIMIT>` | Most matches to print (1 to 2000) |

### sailfork caisson ast-rewrite

Rewrite code by syntax, all or nothing; a dry run unless --apply. Changes something.

```sh
sailfork caisson ast-rewrite <ID> <PATTERN> <REWRITE> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATTERN>` | Code to match: $A captures one node, $$$A any number, $_ one uncaptured node |
| `<REWRITE>` | Replacement, using the pattern's captures |

| Flag | What it does |
| --- | --- |
| `--lang <LANG>` | rust, typescript, tsx, javascript, python or go. Required. |
| `--path <PATH>` | Only change under this folder or file. |
| `--glob <GLOB>` | Only files matching this glob. |
| `--apply` | Write the change; without this it is a dry run that prints the diff. |

### sailfork caisson lsp

Ask a language server for definitions, references, types or compiler errors, including uncommitted edits. Read-only.

```sh
sailfork caisson lsp <ID> <OP> [TARGET] [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<OP>` | status, definition, references, hover or diagnostics |
| `[TARGET]` | path:line:column for definition, references and hover; a path for diagnostics |

| Flag | What it does |
| --- | --- |
| `--lang <LANG>` | rust, typescript, javascript, python or go; needed only without a path. |
| `--limit <LIMIT>` | Most results, 1 to 2000. |
| `--wait <WAIT>` | Seconds to wait for a server still indexing, 0 to 50. |
| `--setup <SETUP>` | Shell command run in /work once before the server starts, such as `pnpm install` |

### sailfork caisson lsp-rename

Rename a symbol with a language server, all or nothing; a dry run unless --apply. Changes something.

```sh
sailfork caisson lsp-rename <ID> <TARGET> <NEW_NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<TARGET>` | path:line:column of the symbol |
| `<NEW_NAME>` | The new name |

| Flag | What it does |
| --- | --- |
| `--wait <WAIT>` | Seconds to wait for a server still indexing, 0 to 50. |
| `--apply` | Write the change; without this it is a dry run that prints the diff. |

### sailfork caisson lsp-stop

End your language server sandboxes on this caisson now. Changes something.

```sh
sailfork caisson lsp-stop <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

| Flag | What it does |
| --- | --- |
| `--lang <LANG>` | Only this language's server. |

### sailfork caisson symbols

Find where functions, types and classes are defined, including uncommitted edits. Read-only.

```sh
sailfork caisson symbols <ID> <QUERY> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<QUERY>` | Part of the name to find (case-insensitive) |

| Flag | What it does |
| --- | --- |
| `--kind <KIND>` | Only this kind: function, method, struct, enum, union, trait, interface, class, type, module, macro, const or static. |
| `--path <PATH>` | Only files whose path contains this. |
| `--limit <LIMIT>` | Most definitions to print (1 to 200) Default `30`. |

### sailfork caisson refs

List a symbol's definitions and references, including uncommitted edits. Read-only.

```sh
sailfork caisson refs <ID> <SYMBOL> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<SYMBOL>` | The exact name of the function, type or variable (case-sensitive) |

| Flag | What it does |
| --- | --- |
| `--path <PATH>` | Only files whose path contains this. |
| `--limit <LIMIT>` | Most references to print (1 to 1000) Default `100`. |

### sailfork caisson delete

Delete one file. Also `caisson rm`, `caisson remove`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork caisson delete <ID> <PATH> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATH>` | File to delete; `cs restore` brings it back until the next commit |

| Flag | What it does |
| --- | --- |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork cs delete c-ab12cd old-notes.txt
sailfork cs restore c-ab12cd old-notes.txt
```

### sailfork caisson put

Upload files and folders concurrently, skipping unchanged files. Changes something.

```sh
sailfork caisson put <ID> <PATHS...> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `<PATHS...>` | Files and folders to upload; folders keep their name and respect .gitignore |

| Flag | What it does |
| --- | --- |
| `--to <PREFIX>` | Folder in the caisson to upload into. |
| `--jobs <JOBS>` | Concurrent uploads. Default `16`. |

Examples:

```sh
sailfork cs put c-ab12cd ./dist
sailfork cs put c-ab12cd logo.png favicon.ico --to site/assets --jobs 8
```

### sailfork caisson diff

Show everything the caisson changed against its base. Read-only.

```sh
sailfork caisson diff <ID>
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

Examples:

```sh
sailfork cs diff c-ab12cd
sailfork cs diff c-ab12cd --json --jq '.[].path'
```

### sailfork caisson test

Run a command on the caisson's code (base plus uncommitted edits) in a throwaway sandbox. Changes something. Supports `--dry-run`.

```sh
sailfork caisson test <ID> [COMMAND...] [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |
| `[COMMAND...]` | One argument runs as a shell command line; several run as program and arguments |

| Flag | What it does |
| --- | --- |
| `--sandbox <SANDBOX_ID>` | Run in this running sandbox of this caisson instead of starting one; it is left running, its /work synced to the caisson. A sandbox of another caisson or of repository code is refused. |
| `--keep` | Leave the sandbox running afterwards and print its id on stderr. |
| `--cmd <COMMAND>` | The command line to run, by /bin/sh -c (or put the command after --) |
| `--image <IMAGE>` | Image of the new sandbox (default buildpack-deps:noble-scm: git, curl, python3 without pip; try python:3.12-slim, node:22, rust:1, golang:1.23) |
| `--minutes <N>` | Minutes until the new sandbox stops anyway, 1 to 1440 (default 60) |
| `--on <HOST_NAME>` | Drydock host to run on, by name (default any online host with room) |
| `--wait <SECS>` | Seconds to wait for a queued sandbox to start, 0 to fail at once when no host has room (default 60, at most 600); after it the sandbox stays queued and its id is printed. |
| `--fresh-workspace` | Discard this caisson's workspace volume on the host so /work starts empty; use when a build is stuck on a bad one. |
| `--timeout <SECS>` | Seconds before the command is killed (default 120, at most 3600) |
| `--env <KEY=VALUE>` | Environment variable for the command; repeat for more. Repeatable. |
| `--dry-run` | Say what would run and start nothing. |
| `--save` | Save what the command changed in /work back to the caisson when it exits 0; ignored files stay out. |
| `--save-on-failure` | With --save, also save after a nonzero exit; a command that timed out never saves. |
| `--affected` | Run only the tests the caisson's changes reach: the Cargo crates and package.json packages that own a changed file and what depends on them; a lockfile, CI config or build root change selects everything. A command given then is the whole suite, run when the change cannot be narrowed or selects everything. Exits 3 when nothing is affected, since no test ran. |
| `--output <PATH>` | A file the command wrote to bring back, read after it ends whatever its exit code: a path under /work or absolute, with `*`, `?` and `[..]` matching within one folder (no `**`); repeat for more. At most 100 files, each up to 16 MiB. Written under --output-dir with the path it has in /work. Repeatable. |
| `--output-dir <DIR>` | Folder the --output files are written to (default: the current folder) |
| `--changes <FILE>` | Apply these changes before the run, in one call: a JSON file (or `-` for stdin) holding the `changes` array of `sailfork api` batch (`[{"path": "a.py", "edits": [{"old": "x", "new": "y"}]}, ...]`). They apply in order, all or nothing: if one cannot apply, nothing changed and nothing runs; if they apply but the run cannot start they stay applied. |
| `--compare` | Run the command on the caisson's base commit and on its edits at once, in two throwaway sandboxes, and print whether the edits fixed or broke it, the output lines only one side printed, and each run's output tail. Exits with the edits run's code (124 on timeout). --changes apply first. |

Examples:

```sh
sailfork caisson test c-ab12cd --org acme -- cargo test
sailfork caisson test c-ab12cd --org acme --image python:3.12-slim -- 'pip install pytest && python -m pytest -q'
sailfork caisson test c-ab12cd --org acme --cmd "npm ci && npm test" --timeout 900
sailfork caisson test c-ab12cd --org acme --keep -- make build
sailfork caisson test c-ab12cd --org acme --dry-run -- make check
sailfork caisson test c-ab12cd --org acme --changes fix.json -- cargo test
```

### sailfork caisson review

Print a review packet for the caisson's diff: adversarial brief, risk prompts, the diff and its `head`. Changes something.

```sh
sailfork caisson review <ID>
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

### sailfork caisson review-submit

Record a review of the diff a packet named: verdict, summary and findings. Changes something.

```sh
sailfork caisson review-submit <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

| Flag | What it does |
| --- | --- |
| `--head <HEAD>` | The `head` of the packet you reviewed. Required. |
| `--verdict <VERDICT>` | `approve` when no confirmed finding is left, else `changes` Required. One of `approve`, `changes`. |
| `--text <TEXT>` | What you checked and what you found. Required. |
| `--findings <FILE>` | JSON file of findings, or `-` for stdin: [{"file", "line", "severity": low\|medium\|high\|critical, "scenario"}]. |

### sailfork caisson review-resolve

Clear a blocking review finding with a note. Changes something.

```sh
sailfork caisson review-resolve <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

| Flag | What it does |
| --- | --- |
| `--finding <FINDING>` | Id of the finding, from the refusal that names it or the review-submit answer. Required. |
| `--text <TEXT>` | Why it no longer applies. Required. |

### sailfork caisson commit

Turn the uncommitted changes into a commit on the caisson's branch. Changes something.

```sh
sailfork caisson commit <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

| Flag | What it does |
| --- | --- |
| `-m`, `--message <MESSAGE>` | Commit message; repeat it as git does, each -m one paragraph. Required. Repeatable. |

Examples:

```sh
sailfork cs commit c-ab12cd -m "Fix the footer links"
```

### sailfork caisson pr

Open a pull request from the caisson's branch. Changes something.

```sh
sailfork caisson pr <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

| Flag | What it does |
| --- | --- |
| `--title <TITLE>` | Pull request title (default: the caisson title) |
| `--body <BODY>` | Description text. |
| `--body-file <FILE>` | Read the description from a file, or `-` for stdin. |
| `--closes <N>` | Issue the pull request closes when merged: adds a `Closes #N` line; repeat for more. Repeatable. |
| `--refs <N>` | Issue it only links: adds a `Refs #N` line; repeat for more. Repeatable. |
| `--stop-forks` | Also stop the other live caissons forked from the same origin (the ones that lost); their branches are kept. |

Examples:

```sh
sailfork cs pr c-ab12cd --title "Fix the footer links" --body "Two links pointed at the old domain."
sailfork cs pr c-ab12cd --json --jq .number
```

### sailfork caisson ship

Commit the uncommitted changes and open the pull request in one go. Changes something.

```sh
sailfork caisson ship <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

| Flag | What it does |
| --- | --- |
| `-m`, `--message <MESSAGE>` | Commit message for the uncommitted writes; repeat it as git does, each -m one paragraph. Required. Repeatable. |
| `--title <TITLE>` | Pull request title (default: the first line of the message) |
| `--body <BODY>` | Description text. |
| `--body-file <FILE>` | Read the description from a file, or `-` for stdin. |
| `--closes <N>` | Issue the pull request closes when merged: adds a `Closes #N` line; repeat for more. Repeatable. |
| `--refs <N>` | Issue it only links: adds a `Refs #N` line; repeat for more. Repeatable. |
| `--stop-forks` | Also stop the other live caissons forked from the same origin (the ones that lost); their branches are kept. |

Examples:

```sh
sailfork cs ship c-ab12cd -m "Fix the footer links" --closes 12
sailfork cs ship c-ab12cd -m "Fix the footer links" --body-file body.md --refs 9 --json --jq .number
```

### sailfork caisson fork

Fork a caisson to try another approach side by side: its commit plus its uncommitted edits, on a new branch. Changes something.

```sh
sailfork caisson fork <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id to fork, e.g. c-ab12cd; it may be stopped or merged |

| Flag | What it does |
| --- | --- |
| `--title <TITLE>` | Title of the fork (default: the source's title and " (fork)") |

Examples:

```sh
sailfork cs fork c-ab12cd
sailfork cs fork c-ab12cd --title "Retry with a streaming parser" --json --jq .id
sailfork cs ship c-ef34gh -m "Parse in a stream" --stop-forks
```

### sailfork caisson stop

Stop a caisson; its branch is kept. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork caisson stop <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Caisson id, e.g. c-ab12cd |

| Flag | What it does |
| --- | --- |
| `--reason <REASON>` | Why it stopped, kept on the caisson. |
| `--delete-branch` | Also delete the caisson's branch even if it has commits, unless a pull request was opened from it (an empty branch is deleted anyway) |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork cs stop c-ab12cd --dry-run
sailfork cs stop c-ab12cd --yes --reason "superseded by c-ef34gh"
sailfork cs stop c-ab12cd --yes --delete-branch
```

### sailfork caisson policy

Show the path rules and limits of the repository's owner (-R owner/repo or --org; no caisson id). Read-only.

```sh
sailfork caisson policy
```

Examples:

```sh
sailfork cs policy
sailfork cs policy -R acme/shop
sailfork cs policy --org acme --json --jq .paths
```

## sailfork mcp

Serve sailfork's tools to a coding agent over MCP (stdio), signed in as you. Read-only.

```sh
sailfork mcp [flags]
```

| Flag | What it does |
| --- | --- |
| `--read-only` | Expose only the tools that never change anything. |
| `--toolsets <LIST>` | Expose only these toolsets, comma separated: caissons, issues, pulls, ci, repos, drydock, context, or all (default: all but drydock, the sandbox tools) |
| `--lockdown` | Hide the titles, bodies and comments of people who cannot push to the repository (env SAILFORK_MCP_LOCKDOWN=1) Reads `SAILFORK_MCP_LOCKDOWN`. |

Examples:

```sh
sailfork mcp -R acme/app
sailfork mcp --read-only
sailfork mcp --toolsets pulls,ci
sailfork mcp --lockdown
```

## sailfork skill

Install the agent skills that ship with this binary.

### sailfork skill install

Write the skills into ~/.claude/skills (or a project's .claude/skills); running it again updates them. Changes something.

```sh
sailfork skill install [flags]
```

| Flag | What it does |
| --- | --- |
| `--project` | Install into this repository's .claude/skills instead of ~/.claude/skills. |
| `--dir <DIR>` | Install into this directory instead, for agents that read skills elsewhere. |

Examples:

```sh
sailfork skill install
sailfork skill install --project
sailfork skill install --dir ~/.codex/skills
```

## sailfork hook

Commands for coding agents' hooks, such as Claude Code's SessionStart and SessionEnd.

### sailfork hook session-start

Print what needs you in this clone's repository as context for a new agent session. Prints nothing and exits 0 outside a Sailfork clone or when the server does not answer within 5 seconds, so it never blocks a session. Read-only.

```sh
sailfork hook session-start
```

### sailfork hook session-end

Hand back the issues the ending agent session holds a lease on, so they leave the Agents page now instead of when the lease lapses. Reads Claude Code's hook JSON on stdin for the session; prints nothing and exits 0. Changes something.

```sh
sailfork hook session-end
```

## sailfork commands

List every command and whether it changes anything; with a command path, its flags, examples and the global flags too. Read-only.

```sh
sailfork commands [WORDS...]
```

| Argument | What it is |
| --- | --- |
| `[WORDS...]` | A command path such as `pr create`; a group lists its subcommands |

Examples:

```sh
sailfork commands
sailfork commands --json --jq '.commands[] | select(.mutates) | .path'
sailfork commands pr merge --json --jq '.commands[0].flags[].long'
```

## sailfork schema

Print the JSON Schema of what a command prints under --json. Read-only.

```sh
sailfork schema <WORDS...>
```

| Argument | What it is |
| --- | --- |
| `<WORDS...>` | A command path such as `pr view` or `issue list` |

Examples:

```sh
sailfork schema pr view
sailfork schema issue list --jq '.properties.items.items.required'
```

## sailfork api

Make an authenticated request to the API. Changes something.

```sh
sailfork api <PATH> [flags]
```

| Argument | What it is |
| --- | --- |
| `<PATH>` | Path such as /api/me |

| Flag | What it does |
| --- | --- |
| `-X`, `--method <METHOD>` | HTTP method (default: GET, or POST when there are fields or --input) |
| `-f`, `--field <FIELDS>` | key=value body field sent as a string (query parameter for GET); repeatable. Repeatable. |
| `-F`, `--typed-field <TYPED_FIELDS>` | key=value body field with a typed value: numbers, true, false and null stay JSON, `@file` sends the file's text; repeatable. Repeatable. |
| `--input <INPUT>` | Send this file as the body (`-` for stdin) |
| `--paginate` | Follow nextCursor and merge every page's items. |
| `--slurp` | With --paginate, print one array of everything. |
| `-H`, `--header <NAME: VALUE>` | Extra request header as `Name: value`; repeatable. Repeatable. |
| `-i`, `--include` | Print the status line and response headers before the body. |
| `--silent` | Print nothing on success (the exit code still tells); an error response's body is not printed either. |

Examples:

```sh
sailfork api /api/me
sailfork api /api/repos/acme/app/pulls -f state=merged
sailfork api /api/repos/acme/app/pulls/12/comments -f body="Nit" -F line=5 -f path=src/lib.rs -F thread=null
sailfork api /api/repos/acme/app/issues --paginate --jq '.[].number'
sailfork api /api/repos/acme/app -i -H "Accept: application/json"
sailfork api /api/repos/acme/app --silent
```

---

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