1# Codex Security CLI reference
2
3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
4
5Use this reference to check the supported `codex-security` commands, flags,
6output formats, and exit behavior. For a guided first scan, start with the
7[CLI quickstart](https://learn.chatgpt.com/docs/security/cli).
8
9The Codex Security CLI is in beta and requires access. Follow the installation
10 instructions provided with your access.
11
12When you install the package in a local project, invoke the executable as
13`npx codex-security`. Use `codex-security` directly when the executable is
14available on your `PATH`.
15
16## Command overview
17
18```text
19usage: codex-security [--version] <command> [options]
20```
21
22The CLI provides these commands:
23
24| Command | Purpose |
25| ----------------------------- | ----------------------------------------------------- |
26| `codex-security scan` | Run a Codex Security scan. |
27| `codex-security install-hook` | Install a Git pre-commit security scan. |
28| `codex-security bulk-scan` | Discover repositories and run resumable bulk scans. |
29| `codex-security scans` | List, inspect, match, rerun, and compare saved scans. |
30| `codex-security findings` | Review and update saved security findings. |
31| `codex-security export` | Export completed findings as CSV, JSON, or SARIF. |
32| `codex-security validate` | Check one or more candidate security findings. |
33| `codex-security patch` | Patch one or more security issues. |
34| `codex-security login` | Sign in, store credentials, or check sign-in status. |
35| `codex-security logout` | Remove the stored sign-in. |
36| `codex-security info` | Show read-only SDK and bundled-plugin metadata. |
37
38The CLI also provides these integration commands:
39
40| Command | Purpose |
41| ---------------------------- | ------------------------------------- |
42| `codex-security completions` | Generate shell completion scripts. |
43| `codex-security mcp` | Register the CLI as an MCP server. |
44| `codex-security skills` | Sync Codex Security skills to agents. |
45
46List all available commands:
47
48```bash
49npx codex-security --help
50```
51
52Add `--help` to a command to inspect its arguments and options:
53
54```bash
55npx codex-security scan --help
56```
57
58`codex-security --version` prints the installed version and exits.
59`codex-security info --json` reports the SDK and bundled-plugin versions.
60Neither command requires Python.
61
62### Discover commands and connect agents
63
64Print the agent-readable command manifest:
65
66```bash
67npx codex-security --llms
68```
69
70Inspect the scan argument schema as JSON:
71
72```bash
73npx codex-security scan --schema --format json
74```
75
76Generate shell completions for Bash:
77
78```bash
79npx codex-security completions bash
80```
81
82Replace `bash` with `zsh` or `fish` for those shells.
83
84Scan results support `--format toon|json|yaml|jsonl` and `--full-output`. This
85framework-level `--format` is separate from `--export-format`, which selects
86the format of an artifact exported from a completed scan. Global command help
87also lists `md`, but scan results don't support Markdown output.
88
89Register the CLI as an MCP server:
90
91```bash
92npx codex-security mcp add
93```
94
95Sync Codex Security skills to your agents:
96
97```bash
98npx codex-security skills add
99```
100
101MCP exposes only the read-only `info` metadata command. Scans, exports,
102authentication, validation, and patching remain CLI-only.
103
104## `codex-security scan`
105
106Run a scan against a repository, selected paths, committed changes, or the
107working tree.
108
109```text
110usage: codex-security scan [-h] [--path PATH | --diff BASE | --working-tree]
111 [--head HEAD] [--base BASE]
112 [--knowledge-base PATH]
113 [--mode {standard,deep}] [--model MODEL]
114 [--output-dir DIR]
115 [--archive-existing]
116 [--plugin-path PATH] [--python PATH]
117 [--codex KEY=VALUE] [--fail-on-severity LEVEL]
118 [--max-cost USD] [--dry-run] [--json] [repository]
119```
120
121`repository` defaults to the current directory.
122
123### Select the scan target
124
125Choose one target type for each scan.
126
127| Argument | Description |
128| ------------------------ | ------------------------------------------------------------------------------- |
129| `--path PATH` | Scan a path relative to the repository. Repeat the flag for more paths. |
130| `--diff BASE` | Scan committed changes from `BASE` to `--head`. The head defaults to `HEAD`. |
131| `--head HEAD` | Set the head revision for `--diff`. |
132| `--working-tree` | Scan staged and unstaged changes against `--base`. The base defaults to `HEAD`. |
133| `--base BASE` | Set the base revision for `--working-tree`. |
134| `--mode {standard,deep}` | Select the scan mode. The default is `standard`. |
135
136`--path`, `--diff`, and `--working-tree` are mutually exclusive. `--head`
137requires `--diff`, and `--base` requires `--working-tree`. Deep mode supports
138repository and path targets.
139
140Diff and working-tree scans require the repository argument to be the Git
141worktree root. The selected refs must exist in that checkout.
142
143Scan the entire repository:
144
145```bash
146npx codex-security scan .
147```
148
149Scan selected paths:
150
151```bash
152npx codex-security scan . --path src --path tests
153```
154
155Scan committed changes:
156
157```bash
158npx codex-security scan . --diff origin/main --head HEAD
159```
160
161Scan staged and unstaged changes:
162
163```bash
164npx codex-security scan . --working-tree --base HEAD
165```
166
167Run a deeper review of the repository:
168
169```bash
170npx codex-security scan . --mode deep
171```
172
173### Add security context
174
175Use `--knowledge-base PATH` to provide architecture documents, threat models,
176or security policies. Repeat the option for more files or directories:
177
178```bash
179npx codex-security scan . \
180 --knowledge-base /path/to/architecture.md \
181 --knowledge-base /path/to/security-policies
182```
183
184Supported documents include `.md`, `.markdown`, `.txt`, `.pdf`, and `.docx`
185files. The CLI searches directories recursively, rejects linked input paths,
186skips linked directory entries, and keeps extracted document content
187outside the saved scan results.
188
189### Set output and policy options
190
191Use these options to keep artifacts, preserve earlier results, or create a
192machine-readable result.
193
194| Argument | Description |
195| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
196| `--output-dir DIR` | Write scan artifacts to a private directory outside the enclosing Git worktree. Defaults to persistent Codex Security state. |
197| `--archive-existing` | Move existing results to `DIR.previous-<timestamp>-<id>` and start with an empty output directory. Requires `--output-dir`. |
198| `--fail-on-severity LEVEL` | Return exit `1` when a completed scan reports a finding at or above `critical`, `high`, `medium`, or `low`. |
199| `--max-cost USD` | Stop a scan when its estimated model cost exceeds the specified USD amount. |
200| `--dry-run` | Check the repository, target, output directory, and Codex configuration without starting a scan. |
201| `--json` | Print manifest, findings, coverage, paths, and turn metadata as one JSON document. |
202
203The cost limit is an estimate, not a hard spending cap. Requests already in
204progress can finish above the limit, and partial scan results remain available.
205
206When you omit `--output-dir`, results persist under
207`$CODEX_HOME/state/plugins/codex-security/scans/<repository>`. `CODEX_HOME`
208defaults to `~/.codex`. Set `CODEX_SECURITY_STATE_DIR` to keep results under
209`$CODEX_SECURITY_STATE_DIR/scans/<repository>` instead. These directories can
210contain source excerpts and vulnerability details, so manage their permissions
211and retention accordingly.
212
213The output directory can be new or empty. On macOS and Linux, an existing
214directory must be private to the current user. A scan can replace an existing
215result directory with `--archive-existing`.
216
217```bash
218npx codex-security scan . \
219 --output-dir /path/outside/repository/results \
220 --archive-existing
221```
222
223Scans are report-only by default. Add `--fail-on-severity` to evaluate a
224severity policy in CI:
225
226```bash
227npx codex-security scan . \
228 --diff origin/main \
229 --output-dir /path/outside/repository/results \
230 --json \
231 --fail-on-severity high \
232 > /path/outside/repository/codex-security.json
233```
234
235A dry run checks local inputs without loading credentials, starting Codex, or
236probing the plugin's Python interpreter:
237
238```bash
239npx codex-security scan . --output-dir /path/outside/repository/results --dry-run
240```
241
242### Configure the runtime
243
244Use runtime options when you need an explicit model, interpreter, plugin, or
245Codex configuration value.
246
247| Argument | Description |
248| -------------------- | -------------------------------------------------------------------------------------------------------- |
249| `--model MODEL` | Select the model for the scan. |
250| `--plugin-path PATH` | Use a Codex Security plugin directory or ZIP to override the bundled plugin. |
251| `--python PATH` | Select the Python interpreter for the plugin runtime. |
252| `--codex KEY=VALUE` | Override an isolated Codex configuration value. Values use TOML syntax. Repeat the flag for more values. |
253
254Quote string values passed through `--codex` so the TOML parser receives a
255string:
256
257```bash
258npx codex-security scan . --codex 'model="<model>"'
259```
260
261Codex Security owns plugin-loading configuration and rejects conflicting
262overrides. Use `--plugin-path` to select a plugin.
263
264## `codex-security install-hook`
265
266Install a Git pre-commit security check for the current repository:
267
268```bash
269npx codex-security install-hook
270```
271
272The check scans staged and unstaged changes before each commit and blocks
273high-severity findings or scan errors. It respects `core.hooksPath` and does
274not replace an existing pre-commit script. Set a different severity threshold
275when needed:
276
277```bash
278npx codex-security install-hook . --fail-on-severity medium
279```
280
281## `codex-security bulk-scan`
282
283Discover and scan GitHub repositories, or run a resumable scan from a
284repository CSV:
285
286For a complete guide to GitHub discovery, CSV inventories, campaign results,
287and containerized scans, see [Run bulk security
288scans](https://learn.chatgpt.com/docs/security/cli/bulk-scans).
289
290```text
291usage: codex-security bulk-scan [input] [--output-dir DIR]
292 [--workers N] [--mode {standard,deep}]
293 [--max-attempts N] [--plugin-path PATH]
294 [--python PATH] [--codex KEY=VALUE]
295```
296
297Run `codex-security bulk-scan` without arguments or options to select
298repositories interactively. This flow requires a GitHub CLI sign-in.
299
300For a prepared repository list, provide a CSV and `--output-dir`:
301
302```bash
303npx codex-security bulk-scan repositories.csv \
304 --output-dir /path/outside/repositories/security-scans \
305 --workers 4
306```
307
308The CSV requires `id`, `repository`, and `revision` columns. Revisions must be
309full commit hashes. Optional `scope` and `mode` columns configure individual
310repositories:
311
312```csv
313id,repository,revision,scope,mode
314service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard
315```
316
317`--workers` limits simultaneous scans and defaults to `4`. `--mode` defaults to
318`standard`, and `--max-attempts` defaults to `1`. Set `--max-attempts` when
319you want to retry a repository after an error. Run the same command again to
320resume a bulk scan from its existing output directory. The CLI skips completed
321repositories only when their recorded result artifacts are still present.
322
323For containerized campaigns, see [Run bulk scans in
324Docker](https://learn.chatgpt.com/docs/security/cli/bulk-scans#run-bulk-scans-in-docker).
325
326## `codex-security scans`
327
328### Find saved scans
329
330List saved scans for the current directory:
331
332```bash
333npx codex-security scans
334```
335
336List scans for a different repository:
337
338```bash
339npx codex-security scans list /path/to/repository
340```
341
342Find scans stored under a specific output directory:
343
344```bash
345npx codex-security scans list --scan-root /path/outside/repository/results
346```
347
348### Inspect or repeat a scan
349
350Show a saved scan's results and configuration:
351
352```bash
353npx codex-security scans show SCAN_ID
354```
355
356Rerun the scan against the current checkout using its original configuration:
357
358```bash
359npx codex-security scans rerun SCAN_ID
360```
361
362### Match and compare findings
363
364Match findings that share the same root cause across two scans:
365
366```bash
367npx codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
368```
369
370Compare the matched scans to find new, persisting, reopened, resolved, and
371unknown findings:
372
373```bash
374npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
375```
376
377A finding is unknown when the later scan has incomplete coverage or doesn't
378cover the finding's original location. Add `--force` to `match` when you need to
379recompute an existing match.
380
381To match all completed scans for the current repository, including scans from
382other checkouts:
383
384```bash
385npx codex-security scans match --all
386```
387
388Scan results can vary even when you rerun the same configuration. Matching and
389comparison track changes; they don't make results deterministic or prove that a
390vulnerability no longer exists. Use `validate` to recheck a security-critical
391finding against the current code.
392
393## `codex-security findings`
394
395Record a reviewed finding as a false positive:
396
397```text
398usage: codex-security findings mark-false-positive OCCURRENCE_ID
399 --reason REASON
400```
401
402Inspect the saved scan to identify the finding occurrence:
403
404```bash
405npx codex-security scans show SCAN_ID
406```
407
408Record a specific explanation for the false positive:
409
410```bash
411npx codex-security findings mark-false-positive FINDING_OCCURRENCE_ID \
412 --reason "The framework escapes this input before it reaches the query"
413```
414
415The reason must not be empty. Codex Security saves the decision for the
416repository and provides it as context to future scans. Each scan independently
417rechecks the current source, controls, and reachability. A previous decision
418doesn't suppress a rule, path, or vulnerability class.
419
420## `codex-security export`
421
422Export CSV, JSON, or SARIF from a completed, sealed scan. Export validates the
423scan artifacts before writing output and leaves the Codex runtime and
424credentials untouched.
425
426```text
427usage: codex-security export [--export-format {csv,json,sarif}]
428 [--output FILE|-] [--source-root PATH]
429 [--python PATH] scan_dir
430```
431
432`scan_dir` is the completed scan directory.
433
434| Argument | Description |
435| ---------------------------------- | ------------------------------------------------------------------------------------------- |
436| `--export-format {csv,json,sarif}` | Select the export format. The default is `sarif`. |
437| `--output FILE\|-` | Write the selected format to a file or stdout. Defaults to a file in the current directory. |
438| `--source-root PATH` | Add source-line fingerprints to SARIF using a repository checkout. |
439| `--python PATH` | Select the Python interpreter for the bundled exporter. |
440
441`--source-root` works only with `--export-format sarif`. JSON preserves
442the sealed findings document. CSV contains portable finding columns and does
443not include local workbench triage state.
444
445Without `--output`, the CLI writes SARIF to `results.sarif`, JSON to
446`findings.json`, and CSV to `findings.csv` in the current working directory.
447Exports can contain source excerpts and vulnerability details. Run the command
448outside the repository or pass `--output` with a private path outside the
449scanned checkout.
450
451Write SARIF to a file:
452
453```bash
454npx codex-security export /path/to/scan \
455 --export-format sarif \
456 --source-root /path/to/repository \
457 --output /path/outside/repository/exports/results.sarif
458```
459
460Write SARIF to stdout:
461
462```bash
463npx codex-security export /path/to/scan --export-format sarif --source-root . --output -
464```
465
466Export findings as JSON:
467
468```bash
469npx codex-security export /path/to/scan \
470 --export-format json \
471 --output /path/outside/repository/exports/findings.json
472```
473
474Export findings as CSV:
475
476```bash
477npx codex-security export /path/to/scan \
478 --export-format csv \
479 --output /path/outside/repository/exports/findings.csv
480```
481
482## `codex-security validate` and `codex-security patch`
483
484Check whether a candidate finding is valid:
485
486```bash
487npx codex-security validate findings.json "Possible SQL injection in src/query.ts:42"
488```
489
490Generate a fix with the bundled remediation skill:
491
492```bash
493npx codex-security patch findings.json "Missing authorization check in src/routes.ts:18"
494```
495
496Each argument can contain literal text or point to a file. Both commands work
497against the current directory. Use `validate` to directly recheck an original
498finding after a fix or when a later scan no longer reports it. A scan
499comparison alone doesn't prove that a fix worked. External tools can use these
500commands without rebuilding the scanner.
501
502## `codex-security login`, `logout`, and `info`
503
504Sign in interactively:
505
506```bash
507npx codex-security login
508```
509
510Use device authentication on a remote or headless machine:
511
512```bash
513npx codex-security login --device-auth
514```
515
516Check the current sign-in:
517
518```bash
519npx codex-security login status
520```
521
522Remove the stored sign-in:
523
524```bash
525npx codex-security logout
526```
527
528Store an API key by passing it on stdin:
529
530```bash
531printenv OPENAI_API_KEY | npx codex-security login --with-api-key
532```
533
534Store an enterprise access token:
535
536```bash
537printenv CODEX_ACCESS_TOKEN | npx codex-security login --with-access-token
538```
539
540Inspect read-only SDK and bundled-plugin metadata:
541
542```bash
543npx codex-security info --json
544```
545
546When you expose the CLI as an MCP server, `info` is the only available command.
547Scans, exports, sign-in, validation, and patching remain CLI-only.
548
549## Read scan output
550
551The CLI writes structured command results to stdout and sends progress,
552completion summaries, and errors to stderr. This lets terminal users read a
553summary while automation captures a clean JSON or SARIF document.
554
555### Completion summary
556
557A completed scan writes its finding count, severity breakdown, coverage,
558elapsed time, result directory, and next step to stderr. It includes worker
559counts and token usage when available:
560
561```text
562codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
563codex-security: Elapsed: 1s. Workers: 3/6.
564codex-security: Tokens: 1,250 input, 200 cached, 30 output.
565codex-security: Results: /path/to/scan
566codex-security: Next: codex-security export /path/to/scan --export-format sarif
567```
568
569Informational findings count toward the summary total. Severity policies
570evaluate only `critical`, `high`, `medium`, and `low` findings.
571
572### JSON output
573
574`scan --json` writes one complete JSON document to stdout. Its top-level shape
575is:
576
577```text
578manifest
579findings
580coverage
581scanDir
582threadId
583reportPath
584artifactsDir
585sarifPath
586turn
587 id
588 status
589 durationMs
590 finalResponse
591 usage
592```
593
594Progress, completion summaries, archive notices, and errors remain on stderr.
595A completed scan still prints the full JSON result when a severity policy
596returns exit `1` or incomplete coverage returns exit `2`.
597
598`codex-security scan --json` emits one JSON document. `codex exec --json`
599 emits a JSON Lines event stream. Use the output format that matches the
600 command you run.
601
602## Scan artifacts
603
604A completed scan keeps the readable report and structured artifacts together:
605
606```text
607<scan-directory>/
608├── scan-manifest.json
609├── findings.json
610├── coverage.json
611├── report.md
612├── artifacts/
613└── exports/
614 └── results.sarif # when produced
615```
616
617The structured files serve different jobs:
618
619| File | Contents |
620| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
621| `scan-manifest.json` | Scan identity, status, target, scope, producer, and sealed artifact records. |
622| `findings.json` | Finding identifiers, severity, confidence, taxonomy, locations, evidence, validation, data flow, reachability, and remediation. |
623| `coverage.json` | Reviewed surfaces, exclusions, deferred work, open questions, and coverage completeness. |
624| `report.md` | Readable scan report. |
625| `artifacts/` | Supporting scan artifacts. |
626| `exports/results.sarif` | SARIF generated during the scan, when present. |
627
628Coverage completeness has three values:
629
630- `complete`: The scan records complete coverage for its selected scope.
631- `partial`: The scan records deferred work or other coverage limits.
632- `unknown`: The scan reports coverage completeness as unknown.
633
634Review deferred surfaces, explicit exclusions, and open questions before using
635coverage as evidence for a security decision.
636
637## Exit codes and signals
638
639The CLI uses these exit codes:
640
641| Exit | Condition |
642| ----- | --------------------------------------------------------------------------------------------------------------------------------------------- |
643| `0` | A scan completed with complete coverage and passed its severity policy, a bulk scan completed without failures, or another command succeeded. |
644| `1` | A completed scan reports a finding at or above the configured severity. |
645| `2` | The CLI found an input, runtime, or export error, a scan has incomplete coverage, or a bulk scan has repositories with errors. |
646| `130` | Ctrl-C interrupted a scan. |
647| `143` | SIGTERM terminated a scan. |
648
649Any scan with `partial` or `unknown` coverage returns `2`, even without a
650severity policy. Completed scans still write the available results to stdout.
651The CLI prints the location of any partial output after an interruption or
652runtime error.
653
654## Authentication and prerequisites
655
656Set `OPENAI_API_KEY` or `CODEX_API_KEY`, sign in with `codex-security login`, or
657use an existing file-backed Codex sign-in. Environment API keys take precedence
658over stored credentials. For CI, keep the API key scoped to the scan step and
659use a trusted workflow.
660
661The CLI requires Node.js 22 or later. Running a scan or exporting findings also
662requires Python 3.10 or later. Python 3.10 also requires `tomli`. Use `--python`
663or `PYTHON` to select an interpreter when automatic discovery is unsuitable.
664
665Continue with the [CLI quickstart](https://learn.chatgpt.com/docs/security/cli), [bulk-scan
666guide](https://learn.chatgpt.com/docs/security/cli/bulk-scans), [CLI FAQ](https://learn.chatgpt.com/docs/security/cli/faq), [CI
667guide](https://learn.chatgpt.com/docs/security/cli/ci), or [TypeScript SDK guide](https://learn.chatgpt.com/docs/security/sdk).
668
669### Plain-text aliases
670
671- --output FILE|-
