Codex Security CLI reference

Use this reference to check the supported codex-security commands, flags, output formats, and exit behavior. For a guided first scan, start with the CLI quickstart.

Install the published package in your project:

npm install @openai/codex-security

Invoke the installed package as npx @openai/codex-security. You can use codex-security directly when the executable is available on your PATH.

Command overview

usage: codex-security [--version] <command> [options]

The CLI provides these commands:

The CLI also provides these integration commands:

List all available commands:

npx @openai/codex-security --help

Add --help to a command to inspect its arguments and options:

npx @openai/codex-security scan --help

codex-security --version prints the installed version and exits. codex-security info --json reports the SDK and bundled-plugin versions. Neither command requires Python.

Discover commands and connect agents

Print the agent-readable command manifest:

npx @openai/codex-security --llms

Inspect the scan argument schema as JSON:

npx @openai/codex-security scan --schema --format json

Generate shell completions for Bash:

npx @openai/codex-security completions bash

Replace bash with zsh or fish for those shells.

Scan results support --format toon|json|yaml|jsonl and --full-output. This framework-level --format is separate from --export-format, which selects the format of an artifact exported from a completed scan. Global command help also lists md, but scan results don’t support Markdown output.

Register the CLI as an MCP server:

npx @openai/codex-security mcp add

Sync Codex Security skills to your agents:

npx @openai/codex-security skills add

MCP exposes only the read-only info metadata command. Scans, exports, authentication, validation, and patching remain CLI-only.

codex-security scan

