Scan flags - AgentGG

This page lists every flag for agentgg scan. Run agentgg scan --help to see the same list from the CLI.

Agent selection

Flag	Default	What it does
`-t, --template <value>`	None	Restricts the scan to specific agents: a slug, a `.md` file, a directory, or a `.txt` list. Without it, the scan runs the default catalog.
`--semgrep-rules <dir>`	None	Points to a directory of local semgrep rule files an agent’s `preFilter` can name. It is searched before the catalog’s own rules directory.

Output and identity

Flag	Default	What it does
`-o, --output <path>`	`./scan-results/`	Sets the output directory for findings and scan state.
`--source-id <id>`	The absolute path of the scan root	Sets a stable ID for the scanned source. Resume state is reused when the ID matches. Set it when the scan path changes between runs.

Phases

Flag	Default	What it does
`--validate`	On	Runs a second validation pass on each finding to reduce false positives.
`--no-validate`	Off	Turns off the second validation pass. Findings then ship without a verdict.
`--score`	On	Runs the CVSS 3.1 score phase after validation and live validation. It skips duplicates and findings that the verdict rejects.
`--no-score`	Off	Turns off the CVSS 3.1 score phase. Findings then ship without a severity score.
`--fix`	On	Writes a suggested fix for each confirmed primary finding, after the score phase. See Suggested fixes.
`--no-fix`	Off	Turns off the fix phase. Confirmed findings then ship without a suggested fix.
`--scope <path>`	The built-in trust-boundary scope	Sets a scope file for the validator. With `--validate`, its rules feed the full classifier. Without `--validate`, it triggers a cheap scope-only check.
`--no-scope`	Off	Turns off the built-in default scope. Trust-boundary rules do not apply during validation.
`--dedup`	On	Runs the de-duplication phase right after detection. It groups findings that share a root cause, per file and across agents, and marks the non-primary ones. Validation and score then run on the primary findings only.
`--no-dedup`	Off	Turns off the de-duplication phase. Every finding is validated and scored alone, and all findings stay in the report.
`--delete-duplicates`	Off	With `--dedup`, removes duplicate findings after validation. The default marks them instead. A duplicate that became the primary is kept.
`--no-summary`	Off	Skips the markdown report at the end of the run. Findings still save to disk. Render the report later with `agentgg summary`.
`--exclude-false-positives`	Off	Skips the per-finding markdown file for findings the validator marks as false positive. Findings still save to disk.
`--re-recon`	Off	Reruns the recon survey and the precondition plan, even when a cached brief exists for this output directory.
`--no-recon`	Off	Skips the recon survey and the precondition gate. Every agent named with `-t` then runs without a check.

Live validation

These flags test findings against your running application. See Test findings against a running app.

Flag	Default	What it does
`--live-validate`	Off	Tests each primary finding against a running application in a Docker sandbox, after validation. Needs `--target-url` and a running Docker daemon.
`--target-url <url>`	None	Sets the root URL of the running application. Required with `--live-validate`.
`--target-context <ctx>`	None	Gives the test agent free-form notes, such as the test login, as text or as `@` and a file path.
`--target-image <ref>`	The pinned sandbox image	Sets a different sandbox image. agentgg does not build or pull a custom image.
`--sandbox-endpoint <url>`	None	Uses a sandbox that already runs, instead of starting Docker. Reads the control token from `$AGENTGG_SANDBOX_TOKEN`.
`--sandbox-control <url>`	The same host, port 8932	Sets the control server of the sandbox that `--sandbox-endpoint` names.
`--reproduce-timeout <s>`	600	Sets the time limit for one finding, in seconds. A test that reaches it keeps no evidence.
`--reproduce-max-turns <n>`	50	Sets the maximum browser steps for one finding.

Resume

Flag	Default	What it does
`--rescan`	Off	Re-analyzes files even when a prior run already covered them with the same content.
`--revalidate-all`	Off	Re-validates findings that already have a verdict on disk.
`--rescore`	Off	Re-scores findings that already have a CVSS score on disk.

Scope

