> ## Documentation Index
> Fetch the complete documentation index at: https://fossa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Reference

> Complete reference for all Fossa CLI commands, flags, and options.

## Global Flags

These flags are available on all commands:

| Flag | Short | Default | Description |
| - | - | - | - |
| `--format <fmt>` | `-f` | `terminal` | Output format: `terminal`, `json`, `markdown` |
| `--output <file>` | `-o` | — | Save output to a file |
| `--verbose` | `-v` | `false` | Verbose output |
| `--quiet` | `-q` | `false` | Quiet mode (errors only) |
| `--agent` | — | `false` | Agent mode: deterministic machine-readable output |

***

## `fossa review`

Analyzes modified files for code quality issues, bugs, security vulnerabilities, and style violations.

### Usage

```bash theme={null}
fossa review                          # Review working tree changes (interactive)
fossa review [files...]               # Review specific files
fossa review --staged                 # Review staged files only
fossa review --branch main            # Compare against a branch
fossa review --commit abc123          # Analyze a specific commit
fossa review --fix                    # Auto-apply all fixable issues
fossa review --prompt-only            # Output optimized for AI agents
```

### Flags

| Flag | Short | Description |
| - | - | - |
| `--staged` | `-s` | Analyze only staged files |
| `--commit <sha>` | `-c` | Analyze diff from a specific commit |
| `--branch <name>` | `-b` | Compare current branch against specified branch |
| `--rules-only` | — | Review using only configured rules (no general suggestions) |
| `--fast` | — | Fast mode: quicker analysis with lighter checks |
| `--focus <text>` | — | Steer the review at a specific area — see [Steer a Review](/en/how_to_use/code_review/review_directive) |
| `--heavy` | — | Deeper pass: extra critic rounds for higher recall (alpha, see below) |
| `--interactive` | `-i` | Interactive mode: navigate and apply fixes |
| `--fix` | — | Automatically apply all fixable issues |
| `--prompt-only` | — | Output optimized for AI agents |
| `--fail-on <severity>` | — | Exit with code 1 if issues meet or exceed severity |
| `--context <file>` | — | Custom context file to include in review |
| `--fields <csv>` | — | Select response fields (JSON/agent mode), e.g. `summary,issues.file` |
| `--github-pat <token>` | — | GitHub token (`read:repo`) used to clone private repos. Trial users only. Also settable via `FOSSA_GITHUB_PAT`. Held in memory only, never persisted. |
| `--no-hunk` | — | Skip the hunk viewer and use the legacy interactive list (interactive sessions only) |

