Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

feat(onboarding): add cs alias and clarify onboarding (#1415)

mldangelo-oai6ce7f47059eb
diff --git a/.github/workflows/node-release.yml b/.github/workflows/node-release.yml
index 0005d9440..0f20fc8f3 100644
--- a/.github/workflows/node-release.yml
+++ b/.github/workflows/node-release.yml
@@ -231,6 +231,8 @@ jobs:
(cd "$consumer" && node --input-type=module --eval 'const sdk = await import("@openai/codex-security"); if (typeof sdk.CodexSecurity !== "function") process.exit(1);')
"$consumer/node_modules/.bin/codex-security" --version
"$consumer/node_modules/.bin/codex-security" --help
+ "$consumer/node_modules/.bin/cs" --version
+ "$consumer/node_modules/.bin/cs" --help
- name: Upload verified package
id: upload
diff --git a/README.md b/README.md
index 441958068..f65c3aa6c 100644
--- a/README.md
+++ b/README.md
@@ -21,15 +21,46 @@ fixing security vulnerabilities in your code.
Requires Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, and Python 3.10+.
Python 3.10 also requires `tomli`.
-This example explicitly requests Daybreak Blue and requires the corresponding
-access. Without Daybreak access, omit `--cyber-access-program daybreak_blue`
-or use `--cyber-access-program standard`.
+Install the CLI globally and sign in:
```bash
-npm install @openai/codex-security
-npx @openai/codex-security login
-npx @openai/codex-security scan /path/to/repository \
- --cyber-access-program daybreak_blue
+npm install --global @openai/codex-security
+cs login
+```
+
+`cs` is a short alias for `codex-security`; both commands run the same CLI.
+The installation creates both commands in npm's global executable directory,
+which must be on your `PATH`. If `cs` already resolves to another tool, use
+`codex-security` instead. If npm stops with an `EEXIST` error for `cs`, use
+`npx @openai/codex-security` without a global installation.
+
+From your repository directory, optionally draft security guidance before your
+first scan:
+
+```bash
+cs policy .
+```
+
+The command saves a draft outside the checkout. Review the proposed diff and
+notes, edit the draft as needed, then copy it to the displayed `Policy target`
+so future scans use it. Generating the draft alone does not install it.
+Skip this step to keep an existing policy or scan without one.
+
+Run your scan from the repository directory:
+
+```bash
+cs scan .
+```
+
+If you have Daybreak Blue access, add `--cyber-access-program daybreak_blue`
+to the scan command. Otherwise, omit the flag or use
+`--cyber-access-program standard`.
+
+To run without a global installation, replace `cs` in these examples with
+`npx @openai/codex-security`, for example:
+
+```bash
+npx @openai/codex-security scan .
```
For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan process's environment.
@@ -45,20 +76,28 @@ Choose a scope and scan mode:
```bash
# Scan selected paths.
-npx @openai/codex-security scan . --path src --path tests
+cs scan . --path src --path tests
# Scan committed changes from a base revision to HEAD.
-npx @openai/codex-security scan . --diff origin/main
+cs scan . --diff origin/main
# Run a deep scan of the repository.
-npx @openai/codex-security scan . --mode deep
+cs scan . --mode deep
```
-Use `npx @openai/codex-security --help` to browse commands, or `scan --help`
+Use `cs --help` to browse commands, or `cs scan --help`
for scan options, cost limits, and patching after a scan.
## TypeScript SDK
+Install the package locally in your TypeScript project:
+
+```bash
+npm install @openai/codex-security
+```
+
+Then import it:
+
```ts
import { CodexSecurity } from "@openai/codex-security";
@@ -80,8 +119,8 @@ validation, severity classification, owner suggestions, and result handling.
Draft security guidance for a repository or one of its components:
```bash
-npx @openai/codex-security policy .
-npx @openai/codex-security policy . --path services/api --knowledge-base architecture.md
+cs policy .
+cs policy . --path services/api --knowledge-base architecture.md
```
The command saves a draft outside the checkout. Review it before installing it
@@ -94,7 +133,7 @@ Scans and policy generation save threat models with their results. Export a save
model without starting another analysis:
```bash
-npx @openai/codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md
+cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md
```
Omit `--scan` to use the current repository's latest completed scan. The
@@ -165,7 +204,7 @@ Store findings, browse them in a dashboard, and review potential duplicates.
Start the local service with:
```bash
-npx @openai/codex-security serve
+cs serve
```
Publish a completed scan with `publish scan --to custom`, then use `dedupe` to
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 7b5d770c6..747edd96a 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -21,11 +21,6 @@ Before version `1.0.0`, minor releases may change the public API.
## Install
-```bash
-npm install @openai/codex-security
-npx @openai/codex-security --version
-```
-
Supported runtimes:
- Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, on macOS, Linux, or Windows.
@@ -43,20 +38,55 @@ work on all supported runtimes.
`PluginBootstrapError`, so existing catches keep working. Knowledge-base
preparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.
+### Install the CLI
+
+Install the CLI globally:
+
+```bash
+npm install --global @openai/codex-security
+cs --version
+```
+
+`cs` is a short alias for `codex-security`; both commands run the same CLI.
+The installation creates both commands in npm's global executable directory,
+which must be on your `PATH`. If `cs` already resolves to another tool, use
+`codex-security` instead. If npm stops with an `EEXIST` error for `cs`, use
+`npx @openai/codex-security` without a global installation.
+
+Continue with the [CLI walkthrough](#cli). To run without a global installation,
+replace `cs` in the CLI examples with `npx @openai/codex-security`.
+
+### Install the TypeScript SDK
+
+Install the package locally in your TypeScript project:
+
+```bash
+npm install @openai/codex-security
+```
+
## Authentication
Sign in with ChatGPT:
+```bash
+cs login
+```
+
+If you installed only the SDK locally, sign in from your project directory:
+
```bash
npx @openai/codex-security login
```
+In the following CLI examples, replace `cs` with `npx @openai/codex-security`
+when using a local SDK installation, including the API-key login example below.
+
For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan process's environment.
These keys apply to the current command without replacing your saved login.
To save an API key instead, pass it on stdin:
```bash
-printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
+printenv OPENAI_API_KEY | cs login --with-api-key
```
SDK calls accept `auth: "auto" | "chatgpt" | "api-key"`. The default, `"auto"`,
@@ -78,7 +108,7 @@ allows it. Otherwise, open an SSH tunnel from your local machine:
ssh -L 1455:localhost:1455 user@remote-host
```
-Run `npx @openai/codex-security login` in that SSH session, then open its sign-in
+Run `cs login` in that SSH session, then open its sign-in
URL in your local browser. Keep SSH connected until login finishes.
### Amazon Bedrock
@@ -359,11 +389,36 @@ To validate GitHub code scanning alerts, first import them with
## CLI
+After [installing the CLI](#install-the-cli), sign in if needed:
+
+```bash
+cs login
+```
+
+From your repository directory, optionally draft security guidance before scanning:
+
+```bash
+cs policy .
+```
+
+The command saves a draft outside the checkout. Review the proposed diff and
+notes, edit the draft as needed, then copy it to the displayed `Policy target`
+so future scans use it. Generating the draft alone does not install it.
+Skip this step to keep an existing policy or scan without one. See
+[Generate a security policy](#generate-a-security-policy) for details.
+
+Then scan the repository:
+
```bash
-npx @openai/codex-security scan .
-npx @openai/codex-security scan . --path src --path tests
-npx @openai/codex-security scan . --diff origin/main --json
-npx @openai/codex-security scan . --dry-run
+cs scan .
+```
+
+To narrow the scan scope or check the configuration before scanning:
+
+```bash
+cs scan . --path src --path tests
+cs scan . --diff origin/main --json
+cs scan . --dry-run
```
Use `--help` to find commands and `<command> --help` for options. Scans are
@@ -375,13 +430,13 @@ scans, custom validation, imports, patching, and integrations.
### Generate a security policy
+To draft guidance for a selected path:
+
```bash
-npx @openai/codex-security policy .
-npx @openai/codex-security policy . --path services/api
+cs policy . --path services/api
```
-`policy` drafts `SECURITY.md` outside the checkout. Review the draft before
-installing it; it guides future scans. The SDK provides `generatePolicy()`,
+The SDK provides `generatePolicy()`,
`preflightPolicy()`, and `previewPolicy()`. See
[policy generation](docs/cli.md#generate-a-security-policy) for SDK examples,
headless use, artifacts, and review requirements.
@@ -391,8 +446,8 @@ headless use, artifacts, and review requirements.
Export saved findings or a threat model without starting another analysis:
```bash
-npx @openai/codex-security export --scan SCAN_ID --export-format sarif --output results.sarif
-npx @openai/codex-security export --scan SCAN_ID --artifact threat-model --output threatmodel.md
+cs export --scan SCAN_ID --export-format sarif --output results.sarif
+cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md
```
The SDK provides `exportArtifact()` for the same offline operations. See
@@ -439,7 +494,7 @@ system, see [SDK records deduplication](docs/dedupe-records.md).
### Running without Docker
```bash
-npx @openai/codex-security serve --port 3000
+cs serve --port 3000
```
Open `http://127.0.0.1:3000/dashboard`. Startup and listing need no API key;
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 085800fec..caa1b61ee 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1,8 +1,9 @@
# CLI and workflows
-Use `npx @openai/codex-security` without a global install. The examples below
-use `codex-security`, which is available after
-`npm install --global @openai/codex-security`.
+The global installation provides both `codex-security` and its short alias `cs`.
+They accept the same arguments and options. The examples below use
+`codex-security`; you can also use `cs` or, without a global installation,
+`npx @openai/codex-security`. See the [installation guide](../README.md#install).
```bash
codex-security --help
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
index 8abea373f..13e6d33af 100644
--- a/sdk/typescript/package.json
+++ b/sdk/typescript/package.json
@@ -31,7 +31,8 @@
"./schemas/project-config.schema.json": "./schemas/project-config.schema.json"
},
"bin": {
- "codex-security": "./bin/codex-security.mjs"
+ "codex-security": "./bin/codex-security.mjs",
+ "cs": "./bin/codex-security.mjs"
},
"files": [
"bin",
diff --git a/sdk/typescript/scripts/smoke-package.mjs b/sdk/typescript/scripts/smoke-package.mjs
index b610435b7..fb4f49220 100644
--- a/sdk/typescript/scripts/smoke-package.mjs
+++ b/sdk/typescript/scripts/smoke-package.mjs
@@ -481,18 +481,12 @@ try {
".bin",
process.platform === "win32" ? "codex-security.cmd" : "codex-security",
);
- assert.equal(
- (await stat(shim)).isFile(),
- true,
- "npm must create the published codex-security executable shim.",
- );
-
const launchEnvironment = {
...process.env,
NODE_OPTIONS: "--preserve-symlinks-main --no-experimental-detect-module",
NODE_USE_ENV_PROXY: undefined,
};
- function runInstalledCli(argument) {
+ function runInstalledCli(shim, argument) {
const options = {
cwd: consumer,
capture: true,
@@ -509,8 +503,43 @@ try {
return run(shim, [argument], options);
}
- const version = runInstalledCli("--version");
- assert.equal(version.trim(), packageManifest.version);
+ for (const name of ["codex-security", "cs"]) {
+ const executable = join(
+ consumer,
+ "node_modules",
+ ".bin",
+ process.platform === "win32" ? `${name}.cmd` : name,
+ );
+ assert.equal(
+ (await stat(executable)).isFile(),
+ true,
+ `npm must create the published ${name} executable shim.`,
+ );
+
+ const version = runInstalledCli(executable, "--version");
+ assert.equal(version.trim(), packageManifest.version);
+
+ const help = runInstalledCli(executable, "--help");
+ assert.match(help, /Usage: codex-security\b/u);
+ assert.match(help, /\bpublish\b/u);
+ assert.match(help, /\bdedupe\b/u);
+ assert.match(help, /\bpolicy\b/u);
+ }
+
+ const scopedVersion = run(
+ npm.command,
+ [
+ ...npm.args,
+ "exec",
+ "--offline",
+ "--no",
+ "--",
+ packageManifest.name,
+ "--version",
+ ],
+ { cwd: consumer, capture: true },
+ );
+ assert.equal(scopedVersion.trim(), packageManifest.version);
const preload = join(consumer, "unavailable-cwd.mjs");
await writeFile(
@@ -547,11 +576,6 @@ try {
assert.equal(failed.stdout, "");
assert.equal(failed.stderr, "working directory is unavailable\n");
- const help = runInstalledCli("--help");
- assert.match(help, /Usage: codex-security\b/u);
- assert.match(help, /\bpublish\b/u);
- assert.match(help, /\bdedupe\b/u);
- assert.match(help, /\bpolicy\b/u);
const policyHelp = run(process.execPath, [launcher, "policy", "--help"], {
cwd: consumer,
capture: true,
diff --git a/sdk/typescript/src/cli-help.ts b/sdk/typescript/src/cli-help.ts
index 6eef178b1..b193f8ec0 100644
--- a/sdk/typescript/src/cli-help.ts
+++ b/sdk/typescript/src/cli-help.ts
@@ -274,8 +274,28 @@ export function formatCliHelp(text: string, columns = 80): string {
if (command === "") {
sections.push(
"Get started:\n" +
- " codex-security login\n" +
- " codex-security scan .\n" +
+ " codex-security login\n\n" +
+ wrap(
+ "In your repository, optionally draft SECURITY.md:",
+ width,
+ " ",
+ " ",
+ ) +
+ "\n codex-security policy .\n" +
+ wrap(
+ "Review and edit the draft, then copy it to the displayed Policy target.",
+ width,
+ " ",
+ " ",
+ ) +
+ "\n" +
+ wrap(
+ "Skip this step to keep an existing policy or scan without one.",
+ width,
+ " ",
+ " ",
+ ) +
+ "\n\n codex-security scan .\n" +
" codex-security findings",
);
} else if (examples) {
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 999d79d74..ca44899a0 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -3237,6 +3237,7 @@ export async function main(
});
const cli = Cli.create("codex-security", {
+ aliases: ["cs"],
description: "Find, review, and fix security issues in your code.",
version: VERSION,
mcp: {
diff --git a/sdk/typescript/tests-ts/cli-help.test.ts b/sdk/typescript/tests-ts/cli-help.test.ts
index e18fdf96f..dff1a3b74 100644
--- a/sdk/typescript/tests-ts/cli-help.test.ts
+++ b/sdk/typescript/tests-ts/cli-help.test.ts
@@ -63,7 +63,10 @@ describe("CLI help", () => {
expect(sectionFor("login")).toBeGreaterThan(sectionFor("scan"));
expect(sectionFor("init")).toBe(sectionFor("login"));
expect(sectionFor("completions")).toBeGreaterThan(sectionFor("scan"));
- expect(text).toContain("codex-security scan .");
+ expect(text).toContain("Aliases: cs");
+ for (const command of ["login", "policy .", "scan .", "findings"]) {
+ expect(text).toContain(` codex-security ${command}`);
+ }
expect(text).toContain("<command> --help");
});
diff --git a/sdk/typescript/tests-ts/cli-launcher.test.ts b/sdk/typescript/tests-ts/cli-launcher.test.ts
index f45ca00ba..bf269ad6c 100644
--- a/sdk/typescript/tests-ts/cli-launcher.test.ts
+++ b/sdk/typescript/tests-ts/cli-launcher.test.ts
@@ -13,20 +13,24 @@ describe("CLI launcher", () => {
const root = await temporaryDirectory("codex-security-cli-bin-");
try {
const launcher = join(packageRoot, "src", "cli.ts");
- const bin =
- process.platform === "win32" ? launcher : join(root, "codex-security");
- if (process.platform !== "win32") {
- await symlink(launcher, bin);
- }
- const { status, stdout, stderr } = await runCommand(
- process.execPath,
- [bin, "--version"],
- { timeout: 30_000 },
- );
+ const bins =
+ process.platform === "win32"
+ ? [launcher]
+ : ["codex-security", "cs"].map((name) => join(root, name));
+ for (const bin of bins) {
+ if (process.platform !== "win32") {
+ await symlink(launcher, bin);
+ }
+ const { status, stdout, stderr } = await runCommand(
+ process.execPath,
+ [bin, "--version"],
+ { timeout: 30_000 },
+ );
- expect(status, stderr).toBe(0);
- expect(stderr).toBe("");
- expect(stdout).toBe(`${VERSION}\n`);
+ expect(status, stderr).toBe(0);
+ expect(stderr).toBe("");
+ expect(stdout).toBe(`${VERSION}\n`);
+ }
} finally {
await rm(root, { recursive: true, force: true });
}
diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.ts
index 30aa0f409..0981cf19a 100644
--- a/sdk/typescript/tests-ts/cli.test.ts
+++ b/sdk/typescript/tests-ts/cli.test.ts
@@ -205,6 +205,7 @@ describe("CLI", () => {
const stderr = capture();
expect(await main([], root.stream, stderr.stream, dependencies())).toBe(0);
expect(root.text()).toContain("Usage: codex-security <command>");
+ expect(root.text()).toContain("Aliases: cs");
expect(root.text()).toContain("bulk-scan");
expect(root.text()).toContain("install-hook");
expect(root.text()).not.toContain("multiscan");
@@ -353,6 +354,11 @@ describe("CLI", () => {
0,
);
expect(completions.text()).toContain('export COMPLETE="bash"');
+ for (const name of ["codex-security", "cs"]) {
+ expect(completions.text()).toMatch(
+ new RegExp(`^complete .+ ${name}$`, "mu"),
+ );
+ }
});
test("documents every public command argument and option", async () => {