Flag	Default	What it does
`--diff <commit>`	None	Restricts the scan to what a commit or a range touched. A bare ref reviews that commit against its parent. `a..b` is the tip-to-tip diff. `a...b` compares the merge base of `a` and `b` against `b`, which matches a pull request review. The working tree does not affect the result.
`--exclude <pattern>`	None	Excludes a path or glob from the scan. Repeat the flag to add more. The scan treats an excluded file as deleted.
`--only <pattern>`	None	Restricts the scan to files that match at least one given glob. Repeat the flag to add more patterns.
`--max-file-size <kb>`	500	Skips files larger than this size, in KB.
`--no-max-file-size`	Off	Removes the file size limit. The scan then reads files of any size.
`--no-default-excludes`	Off	Turns off the built-in exclude set: `node_modules`, `.git`, build directories, lockfiles, and binaries.
`--auto-exclude`	On	Lets the model pick folders to skip before the scan starts, for example tests or generated code.
`--no-auto-exclude`	Off	Turns off automatic folder exclusion. The scan then covers the full tree except your `--exclude` paths.

Limits

Flag	Default	What it does
`--max-files-per-batch <n>`	5	Sets how many candidate files go into one investigation batch.
`--max-anchors-per-batch <n>`	150	Caps the anchor lines in one batch. A file over the cap splits into more than one prompt.
`--no-max-anchors-per-batch`	Off	Removes the anchor cap. The scan never splits a file across batches.
`--max-files-per-agent <n>`	300	Caps the candidate files one agent reviews. The scan drops files past the cap for this run.
`--no-max-files-per-agent`	Off	Removes the per-agent file cap. Each agent then reviews every candidate file.
`--max-batches <n>`	250	Caps the total agent batches for the whole scan. Batches past the cap run on the next scan that reuses the same `--output`.
`--no-max-batches`	Off	Removes the whole-scan batch cap. The scan then runs every batch.
`--concurrency <n>`	5	Sets the maximum LLM sessions that run at the same time for the whole scan.
`--max-turns <n>`	`maxTurnsPerBatch`, else 50 (150 with no file scope)	Sets the maximum tool-use turns for one LLM session, overriding the agent’s own `maxTurnsPerBatch`. It applies to every agent batch, recon, the validator, and the fix phase. The fix phase uses at most 25 turns on every provider except Anthropic. See Targeting for how the per-agent default is chosen.

Provider

Flag	Default	What it does
`--provider <name>`	The saved default	Sets the provider for this run only: `anthropic`, `openai`, `ollama`, `bedrock`, `vertex`, or `openrouter`.
`--api-key <key>`	None	Sets a one-time API key for `anthropic`, `openai`, or `openrouter`. The CLI does not save it. For Anthropic, it also accepts an OAuth token.
`--oauth-token <token>`	None	Sets a one-time Anthropic OAuth token. The CLI does not save it.
`--base-url <url>`	None	Sets a one-time Ollama base URL. The CLI does not save it.
`--region <name>`	None	Sets the region for the active provider. For Bedrock it is an AWS region such as `us-east-1`, and it falls back to `$AWS_REGION` or `$AWS_DEFAULT_REGION`. For Vertex AI it is the publisher region pool, such as `global` or `us-central1`.
`--project <id>`	None	Sets the GCP project ID for Vertex AI. Falls back to `$GOOGLE_CLOUD_PROJECT` or `$GCLOUD_PROJECT`.
`--model <name>`	The saved default	Sets a one-time model override for the selected provider. The CLI does not save it.
`--openrouter-routing <json\|file>`	The saved routing	Sets an OpenRouter provider-routing block for this run, as inline JSON or a path to a JSON file. It overrides the saved routing and the `OPENROUTER_*` environment variables. OpenRouter only. See OpenRouter routing.
`--effort <level>`	None	Sets effort level for tool calls: `low`, `medium`, `high`, or `max`. OpenAI accepts it only on reasoning models. It has no effect on Bedrock, Vertex, or Ollama.
`--thinking <mode>`	None	Sets thinking mode for calls that use tools: `off`, `adaptive`, or `enabled`. Anthropic only; other providers ignore it.

Other

Flag	Default	What it does
`--serve [port]`	Port 3737	Starts a local web UI when the scan finishes. A busy port moves to the next free one.
`-v, --verbose`	Off	Prints more detail during the run.