<Warning>
  `--heavy` is an **alpha** feature, **access by request** — it is off for every organization
  until we enable it. Cloud only for now; not available self-hosted. Until you're opted in the
  flag is accepted but the review runs normally, with no error and no warning. Ask for access on
  [Discord](https://discord.gg/TFZBRk9fT6) or at [support@fossa.local](mailto:support@fossa.local).
  See [Heavy mode](/en/how_to_use/code_review/review_directive#heavy-mode).
</Warning>

### Review Modes

<Tabs>
  <Tab title="Interactive (Default)">
    Navigate files with issue counts, preview suggested fixes, and apply them one by one.

    ```bash theme={null}
    fossa review
    ```
  </Tab>

  <Tab title="Auto-fix">
    Applies all fixable issues at once with a confirmation prompt.

    ```bash theme={null}
    fossa review --fix
    ```
  </Tab>

  <Tab title="AI Agent">
    Minimal, structured output designed for Claude Code, Cursor, or Windsurf. Enables autonomous review-fix loops.

    ```bash theme={null}
    fossa review --prompt-only
    ```
  </Tab>
</Tabs>

***

## `fossa pr suggestions`

Fetch AI-powered suggestions for open pull requests.

### Usage

```bash theme={null}
fossa pr suggestions --pr-url https://github.com/org/repo/pull/42
fossa pr suggestions --pr-number 42 --repo-id <id>
fossa pr suggestions --pr-number 42 --repo-id <id> --severity error,warning
fossa pr suggestions --pr-number 42 --repo-id <id> --format json
```

### Flags

| Flag | Description |
| - | - |
| `--pr-url <url>` | Pull request URL |
| `--pr-number <number>` | Pull request number (requires `--repo-id`) |
| `--repo-id <id>` | Repository ID for the pull request |
| `--severity <list>` | Comma-separated severities to include |
| `--category <list>` | Comma-separated categories to include |
| `--fields <csv>` | Select response fields (JSON/agent mode), e.g. `summary,issues.file` |

***

## `fossa pr business-validation`

Validate a local diff against the business rules/acceptance criteria of a task. Useful before merging to confirm the implementation matches the task intent.

### Usage

```bash theme={null}
fossa pr business-validation --task-url https://linear.app/team/issue/KC-1441
fossa pr business-validation --task-id KC-1441 --staged
fossa pr business-validation --task-id KC-1441 --branch main
fossa pr business-validation --task-id KC-1441 --commit abc123
fossa pr business-validation --task-id KC-1441 --dry-run
```

### Flags

| Flag | Short | Description |
| - | - | - |
| `--task-url <url>` | — | Task URL to append to the validation command |
| `--task-id <id>` | — | Task ID or issue key (e.g. `KC-1441`) to append |
| `--staged` | `-s` | Use only staged changes |
| `--commit <sha>` | `-c` | Use diff from a specific commit |
| `--branch <name>` | `-b` | Compare current branch against a base branch |
| `--dry-run` | — | Print payload without executing the API call |

***

## `fossa auth`

Manage authentication with the Fossa API.

### `auth login`

```bash theme={null}
fossa auth login                              # Interactive login
fossa auth login -e user@mail.com -p password # Non-interactive
```

| Flag | Short | Description |
| - | - | - |
| `--email <email>` | `-e` | Account email |
| `--password <password>` | `-p` | Account password |

### `auth logout`

```bash theme={null}
fossa auth logout
```

Removes local authentication (login and team key).

### `auth status`

```bash theme={null}
fossa auth status
```

Shows authentication mode, email, token validity, organizations, trial status, and usage limits.

### `auth team-key`

```bash theme={null}
fossa auth team-key --key fossa_xxxxx
```

Authenticate using a shared team API key. Can also be set via the `FOSSA_TEAM_KEY` environment variable.

### `auth team-status`

```bash theme={null}
fossa auth team-status
```

Shows team authentication details (organization and team name).

### `auth token`

```bash theme={null}
fossa auth token
```

Generates a CI/CD token for use in automated pipelines. Use with the `FOSSA_TOKEN` environment variable.

***

## `fossa hook`

Manage pre-push Git hooks for automatic code review before pushing.

### `hook install`

```bash theme={null}
fossa hook install                    # Default: fail-on critical, fast mode enabled
fossa hook install --fail-on error    # Block pushes on error severity
fossa hook install --no-fast          # Disable fast mode
fossa hook install --force            # Overwrite existing hook
```

| Flag | Default | Description |
| - | - | - |
| `--fail-on <severity>` | `critical` | Minimum severity to block push |
| `--fast` / `--no-fast` | `true` | Enable/disable fast mode |
| `--force` | — | Overwrite existing hook without prompting |

### `hook uninstall`

```bash theme={null}
fossa hook uninstall
```

Removes the pre-push hook installed by Fossa.

### `hook status`

```bash theme={null}
fossa hook status
```

Shows hook status, fail-on severity, fast mode setting, and path.

### Skipping the Hook

```bash theme={null}
FOSSA_SKIP_HOOK=1 git push
```

***

## `fossa config centralized`

Manage centralized configuration from the CLI.

### Usage

```bash theme={null}
fossa config centralized status
fossa config centralized init [owner/repo] --sync-option <pr|manual>
fossa config centralized sync
fossa config centralized disable
fossa config centralized download --out ./centralized-config.zip
```

### Subcommands

| Subcommand | Description |
| - | - |
| `status` | Show whether centralized config is enabled and the selected source repository |
| `init [repository]` | Enable centralized config for a selected repository |
| `sync` | Run centralized config sync on demand |
| `disable` | Disable centralized config and clear selected repository |
| `download --out <path>` | Download centralized config ZIP bundle |

### Flags

| Flag | Applies To | Description |
| - | - | - |
| `--sync-option <pr \| manual>` | `init` | Sync strategy. Default is `pr` |
| `--out <path>` | `download` | Required output path for ZIP file |
| `--json` | all centralized subcommands | Output structured JSON |

For a complete walkthrough, see: [/en/how\_to\_use/code\_review/configs/centralized\_config#cli-dedicated-section](/en/how_to_use/code_review/configs/centralized_config#cli)

***

## `fossa config repo`

Inspect and update repository settings stored in Fossa. Team-key auth is required. Use `.` to target the current repository.

<Note>`fossa config repo` and `fossa config remote` are aliases for the same command group.</Note>

### Usage

```bash theme={null}
fossa config repo add                                   # Add current repo to Fossa
fossa config repo add owner/repo                        # Add a specific repo
fossa config repo list                                  # List configured repos
fossa config repo show                                  # Show current repo settings
fossa config repo setup                                 # Guided setup wizard
fossa config repo set . reviewEnabled true              # Set a setting directly
fossa config repo open                                  # Open the Fossa dashboard
fossa config repo add-ignore-file . "**/*.generated.ts"
fossa config repo add-base-branch . "release/*"
fossa config repo add-ignore-title . "^WIP:"
```

### Subcommands

| Subcommand | Description |
| - | - |
| `add [repository]` | Add a repository to Fossa (shortcut: `fossa config -r [repository]`) |
| `list` | List repositories configured in Fossa |
| `show [repository]` | Show repository settings |
| `setup [repository]` | Run a guided repository setup wizard |
| `set [repository] <key> <value>` | Set a repository setting directly |
| `open [repository]` | Open the Fossa dashboard for advanced settings |
| `add-pattern [repository] <field> <pattern>` | Add a pattern to a list field (`ignore-files`, `base-branches`, `ignore-titles`) |
| `remove-pattern [repository] <field> <pattern>` | Remove a pattern from a list field |
| `add-ignore-file [repository] <pattern>` | Shortcut: add a pattern to ignored file patterns |
| `remove-ignore-file [repository] <pattern>` | Shortcut: remove an ignored file pattern |
| `add-base-branch [repository] <pattern>` | Shortcut: add a base branch pattern |
| `remove-base-branch [repository] <pattern>` | Shortcut: remove a base branch pattern |
| `add-ignore-title [repository] <pattern>` | Shortcut: add an ignored title pattern |
| `remove-ignore-title [repository] <pattern>` | Shortcut: remove an ignored title pattern |

### Flags

| Flag | Applies To | Description |
| - | - | - |
| `--no-prompt` | `add` | Skip the post-add setup prompt |

***

## `fossa rules`

Create, update, and view Fossy Rules — structured rules that Fossa applies during review.

### Usage

```bash theme={null}
fossa rules view                                         # View all rules for your team
fossa rules view --repo-id <id>                          # Filter by repository
fossa rules view --uuid <rule-uuid>                      # Fetch a single rule
fossa rules create --title "No console.log" --rule "Avoid leaving console.log in committed code" --severity high
fossa rules update --uuid <rule-uuid> --severity critical
```

### Subcommands

| Subcommand | Description |
| - | - |
| `create` | Create a new Fossy Rule |
| `update` | Update an existing rule |
| `view` | View Fossy Rules |

### `rules create` Flags

| Flag | Default | Description |
| - | - | - |
| `--title <title>` | — | Rule title |
| `--rule <rule>` | — | Rule content/description |
| `--repo-id <id>` | `global` | Repository ID (or `global` to apply to all repos) |
| `--severity <severity>` | `medium` | `low`, `medium`, `high`, `critical` |
| `--scope <scope>` | `file` | `pull request` or `file` |
| `--path <glob>` | `**/*` | Glob pattern for file targeting |
| `--json` | `false` | Output created rule as JSON |

### `rules update` Flags

| Flag | Description |
| - | - |
| `--uuid <uuid>` | Rule UUID to update (required) |
| `--repo-id <id>` | Updated repository ID |
| `--title <title>` | Updated title |
| `--rule <rule>` | Updated content/description |
| `--severity <severity>` | Updated severity |
| `--scope <scope>` | Updated scope |
| `--path <glob>` | Updated glob pattern |
| `--json` | Output updated rule as JSON |

### `rules view` Flags

| Flag | Description |
| - | - |
| `--uuid <uuid>` | Fetch a single rule by UUID |
| `--repo-id <id>` | Filter rules by repository ID |
| `--json` | Output rules as JSON |

***

## `fossa skills`

Inspect and install the agent skills bundled with the CLI (Claude Code, Cursor, Codex).

### Usage

```bash theme={null}
fossa skills list                                        # List bundled skills
fossa skills install                                     # Install into detected agent roots
fossa skills install --dry-run                           # Preview changes
fossa skills resync                                      # Re-sync bundled skills
fossa skills uninstall                                   # Remove bundled skills
```

### Subcommands

| Subcommand | Description |
| - | - |
| `list` | List bundled skills available in this CLI package |
| `sync` | Sync bundled skills to detected local agent directories |
| `resync` | Re-sync bundled skills to detected local agent directories |
| `install` | Install bundled skills into detected agent roots (creates dirs as needed) |
| `uninstall` | Uninstall bundled managed skills from detected agent directories |

### Flags

| Flag | Applies To | Description |
| - | - | - |
| `--dry-run` | `install`, `sync`, `resync`, `uninstall` | Show planned changes without writing files |

<Tip>For full multi-agent bootstrap, prefer the platform installer (`curl -fsSL https://review-skill.com/install | bash`). `fossa skills` covers local re-sync and cleanup.</Tip>

***

## `fossa status`

Show a consolidated Fossa status: auth mode, organization, repository, hook, bundled skills, and CLI version.

```bash theme={null}
fossa status
```

Useful as a first diagnostic when something misbehaves or when onboarding a new machine.

***

## `fossa diff`

Open the current changeset in the Hunk terminal diff viewer.

```bash theme={null}
fossa diff
```

This is a thin wrapper around `hunk diff` — every argument you pass is forwarded to it
unchanged, so any flag Hunk supports works here too.

<Note>
  Useful for eyeballing a changeset before running `fossa review` on it. The same viewer backs
  the interactive review experience; pass `--no-hunk` to `fossa review` if you prefer the
  legacy list.
</Note>

***

## `fossa update`

Update the Fossa CLI to the latest version from npm.

```bash theme={null}
fossa update
```

Resolves the correct global install command for your package manager (`npm`, `yarn`, `pnpm`, `bun`) and runs it. If an installer script was used, the CLI points you to the re-run command instead.

***

## Severity Levels

Issues are categorized by severity, from most to least critical:

| Level | Description |
| - | - |
| `critical` | Major security or stability issues requiring immediate attention |
| `error` | Significant bugs or problems |
| `warning` | Potential issues worth addressing |
| `info` | Suggestions and best practices |

## Issue Categories

| Category | Description |
| - | - |
| `security_vulnerability` | Security-related issues |
| `bug` | Potential bugs |
| `performance` | Performance optimization opportunities |
| `code_quality` | Code quality improvements |
| `best_practices` | Best practice violations |
| `complexity` | Code complexity issues |
| `maintainability` | Maintainability concerns |
| `style` | Code style issues |
| `documentation` | Documentation gaps (accepted by `--category` on `fossa pr suggestions`) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.