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 Codex Security CLI and SDK are in limited beta. Approved customers and partners receive installation instructions with their access. Contact your account team if you need access.

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

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.

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

security/cli/faq.md +38 −20

14partners receive installation instructions with their access. Contact your14partners receive installation instructions with their access. Contact your

15account team if you need access.15account team if you need access.

16 16

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

19When your environment includes `OPENAI_API_KEY` or `CODEX_API_KEY`, scans

20without an interactive terminal and JSON and JSONL scans use the environment

21API key by default, even after a successful ChatGPT or access-token login.

22Interactive scans with text output ask you to choose when a ChatGPT sign-in is

23also available. Dry runs don't prompt or load credentials.

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

27```bash

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

29```

31To make your stored credentials the automatic default, run

32`unset OPENAI_API_KEY CODEX_API_KEY`. For all supported authentication modes,

33see the [CLI reference](https://learn.chatgpt.com/docs/security/cli/reference#select-scan-authentication).

17### How does bulk repository scanning work35### How does bulk repository scanning work

18 36

19Sign in with GitHub CLI:37Sign in with GitHub CLI:

25Discover and select repositories from a GitHub account or organization:43Discover and select repositories from a GitHub account or organization:

26 44

27```bash45```bash

~~28npx codex-security bulk-scan~~46npx @openai/codex-security bulk-scan

29```47```

30 48

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

32 50

33```bash51```bash

~~34npx codex-security bulk-scan repositories.csv \~~52npx @openai/codex-security bulk-scan repositories.csv \

35 --output-dir /path/outside/repositories/security-scans \53 --output-dir /path/outside/repositories/security-scans \

36 --workers 454 --workers 4

37```55```

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

49 67

50```bash68```bash

~~51npx codex-security bulk-scan repositories.csv \~~69npx @openai/codex-security bulk-scan repositories.csv \

52 --output-dir /path/outside/repositories/security-scans \70 --output-dir /path/outside/repositories/security-scans \

53 --workers 4 \71 --workers 4 \

54 --max-attempts 372 --max-attempts 3

60`--knowledge-base`:78`--knowledge-base`:

61 79

62```bash80```bash

~~63npx codex-security scan . \~~81npx @openai/codex-security scan . \

64 --knowledge-base /path/to/architecture.md \82 --knowledge-base /path/to/architecture.md \

65 --knowledge-base /path/to/security-policies83 --knowledge-base /path/to/security-policies

66```84```

76List saved scans for your repository:94List saved scans for your repository:

77 95

78```bash96```bash

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

80```98```

81 99

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

83 101

84```bash102```bash

~~85npx codex-security scans show SCAN_ID~~103npx @openai/codex-security scans show SCAN_ID

86```104```

87 105

88Each completed scan keeps its report, findings, coverage, and supporting106Each completed scan keeps its report, findings, coverage, and supporting

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

95 113

96```bash114```bash

~~97npx codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID~~115npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

98```116```

99 117

100Compare the matched findings:118Compare the matched findings:

101 119

102```bash120```bash

103npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID121npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

104```122```

105 123

106The comparison identifies new, persisting, reopened, resolved, and unknown124The comparison identifies new, persisting, reopened, resolved, and unknown

112Inspect the saved scan to find the occurrence ID:130Inspect the saved scan to find the occurrence ID:

113 131

114```bash132```bash

115npx codex-security scans show SCAN_ID133npx @openai/codex-security scans show SCAN_ID

116```134```

117 135

118Record why that finding doesn't apply:136Record why that finding doesn't apply:

119 137

120```bash138```bash

121npx codex-security findings mark-false-positive FINDING_OCCURRENCE_ID \139npx @openai/codex-security findings mark-false-positive FINDING_OCCURRENCE_ID \

122 --reason "The framework escapes this input before it reaches the query"140 --reason "The framework escapes this input before it reaches the query"

123```141```

124 142

135rerunning your baseline scan:153rerunning your baseline scan:

136 154

137```bash155```bash

138npx codex-security scans rerun BASELINE_SCAN_ID156npx @openai/codex-security scans rerun BASELINE_SCAN_ID

139```157```

140 158

141Match the baseline findings to the new scan:159Match the baseline findings to the new scan:

142 160

143```bash161```bash

144npx codex-security scans match BASELINE_SCAN_ID REPEAT_SCAN_ID162npx @openai/codex-security scans match BASELINE_SCAN_ID REPEAT_SCAN_ID

145```163```

146 164

147Compare the matched results:165Compare the matched results:

148 166

149```bash167```bash

150npx codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID168npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

151```169```

152 170

153Provide shared architecture and security guidance when missing context may171Provide shared architecture and security guidance when missing context may

160After applying a fix, rerun the original scan:178After applying a fix, rerun the original scan:

161 179

162```bash180```bash

163npx codex-security scans rerun BEFORE_SCAN_ID181npx @openai/codex-security scans rerun BEFORE_SCAN_ID

164```182```

165 183

166Match the original findings to the new scan:184Match the original findings to the new scan:

167 185

168```bash186```bash

169npx codex-security scans match BEFORE_SCAN_ID AFTER_SCAN_ID187npx @openai/codex-security scans match BEFORE_SCAN_ID AFTER_SCAN_ID

170```188```

171 189

172Compare the matched findings:190Compare the matched findings:

173 191

174```bash192```bash

175npx codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID193npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

176```194```

177 195

178Confirm that the new scan covers the original target and affected path without196Confirm that the new scan covers the original target and affected path without

180checkout:198checkout:

181 199

182```bash200```bash

183npx codex-security validate /path/to/original/findings.json \201npx @openai/codex-security validate /path/to/original/findings.json \

184 "Recheck the SQL injection in src/orders.ts:42 against the current code"202 "Recheck the SQL injection in src/orders.ts:42 against the current code"

185```203```

186 204

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

205 223

206```bash224```bash

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

208```226```

209 227

210The limit is an estimate, not a hard spending cap. Requests already in228The limit is an estimate, not a hard spending cap. Requests already in

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

217 235

218```bash236```bash

219npx codex-security install-hook237npx @openai/codex-security install-hook

220```238```

221 239

222For pull-request checks, scan the committed changes and set a severity240For pull-request checks, scan the committed changes and set a severity

223threshold:241threshold:

224 242

225```bash243```bash

226npx codex-security scan . \244npx @openai/codex-security scan . \

227 --diff origin/main \245 --diff origin/main \

228 --fail-on-severity high246 --fail-on-severity high

229```247```