Codex Security CLI FAQ

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Find answers to common questions about scanning repositories and managing security findings from the terminal. For installation and a first scan, start with the CLI quickstart.

Repository scans

Who can use the CLI

The @openai/codex-security package is public. Install the CLI and SDK:

npm install @openai/codex-security

Running scans requires Codex Security access. For best results, use an account verified for Trusted Access for Cyber.

Why does a scan use an API key after sign-in

When your environment includes OPENAI_API_KEY or CODEX_API_KEY, scans without an interactive terminal and JSON and JSONL scans use the environment API key by default, even after a successful ChatGPT or access-token login. Interactive scans with text output ask you to choose when a ChatGPT sign-in is also available. Dry runs don't prompt or load credentials.

To use your stored credentials for a scan, select them explicitly:

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

To require an API key from OPENAI_API_KEY or CODEX_API_KEY:

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

To make your stored credentials the automatic default, run unset OPENAI_API_KEY CODEX_API_KEY. For all supported authentication modes, see the CLI reference.

How does bulk repository scanning work

Sign in with GitHub CLI:

gh auth login

Discover and select repositories from a GitHub account or organization:

npx @openai/codex-security bulk-scan

For a prepared list, provide a repository CSV and an output directory:

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

See Run bulk security scans for GitHub discovery, the CSV format, campaign results, and available options.

Can an interrupted bulk scan resume

Yes. Run the same bulk-scan command with the original CSV and output directory. Codex Security skips completed repositories when their recorded scan artifacts remain intact.

Add --max-attempts 3 to retry temporary repository or scan errors:

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

How can a scan use architecture and security policies

Pass architecture documents, threat models, or security policies with --knowledge-base:

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

Codex Security uses these documents as context for the current scan. For supported file types and directory behavior, see Add security context.

Findings and coverage

Where can teams find earlier scan results

List saved scans for your repository:

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

Use a scan ID from the results to inspect its findings:

npx @openai/codex-security scans show SCAN_ID

Each completed scan keeps its report, findings, coverage, and supporting artifacts together. See Scan artifacts for the full layout.

What if the CLI can't save scan history

Codex Security keeps scan history in a workbench database. If the default state directory isn't writable, choose a private directory outside the repository:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

How do scans distinguish new and known findings

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

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Compare the matched findings:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

The comparison identifies new, persisting, reopened, resolved, and unknown findings. A finding counts as resolved only when the later scan covers its original target and affected path without coverage gaps.

How does false-positive feedback work

Inspect the saved scan to find the occurrence ID:

npx @openai/codex-security scans show SCAN_ID

Record why that finding doesn't apply:

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

Future scans of the same repository receive that explanation as context. They still independently check the current source, controls, and reachability. A dismissal doesn't suppress a rule, path, or vulnerability class.

For command details, see the findings reference.

Why can repeat scans return different findings

AI-assisted scans can vary, even with the same scan configuration. Start by rerunning your baseline scan:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

Match the baseline findings to the new scan:

npx @openai/codex-security scans match BASELINE_SCAN_ID REPEAT_SCAN_ID

Compare the matched results:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Provide shared architecture and security guidance when missing context may contribute to the variation. Matching can identify the same underlying finding across runs, but it doesn't make scans deterministic. Directly recheck any important finding that disappears.

How can a team confirm that a fix worked

After applying a fix, rerun the original scan:

npx @openai/codex-security scans rerun BEFORE_SCAN_ID

Match the original findings to the new scan:

npx @openai/codex-security scans match BEFORE_SCAN_ID AFTER_SCAN_ID

Compare the matched findings:

npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

Confirm that the new scan covers the original target and affected path without coverage gaps. Then directly recheck the original finding against the current checkout:

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

A missing finding or scan comparison alone doesn't prove that a fix worked.

What does incomplete coverage mean

Coverage can be complete, partial, or unknown. Review coverage.json for excluded paths, deferred surfaces, and open questions before treating a scan as evidence of review.

Scans with partial or unknown coverage return exit code 2, even without a severity policy. They still keep any available findings and coverage. A later scan can't establish that an earlier finding no longer exists when it doesn't cover that finding's original path.

Automation and cost

How do scan cost limits work

Set an estimated cost limit in USD before starting the scan:

npx @openai/codex-security scan . --max-cost 5

The limit is an estimate, not a hard spending cap. Requests already in progress can finish above the limit. Codex Security keeps available results when the scan stops.

Can scans check commits and pull requests

Install a pre-commit security check for staged and unstaged changes:

npx @openai/codex-security install-hook

For pull-request checks, scan the committed changes and set a severity threshold:

npx @openai/codex-security scan . \
  --diff origin/main \
  --fail-on-severity high

A complete scan returns exit code 1 when it finds an issue at or above the selected severity. See Run scans in CI for the complete GitHub Actions workflow, artifact handling, and SARIF export.

Can another application run scans directly

Yes. Use the TypeScript SDK to start scans, select targets, inspect findings and coverage, track progress, and apply cost controls from an application or developer tool.