CLI Reference¶

The foil CLI is a Click application with two flavours of commands:

scanning & findings — scan, findings, investigations, map
server & runtime — server, status, model, calibrate, uninstall

All commands support --help. The pages in this section are auto-generated from the Click app, so they always match the installed binary.

Command map¶

Command	Purpose
`scan`	Scan a file or directory for security vulnerabilities
`cancel-scan`	Cancel a running project scan by job ID
`scan-status`	Show running scan jobs and queue depth
`status`	Shortcut for `server status`
`findings`	View stored findings from the knowledge graph
`investigations`	View Phase 6 agentic investigation history
`map`	Show the code map for a project
`model`	Manage local LLM models
`server`	Manage the background server and vllm-mlx engine
`calibrate`	Run the model calibration benchmark
`uninstall`	Remove Foil completely

Full auto-generated reference¶

The block below renders the entire command tree in one place. Individual pages narrow the scope for easier navigation.

foil¶

Foil — Local AI-powered security code review for Apple Silicon.

By Peach Studio · https://peachstudio.be

Usage:

foil [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--version`	boolean	Show the version and exit.	`False`
`--verbose`	boolean	Enable verbose logging	`False`
`--help`	boolean	Show this message and exit.	`False`

foil calibrate¶

Run model calibration benchmark.

Usage:

foil calibrate [OPTIONS]

Options:

Name	Type	Description	Default
`--show`	boolean	Show calibration results	`False`
`--help`	boolean	Show this message and exit.	`False`

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:

Name	Type	Description	Default
`--server-url`	text	Foil server URL (default: http://127.0.0.1:9090)	None
`--help`	boolean	Show this message and exit.	`False`

foil findings¶

View stored findings from the knowledge graph.

PROJECT_PATH is the project folder (or any path inside it). Defaults to current directory.

Usage:

foil findings [OPTIONS] [PROJECT_PATH]

Options:

Name	Type	Description	Default
`--filter`	choice (`high` \| `medium` \| `low` \| `HIGH` \| `MEDIUM` \| `LOW`)	Filter by severity (e.g., --filter high)	`Sentinel.UNSET`
`--file`	text	Filter by file path	`Sentinel.UNSET`
`--show-all`	boolean	Include low-confidence findings	`False`
`--format`	choice (`json` \| `text`)	N/A	`text`
`--help`	boolean	Show this message and exit.	`False`

foil investigations¶

View Phase 6 agentic investigation history.

Shows every finding Phase 6 investigated during a foil scan --deep run, including DISMISSED ones — so you can audit what the scanner ruled out and why. CONFIRMED findings are also visible in foil findings (with verified=True); DISMISSED and UNCERTAIN verdicts only show here.

PROJECT_PATH is the project folder (or any path inside it). Defaults to current directory.

Usage:

foil investigations [OPTIONS] [PROJECT_PATH]

Options:

Name	Type	Description	Default
`--filter`	choice (`confirmed` \| `dismissed` \| `uncertain` \| `CONFIRMED` \| `DISMISSED` \| `UNCERTAIN`)	Filter by verdict	`Sentinel.UNSET`
`--format`	choice (`json` \| `text`)	N/A	`text`
`--help`	boolean	Show this message and exit.	`False`

foil map¶

Show the code map for a project (no LLM needed).

Usage:

foil map [OPTIONS] [TARGET]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil model¶

Manage LLM models.

Usage:

foil model [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil model activate¶

Activate a downloaded model. Restarts vllm-mlx if server is running.

Usage:

foil model activate [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil model delete¶

Delete a downloaded model.

Usage:

foil model delete [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil model download¶

Download a model from HuggingFace.

Usage:

foil model download [OPTIONS] REPO_ID

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil model list¶

List downloaded models.

Usage:

foil model list [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

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:

Name	Type	Description	Default
`--exclude`	text	Glob patterns to exclude	`Sentinel.UNSET`
`--depth`	choice (`quick` \| `standard` \| `thorough`)	N/A	`standard`
`--diff`	text	Scan only git diff against base	None
`--rescan`	boolean	Force rescan all files (ignore cached hashes)	`False`
`--engine`	choice (`v1` \| `v2`)	Scanner engine (v1=file-level, v2=function-level)	`v2`
`--format`	choice (`json` \| `text`)	N/A	`json`
`--standalone`	boolean	Start a local LLM server instead of using the running foil server	`False`
`--server-url`	text	Foil server URL (default: http://127.0.0.1:9090)	None
`--deep`	boolean	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.	`False`
`--no-guided-json`	boolean	Disable guided JSON schema enforcement. The model outputs freely and FindingParser handles parsing. May improve recall at the cost of occasional malformed output.	`False`
`--help`	boolean	Show this message and exit.	`False`

foil scan-status¶

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

Usage:

foil scan-status [OPTIONS]

Options:

Name	Type	Description	Default
`--server-url`	text	Foil server URL (default: http://127.0.0.1:9090)	None
`--help`	boolean	Show this message and exit.	`False`

foil server¶

Manage the running foil server and vllm-mlx engine.

Usage:

foil server [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil server clear-cache¶

Clear vllm-mlx prefix cache and GPU memory.

Usage:

foil server clear-cache [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil server license¶

Show current license status.

Usage:

foil server license [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil server logs¶

Show server logs (foil + vllm-mlx).

Usage:

foil server logs [OPTIONS]

Options:

Name	Type	Description	Default
`--lines`, `-n`	integer	Number of lines to show	`50`
`--follow`, `-f`	boolean	Follow log output	`False`
`--help`	boolean	Show this message and exit.	`False`

foil server projects¶

List registered projects.

Usage:

foil server projects [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil server remove-project¶

Remove a registered project.

Usage:

foil server remove-project [OPTIONS] PROJECT_ID

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil server resetpw¶

Reset the web UI password to default (IlovePeach).

Usage:

foil server resetpw [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil server restart-engine¶

Restart vllm-mlx without restarting the API server.

Usage:

foil server restart-engine [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil server start¶

Start the foil server in the background. Returns immediately.

Usage:

foil server start [OPTIONS]

Options:

Name	Type	Description	Default
`--port`	integer	Server port	`9090`
`--host`	text	Server host	`127.0.0.1`
`--project`	text	Project directories to register	`Sentinel.UNSET`
`--foreground`, `-f`	boolean	Run in foreground (default: background)	`False`
`--help`	boolean	Show this message and exit.	`False`

foil server status¶

Show status of foil server and vllm-mlx.

Usage:

foil server status [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil server stop¶

Stop the foil server and vllm-mlx.

Usage:

foil server stop [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil status¶

Shortcut for 'foil server status'.

Usage:

foil status [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

foil uninstall¶

Remove Foil completely from this machine.

Stops the server, removes ~/.foil (venv, database, settings, keys), removes the CLI from PATH, and optionally removes Foil.app.

Usage:

foil uninstall [OPTIONS]

Options:

Name	Type	Description	Default
`--keep-projects`	boolean	Keep project knowledge graphs (findings, code maps)	`False`
`--keep-models`	boolean	Keep downloaded models (~4+ GB each)	`False`
`--yes`, `-y`	boolean	Skip confirmation	`False`
`--help`	boolean	Show this message and exit.	`False`