Run a scan against a repository, selected paths, committed changes, or the working tree.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH] [--scan-prompt-file FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository defaults to the current directory.

Select scan authentication

Use --auth auto, the default, to select credentials automatically. When both a ChatGPT sign-in and OPENAI_API_KEY or CODEX_API_KEY are available, interactive scans with text output ask which credential to use. CI, JSON and JSONL scans, and other scans without an interactive terminal use the environment API key. Dry runs don’t prompt or load credentials.

To use your stored credentials, pass --auth chatgpt:

npx @openai/codex-security scan . --auth chatgpt

To use an environment API key, pass --auth api-key:

npx @openai/codex-security scan . --auth api-key

To make stored credentials the automatic default, run unset OPENAI_API_KEY CODEX_API_KEY.

Use OpenRouter or Fireworks

Select OpenRouter with its API key and an explicit model:

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

Select Fireworks with its API key and an explicit model:

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

Both providers also support bulk-scan.

Use Amazon Bedrock

Select Amazon Bedrock with --provider amazon-bedrock and specify an explicit Bedrock model with --model:

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

Set AWS_REGION and authenticate with AWS_BEARER_TOKEN_BEDROCK, standard AWS access keys, an AWS profile, web identity, container credentials, or the default AWS credential chain. Bedrock scans use AWS credentials instead of --auth, ChatGPT sign-in, or an OpenAI API key. Both scan and bulk-scan support --provider.

Select the scan target

Choose one target type for each scan.

--path, --diff, and --working-tree are mutually exclusive. --head requires --diff, and --base requires --working-tree. Deep mode supports repository and path targets.

Diff and working-tree scans require the repository argument to be the Git worktree root. The selected refs must exist in that checkout.

Scan the entire repository:

npx @openai/codex-security scan .

Scan selected paths:

npx @openai/codex-security scan . --path src --path tests

Scan committed changes:

npx @openai/codex-security scan . --diff origin/main --head HEAD

Scan staged and unstaged changes:

npx @openai/codex-security scan . --working-tree --base HEAD

Run a deeper review of the repository:

npx @openai/codex-security scan . --mode deep

Configure deep scans

Use these options with --mode deep to control discovery concurrency and runtime:

--subagents accepts zero or a positive integer. The other options require a positive integer. These options aren’t available for standard scans.

For example, limit a deep scan to two discovery workers and ten total runs:

npx @openai/codex-security scan . \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10

Set persistent defaults in ~/.codex/codex-security/config.toml, or in $CODEX_HOME/codex-security/config.toml when you set CODEX_HOME:

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10

Command-line options override these defaults. scan --workers controls discovery workers within one scan; bulk-scan --workers controls concurrent repository scans.

Add security context

Use --knowledge-base PATH to provide architecture documents, threat models, or security policies. Repeat the option for more files or directories:

npx @openai/codex-security scan . \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Supported documents include .md, .markdown, .txt, .pdf, and .docx files. The CLI searches directories recursively, rejects linked input paths, skips linked directory entries, and keeps extracted document content outside the saved scan results.

Add scan instructions

To add scan instructions, provide a text or Markdown file with --scan-prompt-file. Use --post-scan-prompt-file to run follow-up instructions in the same authenticated session after a completed scan with complete coverage:

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

For example, use the scan prompt to focus on authorization boundaries and ask the follow-up to write a new post-scan-summary.md in the scan directory.

Set output and policy options

Use these options to keep artifacts, preserve earlier results, or create a machine-readable result.

The cost limit is an estimate, not a hard spending cap. Requests already in progress can finish slightly above the limit. If a scan aborts due to the cost limit, partial scan results remain available on disk.

When you omit --output-dir, results persist under $CODEX_HOME/state/plugins/codex-security/scans/<repository>. CODEX_HOME defaults to ~/.codex. Set CODEX_SECURITY_STATE_DIR to keep results under $CODEX_SECURITY_STATE_DIR/scans/<repository> instead. These directories can contain source excerpts and vulnerability details, so manage their permissions and retention accordingly.

The workbench keeps scan history in $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Setting CODEX_SECURITY_STATE_DIR also moves the workbench database.

The output directory must be outside the scanned directory and any enclosing Git worktree. A scan can replace an existing result directory with --archive-existing.

To preserve earlier results before reusing an output directory:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

Scans are report-only by default. Add --fail-on-severity to evaluate a severity policy in CI:

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

A dry run checks local inputs, including knowledge-base documents, without loading credentials, starting Codex, or probing the plugin’s Python interpreter:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

Configure the runtime

Use runtime options when you need an explicit model, interpreter, plugin, or Codex configuration value.

To select a different model and reasoning effort without writing TOML:

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

Quote string values passed through --codex so the TOML parser receives a string:

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

codex-security install-hook

Install a Git pre-commit security check for the current repository:

npx @openai/codex-security install-hook

The check scans staged and unstaged changes before each commit and blocks high-severity findings or scan errors. It respects core.hooksPath and does not replace an existing pre-commit script. Set a different severity threshold when needed:

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

Discover and scan GitHub repositories, or run a resumable scan from a repository CSV:

For a complete guide to GitHub discovery, CSV inventories, campaign results, and containerized scans, see Run bulk security scans.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Run npx @openai/codex-security bulk-scan without arguments to select repositories interactively. This flow requires a GitHub CLI sign-in.

To choose a model and reasoning effort during interactive discovery:

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

For a prepared repository list, provide a CSV and --output-dir:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

The CSV requires id, repository, and revision columns. Revisions must be full commit hashes. Optional scope, mode, and prompt columns configure individual repositories:

id,repository,revision,scope,mode,prompt
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Review authorization boundaries.

Use --knowledge-base PATH to share security documents across every repository. Use --scan-prompt-file FILE to add shared scan instructions; the CSV prompt column adds repository-specific instructions after that shared prompt. --post-scan-prompt-file FILE runs follow-up instructions after each completed scan with complete coverage.

--workers limits simultaneous repository scans and defaults to 4. --mode defaults to standard, and --max-attempts defaults to 1. Set --max-attempts to retry repository or scan errors. Completed scans with incomplete coverage aren’t retried. Their results remain available, and the command returns exit code 2.

Run the same command again to resume from an existing output directory. The CLI skips completed scans, including scans with incomplete coverage.

For containerized campaigns, see Run bulk scans in Docker.

codex-security scans

Find saved scans

List saved scans for the current directory:

npx @openai/codex-security scans

List scans for a different repository:

npx @openai/codex-security scans list /path/to/repository

Find scans stored under a specific output directory:

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

Inspect or repeat a scan

Show a saved scan’s results and configuration:

npx @openai/codex-security scans show SCAN_ID

Rerun the scan against the current checkout using its original configuration:

npx @openai/codex-security scans rerun SCAN_ID

Match and compare findings

Compare two scans to find new, persisting, reopened, resolved, and unknown findings:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

The comparison automatically matches findings that share the same root cause and reuses saved matches. To save matches explicitly, use scans match:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

A finding is unknown when the later scan has incomplete coverage or doesn’t cover the finding’s original location. Add --force to match when you need to recompute an existing match.

To match all completed scans for the current repository, including scans from other checkouts:

npx @openai/codex-security scans match --all

Scan results can vary even when you rerun the same configuration. Matching and comparison track changes; they don’t make results deterministic or prove that a vulnerability no longer exists. Use validate to recheck a security-critical finding against the current code.

codex-security findings

Record a reviewed finding as a false positive:

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

Inspect the saved scan to identify the finding occurrence:

npx @openai/codex-security scans show SCAN_ID

Record a specific explanation for the false positive:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

The reason must not be empty. Codex Security saves the decision for the repository and provides it as context to future scans. Each scan independently rechecks the current source, controls, and reachability. A previous decision doesn’t suppress a rule, path, or vulnerability class.

codex-security export

Export CSV, JSON, or SARIF from a completed, sealed scan. Export validates the scan artifacts before writing output and leaves the Codex runtime and credentials untouched.

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir is the completed scan directory.

--source-root works only with --export-format sarif. JSON preserves the sealed findings document. CSV contains portable finding columns and does not include local workbench triage state.

Without --output, the CLI writes SARIF to results.sarif, JSON to findings.json, and CSV to findings.csv in the current working directory. Exports can contain source excerpts and vulnerability details. Run the command outside the repository or pass --output with a private path outside the scanned checkout.

Write SARIF to a file:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

Write SARIF to stdout:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

Export findings as JSON:

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

Export findings as CSV:

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

codex-security validate and codex-security patch

Check whether a candidate finding is valid:

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

Generate a fix with the bundled remediation skill:

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

Each argument can contain literal text or point to a file. Both commands work against the current directory. Use validate to directly recheck an original finding after a fix or when a later scan no longer reports it. A scan comparison alone doesn’t prove that a fix worked. External tools can use these commands without rebuilding the scanner.

Use --effort to select reasoning effort for either command:

npx @openai/codex-security validate "Possible SQL injection" --effort high

codex-security login, logout, and info

Sign in interactively:

npx @openai/codex-security login

Use device authentication on a remote or headless machine:

npx @openai/codex-security login --device-auth

Check the current sign-in:

npx @openai/codex-security login status

Remove the stored sign-in:

npx @openai/codex-security logout

Store an API key by passing it on stdin:

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

Store an enterprise access token:

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

Inspect read-only SDK and bundled-plugin metadata:

npx @openai/codex-security info --json

When you expose the CLI as an MCP server, info is the only available command. Scans, exports, sign-in, validation, and patching remain CLI-only.

Read scan output

By default, scans send progress, completion summaries, and errors to stderr without writing the complete scan result to stdout. Request --json, --format, or --full-output to send structured scan results to stdout.

Interactive terminals show a live dashboard with the current scan phase, reviewed files, activity, token usage, and estimated cost. CI and redirected output use plain-text progress. Add --headless to use plain-text progress in an interactive terminal:

npx @openai/codex-security scan . --headless

Verbose diagnostics

Add --verbose to print redacted lifecycle, authentication, progress, and cost diagnostics to stderr:

npx @openai/codex-security scan . --verbose

Set CODEX_SECURITY_LOG_LEVEL=debug to enable the same diagnostics without the flag. LOG_LEVEL=debug also enables diagnostics when CODEX_SECURITY_LOG_LEVEL is unset.

These logging controls apply only to the CLI. Credentials and provider identifiers remain redacted, and structured scan results remain on stdout.

Completion summary

A completed scan writes its finding count, severity breakdown, coverage, elapsed time, report path, and result directory to stderr. It includes token usage and estimated cost when available:

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

Informational findings count toward the summary total. Severity policies evaluate only critical, high, medium, and low findings.

JSON output

scan --json writes one complete JSON document to stdout. Its top-level shape is:

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

Progress, completion summaries, archive notices, and errors remain on stderr. A completed scan still prints the full JSON result when a severity policy returns exit 1 or incomplete coverage returns exit 2.

Scan artifacts

A completed scan keeps the readable report and structured artifacts together:

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

The structured files serve different jobs:

Coverage completeness has three values:

• complete: The scan records complete coverage for its selected scope.
• partial: The scan records deferred work or other coverage limits.
• unknown: The scan reports coverage completeness as unknown.

Review deferred surfaces, explicit exclusions, and open questions before using coverage as evidence for a security decision.

Exit codes and signals

The CLI uses these exit codes:

Any scan with partial or unknown coverage returns 2, even without a severity policy. When you request structured output, completed scans still write the available results to stdout. The CLI prints the location of any partial output after an interruption or runtime error.

Authentication and prerequisites

Set OPENAI_API_KEY or CODEX_API_KEY, sign in with npx @openai/codex-security login, or use an existing file-backed Codex sign-in. For OpenRouter or Fireworks, set the provider’s API key and select a model. For Amazon Bedrock, use a Bedrock API key or the standard AWS credential chain instead.

For credential selection, see Select scan authentication.

For CI, keep the API key scoped to the scan step and use a trusted workflow.

The CLI requires Node.js 22.13.0 or later. Running a scan or exporting findings also requires Python 3.10 or later. Python 3.10 also requires tomli. Use --python or PYTHON to select an interpreter when automatic discovery is unsuitable.

Continue with the CLI quickstart, bulk-scan guide, CLI FAQ, CI guide, or TypeScript SDK guide.