Concepts

Mental models to get the most out of the Fossa CLI.

A short tour of the ideas that show up everywhere in the CLI. Read this once and the rest of the docs will make more sense.

Diff Modes

Every review needs to answer one question: what changed? The CLI supports four diff modes, each with a different source of truth.

Mode	Source of diff	Inlines files?	When to use
Working tree (default)	Uncommitted changes in your working directory	Yes	Mid-development, before staging anything.
Staged (--staged)	git diff --cached	Yes	About to commit — same scope as git commit.
Branch (--branch <base>)	base..HEAD committed diff	No	Pre-merge review of the whole branch.
Commit (--commit <sha>)	The diff introduced by a single commit	No	Audit one commit, cherry-pick review.

Why does inlining matter? Working-tree and staged reviews send file contents alongside the diff because the backend can’t see your uncommitted work. Branch and commit modes skip inlining — the backend clones the same commit directly. That’s why branch/commit reviews work on huge diffs where working-tree reviews would exceed request size limits.

Review Modes

Three output styles, same underlying review.

• Interactive (default) — a TUI that lists files, expands issues, and applies fixes one at a time with a preview. The natural way to work in a terminal.
• Auto-fix (--fix) — applies every fixable issue at once, with a single confirmation. Use when you trust the rules and want to batch-apply.
• Prompt-only (--prompt-only) — minimal, structured text designed for AI agents to parse and act on. Pair with --fail-on in an agent loop so the loop exits cleanly when the review is clean.

You can also use --format json or --format markdown with any command for non-interactive consumers (CI, scripts, webhooks).

Authentication Modes

Pick one per machine. The CLI auto-detects what’s available.

• Trial — no auth. 5 reviews per day. Good for “try it once”.
• Personal login (fossa auth login) — an individual account. Tokens refresh automatically.
• Team key (fossa auth team-key --key fossa_xxxxx) — one shared key for a team, generated in the dashboard. Recommended for AI agents and anywhere you don’t want interactive logins.
• CI/CD token (fossa auth token) — a long-lived token for pipelines. Generated from a logged-in machine, used via FOSSA_TOKEN.

See Getting Started for the full decision tree.

Fossy Rules

A Fossy Rule is a structured rule the Fossa reviewer applies during every review, scoped to a repository or global to your team.

Rule
├── title          "No console.log in production code"
├── rule           "Avoid leaving console.log in committed code"
├── severity       low | medium | high | critical
├── scope          file | pull request
├── path           **/*.ts       (glob for file targeting)
└── repo-id        <uuid> | global

Rules layer on top of the general Fossa review — the AI uses them as additional criteria, not replacements.

Manage rules from the dashboard or from the CLI with fossa rules create|update|view. The CLI is useful when you want rules in version control (generate them from a script, check into a repo, re-apply on provisioning).

Repository Settings

Every repository in Fossa has settings that govern how reviews behave: ignored files, base branch patterns, title filters, feature toggles. These live in the Fossa backend and are mirrored anywhere the repo is reviewed (web PRs, CLI reviews, agent loops).

From the CLI:

fossa config repo list                 # See your configured repos
fossa config repo show                 # See settings for the current repo
fossa config repo setup                # Guided wizard
fossa config repo set . reviewEnabled true
fossa config repo add-ignore-file . "**/*.generated.ts"
fossa config repo open                 # Jump to the web dashboard

fossa config repo and fossa config remote are aliases for the same command group.

Centralized Config

Normally, each repository’s settings live in Fossa. Centralized Config lets a team store those settings in a single source-of-truth git repository — every change becomes a pull request against that repo, giving you review and version history on your review configuration itself.

Enable, sync, or inspect state:

fossa config centralized status
fossa config centralized init owner/config-repo --sync-option pr
fossa config centralized sync
fossa config centralized disable

Use Centralized Config when your team wants auditable, versioned control over review settings. Keep the default (per-repo settings in Fossa) when that ceremony is overkill.

Business Validation

Where fossa review asks “is this code good?”, fossa pr business-validation asks “does this diff actually do what the task said to do?”. You point it at a Linear/Jira/URL-based task and a diff source (working tree, staged, branch, commit) and it checks the implementation against the task’s acceptance criteria.

fossa pr business-validation --task-id KC-1441 --branch main
fossa pr business-validation --task-url https://linear.app/… --staged

Pair with a pre-merge check to catch “code works, but it’s not what was asked for” before human review.

AI Agent Output (--prompt-only and --agent)

Two related flags, different jobs.

• --prompt-only — output is optimized for an AI agent to parse and act on. Only works on commands that produce review-style output (review, pr suggestions).
• --agent — global flag that enforces deterministic, machine-readable output on any command. Use when a script or agent parses CLI output; combine with --format json for strictness.

Most agent integrations just need --prompt-only. Reach for --agent when you’re orchestrating the CLI from a harness or a tool-calling loop that has strict format expectations.

Next steps

Command Reference

Full command + flag listing.

AI Agents

Build review-fix loops with coding agents.

Troubleshooting

Common errors and exit codes.