scan¶

Scan a file or directory. By default, delegates to the running foil server started by the tray app or by foil server start.

foil scan¶

Scan a file or directory for security vulnerabilities.

By default, delegates to the running foil server (started via Foil.app or foil server start). Use --standalone to run a local LLM server instead (loads the model in this process — slower startup, uses more memory).

Usage:

foil scan [OPTIONS] TARGET

Options:

  --exclude TEXT                  Glob patterns to exclude
  --depth [quick|standard|thorough]
  --diff TEXT                     Scan only git diff against base
  --rescan                        Force rescan all files (ignore cached
                                  hashes)
  --engine [v1|v2]                Scanner engine (v1=file-level, v2=function-
                                  level)
  --format [json|text]
  --standalone                    Start a local LLM server instead of using
                                  the running foil server
  --server-url TEXT               Foil server URL (default:
                                  http://127.0.0.1:9090)
  --deep                          Enable Phase 6 investigation loop for HIGH
                                  logic-vuln findings (IDOR, broken auth,
                                  broken access). Adds 30-90s per HIGH
                                  finding. Recommended for targeted audits,
                                  not CI/CD.
  --no-guided-json                Disable guided JSON schema enforcement. The
                                  model outputs freely and FindingParser
                                  handles parsing. May improve recall at the
                                  cost of occasional malformed output.
  --help                          Show this message and exit.

Typical invocations¶

# Standard scan of a project
foil scan ~/src/myapp

# Quick smoke test
foil scan ~/src/myapp --depth quick

# Targeted audit with agentic deep dive
foil scan ~/src/myapp --deep

# Scan only changes against main
foil scan ~/src/myapp --diff main

# Standalone mode — no running server required
foil scan ~/src/myapp --standalone

Notes¶

--engine v2 (default) runs the function-level scanner. v1 is legacy file-level.
--deep adds 30–90s per HIGH logic-class finding. Recommended for audits, not CI/CD.
--rescan forces a full re-scan; without it, unchanged files are skipped by hash.
Output with --format json is machine-readable and mirrors what the dashboard consumes.

cancel-scan¶

foil cancel-scan¶

Cancel a running project scan by job ID.

The job ID is returned when you start a project scan via the API (POST /api/scan/project). You can also find running jobs via foil scan-status.

Usage:

foil cancel-scan [OPTIONS] JOB_ID

Options:

  --server-url TEXT  Foil server URL (default: http://127.0.0.1:9090)
  --help             Show this message and exit.

scan-status¶

foil scan-status¶

Show running scan jobs. Use the job ID with foil cancel-scan.

Usage:

foil scan-status [OPTIONS]

Options:

  --server-url TEXT  Foil server URL (default: http://127.0.0.1:9090)
  --help             Show this message and exit.