118 [--subagents N] [--stop-after-no-new N]118 [--subagents N] [--stop-after-no-new N]
119 [--max-discovery-runs N] [--max-time-hours HOURS]119 [--max-discovery-runs N] [--max-time-hours HOURS]
120 [--model MODEL]120 [--model MODEL]
121 [--effort {minimal,low,medium,high,xhigh}]121 [--effort {minimal,low,medium,high,xhigh,max}]
122 [--output-dir DIR]122 [--output-dir DIR]
123 [--archive-existing]123 [--archive-existing]
124 [--plugin-path PATH] [--python PATH]124 [--plugin-path PATH] [--python PATH]
125 [--codex KEY=VALUE] [--fail-on-severity LEVEL]125 [--codex KEY=VALUE] [--fail-on-severity LEVEL]
126 [--patch] [--patch-severity {critical,high,medium,low}]
127 [--create-pr]
126 [--max-cost USD] [--dry-run] [--headless] [--verbose]128 [--max-cost USD] [--dry-run] [--headless] [--verbose]
127 [--json] [--format {toon,json,yaml,jsonl}]129 [--json] [--format {toon,json,yaml,jsonl}]
128 [--full-output] [repository]130 [--full-output] [repository]
337| `--output-dir DIR` | Write scan artifacts to a private directory outside the enclosing Git worktree. Defaults to persistent Codex Security state. |339| `--output-dir DIR` | Write scan artifacts to a private directory outside the enclosing Git worktree. Defaults to persistent Codex Security state. |
338| `--archive-existing` | Move existing results to `DIR.previous-<timestamp>-<id>` and start with an empty output directory. Requires `--output-dir`. |340| `--archive-existing` | Move existing results to `DIR.previous-<timestamp>-<id>` and start with an empty output directory. Requires `--output-dir`. |
339| `--fail-on-severity LEVEL` | Return exit `1` when a completed scan reports a finding at or above `critical`, `high`, `medium`, or `low`. |341| `--fail-on-severity LEVEL` | Return exit `1` when a completed scan reports a finding at or above `critical`, `high`, `medium`, or `low`. |
342| `--patch` | Fix and verify selected findings after a complete scan. |
343| `--patch-severity LEVEL` | Patch findings at or above `critical`, `high`, `medium`, or `low`. Defaults to `low`. |
344| `--create-pr` | Commit verified patch files and open a GitHub pull request. Requires `--patch`. |
340| `--max-cost USD` | Stop a scan when its estimated model cost exceeds the specified USD amount. |345| `--max-cost USD` | Stop a scan when its estimated model cost exceeds the specified USD amount. |
341| `--dry-run` | Check the repository, target, knowledge base, output directory, and Codex configuration without starting a scan. |346| `--dry-run` | Check the repository, target, knowledge base, output directory, and Codex configuration without starting a scan. |
342| `--headless` | Show plain-text progress instead of the interactive scan dashboard. |347| `--headless` | Show plain-text progress instead of the interactive scan dashboard. |
406| `--auth {auto,chatgpt,api-key}` | Select the scan credentials. The default is `auto`. |411| `--auth {auto,chatgpt,api-key}` | Select the scan credentials. The default is `auto`. |
407| `--provider {openai,openrouter,fireworks,amazon-bedrock}` | Select the inference provider. The default is `openai`. |412| `--provider {openai,openrouter,fireworks,amazon-bedrock}` | Select the inference provider. The default is `openai`. |
408| `--model MODEL` | Select the model. The default is `gpt-5.6-sol`. Required for OpenRouter, Fireworks, and Amazon Bedrock. |413| `--model MODEL` | Select the model. The default is `gpt-5.6-sol`. Required for OpenRouter, Fireworks, and Amazon Bedrock. |
409| `--effort {minimal,low,medium,high,xhigh}` | Select the model's reasoning effort. The default is `xhigh`. |414| `--effort {minimal,low,medium,high,xhigh,max}` | Select the model's reasoning effort. The default is `xhigh`. |
410| `--plugin-path PATH` | Use a Codex Security plugin directory or ZIP to override the bundled plugin. |415| `--plugin-path PATH` | Use a Codex Security plugin directory or ZIP to override the bundled plugin. |
411| `--python PATH` | Select the Python interpreter for the plugin runtime. |416| `--python PATH` | Select the Python interpreter for the plugin runtime. |
412| `--codex KEY=VALUE` | Override an isolated Codex configuration value. Values use TOML syntax. Repeat the flag for more values. |417| `--codex KEY=VALUE` | Override an isolated Codex configuration value. Values use TOML syntax. Repeat the flag for more values. |
455 [--workers N] [--mode {standard,deep}]460 [--workers N] [--mode {standard,deep}]
456 [--provider {openai,openrouter,fireworks,amazon-bedrock}]461 [--provider {openai,openrouter,fireworks,amazon-bedrock}]
457 [--model MODEL]462 [--model MODEL]
458 [--effort {minimal,low,medium,high,xhigh}]463 [--effort {minimal,low,medium,high,xhigh,max}]
459 [--knowledge-base PATH]464 [--knowledge-base PATH]
460 [--scan-prompt-file FILE]465 [--scan-prompt-file FILE]
461 [--post-scan-prompt-file FILE]466 [--post-scan-prompt-file FILE]
801 "Missing authorization check in src/routes.ts:18"806 "Missing authorization check in src/routes.ts:18"
802```807```
803 808
804Each argument can contain literal text or point to a file. Both commands work809Each positional argument accepts literal text or a file path. These inputs use
805against the current directory. Use `validate` to directly recheck an original810the current directory. Use `validate` to recheck a finding after a fix or when a
806finding after a fix or when a later scan no longer reports it. A scan811later scan no longer reports it. Comparing scans alone doesn't prove that a fix
807comparison alone doesn't prove that a fix worked. External tools can use these812worked.
808commands without rebuilding the scanner.
809 813
810Use `--effort` to select reasoning effort for either command:814Use `--effort` to select reasoning effort for either command:
811 815
813npx @openai/codex-security validate "Possible SQL injection" --effort high817npx @openai/codex-security validate "Possible SQL injection" --effort high
814```818```
815 819
820### Patch findings after a scan
821
822Use `scan --patch` to fix findings after a complete scan. This requires
823`@openai/codex-security` 0.1.15 or later. The default severity threshold is
824`low`. This command selects high and critical findings:
825
826```bash
827npx @openai/codex-security scan . --patch --patch-severity high --json
828```
829
830Verified and already-fixed findings don't trigger `--fail-on-severity`.
831
832### Patch saved findings
833
834Pass a finding or occurrence ID to patch its original repository, or select
835findings from a saved scan:
836
837```bash
838npx @openai/codex-security patch OCCURRENCE_ID
839npx @openai/codex-security patch --scan SCAN_ID --severity high --json
840npx @openai/codex-security patch --scan latest --severity medium
841```
842
843`--scan latest` selects the latest completed scan for the current repository.
844Saved-finding commands support `--json`; literal-text and file inputs don't.
845
846Add `--create-pr` to commit only verified patch files and open a pull request
847with the GitHub CLI:
848
849```bash
850npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr
851```
852
853If the push or pull request fails, run the printed `patch --resume-pr BRANCH`
854command from the same repository to retry.
855
856### Patch Linear issues
857
858Set `CODEX_SECURITY_LINEAR_API_KEY` or `LINEAR_API_KEY` for a personal API key,
859or `LINEAR_ACCESS_TOKEN` for an OAuth token. Prefer an environment variable to
860`--linear-api-key KEY` to keep the key out of shell history.
861
862Import an issue by ID or URL. Repeat `--linear-issue` to select more than one
863issue:
864
865```bash
866npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124
867```
868
869Use `--linear-project` to select a project's open issues. Add `--linear-filter`
870to narrow the selection:
871
872```bash
873npx @openai/codex-security patch --linear-project "Security backlog" \
874 --linear-filter '{"labels":{"name":{"eq":"security"}}}'
875```
876
877The CLI excludes completed and canceled issues unless the filter sets `state`.
878It doesn't change the Linear issues.
879
816## `codex-security login`, `logout`, and `info`880## `codex-security login`, `logout`, and `info`
817 881
818Sign in interactively:882Sign in interactively:
875npx @openai/codex-security scan . --headless939npx @openai/codex-security scan . --headless
876```940```
877 941
942The dashboard also shows live session details. They aren't redacted and can
943contain source code or credentials. Review them before sharing.
944
878### Verbose diagnostics945### Verbose diagnostics
879 946
880Add `--verbose` to print redacted lifecycle, authentication, progress, and cost947Add `--verbose` to print redacted lifecycle, authentication, progress, and cost
932 usage999 usage
933```1000```
934 1001
1002When [patching](#patch-findings-after-a-scan), JSON output also includes patch
1003results and any created pull request.
1004
935Progress, completion summaries, archive notices, and errors remain on stderr.1005Progress, completion summaries, archive notices, and errors remain on stderr.
936A completed scan still prints the full JSON result when a severity policy1006A completed scan still prints the full JSON result when a severity policy
937returns exit `1` or incomplete coverage returns exit `2`.1007returns exit `1` or incomplete coverage returns exit `2`.
