CLI reference

staff [serve] [<slug>] [--port <n>] [--open] [--no-open] [--repo <dir>]
                                       Open the web UI (default). <slug> like main..WT.
staff diff [<slug>] [--base] [--head]  Create/load a diff and make it active.
staff files [--json]                   List the file-level changes for a diff.
staff review post [--pr <n>] [--github-repo <owner/name>]
                                       Post active-diff comments to a GitHub PR.
staff comment add|edit|delete|list|resolve|unresolve
                                       Post and manage review comments (used by the skills).
staff settings [get <key>]             Read global settings (e.g. loopMaxRounds).
staff settings set openBrowser false   Stop opening the browser automatically.
staff install                          Choose skill groups + initialize the .staffreview/ store.
staff --help                           Full usage.

Diffs

staff main..WT                         # open the UI on main → working tree
staff main..WT --port 4400             # serve the UI on a specific port
staff main..WT --no-open               # start the server and print the URL only
staff --open                           # override openBrowser=false for one run
staff diff main..WT --json             # create/load the diff, print its JSON
staff diff --base HEAD --head working-tree --json
staff active --json                    # the currently active diff
staff files --json                     # { path, status, oldContent, newContent } per file

A slug is <base>..<head>, where each side is WT (working tree), STAGED, or a git ref (branch, tag, or SHA).

GitHub pull requests

staff review post                      # use Informant or GitHub Actions context
staff review post --slug main..WT      # post a specific diff using CI context
staff review post --github-repo owner/repo --pr 123 --commit "$HEAD_SHA"

The command calls the GitHub REST API directly and requires GH_TOKEN or GITHUB_TOKEN. Outside Informant or GitHub Actions, pass both --github-repo and --pr. It posts root comments as one PR review, rejects stale base/head context, and skips a review already posted for the same commit. Replies and resolved-thread metadata remain local.

In GitHub Actions, the command reads GITHUB_REPOSITORY and the pull-request event at GITHUB_EVENT_PATH, so it also works from a detached checkout. Grant the workflow token permission to post reviews and check out the PR head rather than GitHub's synthetic merge commit:

permissions:
  contents: read
  pull-requests: write

steps:
  - uses: actions/checkout@v4
    with:
      ref: ${{ github.event.pull_request.head.sha }}

Ignoring files in reviews

Add a .staffignore file at the repository root to exclude paths from Staff Review diffs and agent reviews. It uses the same pattern syntax as .gitignore:

.agents/skills/
generated/
*.snap

Comments

# Inline (anchored to a file + line); add --end-line for a range
staff comment add --file path/to/file.ts --line 42 --side new \
  --author "Opus 4.8" --priority P1 --body "Off-by-one: misses the last element."

# Top-level (no --file/--line)
staff comment add --author "Opus 4.8" --body "Overall looks good once tests pass."

# Reply, edit, delete
staff comment add --reply-to <id> --author "Opus 4.8" --body "Good catch."
staff comment edit --id <id> --body "Corrected wording."
staff comment delete --id <id>

# List
staff comment list --json
staff comment list --open --json

# Resolve / unresolve a thread
staff comment resolve --thread <id> --author "Opus 4.8" --status fixed   --body "Reordered the loop, added a test."
staff comment resolve --thread <id> --author "Opus 4.8" --status skipped --body "Intentional — see ADR-0007."
staff comment resolve --thread <id> --author "Opus 4.8" --status documented --body "Saved." --documented-as error-handling.md
staff comment unresolve --thread <id>

--priority (P1/P2/P3) is an agent-only severity for triage — P1 is the most urgent. Humans don’t set it; leave it off for purely informational top-level comments.

Settings

staff settings get loopMaxRounds       # /staff-loop round cap (default 5)
staff settings get reviewAgents        # /staff-review agent fan-out (default 2)
staff settings get sectionAgents       # /staff-section agent fan-out (default 2)
staff settings get docsAgents          # /staff-docs scout fan-out (default 5)
staff settings get openBrowser         # browser auto-open preference
staff settings set openBrowser false   # make --no-open the default
staff settings get wrapLines           # diff line wrapping preference
staff settings set wrapLines false     # make diffs horizontally scroll by default
staff settings get structuredHighlighting        # intra-line word-diff toggle
staff settings set structuredHighlighting false  # turn it off by default

Settings (theme, split/unified, font size, syntax theme, browser auto-open, line wrapping, intra-line word-diff highlighting, review-loop cap, the review agent count, the section review agent count, and the docs scout count) live in the gear menu and persist globally.