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

fix(cli): resolve command paths and isolate standalone actions (#2596)

Michael D'Angelof85de80d1e9c
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 0e5943841..c73e33d26 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -14,7 +14,10 @@ codex-security info --json
`--help` lists commands by task; `<command> --help` lists its options.
`info --json` reports package, plugin, runtime, and model details.
-`scans` and `findings` default to their `list` subcommands.
+`scans` and `findings` default to their `list` subcommands. Global output options
+can appear around a subcommand, for example `cs scans --json show`. Use `--`
+after the command to pass the remaining words as literal positional arguments,
+including file names that begin with a dash.
## Find a workflow
@@ -39,12 +42,15 @@ codex-security info --json
## Updating the CLI
-Run `cs --update` to update an npm global installation managed by the running
+Run `cs update` to update an npm global installation managed by the running
Node distribution. It uses Node’s bundled npm, the public npm registry, and
disabled lifecycle scripts. If you use a custom registry or proxy, run your
package manager’s update command directly.
-For a project dependency, `cs --update` prints the package-manager command for
+The legacy `cs --update` spelling also works. Invoke the updater or the stdio
+server (`cs --mcp`) on its own.
+
+For a project dependency, `cs update` prints the package-manager command for
you to run in the declaring project. For other global installations it prints
the corresponding package-manager command and installation location. For npx,
use `npx @openai/codex-security@latest` on the next run. For a standalone
diff --git a/sdk/typescript/src/cli-help.ts b/sdk/typescript/src/cli-help.ts
index e161c5bd3..d8f7cb790 100644
--- a/sdk/typescript/src/cli-help.ts
+++ b/sdk/typescript/src/cli-help.ts
@@ -13,7 +13,7 @@ const COMMAND_GROUPS: readonly Group[] = [
["Automate", ["bulk-scan", "scan-components", "install-hook"]],
[
"Configure and troubleshoot",
- ["login", "logout", "init", "info", "feedback"],
+ ["login", "logout", "init", "info", "feedback", "update"],
],
];
@@ -106,7 +106,6 @@ const OUTPUT_FLAGS = ["format", "json", "filter-output", "full-output"];
const OUTPUT_GROUPS: readonly Group[] = [
["Help and version", ["help", "version"]],
- ["Maintenance", ["update"]],
["Output", OUTPUT_FLAGS],
];
@@ -213,6 +212,7 @@ function globalRows(rows: Row[], command: string): Row[] {
command,
);
const visible = rows.filter(({ label }) => {
+ if (label === "--update") return false;
if (scan && label.startsWith("--filter-output")) return false;
return !(
plainOutput &&
diff --git a/sdk/typescript/src/cli-integrations.ts b/sdk/typescript/src/cli-integrations.ts
index e0a627790..c4931cd54 100644
--- a/sdk/typescript/src/cli-integrations.ts
+++ b/sdk/typescript/src/cli-integrations.ts
@@ -281,36 +281,57 @@ export async function serveIntegration(
cli: Cli.Cli,
cliOptions: Cli.create.Options,
output: Cli.serve.Options,
+ command: string | undefined,
+ literalArgs: readonly string[],
): Promise<boolean> {
const manifest =
(argv.includes("--llms") || argv.includes("--llms-full")) &&
!argv.some((arg) =>
["--help", "-h", "--version", "--schema"].includes(arg),
);
- if (
- !manifest &&
- !argv.some((arg) => ["mcp", "skills", "skill"].includes(arg))
- )
- return false;
- const words = parseArgs({
- args: argv,
- options: outputOptions,
- strict: false,
- allowPositionals: true,
- }).positionals;
- // Incur also accepts its binary name before a built-in command.
- if (words[0] === cliName) {
- argv = argv.toSpliced(argv.indexOf(cliName), 1);
- words.shift();
+ const group = command === "skill" ? "skills" : command;
+ const integration = group === "mcp" || group === "skills";
+ if (!integration && !manifest && group !== "completions") return false;
+ if (group === "completions") {
+ const [, shell, ...extra] = [
+ ...parseArgs({
+ args: argv,
+ options: outputOptions,
+ allowPositionals: true,
+ }).positionals,
+ ...literalArgs,
+ ];
+ if (extra.length)
+ throw new Error("Unexpected positional argument for completions.");
+ if (shell !== undefined && !completionShell.safeParse(shell).success)
+ throw new Error(
+ `Unknown shell. Supported: ${completionShell.options.join(", ")}.`,
+ );
+ if (argv.includes("--schema") || argv.includes("--version")) {
+ const section = Cli.create(cliName + " completions", {
+ version: cliOptions.version,
+ update: false,
+ sync: false,
+ args: z.object({ shell: completionShell }),
+ run: () => undefined,
+ });
+ await section.serve(
+ argv.filter((arg) => arg !== group && arg !== shell),
+ output,
+ );
+ return true;
+ }
+ if (!manifest) {
+ await cli.serve([...argv, ...literalArgs], output);
+ return true;
+ }
}
- const group = words[0] === "skill" ? "skills" : words[0];
- if (!manifest && group !== "mcp" && group !== "skills") return false;
const { tokens, positionals, values } = parseArgs({
args: argv,
options,
allowPositionals: true,
tokens: true,
- strict: group === "mcp" || group === "skills",
+ strict: integration,
});
const plain = !Object.keys(formatOptions).some((key) =>
Object.hasOwn(values, key),
@@ -321,6 +342,18 @@ export async function serveIntegration(
cliOptions,
manifest ? undefined : { output, plain, full },
);
+ if (integration) {
+ const section = group === "mcp" ? mcp : skills;
+ const [, verb, ...extra] = positionals;
+ if (literalArgs.length || extra.length)
+ throw new Error(
+ `Unexpected positional argument for ${group}${verb ? " " + verb : ""}.`,
+ );
+ if (verb && !Cli.toCommands.get(section)!.has(verb)) {
+ await cli.serve([group, verb, "--help"], output);
+ return true;
+ }
+ }
if (manifest) {
// Put the mode first so a missing format/filter operand cannot consume it
// and fall through to a command handler.
@@ -336,11 +369,9 @@ export async function serveIntegration(
);
return true;
}
- if (group !== "mcp" && group !== "skills") return false;
+ if (!integration) return false;
const section = group === "mcp" ? mcp : skills;
- const [, verb, ...extra] = positionals;
- if (extra.length)
- throw new Error(`Unexpected positional argument for ${group} ${verb}.`);
+ const [, verb] = positionals;
if (!verb && !values.version) {
const invalid = tokens.find(
(token) =>
@@ -363,10 +394,6 @@ export async function serveIntegration(
);
return true;
}
- if (verb && !Cli.toCommands.get(section)!.has(verb)) {
- await cli.serve([group, verb, "--help"], output);
- return true;
- }
// The public flag names a scope directly. Incur reserves --no-* for
// negation; pass its schema's field name after Node tokenizes the CLI flag.
const args = argv.slice();
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 374cf1aec..c6553522a 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -466,6 +466,14 @@ const FRAMEWORK_VALUE_OPTIONS = new Set([
"--token-limit",
"--token-offset",
]);
+const INSPECTION_FLAGS = [
+ "-h",
+ "--help",
+ "--schema",
+ "--version",
+ "--llms",
+ "--llms-full",
+];
const OUTPUT_OPTION =
/^--(?:format|filter-output|full-output|token-count|token-limit|token-offset)(?:=|$)/u;
const HIDE_CURSOR = "\u001B[?25l";
@@ -2452,101 +2460,24 @@ export async function main(
const completion = completionShell.safeParse(process.env["COMPLETE"]);
const shellArgv = argv;
if (completion.success) argv = [];
- if (
- argv.includes("--mcp") &&
- argv.some((arg) =>
- [
- "--help",
- "-h",
- "--schema",
- "--version",
- "--llms",
- "--llms-full",
- ].includes(arg),
- )
- ) {
- argv = argv.filter((arg) => arg !== "--mcp");
- }
- const remediationOperation =
- argv[0] === "patch"
- ? "patch"
- : argv[0] === "verify-fix"
- ? "verify"
- : undefined;
- const recordsCommand =
- argv[0] === "dedupe" ||
- argv[0] === "validate" ||
- argv[0] === "classify-severity"
- ? argv[0]
- : undefined;
- const hostedCommand =
- argv[0] === "scan" || remediationOperation !== undefined;
- if (
- ((recordsCommand !== undefined && argv.includes("--records")) ||
- (hostedCommand &&
- argv.some((arg) => arg === "--host" || arg.startsWith("--host=")))) &&
- !argv.includes("--help") &&
- !argv.includes("-h") &&
- !argv.includes("--schema")
- ) {
- let classificationRuns: number | undefined;
- if (argv[0] === "classify-severity") {
- try {
- const { values } = parseArgs({
- args: argv.slice(1),
- options: {
- records: { type: "boolean" },
- runs: { type: "string" },
- },
- });
- if (values.runs !== undefined)
- classificationRuns = reviewRunsOption.parse(Number(values.runs));
- } catch {
- errorOutput.write(
- `codex-security: Use --records with only --runs (an integer from 1 to 10; default: ${DEFAULT_REVIEW_RUNS}).\n`,
- );
- return 2;
- }
- } else if (argv.length !== 2 || (hostedCommand && argv[1] !== "--host")) {
- errorOutput.write(
- hostedCommand
- ? `codex-security: --host must be used alone with ${argv[0]}.\n`
- : `codex-security: --records must be used alone with ${argv[0]}.\n`,
- );
- return 2;
- }
- const controller = new AbortController();
- const removeSignals = listenForAbort(dependencies, controller);
- let exitCode: number;
- try {
- const input = dependencies.recordsInput ?? process.stdin;
- const code =
- recordsCommand !== undefined
- ? await runHostRecordsProtocol(recordsCommand, input, output, {
- signal: controller.signal,
- classificationRuns,
- })
- : remediationOperation !== undefined
- ? await runHostedRemediationProtocol(
- input,
- output,
- controller.signal,
- remediationOperation,
- )
- : await runHostedScanProtocol(input, output, controller.signal);
- exitCode =
- controller.signal.reason === "SIGINT"
- ? 130
- : controller.signal.reason === "SIGTERM"
- ? 143
- : code;
- } finally {
- removeSignals();
- }
- // Protocol writes have flushed or been canceled. Node's stdout ignores destroy().
- if (output === process.stdout) process.exit(exitCode);
- return exitCode;
- }
+ const separator = argv.indexOf("--");
+ const literalArgs = separator < 0 ? [] : argv.slice(separator + 1);
+ if (separator >= 0) argv = argv.slice(0, separator);
+ const inspection = argv.some((arg) => INSPECTION_FLAGS.includes(arg));
+ const actionFlags = argv.filter(
+ (arg) => arg === "--mcp" || arg === "--update",
+ );
+ const actionOptions = argv.filter((arg) => arg !== actionFlags[0]);
+ const mixedAction =
+ actionFlags.length > 0 &&
+ (actionFlags.length !== 1 ||
+ literalArgs.length > 0 ||
+ firstNonGlobal(actionOptions, 0) < actionOptions.length ||
+ (actionFlags[0] === "--mcp" && !inspection && actionOptions.length > 0));
+ if (!mixedAction && actionFlags[0] === "--update")
+ argv = ["update", ...actionOptions];
+ if (!mixedAction && actionFlags[0] === "--mcp" && inspection)
+ argv = actionOptions;
const positionals: string[] = [];
let exitCode = 0;
let frameworkExit: number | undefined;
@@ -5202,29 +5133,9 @@ export async function main(
configuration: z.record(z.string(), z.unknown()),
});
- const inspectionFlags = [
- "-h",
- "--help",
- "--version",
- "--schema",
- "--llms",
- "--llms-full",
- ];
- if (
- argv.includes("--update") &&
- argv.some((arg) => inspectionFlags.includes(arg))
- )
- argv = argv.filter((arg) => arg !== "--update");
const cliOptions: Cli.create.Options = {
aliases: ["cs"],
- // The SDK owns update notices and uses the same installation resolver for
- // the explicit update action. Avoid Incur's second, global npm updater.
- update: argv.includes("--update")
- ? {
- package: "@openai/codex-security",
- install: () => installUpdate(dependencies.environment),
- }
- : false,
+ update: false,
description: "Find, review, and fix security issues in your code.",
version: VERSION,
mcp: {
@@ -5235,6 +5146,25 @@ export async function main(
},
};
const cli = Cli.create("codex-security", cliOptions)
+ .command("update", {
+ description: "Update the CLI or show the command for this installation.",
+ destructive: true,
+ async run({ format, error }) {
+ try {
+ await installUpdate(dependencies.environment);
+ } catch (cause) {
+ return error({
+ code: "UPDATE_FAILED",
+ message: errorMessage(cause),
+ exitCode: 2,
+ });
+ }
+ const name = "@openai/codex-security";
+ if (output.isTTY && useDefaultOutput(format))
+ renderedOutput = `✓ Updated ${name}\n`;
+ return { name };
+ },
+ })
.command(scanHistory)
.command("policy", {
description: "Draft SECURITY.md for review.",
@@ -8120,49 +8050,147 @@ export async function main(
prepareCliExamples(commands);
const valueOptions = cliValueOptions(commands);
const isPositional = (value: string, index: number) =>
- !value.startsWith("-") &&
+ (value === "-" || !value.startsWith("-")) &&
(index === 0 || !valueOptions.has(argv[index - 1]!));
- const commandIndex = argv.findIndex(isPositional);
+ // A leading terminator still permits a positional command name.
+ let commandIndex = argv.findIndex(isPositional);
+ if (
+ commandIndex < 0 &&
+ !actionFlags.length &&
+ literalArgs[0] &&
+ !literalArgs[0].startsWith("-") &&
+ firstNonGlobal(argv, 0) === argv.length
+ ) {
+ commandIndex = argv.length;
+ const name = literalArgs.shift()!;
+ const group = commands.get(name);
+ const verb = literalArgs[0];
+ argv = [...argv, name];
+ if (group && "_group" in group && verb && group.commands.has(verb))
+ argv = [...argv, literalArgs.shift()!];
+ }
+ if (argv[commandIndex] === "codex-security") {
+ argv = argv.toSpliced(commandIndex, 1);
+ commandIndex = argv.findIndex(isPositional);
+ }
const command = argv[commandIndex];
- const following = argv[commandIndex + 1];
+ const entry = command === undefined ? undefined : commands.get(command);
+ const verbIndex = firstNonGlobal(argv, commandIndex + 1);
+ let following = argv[verbIndex];
const scanImport = command === "scan" && following === "import";
if (
command === "scan" &&
!scanImport &&
- argv.some(
- (value, index) => index > commandIndex && isPositional(value, index),
- )
+ (literalArgs.length ||
+ argv.some(
+ (value, index) => index > commandIndex && isPositional(value, index),
+ ))
) {
// A repository such as "imports" or "./import" is a positional even when
// shared options precede it. Bypass Incur's subcommand typo suggestions.
- const scan = commands.get(command);
- if (scan && "_group" in scan && scan.root) commands.set(command, scan.root);
+ if (entry && "_group" in entry && entry.root)
+ commands.set(command, entry.root);
}
-
if (
(command === "scans" || command === "findings") &&
!argv.includes("--help") &&
!argv.includes("-h") &&
+ !argv.some((arg) => arg === "--llms" || arg === "--llms-full") &&
(following === undefined || following.startsWith("-"))
) {
- argv = argv.toSpliced(commandIndex + 1, 0, "list");
- }
-
+ argv = argv.toSpliced(verbIndex, 0, "list");
+ following = "list";
+ }
+ const nested =
+ entry &&
+ "_group" in entry &&
+ following !== undefined &&
+ entry.commands.has(following);
+ const subcommand = nested ? following : undefined;
+ const selected =
+ entry && "_group" in entry
+ ? subcommand
+ ? entry.commands.get(subcommand)
+ : entry.root
+ : entry;
+ const protocolFlag =
+ ["scan", "patch", "verify-fix"].includes(command ?? "") && !scanImport
+ ? "--host"
+ : ["validate", "classify-severity", "dedupe"].includes(command ?? "")
+ ? "--records"
+ : undefined;
+ let protocol = false;
+ let classificationRuns: number | undefined;
function validateCliArguments(): string | undefined {
- if (argv.includes("--help") || argv.includes("-h")) return undefined;
- if (frameworkFlags.malformedFilter)
- return "--filter-output requires matching brackets for array slices.";
- if (command === undefined || !commands.has(command)) return undefined;
+ if (argv.includes("--incur-update-check"))
+ return "Unknown flag: --incur-update-check";
+ if (mixedAction) return `${actionFlags.join(" and ")} must be used alone.`;
+ if (command === undefined && literalArgs.length)
+ return "Select a command before --.";
+ if (frameworkFlags.argumentError) return frameworkFlags.argumentError;
+ if (command === undefined) return undefined;
+ if (!entry) {
+ if (["skills", "skill", "mcp", "completions"].includes(command))
+ return undefined;
+ if (inspection)
+ return `Unknown command ${diagnosticValue(command)}. Use codex-security --help.`;
+ return undefined;
+ }
+ if (
+ "_group" in entry &&
+ !entry.root &&
+ following &&
+ !following.startsWith("-") &&
+ !subcommand
+ )
+ // Discovery otherwise widens an unknown path to its parent. Execution
+ // already reports unknown verbs with Incur's spelling suggestions.
+ return inspection
+ ? `Unknown command ${diagnosticValue(command + " " + following)}. Use codex-security ${command} --help.`
+ : undefined;
+ if (protocolFlag && !inspection) {
+ const negative = "--no-" + protocolFlag.slice(2);
+ const flags = argv.filter(
+ (arg) =>
+ arg === protocolFlag ||
+ arg.startsWith(protocolFlag + "=") ||
+ arg === negative,
+ );
+ const last = flags.at(-1);
+ protocol = last === protocolFlag || last === protocolFlag + "=true";
+ if (protocol) {
+ const rest = argv.filter(
+ (arg, index) => index !== commandIndex && !flags.includes(arg),
+ );
+ if (
+ command === "classify-severity" &&
+ commandIndex === 0 &&
+ !literalArgs.length
+ ) {
+ try {
+ const { values } = parseArgs({
+ args: rest,
+ options: { runs: { type: "string" } },
+ });
+ if (values.runs !== undefined)
+ classificationRuns = reviewRunsOption.parse(Number(values.runs));
+ } catch {
+ return `Use --records with only --runs (an integer from 1 to 10; default: ${DEFAULT_REVIEW_RUNS}).`;
+ }
+ } else if (rest.length || literalArgs.length || commandIndex !== 0)
+ return `${protocolFlag} must be used alone with ${command}.`;
+ }
+ }
const structuredOutput = frameworkFlags.formats.some(isJsonFormat);
if (
structuredOutput &&
(["validate", "logout"].includes(command) ||
(command === "login" && following !== "status")) &&
- !argv.includes("--schema")
+ !inspection
) {
return `${command} does not support noninteractive JSON output; run it without --json, --format json, or --format jsonl.`;
}
- if (command === "export" && structuredOutput) {
+ if (command === "export" && structuredOutput && !inspection) {
const hasValue = (flag: string, value: string) =>
argv.some(
(arg, index) =>
@@ -8187,7 +8215,7 @@ export async function main(
}
}
}
- if (command === "scan" && !argv.includes("--schema")) {
+ if (command === "scan" && !inspection) {
if (frameworkFlags.filters.length) {
return "--filter-output is not supported for scan results.";
}
@@ -8195,13 +8223,6 @@ export async function main(
return "Markdown output is not supported for scan results.";
}
}
- const nestedCommand =
- scanImport ||
- command === "scans" ||
- command === "findings" ||
- command === "publish" ||
- command === "import";
- const subcommand = nestedCommand ? argv[commandIndex + 1] : undefined;
if (
frameworkFlags.rawStructuredOutput &&
!(command === "scans" && subcommand === "logs")
@@ -8221,21 +8242,14 @@ export async function main(
return "--filter-output must select an info metadata field.";
}
}
- const entry = commands.get(command)!;
- const selected =
- "_group" in entry
- ? subcommand === undefined
- ? entry.root
- : entry.commands.get(subcommand)
- : entry;
let lastPositionalIndex = -1;
for (
- let index = commandIndex + (nestedCommand ? 2 : 1);
+ let index = nested ? verbIndex + 1 : commandIndex + 1;
index < argv.length;
index += 1
) {
const value = argv[index]!;
- if (!value.startsWith("-")) {
+ if (value === "-" || !value.startsWith("-")) {
positionals.push(value);
lastPositionalIndex = index;
continue;
@@ -8269,29 +8283,35 @@ export async function main(
continue;
const next = argv[index + 1];
if (next === undefined || next.startsWith("--") || next === "-h") {
- if (scanImport && option === "--json" && argv.includes("--schema"))
- continue;
+ if (scanImport && option === "--json" && inspection) continue;
return `Missing value for flag: ${option}`;
}
index += 1;
}
- if (
- command === "login" &&
- positionals.length > 0 &&
- (following !== "status" || positionals.length !== 1)
- ) {
+ const beforeDelimiter = positionals.length;
+ positionals.push(...literalArgs);
+ if (command === "login" && !subcommand && positionals.length)
return "Use login to sign in or login status to inspect authentication.";
+ // Incur's global flag extractor doesn't recognize --. Supply literal
+ // arguments to the positional schema as inputs so its normal validation
+ // still applies and no layer can reinterpret a value as a framework flag.
+ if (literalArgs.length && selected && "args" in selected && selected.args) {
+ const shape: Record<string, z.ZodType> = {};
+ for (const [index, key] of Object.keys(selected.args.shape).entries()) {
+ const literal = literalArgs[index - beforeDelimiter];
+ if (literal !== undefined)
+ shape[key] = selected.args.shape[key].prefault(literal);
+ }
+ selected.args = selected.args.extend(shape);
}
if (
command !== "validate" &&
command !== "verify-fix" &&
command !== "patch" &&
positionals.length >
- (scanImport || command === "logout" || command === "info"
- ? 0
- : subcommand === "compare" || subcommand === "match"
- ? 2
- : 1)
+ (selected && "args" in selected && selected.args
+ ? Object.keys(selected.args.shape).length
+ : 0)
) {
const previous = argv[lastPositionalIndex - 1]?.split("=", 1)[0];
const hint = previous?.startsWith("-")
@@ -8302,11 +8322,15 @@ export async function main(
}
const frameworkFlags = parseFrameworkArguments(
argv,
- scanImport ? commandIndex + 2 : argv.length,
+ scanImport ? verbIndex + 1 : argv.length,
);
const frameworkArgv = frameworkFlags.args;
const { jsonFormat } = frameworkFlags;
- const policyFullOutput = command === "policy" && frameworkFlags.fullOutput;
+ const policyFullOutput =
+ command === "policy" &&
+ frameworkFlags.fullOutput &&
+ !mixedAction &&
+ !argv.includes("--incur-update-check");
const scanErrorFormat =
command === "scan" && !scanImport && frameworkFlags.fullOutput
? jsonFormat
@@ -8327,14 +8351,60 @@ export async function main(
await writeCliOutput(output, argumentFailure(argumentError));
return 2;
}
+ if (protocol) {
+ const recordsCommand =
+ command === "dedupe" ||
+ command === "validate" ||
+ command === "classify-severity"
+ ? command
+ : undefined;
+ const remediationOperation =
+ command === "patch"
+ ? "patch"
+ : command === "verify-fix"
+ ? "verify"
+ : undefined;
+ const controller = new AbortController();
+ const removeSignals = listenForAbort(dependencies, controller);
+ let exitCode: number;
+ try {
+ const input = dependencies.recordsInput ?? process.stdin;
+ const code =
+ recordsCommand !== undefined
+ ? await runHostRecordsProtocol(recordsCommand, input, output, {
+ signal: controller.signal,
+ classificationRuns,
+ })
+ : remediationOperation !== undefined
+ ? await runHostedRemediationProtocol(
+ input,
+ output,
+ controller.signal,
+ remediationOperation,
+ )
+ : await runHostedScanProtocol(input, output, controller.signal);
+ exitCode =
+ controller.signal.reason === "SIGINT"
+ ? 130
+ : controller.signal.reason === "SIGTERM"
+ ? 143
+ : code;
+ } finally {
+ removeSignals();
+ }
+ // Protocol writes have flushed or been canceled. Node's stdout ignores destroy().
+ if (output === process.stdout) process.exit(exitCode);
+ return exitCode;
+ }
const updateController = new AbortController();
const pendingUpdate =
errorOutput.isTTY === true &&
argv.length > 0 &&
- argv[0] !== "completions" &&
+ command !== "completions" &&
+ command !== "update" &&
!process.env["COMPLETE"] &&
!argv.some((argument) =>
- [...inspectionFlags, "--dry-run", "--update"].includes(argument),
+ [...INSPECTION_FLAGS, "--dry-run", "--mcp"].includes(argument),
) &&
updateNoticeEnabled(dependencies.environment)
? dependencies
@@ -8354,7 +8424,14 @@ export async function main(
},
};
if (
- !(await serveIntegration(frameworkArgv, cli, cliOptions, serveOptions))
+ !(await serveIntegration(
+ frameworkArgv,
+ cli,
+ cliOptions,
+ serveOptions,
+ command,
+ literalArgs,
+ ))
) {
await cli.serve(frameworkArgv, serveOptions);
}
@@ -8867,6 +8944,29 @@ function isJsonFormat(format: string | undefined): format is "json" | "jsonl" {
return format === "json" || format === "jsonl";
}
+/** Skip recognized global options and their operands while locating a command. */
+function firstNonGlobal(argv: readonly string[], start: number): number {
+ let index = start;
+ while (index < argv.length) {
+ const value = argv[index]!;
+ const [flag] = value.split("=", 1);
+ if (FRAMEWORK_VALUE_OPTIONS.has(flag!)) {
+ if (
+ !value.includes("=") &&
+ (argv[index + 1] === undefined || argv[index + 1]!.startsWith("-"))
+ )
+ break;
+ index += value.includes("=") ? 1 : 2;
+ } else if (
+ INSPECTION_FLAGS.includes(value) ||
+ ["--json", "--full-output", "--token-count"].includes(value)
+ ) {
+ index++;
+ } else break;
+ }
+ return index;
+}
+
function parseFrameworkArguments(
argv: readonly string[],
firstImportOption: number,
@@ -8876,7 +8976,7 @@ function parseFrameworkArguments(
const filters: (string | undefined)[] = [];
const tokenArguments: string[] = [];
let fullOutput = false;
- let malformedFilter = false;
+ let argumentError: string | undefined;
for (let index = 0; index < argv.length; index++) {
const argument = argv[index]!;
const next = argv[index + 1];
@@ -8905,10 +9005,16 @@ function parseFrameworkArguments(
const operand =
equals >= 0
? argument.slice(equals + 1)
- : next?.startsWith("--")
+ : /^-(?:-|[a-z])/iu.test(next ?? "")
? undefined
: next;
if (equals < 0 && operand !== undefined) index++;
+ if (
+ operand === undefined ||
+ (!operand && (flag === "--filter-output" || flag === "--format"))
+ ) {
+ argumentError ??= `Missing value for flag: ${flag}`;
+ }
if (flag === "--filter-output") {
filters.push(operand);
// Incur cannot advance past an unterminated array slice.
@@ -8916,7 +9022,8 @@ function parseFrameworkArguments(
operand !== undefined &&
!/^(?:[^\[\]]|\[[^\[\]]*\])*$/u.test(operand)
) {
- malformedFilter = true;
+ argumentError ??=
+ "--filter-output requires matching brackets for array slices.";
continue;
}
}
@@ -8936,7 +9043,7 @@ function parseFrameworkArguments(
formats,
jsonFormat,
fullOutput,
- malformedFilter,
+ argumentError,
filters,
tokenArguments,
rawStructuredOutput:
diff --git a/sdk/typescript/tests-ts/cli-diagnostics.test.ts b/sdk/typescript/tests-ts/cli-diagnostics.test.ts
index e2416bb8f..4f549a6c9 100644
--- a/sdk/typescript/tests-ts/cli-diagnostics.test.ts
+++ b/sdk/typescript/tests-ts/cli-diagnostics.test.ts
@@ -295,14 +295,7 @@ describe("CLI diagnostics", () => {
deps.currentDirectory = fail;
expect(
await runCli(
- [
- ...command,
- "--filter-output",
- "--help",
- "--format",
- "md",
- "--full-output",
- ],
+ [...command, "--format", "json", "--format", "md", "--full-output"],
deps,
),
).toBe(2);
diff --git a/sdk/typescript/tests-ts/cli-help.test.ts b/sdk/typescript/tests-ts/cli-help.test.ts
index 20206562a..0adde118c 100644
--- a/sdk/typescript/tests-ts/cli-help.test.ts
+++ b/sdk/typescript/tests-ts/cli-help.test.ts
@@ -1,4 +1,6 @@
import { describe, expect, test } from "bun:test";
+import { readdir } from "node:fs/promises";
+import { scopedTemporaryDirectory } from "./support/temporary-directories.js";
import { main } from "../src/cli.js";
import { DEFAULT_CODEX_CONFIG, scanModelConfiguration } from "../src/config.js";
import { DEFAULT_DEEP_SCAN_SETTINGS } from "../src/deep-scan-defaults.js";
@@ -80,6 +82,8 @@ describe("CLI help", () => {
expect(sectionFor("findings")).toBe(sectionFor("scans"));
expect(sectionFor("login")).toBeGreaterThan(sectionFor("scan"));
expect(sectionFor("init")).toBe(sectionFor("login"));
+ expect(sectionFor("update")).toBe(sectionFor("login"));
+ expect(text).not.toContain("--update");
expect(sectionFor("completions")).toBeGreaterThan(sectionFor("scan"));
expect(text).toContain("Aliases: cs");
for (const command of [
@@ -306,6 +310,172 @@ describe("CLI help", () => {
},
);
+ test.each([
+ ["scans", "show"],
+ ["findings", "false-positive"],
+ ["scan", "import"],
+ ["login", "status"],
+ ["publish", "findings"],
+ ])("resolves %s %s around global options", async (group, verb) => {
+ const flags = ["--format", "json", "--schema"];
+ const expected = JSON.parse(await help([group, verb, ...flags]));
+ expect(JSON.parse(await help([group, ...flags, verb]))).toEqual(expected);
+ });
+
+ test.each(
+ [
+ ["bogus", "--llms-full"],
+ ["scans", "--json", "bogus", "--llms"],
+ ["mcp", "bogus", "--llms-full"],
+ ["info", "extra", "--help"],
+ ["info", "extra", "--schema"],
+ ["info", "extra", "--llms"],
+ ["completions", "zsh", "extra"],
+ ["completions", "zsh", "--", "--version"],
+ ["skills", "list", "--", "--no-global"],
+ ].map((args) => ({ args })),
+ )(
+ "rejects unknown discovery paths or surplus words (%j)",
+ async ({ args }) => {
+ const stdout = capture();
+ const stderr = capture();
+ expect(
+ await main(args, stdout.stream, stderr.stream, dependencies()),
+ ).toBe(2);
+ expect(stdout.text()).toBe("");
+ expect(stderr.text()).toMatch(
+ /Unknown command|not a command|Unexpected positional/,
+ );
+ },
+ );
+
+ test.each([
+ ["scans", "shwo", "show"],
+ ["mcp", "doctr", "doctor"],
+ ["skills", "lsit", "list"],
+ ])("preserves suggested verbs for %s %s", async (group, typo, verb) => {
+ const stderr = capture();
+ expect(
+ await main(
+ [group, typo],
+ capture().stream,
+ stderr.stream,
+ dependencies(),
+ ),
+ ).toBe(2);
+ expect(stderr.text()).toContain(`Did you mean '${verb}'?`);
+ });
+
+ test("uses the completion shell schema without generating a script", async () => {
+ const schema = JSON.parse(
+ await help(["completions", "--json", "--schema"]),
+ );
+ expect(schema.args.properties.shell.enum).toContain("zsh");
+ });
+
+ test.each(
+ [
+ ["scan", ".", "--dry-run", "--update"],
+ ["scans", "list", "--mcp"],
+ ["policy", "--full-output", "--mcp"],
+ ["--mcp", "--update"],
+ ["scan", ".", "--dry-run", "--incur-update-check"],
+ ].map((args) => ({ args })),
+ )("rejects mixed or private actions (%j)", async ({ args }) => {
+ const stdout = capture();
+ const stderr = capture();
+ expect(await main(args, stdout.stream, stderr.stream, dependencies())).toBe(
+ 2,
+ );
+ expect(stdout.text()).toBe("");
+ expect(stderr.text()).toMatch(/must be used alone|Unknown flag/);
+ });
+
+ test.each(["--filter-output", "--format", "--token-limit", "--token-offset"])(
+ "%s cannot turn a following switch into a value and dispatch a write",
+ async (flag) => {
+ await using temp = await scopedTemporaryDirectory("cli-missing-global-");
+ const deps = dependencies({ currentDirectory: temp.path });
+ for (const next of [
+ "-h",
+ "--help",
+ "--version",
+ "--schema",
+ "--llms",
+ "--llms-full",
+ "--mcp",
+ "--update",
+ "--incur-update-check",
+ "--json",
+ "--full-output",
+ "-c",
+ ]) {
+ const stderr = capture();
+ expect(
+ await main(
+ [flag, next, "init", "new.yaml"],
+ capture().stream,
+ stderr.stream,
+ deps,
+ ),
+ ).toBe(2);
+ expect(stderr.text()).toMatch(
+ /Missing value|must be used alone|Unknown flag/,
+ );
+ }
+ expect(await readdir(temp.path)).toEqual([]);
+ },
+ );
+
+ test("the equals form keeps a dash-leading filter value literal", async () => {
+ await using temp = await scopedTemporaryDirectory("cli-explicit-filter-");
+ expect(
+ await main(
+ ["--filter-output=-h", "init", "new.yaml"],
+ capture().stream,
+ capture().stream,
+ dependencies({ currentDirectory: temp.path }),
+ ),
+ ).toBe(0);
+ expect(await readdir(temp.path)).toEqual(["new.yaml"]);
+ });
+
+ test("passes option-shaped filenames after -- through positional validation", async () => {
+ await using temp = await scopedTemporaryDirectory("cli-literal-args-");
+ const deps = dependencies({ currentDirectory: temp.path });
+ const stdout = capture();
+ const stderr = capture();
+ expect(
+ await main(
+ ["init", "--", "--version.yaml"],
+ stdout.stream,
+ stderr.stream,
+ deps,
+ ),
+ ).toBe(0);
+ expect(
+ await main(
+ ["--", "init", "--mcp.json"],
+ stdout.stream,
+ stderr.stream,
+ deps,
+ ),
+ ).toBe(0);
+ expect((await readdir(temp.path)).sort()).toEqual([
+ "--mcp.json",
+ "--version.yaml",
+ ]);
+ expect(
+ await main(
+ ["init", "--", "--version"],
+ stdout.stream,
+ stderr.stream,
+ deps,
+ ),
+ ).toBe(2);
+ expect(stderr.text()).toContain(".yaml");
+ });
+
test("links both file import routes and keeps the vendor preview copyable", async () => {
const menu = (await help(["import", "--help"])).replace(/\s+/gu, " ");
expect(menu).toContain("publish findings --help");
diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.ts
index 118991a48..eb40b32ae 100644
--- a/sdk/typescript/tests-ts/cli.test.ts
+++ b/sdk/typescript/tests-ts/cli.test.ts
@@ -3794,10 +3794,6 @@ describe("CLI", () => {
["bulk-scan", "--knowledge-base="],
"--knowledge-base must not be empty",
],
- [
- ["bulk-scan", "--output-dir", "results", "--", "repositories.csv"],
- "Unknown flag: --",
- ],
[["scan", ".", "--model="], "--model must not be empty"],
[
["scan", ".", "--provider", "openrouter"],
diff --git a/sdk/typescript/tests-ts/external-findings-publish.test.ts b/sdk/typescript/tests-ts/external-findings-publish.test.ts
index 30822d3b0..ebf2d9c71 100644
--- a/sdk/typescript/tests-ts/external-findings-publish.test.ts
+++ b/sdk/typescript/tests-ts/external-findings-publish.test.ts
@@ -11247,12 +11247,24 @@ test("publication rejects malformed options without writing findings", async ()
).toBe(2);
expect(cli.stderr.text()).toContain("Missing value for flag");
}
+ const missingGlobal = createCliTest(main);
+ expect(
+ await missingGlobal.runCli(
+ ["--filter-output", "--token-limit", ...f.command],
+ f.cliDeps,
+ ),
+ ).toBe(2);
+ expect(missingGlobal.stderr.text()).toContain(
+ "Missing value for flag: --filter-output",
+ );
const extraArguments = createCliTest(main);
expect(
await extraArguments.runCli(
[
"--filter-output",
+ "status",
"--token-limit",
+ "5",
...f.command,
"--yes",
"extra-1",
diff --git a/sdk/typescript/tests-ts/hosted-remediation.test.ts b/sdk/typescript/tests-ts/hosted-remediation.test.ts
index b52adc406..29c6182c4 100644
--- a/sdk/typescript/tests-ts/hosted-remediation.test.ts
+++ b/sdk/typescript/tests-ts/hosted-remediation.test.ts
@@ -391,10 +391,15 @@ test.each(["patch", "verify-fix"])(
const input = new PassThrough();
const stdout = capture();
const stderr = capture();
- const completed = main([command, "--host"], stdout.stream, stderr.stream, {
- ...dependencies(),
- recordsInput: input,
- });
+ const completed = main(
+ [command, "--host=true"],
+ stdout.stream,
+ stderr.stream,
+ {
+ ...dependencies(),
+ recordsInput: input,
+ },
+ );
input.write(
JSON.stringify({
jsonrpc: "2.0",
@@ -414,7 +419,6 @@ test.each(["patch", "verify-fix"])(
);
test.each([
- { args: ["patch", "--host=true"] },
{ args: ["patch", "--host", "--create-pr"] },
{ args: ["verify-fix", "finding.md", "--host"] },
])("hosted remediation rejects mixed arguments $args", async ({ args }) => {
diff --git a/sdk/typescript/tests-ts/hosted-scan.test.ts b/sdk/typescript/tests-ts/hosted-scan.test.ts
index 22559ba1e..5900b6f99 100644
--- a/sdk/typescript/tests-ts/hosted-scan.test.ts
+++ b/sdk/typescript/tests-ts/hosted-scan.test.ts
@@ -790,7 +790,7 @@ test.each(["valid", "tampered"] as const)(
: { ...severityRubric, markdown: severityRubric.markdown.trimEnd() };
const input = new PassThrough();
const output = capture();
- const run = main(["scan", "--host"], output.stream, capture().stream, {
+ const run = main(["scan", "--host=true"], output.stream, capture().stream, {
...dependencies(),
recordsInput: input,
});
@@ -842,7 +842,6 @@ test.each([
);
test.each([
- { args: ["scan", "--host=true"] },
{ args: ["scan", "--host", "--path", "service-a"] },
{ args: ["scan", ".", "--host"] },
])("host mode rejects unsupported combinations %p", async ({ args }) => {
@@ -855,6 +854,19 @@ test.each([
expect(stderr.text()).toContain("--host must be used alone");
});
+test("--host=false leaves a scan preview in CLI mode", async () => {
+ const stdout = capture();
+ expect(
+ await main(
+ ["scan", ".", "--host=false", "--dry-run", "--json"],
+ stdout.stream,
+ capture().stream,
+ dependencies(),
+ ),
+ ).toBe(0);
+ expect(JSON.parse(stdout.text()).dryRun).toBe(true);
+});
+
test.each([false, true])(
"CLI pipes retain reasoning effort, progress and execution receipts, including cancellation (%p)",
async (cancel) => {
diff --git a/sdk/typescript/tests-ts/validation-records.test.ts b/sdk/typescript/tests-ts/validation-records.test.ts
index b44411b64..85254785e 100644
--- a/sdk/typescript/tests-ts/validation-records.test.ts
+++ b/sdk/typescript/tests-ts/validation-records.test.ts
@@ -102,7 +102,7 @@ test.each([undefined, "", "\t", " synthetic-effort "])(
deps.runCodex = mock(throwing("Local execution is forbidden"));
const stderr = capture(true);
const completion = main(
- ["validate", "--records"],
+ ["validate", "--records=true"],
stdout,
stderr.stream,
deps,
@@ -171,7 +171,7 @@ test("alternate records flag syntax cannot start local validation", async () =>
deps,
),
).toBe(2);
- expect(stderr.text()).toContain("Use validate --records alone");
+ expect(stderr.text()).toContain("must be used alone with validate");
expect(deps.runCodex).not.toHaveBeenCalled();
});