Codex Security CLI quickstart

Run a standard scan of a local repository with the standalone Codex Security CLI. This quickstart ends with a saved report you can review and revisit. For scans inside a Codex conversation, use the Codex Security plugin.

Check the prerequisites

You need Node.js 22 (22.13.0 or later), 24, or 26, plus Python 3.10 or later. Python 3.10 also needs tomli. Scans using OpenAI inference require Codex Security access. Depending on your account and repository, full-repository scans may also require Trusted Access for Cyber.

The CLI runs with your operating-system permissions and doesn’t pause for approval. Scan processes can inherit your environment, so remove unrelated credentials before starting. See Local scan permissions.

Set up and verify the CLI

Run the public package with npx:

npx @openai/codex-security --version

The command prints the installed package version. Use info --json to check the bundled plugin version, or --help to list commands. Package changes are listed in the CLI and SDK releases.

Sign in

Sign in with your ChatGPT account:

npx @openai/codex-security login

On a machine without a browser, add --device-auth and follow the displayed sign-in instructions. Use --auth chatgpt in the scan commands below to select that sign-in even when your environment also contains an API key.

For API keys and other providers, see Select scan authentication. For Amazon Bedrock, use AWS credentials and model access instead of a ChatGPT sign-in or OpenAI API key.

Prepare a scan

Replace these paths with your repository and a new results directory outside its Git worktree:

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Results can include source excerpts and vulnerability details. Choose a private location. If you omit --output-dir, the CLI uses its persistent state directory.

Check the target and output location:

npx @openai/codex-security scan "$REPOSITORY" \
  --auth chatgpt --output-dir "$SCAN_DIR" --dry-run

A successful dry run confirms the local inputs. It doesn’t start a scan, load credentials, or check the plugin’s Python interpreter, so it doesn’t establish that authentication and runtime setup will succeed.

Run your first scan

Remove --dry-run to start the scan:

npx @openai/codex-security scan "$REPOSITORY" \
  --auth chatgpt --output-dir "$SCAN_DIR"

An interactive terminal shows a live dashboard. Non-interactive terminals show progress lines. Add --headless to use progress lines in an interactive terminal too. The dashboard and saved logs can contain source code or credentials. Review them before sharing.

When the scan finishes, stderr includes the report path, finding count, and elapsed time. For example:

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

By default, the severity of a finding doesn’t cause a scan to fail. For machine-readable stdout, add --json. To make findings fail a CI check, set a severity policy.

Review the results

Open report.md from the reported directory. Confirm the target and revision, then read the coverage before reviewing individual findings.

Check scan.status in scan-manifest.json to confirm that the scan completed. Review coverage.json for reviewed surfaces, excluded paths, deferred work, and open questions.

A completed scan exits with 0 unless findings meet a configured severity threshold, which returns 1. Coverage gaps don’t change the exit code, so exit 0 doesn’t mean every file was reviewed. Input, execution, result-integrity, or required-output failures return 2. The CLI reference explains the exit codes.

For each finding, check the affected code, attacker prerequisites, validation evidence, and remaining uncertainty. A source-based finding doesn’t necessarily include a successful runtime reproduction. Select a finding for remediation only after its evidence supports the claimed issue.

Keep the scan directory together when sharing or archiving it. It contains scan-manifest.json, findings.json, and coverage.json alongside the report and supporting artifacts. See Scan artifacts for the full layout.

Revisit a saved scan

List scans for the repository:

npx @openai/codex-security scans list "$REPOSITORY"

Copy a scan ID from the results:

npx @openai/codex-security scans show SCAN_ID

After a complete interactive scan with findings, the CLI also offers a finding browser. Review the evidence there before choosing a fix. For saved findings, use the validate and patch commands.

Choose the next scan

For authentication problems, repeat-scan differences, or false-positive feedback, see the CLI FAQ.