Codex Security CLI quickstart

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to 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 @openai/codex-security package is public. Running scans requires Codex Security 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

Install the published package:

npm install @openai/codex-security

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 complete command help. The CLI reference covers each argument, output format, and exit code.

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, set an OpenAI API key:

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. When both a stored ChatGPT sign-in and an environment API key are available, interactive scans with text output ask which to use. CI, JSON and JSONL scans, and other unattended scans use the API key by default.

To use your ChatGPT sign-in when an API key is also set, select it explicitly:

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

To require the environment API key, select API-key authentication:

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.

If the default state directory isn't writable, select a writable directory outside the scanned repository:

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

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"

By default, the CLI writes scan progress and its completion summary to stderr. It doesn't print the full scan result to stdout. A completed scan prints a summary like this:

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

Token usage and estimated cost appear when available. To print the complete result as machine-readable JSON, request structured output explicitly:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

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.

Choose a model and reasoning effort

Scans use gpt-5.6-sol with xhigh reasoning effort by default. Select a different model and effort when the task requires them:

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

Supported effort levels are minimal, low, medium, high, and xhigh.

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.json records the target, scope, producer, and sealed artifacts.
findings.json records severity, confidence, locations, evidence, and remediation for each finding.
coverage.json records 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

Deep mode supports repository and path targets, not diff or working-tree scans.

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

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

To mark a reviewed finding as a false positive, explain why the finding doesn't apply:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Later scans consider that explanation but still recheck the current code.

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.

security/cli.md +67 −25

7repositories you own or have permission to assess, review findings over time,7repositories you own or have permission to assess, review findings over time,

8and check changes before they land.8and check changes before they land.

9 9

~~10The Codex Security CLI and SDK are in beta and require access. Follow the~~10The `@openai/codex-security` package is public. Running scans requires Codex

