> ## 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.

# Getting Started

> Install the Fossa CLI, authenticate, and run your first review.

This guide gets you from zero to a reviewed diff in under five minutes.

<Steps>
  <Step title="Install">
    <Tabs>
      <Tab title="Skill Installer (Recommended)">
        Installs the CLI and deploys Fossa skills to all detected AI agents (Claude Code, Cursor, Codex, Windsurf):

        ```bash theme={null}
        curl -fsSL https://review-skill.com/install | bash
        ```
      </Tab>

      <Tab title="npm">
        ```bash theme={null}
        npm install -g @fossa/cli
        ```
      </Tab>

      <Tab title="npx (No Install)">
        ```bash theme={null}
        npx @fossa/cli review
        ```
      </Tab>

      <Tab title="curl">
        ```bash theme={null}
        curl -fsSL https://review-skill.com/install | bash
        ```
      </Tab>
    </Tabs>

    <Note>Requires Node.js >= 20.0.0.</Note>

    Verify the install:

    ```bash theme={null}
    fossa --version
    fossa status
    ```
  </Step>

  <Step title="Authenticate">
    Pick the path that matches your situation. You can also skip auth and run `fossa review` directly — it works in trial mode with daily limits.

    <Tabs>
      <Tab title="Solo developer">
        Sign in with a personal account:

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

        Tokens are stored in `~/.fossa/credentials.json` and auto-refreshed.
      </Tab>

      <Tab title="Team (shared key)">
        Generate a team key at <a href="https://app.fossa.local/organization/cli-keys" target="_blank">app.fossa.local/organization/cli-keys</a> and apply it:

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

        Or distribute the bootstrap command to your team — it installs the CLI and configures the key in one shot:

        ```bash theme={null}
        curl -fsSL https://review-skill.com/install | bash -s -- --team-key fossa_xxxxx
        ```

        <Warning>Save the key when it's shown — it won't be displayed again.</Warning>
      </Tab>

      <Tab title="AI agent">
        For AI coding agents (Claude Code, Cursor, Codex), team keys are the recommended path — no individual login, no interactive prompts. Set the key once:

        ```bash theme={null}
        export FOSSA_TEAM_KEY=fossa_xxxxx
        ```

        Add it to your shell profile so the agent picks it up on every run.
      </Tab>

      <Tab title="CI/CD">
        From a logged-in machine, generate a long-lived token:

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

        In your pipeline, set:

        ```bash theme={null}
        export FOSSA_TOKEN=<generated-token>
        ```

        See [Self-Hosted Setup](self_hosted) for full CI examples.
      </Tab>
    </Tabs>

    <Info>
      **Self-hosting Fossa?** Point the CLI to your API before authenticating:

      ```bash theme={null}
      export FOSSA_API_URL=https://fossa-api.yourcompany.com
      ```

      HTTPS is required except for `localhost`.
    </Info>

    Confirm the auth state:

    ```bash theme={null}
    fossa auth status
    ```
  </Step>

  <Step title="Run your first review">
    Inside any git repository with uncommitted changes:

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

    The CLI analyzes your working tree diff, prints a summary, and (in interactive mode) lets you browse file-by-file, preview suggested fixes, and apply them.

    Common variations:

    ```bash theme={null}
    fossa review --staged             # Only staged files
    fossa review --branch main        # Compare current branch against main
    fossa review --commit abc123      # Analyze a single commit
    fossa review --fix                # Auto-apply every fixable issue
    fossa review --prompt-only        # Compact output for AI agents
    fossa review --fail-on error      # Exit non-zero on error-or-worse (CI-friendly)
    ```

    <Tip>
      Working-tree reviews (default) and `--staged` inline file contents so the backend sees your uncommitted changes. `--branch` and `--commit` modes skip inlining since the backend can fetch those commits itself — this is why those modes work well on huge branches.
    </Tip>
  </Step>

  <Step title="Choose what's next">
    Depending on your goal:

    <CardGroup cols={2}>
      <Card title="Automate on every push" icon="shield-check" href="commands#fossa-hook">
        Install the pre-push hook with `fossa hook install`.
      </Card>

      <Card title="Run reviews in CI" icon="infinity" href="self_hosted#cicd-integration">
        GitHub Actions, GitLab CI, and generic pipeline examples.
      </Card>

      <Card title="Plug into an AI agent" icon="robot" href="ai_agents">
        Feed `--prompt-only` into Claude Code, Cursor, or Codex for autonomous fix loops.
      </Card>

      <Card title="Configure the repo" icon="sliders" href="commands#fossa-config-repo">
        Manage ignored files, base branches, and review settings from the CLI.
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Environment Variables

These env vars configure the CLI across all commands.

| Variable | Description |
| - | - |
| `FOSSA_API_URL` | API endpoint (default: `https://api.fossa.local`) |
| `FOSSA_TEAM_KEY` | Team key for shared access and AI agents |
| `FOSSA_TOKEN` | CI/CD token generated via `fossa auth token` |
| `FOSSA_VERBOSE` | Set to `true` for verbose output |
| `FOSSA_SKIP_HOOK` | Set to `1` to skip the pre-push hook for a single `git push` |
| `FOSSA_REQUEST_TIMEOUT_MIN` | Per-request timeout in minutes (default: `60`) |
| `CF_ACCESS_CLIENT_ID` | Cloudflare Access client ID (APIs behind Zero Trust) |
| `CF_ACCESS_CLIENT_SECRET` | Cloudflare Access client secret |

For self-hosted setups, tokens, and Cloudflare Access, see [Self-Hosted Setup](self_hosted).

## Troubleshooting

Ran into an error? Check the [Troubleshooting guide](troubleshooting) for common symptoms and fixes.


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