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.

When you install the package in a local project, invoke the executable as npx codex-security. 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 codex-security --help

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

npx 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 codex-security --llms

Inspect the scan argument schema as JSON:

npx codex-security scan --schema --format json

Generate shell completions for Bash:

npx 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 codex-security mcp add

Sync Codex Security skills to your agents:

npx 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] [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--json] [repository]

repository defaults to the current directory.

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 codex-security scan .

Scan selected paths:

npx codex-security scan . --path src --path tests

Scan committed changes:

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

Scan staged and unstaged changes:

npx codex-security scan . --working-tree --base HEAD

Run a deeper review of the repository:

npx codex-security scan . --mode deep

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 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.

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 above the limit, and partial scan results remain available.

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 output directory can be new or empty. On macOS and Linux, an existing directory must be private to the current user. A scan can replace an existing result directory with --archive-existing.

npx 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 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 without loading credentials, starting Codex, or probing the plugin’s Python interpreter:

npx 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.

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

npx codex-security scan . --codex 'model="<model>"'

Codex Security owns plugin-loading configuration and rejects conflicting overrides. Use --plugin-path to select a plugin.

codex-security install-hook

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

npx 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 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}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Run codex-security bulk-scan without arguments or options to select repositories interactively. This flow requires a GitHub CLI sign-in.

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

npx 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 and mode columns configure individual repositories:

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

--workers limits simultaneous scans and defaults to 4. --mode defaults to standard, and --max-attempts defaults to 1. Set --max-attempts when you want to retry a repository after an error. Run the same command again to resume a bulk scan from its existing output directory. The CLI skips completed repositories only when their recorded result artifacts are still present.

For containerized campaigns, see Run bulk scans in Docker.

codex-security scans

Find saved scans

List saved scans for the current directory:

npx codex-security scans

List scans for a different repository:

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

Find scans stored under a specific output directory:

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

Inspect or repeat a scan

Show a saved scan’s results and configuration:

npx codex-security scans show SCAN_ID

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

npx codex-security scans rerun SCAN_ID

Match and compare findings

Match findings that share the same root cause across two scans:

npx codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

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

npx codex-security scans compare 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 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 mark-false-positive OCCURRENCE_ID
                       --reason REASON

Inspect the saved scan to identify the finding occurrence:

npx codex-security scans show SCAN_ID

Record a specific explanation for the false positive:

npx codex-security findings mark-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 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 codex-security export /path/to/scan --export-format sarif --source-root . --output -

Export findings as JSON:

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

Export findings as CSV:

npx 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 codex-security validate findings.json "Possible SQL injection in src/query.ts:42"

Generate a fix with the bundled remediation skill:

npx 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.

codex-security login, logout, and info

Sign in interactively:

npx codex-security login

Use device authentication on a remote or headless machine:

npx codex-security login --device-auth

Check the current sign-in:

npx codex-security login status

Remove the stored sign-in:

npx codex-security logout

Store an API key by passing it on stdin:

printenv OPENAI_API_KEY | npx codex-security login --with-api-key

Store an enterprise access token:

printenv CODEX_ACCESS_TOKEN | npx codex-security login --with-access-token

Inspect read-only SDK and bundled-plugin metadata:

npx 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

The CLI writes structured command results to stdout and sends progress, completion summaries, and errors to stderr. This lets terminal users read a summary while automation captures a clean JSON or SARIF document.

Completion summary

A completed scan writes its finding count, severity breakdown, coverage, elapsed time, result directory, and next step to stderr. It includes worker counts and token usage when available:

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s. Workers: 3/6.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Results: /path/to/scan
codex-security: Next: codex-security export /path/to/scan --export-format sarif

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. 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 codex-security login, or use an existing file-backed Codex sign-in. Environment API keys take precedence over stored credentials. For CI, keep the API key scoped to the scan step and use a trusted workflow.

The CLI requires Node.js 22 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.