~~11 installation instructions provided with your access. For an interactive scan~~11 Security access. For an interactive scan in Codex, start with the [Codex

~~12 in Codex, start with the [Codex Security plugin~~12 Security plugin quickstart](https://learn.chatgpt.com/docs/security/plugin). For connected GitHub

~~13 quickstart](https://learn.chatgpt.com/docs/security/plugin). For connected GitHub repositories, see~~13 repositories, see [Codex Security cloud setup](https://learn.chatgpt.com/docs/security/setup).

~~14 [Codex Security cloud setup](https://learn.chatgpt.com/docs/security/setup).~~

15 14

16## Check the prerequisites15## Check the prerequisites

17 16

21 20

22## Set up and verify the CLI21## Set up and verify the CLI

23 22

~~24Follow the installation instructions provided for your Codex Security access.~~23Install the published package:

25```bash

26npm install @openai/codex-security

27```

25Check the installed version:29Check the installed version:

26 30

27```bash31```bash

34npx @openai/codex-security --help38npx @openai/codex-security --help

35```39```

36 40

~~37Use `npx @openai/codex-security scan --help` or `npx @openai/codex-security export --help` for the~~41Use `npx @openai/codex-security scan --help` or

~~38complete command help. The [CLI reference](https://learn.chatgpt.com/docs/security/cli/reference)~~42`npx @openai/codex-security export --help` for complete command help. The

~~39covers each argument, output format, and exit code.~~43[CLI reference](https://learn.chatgpt.com/docs/security/cli/reference) covers each argument, output

44format, and exit code.

40 45

41## Sign in46## Sign in

42 47

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

53```58```

54 59

~~55For CI and other automated workflows, use an OpenAI API key instead:~~60For CI and other automated workflows, set an OpenAI API key:

56 61

57```bash62```bash

58export OPENAI_API_KEY="<your-api-key>"63export OPENAI_API_KEY="<your-api-key>"

59```64```

60 65

61Keep API keys in your shell or secret manager. Codex Security can also reuse an66Keep API keys in your shell or secret manager. Codex Security can also reuse an

~~62existing file-backed Codex sign-in.~~67existing file-backed Codex sign-in. When both a stored ChatGPT sign-in and an

68environment API key are available, interactive scans with text output ask

69which to use. CI, JSON and JSONL scans, and other unattended scans use the

70API key by default.

63 71

~~64If a ChatGPT sign-in and `OPENAI_API_KEY` or `CODEX_API_KEY` are both~~72To use your ChatGPT sign-in when an API key is also set, select it explicitly:

~~65available, interactive scans with text output ask which credential to use. CI,~~

~~66JSON and JSONL scans, and other scans without an interactive terminal use the~~

~~67environment API key by default. Dry runs don't prompt or load credentials.~~

~~69To use your stored sign-in for a scan, pass `--auth chatgpt`:~~

70 73

71```bash74```bash

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

73```76```

74 77

~~75To use an environment API key, pass `--auth api-key`:~~78To require the environment API key, select API-key authentication:

76 79

77```bash80```bash

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

102state directory. Results can include source excerpts and vulnerability details,105state directory. Results can include source excerpts and vulnerability details,

103so choose a private location and an appropriate retention policy.106so choose a private location and an appropriate retention policy.

104 107

108If the default state directory isn't writable, select a writable directory

109outside the scanned repository:

110

111```bash

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

113```

114

105Check the repository, target, and output directory before starting a scan:115Check the repository, target, and output directory before starting a scan:

106 116

107```bash117```bash

119npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"129npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

120```130```

121 131

122The CLI writes the scan result to stdout and sends progress and its completion132By default, the CLI writes scan progress and its completion summary to stderr.

123summary to stderr. A completed scan prints a summary like this:133It doesn't print the full scan result to stdout. A completed scan prints a

134summary like this:

124 135

125```text136```text

126codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.137codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.

127codex-security: Elapsed: 42s. Workers: 3/6.138codex-security: Elapsed: 42s.

139codex-security: Report: /path/outside/repository/codex-security-results/report.md

128codex-security: Results: /path/outside/repository/codex-security-results140codex-security: Results: /path/outside/repository/codex-security-results

129codex-security: Next: codex-security export /path/outside/repository/codex-security-results --export-format sarif

130```141```

131 142

132For a local package installation, run the suggested export command with143Token usage and estimated cost appear when available. To print the complete

133`npx @openai/codex-security`.144result as machine-readable JSON, request structured output explicitly:

145

146```bash

147npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

148```

134 149

135Scans are report-only by default, so findings remain available for local150Scans are report-only by default, so findings remain available for local

136review. You may want to add a severity threshold when you are ready to [run scans in151review. You may want to add a severity threshold when you are ready to [run scans in

137CI](https://learn.chatgpt.com/docs/security/cli/ci).152CI](https://learn.chatgpt.com/docs/security/cli/ci).

138 153

154## Choose a model and reasoning effort

155

156Scans use `gpt-5.6-sol` with `xhigh` reasoning effort by default. Select a

157different model and effort when the task requires them:

158

159```bash

160npx @openai/codex-security scan "$REPOSITORY" \

161 --model gpt-5.6-terra \

162 --effort high

163```

164

165Supported effort levels are `minimal`, `low`, `medium`, `high`, and `xhigh`.

166

139## Review the results167## Review the results

140 168

141Open `report.md` for the readable result. The scan directory also contains the169Open `report.md` for the readable result. The scan directory also contains the

169Use a path scan when a repository contains separate services or packages:197Use a path scan when a repository contains separate services or packages:

170 198

171```bash199```bash

172npx @openai/codex-security scan "$REPOSITORY" --path services/billing --path packages/auth200npx @openai/codex-security scan "$REPOSITORY" \

201 --path services/billing \

202 --path packages/auth

173```203```

174 204

175Review committed changes between the base revision and `HEAD`:205Review committed changes between the base revision and `HEAD`:

193npx @openai/codex-security scan "$REPOSITORY" --mode deep223npx @openai/codex-security scan "$REPOSITORY" --mode deep

194```224```

195 225

226Deep mode supports repository and path targets, not diff or working-tree scans.

227

196## Add architecture and security context228## Add architecture and security context

197 229

198Provide architecture documents, threat models, or security policies as scan230Provide architecture documents, threat models, or security policies as scan

296npx @openai/codex-security scans show SCAN_ID328npx @openai/codex-security scans show SCAN_ID

297```329```

298 330

331To mark a reviewed finding as a false positive, explain why the finding doesn't

332apply:

333

334```bash

335npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \

336 --reason "The route already checks permissions"

337```

338

339Later scans consider that explanation but still recheck the current code.

340

299Run the same scan against the current checkout using its original configuration:341Run the same scan against the current checkout using its original configuration:

300 342

301```bash343```bash