Codex Security CLI quickstart
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending
.mdto the page URL.
Codex Security helps security and engineering teams find, confirm, and fix vulnerabilities. Use its command-line interface (CLI) to scan repositories you own or have permission to assess, review findings over time, and check changes before they land.
The Codex Security CLI and SDK are in beta and require access. Follow the installation instructions provided with your access. For an interactive scan in Codex, start with the Codex Security plugin quickstart. For connected GitHub repositories, see Codex Security cloud setup.
Check the prerequisites
The CLI requires Node.js 22 or later. Running a scan or exporting findings also requires Python 3.10 or later. For more detail, see Authentication and prerequisites.
Set up and verify the CLI
Follow the installation instructions provided for your Codex Security access. Check the installed version:
npx @openai/codex-security --version
List the available commands:
npx @openai/codex-security --help
Use npx @openai/codex-security scan --help or npx @openai/codex-security export --help for the
complete command help. The CLI reference
covers each argument, output format, and exit code.
Sign in
For local use, sign in with your ChatGPT account:
npx @openai/codex-security login
On a remote or headless machine, use device authentication:
npx @openai/codex-security login --device-auth
For CI and other automated workflows, use an OpenAI API key instead:
export OPENAI_API_KEY="<your-api-key>"
Keep API keys in your shell or secret manager. Codex Security can also reuse an existing file-backed Codex sign-in.
If a ChatGPT sign-in and OPENAI_API_KEY or CODEX_API_KEY are both
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 by default. Dry runs don't prompt or load credentials.
To use your stored sign-in for a scan, 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 your stored sign-in the automatic default, unset both environment API keys:
unset OPENAI_API_KEY CODEX_API_KEY
Depending on your account and repository, full-repository scans may also require Trusted Access for Cyber. Signing in or setting an API key doesn't grant that access.
Prepare a scan
Choose a repository to scan and a directory to write results.
REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results
If you omit --output-dir, Codex Security saves results in its own persistent
state directory. Results can include source excerpts and vulnerability details,
so choose a private location and an appropriate retention policy.
Check the repository, target, and output directory before starting a scan:
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run
The dry run checks local inputs without starting Codex, loading credentials, or probing the plugin's Python interpreter.
Run your first scan
Run a standard scan and keep its results in the selected directory:
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"
The CLI writes the scan result to stdout and sends progress and its completion summary to stderr. A completed scan prints a summary like this:
codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s. Workers: 3/6.
codex-security: Results: /path/outside/repository/codex-security-results
codex-security: Next: codex-security export /path/outside/repository/codex-security-results --export-format sarif
For a local package installation, run the suggested export command with
npx @openai/codex-security.
Scans are report-only by default, so findings remain available for local review. You may want to add a severity threshold when you are ready to run scans in CI.
Review the results
Open report.md for the readable result. The scan directory also contains the
structured files used by automation:
codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
└── results.sarif # when produced
scan-manifest.jsonrecords the target, scope, producer, and sealed artifacts.findings.jsonrecords severity, confidence, locations, evidence, and remediation for each finding.coverage.jsonrecords reviewed surfaces, exclusions, deferred work, open questions, and coverage completeness.
Coverage can be complete, partial, or unknown. Read any deferred areas or
open questions before treating the scan as evidence of review.
The CLI reference describes
the full artifact and output contract.
Choose the next scan
Use a path scan when a repository contains separate services or packages:
npx @openai/codex-security scan "$REPOSITORY" --path services/billing --path packages/auth
Review committed changes between the base revision and HEAD:
npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD
Review staged and unstaged changes against HEAD:
npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD
Diff and working-tree scans expect the repository argument to be the Git worktree root. Fetch the selected revisions before starting a diff scan.
Use deep mode when a repository or path needs broader review:
npx @openai/codex-security scan "$REPOSITORY" --mode deep
Add architecture and security context
Provide architecture documents, threat models, or security policies as scan context. This helps Codex Security evaluate findings against how your system actually works:
npx @openai/codex-security scan "$REPOSITORY" \
--knowledge-base /path/to/architecture.md \
--knowledge-base /path/to/security-policies
Set a scan budget
Use --max-cost to stop a scan when its estimated model cost exceeds a limit
in USD:
npx @openai/codex-security scan "$REPOSITORY" --max-cost 5
Requests already in progress can finish above the limit. Codex Security keeps the available results when a scan stops.
Scan changes before each commit
Install a Git pre-commit security check for your repository:
npx @openai/codex-security install-hook
The check scans staged and unstaged changes before each commit. It blocks high-severity findings and scan errors without replacing an existing pre-commit script.
Scan repositories in bulk
Sign in to GitHub before discovering repositories:
gh auth login
Discover and select repositories from your GitHub account or organization:
npx @openai/codex-security bulk-scan
The interactive flow excludes archived repositories and forks. It asks you to confirm the selected repositories before scanning.
To scan a prepared repository list, provide a CSV and an output directory:
npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4
Run the same command again to resume an existing bulk scan. Completed
repositories with intact result artifacts aren't scanned again. Add
--max-attempts 3 when you want to retry temporary repository or scan errors.
For GitHub discovery, CSV preparation, campaign results, and Docker setup, see Run bulk security scans.
Run bulk scans in Docker
If your access includes the Codex Security Docker image, use the supplied hardened Compose configuration and security profile on a Linux Docker host. The host must support unprivileged user namespace creation. Supply a repository CSV, keep results and sign-in state in persistent mounted directories, and provide credentials through your environment or a secret manager:
docker compose run --rm codex-security \
bulk-scan /input/repositories.csv \
--output-dir /output \
--workers 4
The container runs bulk scans without prompts. Use the CLI outside Docker when
you want to discover repositories interactively. For private repositories,
provide GH_TOKEN or GITHUB_TOKEN through your environment or secret
manager. The sign-in requirements, including account and repository
access, also apply to containerized scans.
Revisit a saved scan
List the saved scans for your repository:
npx @openai/codex-security scans list "$REPOSITORY"
Copy a scan ID from the results to inspect its findings and configuration:
npx @openai/codex-security scans show SCAN_ID
Run the same scan against the current checkout using its original configuration:
npx @openai/codex-security scans rerun SCAN_ID
To compare two scans, first match findings that share the same root cause:
npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
Then check which findings are new, persisting, reopened, resolved, or unknown:
npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
For the bulk-scan CSV format, scan-history filters, and command options, see the CLI reference.
Continue with the workflow that fits your goal:
- Run bulk security scans to discover GitHub repositories or scan a pinned CSV inventory.
- Read the CLI FAQ for answers about scan history, false-positive feedback, coverage, and fix verification.
- Run scans in CI to review pull requests, preserve results, and set a severity policy.
- Use the CLI reference to check every flag, output format, artifact, and exit code.
- Integrate the TypeScript SDK to run scans from an application or developer tool.