Skip to main content
Start any investigation with:
fossa status shows the consolidated state (auth mode, org, repo, hook, version). --verbose prints the resolved API URL and per-request details.

​
Common Errors

The CLI isn’t on your PATH. Reinstall with your package manager’s global flag, or use npx @fossa/cli <command> for one-off runs.
  • npm install -g @fossa/cli
  • yarn global add @fossa/cli
  • pnpm add -g @fossa/cli
  • bun add -g @fossa/cli
If you installed via the skill installer, re-run curl -fsSL https://review-skill.com/install | bash to fix PATH entries.
  • Run fossa auth status to see the current mode.
  • If using a team key, verify it’s still active at app.fossa.local/organization/cli-keys.
  • If using personal login, try fossa auth login again — the refresh token may have expired.
  • For CI, confirm FOSSA_TOKEN (or FOSSA_TEAM_KEY) is set in the environment the pipeline runs in.
  • If self-hosted, confirm FOSSA_API_URL points to the correct instance.
fossa review requires a git working directory. cd into a repo or initialize one with git init. For fossa config repo commands, you can pass owner/repo explicitly instead of ..
Large branches (hundreds of files, thousands of lines) can take several minutes. The default request timeout is 60 minutes — you should see progress in verbose mode.
  • Use --verbose to confirm the request is in flight.
  • For very large diffs, prefer --branch <base> or --commit <sha> over working-tree mode: these let the backend clone the same commit instead of receiving inlined file contents.
  • Override the timeout with FOSSA_REQUEST_TIMEOUT_MIN=90 fossa review if needed.
  • Split work across smaller branches when practical.
Review honors the ignore-files patterns configured in fossa config repo. List current settings with:
You can add or remove patterns:
Binary files, images, and lockfiles are skipped by default.
Trial mode allows 5 reviews per day. Sign in with fossa auth login or configure a team key via fossa auth team-key --key fossa_xxxxx to raise limits. fossa auth status prints your current usage.
Your FOSSA_API_URL is hitting a reverse proxy or Cloudflare Access page instead of the API. Check:
  • The URL path (no stray /api, /v1, etc.).
  • Cloudflare Access credentials (CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET) if applicable.
  • That the proxy forwards Authorization and CF-Access-* headers intact.
The CLI rejects non-HTTPS API URLs for everything except localhost and 127.0.0.1. Provision a valid TLS certificate for your self-hosted instance, or use http://localhost:<port> for local development.
  • Confirm installation: fossa hook status.
  • Make sure .git/hooks/pre-push is executable.
  • Other hook managers (Husky, Lefthook, pre-commit) may overwrite .git/hooks/pre-push. Either chain them or reinstall with fossa hook install --force.
  • Skip the hook for a single push: FOSSA_SKIP_HOOK=1 git push.
Self-hosted instances can enforce device limits per organization. Ask your admin to increase the limit or remove unused devices from the dashboard.

​
Exit Codes

Use these in scripts and CI pipelines.
For CI, pair --fail-on error with --format json and --output review.json to surface structured results as pipeline artifacts without affecting the exit code logic.

​
Debugging Tips

  • --verbose on any command prints the resolved API URL, request IDs, and timings.
  • fossa schema outputs the machine-readable command schema — useful when your agent reports a missing flag.
  • --agent enforces deterministic, machine-readable output; combine with --format json when scripting.
  • FOSSA_VERBOSE=true persists verbose mode across multiple commands in a session.

​
Getting Help

  • Report bugs: github.com/brittytino/fossa/issues
  • Feature requests, configuration questions: your Fossa account manager, or support@fossa.local.
  • For self-hosted deployments, include fossa status --verbose output when filing an issue.