Skip to content

Chrome DevTools for coding agents

fix(cli): pass positional values starting with `-` through to tools (#3084)

Alex Rudenko9de05ae6e59c
diff --git a/scripts/generate-cli.ts b/scripts/generate-cli.ts
index 0f19bfd2..367ad99c 100644
--- a/scripts/generate-cli.ts
+++ b/scripts/generate-cli.ts
@@ -23,11 +23,19 @@ const OUTPUT_PATH = path.join(
'../src/config/cli-options.ts',
);
+/**
+ * Optional args that intentionally remain positional for backwards-compatible
+ * CLI syntax. Every required arg is positional; every other optional arg is a
+ * flag.
+ */
+const OPTIONAL_POSITIONAL_ARGS = new Set(['evaluate_script:function']);
+
interface CliOption {
name: string;
type: string;
description: string;
required: boolean;
+ positional: boolean;
default?: unknown;
enum?: unknown[];
}
@@ -41,7 +49,7 @@ interface JsonSchema {
enum?: unknown[];
}
-function schemaToCLIOptions(schema: JsonSchema): CliOption[] {
+function schemaToCLIOptions(toolName: string, schema: JsonSchema): CliOption[] {
if (!schema || !schema.properties) {
return [];
}
@@ -60,6 +68,8 @@ function schemaToCLIOptions(schema: JsonSchema): CliOption[] {
type: prop.type,
description,
required: isRequired,
+ positional:
+ isRequired || OPTIONAL_POSITIONAL_ARGS.has(`${toolName}:${name}`),
default: prop.default,
enum: prop.enum,
};
@@ -109,7 +119,7 @@ async function generateCli() {
const inputSchema = zod.toJSONSchema(zod.object(tool.schema), {
io: 'input',
}) as JsonSchema;
- const options = schemaToCLIOptions(inputSchema);
+ const options = schemaToCLIOptions(tool.name, inputSchema);
const args: Record<string, CliOption> = {};
for (const opt of options) {
args[opt.name] = opt;
@@ -171,6 +181,8 @@ export interface ArgDef {
type: string;
description: string;
required: boolean;
+ /** Whether the arg is a positional on the command line, otherwise a flag. */
+ positional: boolean;
default?: string | number | boolean;
enum?: ReadonlyArray<string | number>;
}
diff --git a/src/bin/chrome-devtools.ts b/src/bin/chrome-devtools.ts
index 13900d33..59ea2375 100644
--- a/src/bin/chrome-devtools.ts
+++ b/src/bin/chrome-devtools.ts
@@ -28,7 +28,11 @@ import {hideBin, yargs, type CallToolResult} from '../third_party/index.js';
import {checkForUpdates} from '../utils/check-for-updates.js';
import {VERSION} from '../version.js';
-import {buildCommand, isOptionalPositionalArg} from '../config/cli-commands.js';
+import {
+ buildCommand,
+ getCommandArgSpec,
+ shieldLiteralArgs,
+} from '../config/cli-commands.js';
import {commands} from '../config/cli-options.js';
import {mcpOptions, getCliOptions} from '../config/mcp-options.js';
@@ -61,7 +65,15 @@ async function start(
logDisclaimers(parsedArgs);
}
-const y = yargs(hideBin(process.argv))
+const {argv: cliArgs, restore: restoreLiteralArg} = shieldLiteralArgs(
+ hideBin(process.argv),
+ commandName => {
+ const commandDef = commands[commandName];
+ return commandDef ? getCommandArgSpec(commandDef.args) : undefined;
+ },
+);
+
+const y = yargs(cliArgs)
.locale('en') // Force English to ensure error string matching works in .fail, all custom messages we output are in English anyways
.scriptName('chrome-devtools')
.showHelpOnFail(true)
@@ -212,7 +224,7 @@ for (const [commandName, commandDef] of Object.entries(commands)) {
? 'array'
: 'string';
- if (opt.required || isOptionalPositionalArg(commandName, argName)) {
+ if (opt.positional) {
const options: PositionalOptions = {
describe: opt.description,
type: type as PositionalOptions['type'],
@@ -255,7 +267,7 @@ for (const [commandName, commandDef] of Object.entries(commands)) {
const commandArgs: Record<string, unknown> = {};
for (const argName of Object.keys(args)) {
if (argName in argv) {
- commandArgs[argName] = argv[argName];
+ commandArgs[argName] = restoreLiteralArg(argv[argName]);
}
}
diff --git a/src/config/cli-commands.ts b/src/config/cli-commands.ts
index 03163e1e..36d519d3 100644
--- a/src/config/cli-commands.ts
+++ b/src/config/cli-commands.ts
@@ -6,22 +6,13 @@
import type {ArgDef} from './cli-options.js';
-const OPTIONAL_POSITIONAL_ARGS = new Set(['evaluate_script:function']);
-
-export function isOptionalPositionalArg(
- commandName: string,
- argName: string,
-): boolean {
- return OPTIONAL_POSITIONAL_ARGS.has(`${commandName}:${argName}`);
-}
-
/**
* Builds the yargs command string and usage line for a CLI command.
*
* Optional flag args are rendered as `[--flag]` in the usage line only: as
* part of the command string yargs parses each one as a trailing positional,
- * and a variadic positional has to be the last one. A small set of optional
- * args intentionally remain positional for backwards-compatible CLI syntax.
+ * and a variadic positional has to be the last one. Which args are positional
+ * is decided at build time by `scripts/generate-cli.ts`.
*/
export function buildCommand(
commandName: string,
@@ -30,14 +21,200 @@ export function buildCommand(
let command = commandName;
let flags = '';
for (const [name, arg] of Object.entries(args)) {
- if (arg.required) {
+ if (!arg.positional) {
+ flags += ` [--${name}]`;
+ } else if (arg.required) {
command += arg.type === 'array' ? ` <${name}..>` : ` <${name}>`;
- } else if (isOptionalPositionalArg(commandName, name)) {
- command += arg.type === 'array' ? ` [${name}..]` : ` [${name}]`;
} else {
- flags += ` [--${name}]`;
+ command += arg.type === 'array' ? ` [${name}..]` : ` [${name}]`;
}
}
return {command, usage: `$0 ${command}${flags}`};
}
+
+export type OptionKind = 'boolean' | 'array' | 'value';
+
+/**
+ * Options that are available on every tool command and are consumed by yargs
+ * rather than forwarded to the tool.
+ */
+export const GLOBAL_CLI_OPTIONS: ReadonlyMap<string, OptionKind> = new Map([
+ ['sessionId', 'value'],
+ ['outputFormat', 'value'],
+ ['help', 'boolean'],
+ ['version', 'boolean'],
+]);
+
+/**
+ * Describes what a CLI command accepts, as needed by `shieldLiteralArgs`.
+ */
+export interface CommandArgSpec {
+ /** Known option names (camelCase and aliases) and how they take values. */
+ options: Map<string, OptionKind>;
+ /** Number of positional arguments. */
+ positionalCount: number;
+ /** Whether the last positional is variadic. */
+ variadic: boolean;
+}
+
+/**
+ * Builds a `CommandArgSpec` for a tool command from its generated arg
+ * definitions and the options available on every command.
+ */
+export function getCommandArgSpec(
+ args: Record<string, ArgDef>,
+ globalOptions: ReadonlyMap<string, OptionKind> = GLOBAL_CLI_OPTIONS,
+): CommandArgSpec {
+ const options = new Map(globalOptions);
+ let positionalCount = 0;
+ let variadic = false;
+ for (const [name, arg] of Object.entries(args)) {
+ if (arg.positional) {
+ positionalCount++;
+ variadic = arg.type === 'array';
+ } else {
+ options.set(name, toOptionKind(arg.type));
+ }
+ }
+ return {options, positionalCount, variadic};
+}
+
+export function toOptionKind(type: string | undefined): OptionKind {
+ if (type === 'boolean') {
+ return 'boolean';
+ }
+ if (type === 'array') {
+ return 'array';
+ }
+ return 'value';
+}
+
+const LITERAL_ARG_PREFIX = '\0literal:';
+// Mirrors yargs-parser's negative number detection.
+const NEGATIVE_NUMBER = /^-\d+(\.\d*)?(e-?\d+)?$/;
+
+function optionName(token: string): string {
+ let name = token.replace(/^-+/, '');
+ const eq = name.indexOf('=');
+ if (eq !== -1) {
+ name = name.slice(0, eq);
+ }
+ if (name.startsWith('no-')) {
+ name = name.slice(3);
+ }
+ return name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/**
+ * Shields positional values that yargs cannot carry through its parsing.
+ *
+ * yargs re-parses command positionals as `--name value` pairs, and in that
+ * pass yargs-parser treats any value starting with `-` (other than a negative
+ * number) as the next flag, replacing the value with `''`. It also never fills
+ * positionals from the tokens after `--`. See
+ * https://github.com/yargs/yargs/issues/1312 and
+ * https://github.com/yargs/yargs/issues/1821.
+ *
+ * Shielded tokens are replaced by opaque placeholders that `restore` maps back
+ * to the original values. A token is shielded when:
+ *
+ * - it is a lone `-`, which can never be an option;
+ * - it follows the first `--`, which is dropped so the tokens populate
+ * positionals;
+ * - it starts with `-`, is not a known option of the command, and the command
+ * still has an unfilled positional. Known options and their values are
+ * skipped the way yargs consumes them, so a dash-prefixed value such as
+ * `--flag` in a positional slot is passed through as text, while an unknown
+ * flag after all positionals are filled is still rejected by yargs.
+ *
+ * `getSpec` resolves the spec of a command by name and returns `undefined`
+ * for tokens that are not a command.
+ */
+export function shieldLiteralArgs(
+ argv: readonly string[],
+ getSpec: (commandName: string) => CommandArgSpec | undefined,
+): {
+ argv: string[];
+ restore: (value: unknown) => unknown;
+} {
+ const literals = new Map<string, string>();
+ const result: string[] = [];
+ const shield = (token: string): void => {
+ const placeholder = `${LITERAL_ARG_PREFIX}${literals.size}`;
+ literals.set(placeholder, token);
+ result.push(placeholder);
+ };
+
+ let spec: CommandArgSpec | undefined;
+ let filled = 0;
+ let afterDoubleDash = false;
+ for (let i = 0; i < argv.length; i++) {
+ const token = argv[i];
+ if (afterDoubleDash) {
+ shield(token);
+ continue;
+ }
+ if (token === '--') {
+ afterDoubleDash = true;
+ continue;
+ }
+ if (token === '-') {
+ shield(token);
+ filled++;
+ continue;
+ }
+ if (!token.startsWith('-') || NEGATIVE_NUMBER.test(token)) {
+ result.push(token);
+ if (!spec) {
+ spec = getSpec(token);
+ } else {
+ filled++;
+ }
+ continue;
+ }
+
+ const kind = spec?.options.get(optionName(token));
+ if (kind !== undefined) {
+ result.push(token);
+ if (token.includes('=')) {
+ continue;
+ }
+ if (kind === 'boolean') {
+ if (/^(true|false)$/.test(argv[i + 1] ?? '')) {
+ result.push(argv[++i]);
+ }
+ } else if (kind === 'array') {
+ while (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+ result.push(argv[++i]);
+ }
+ } else if (i + 1 < argv.length) {
+ result.push(argv[++i]);
+ }
+ continue;
+ }
+
+ const hasUnfilledPositional =
+ spec !== undefined &&
+ (filled < spec.positionalCount ||
+ (spec.variadic && spec.positionalCount > 0));
+ if (hasUnfilledPositional) {
+ shield(token);
+ filled++;
+ } else {
+ result.push(token);
+ }
+ }
+
+ const restore = (value: unknown): unknown => {
+ if (typeof value === 'string') {
+ return literals.get(value) ?? value;
+ }
+ if (Array.isArray(value)) {
+ return value.map(restore);
+ }
+ return value;
+ };
+
+ return {argv: result, restore};
+}
diff --git a/src/config/cli-options.ts b/src/config/cli-options.ts
index c63ef58e..248430ea 100644
--- a/src/config/cli-options.ts
+++ b/src/config/cli-options.ts
@@ -15,6 +15,8 @@ export interface ArgDef {
type: string;
description: string;
required: boolean;
+ /** Whether the arg is a positional on the command line, otherwise a flag. */
+ positional: boolean;
default?: string | number | boolean;
enum?: ReadonlyArray<string | number>;
}
@@ -37,6 +39,7 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
retainedSize: {
name: 'retainedSize',
@@ -44,6 +47,7 @@ export const commands: Commands = {
description:
'Inclusive range for the dead-field score of a context (e.g. "10KB", "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.',
required: false,
+ positional: false,
},
scopeInfoNodeId: {
name: 'scopeInfoNodeId',
@@ -51,6 +55,7 @@ export const commands: Commands = {
description:
'Only return contexts declared by the scope with this ScopeInfo node id, as reported in the scope header of a previous call.',
required: false,
+ positional: false,
},
maxNameLength: {
name: 'maxNameLength',
@@ -58,12 +63,14 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
pageIdx: {
name: 'pageIdx',
type: 'integer',
description: 'The zero-based page index. Defaults to 0.',
required: false,
+ positional: false,
},
pageSize: {
name: 'pageSize',
@@ -71,6 +78,7 @@ export const commands: Commands = {
description:
'The number of contexts to return per page. Defaults to 20.',
required: false,
+ positional: false,
},
},
},
@@ -83,6 +91,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
uid: {
name: 'uid',
@@ -90,12 +99,14 @@ export const commands: Commands = {
description:
'The uid of an element on the page from the page content snapshot',
required: true,
+ positional: true,
},
dblClick: {
name: 'dblClick',
type: 'boolean',
description: 'Set to true for double clicks. Default is false.',
required: false,
+ positional: false,
},
includeSnapshot: {
name: 'includeSnapshot',
@@ -103,6 +114,7 @@ export const commands: Commands = {
description:
'Whether to include a snapshot in the response. Default is false.',
required: false,
+ positional: false,
},
},
},
@@ -116,24 +128,28 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
x: {
name: 'x',
type: 'number',
description: 'The x coordinate',
required: true,
+ positional: true,
},
y: {
name: 'y',
type: 'number',
description: 'The y coordinate',
required: true,
+ positional: true,
},
dblClick: {
name: 'dblClick',
type: 'boolean',
description: 'Set to true for double clicks. Default is false.',
required: false,
+ positional: false,
},
includeSnapshot: {
name: 'includeSnapshot',
@@ -141,6 +157,7 @@ export const commands: Commands = {
description:
'Whether to include a snapshot in the response. Default is false.',
required: false,
+ positional: false,
},
},
},
@@ -154,6 +171,7 @@ export const commands: Commands = {
type: 'string',
description: 'A path to the .heapsnapshot file to close.',
required: true,
+ positional: true,
},
},
},
@@ -168,6 +186,7 @@ export const commands: Commands = {
description:
'The ID of the page to close. Call list_pages to list pages.',
required: true,
+ positional: true,
},
},
},
@@ -182,6 +201,7 @@ export const commands: Commands = {
description:
'A path to the base .heapsnapshot file (earlier snapshot).',
required: true,
+ positional: true,
},
currentFilePath: {
name: 'currentFilePath',
@@ -189,6 +209,7 @@ export const commands: Commands = {
description:
'A path to the current .heapsnapshot file (later snapshot).',
required: true,
+ positional: true,
},
classIndex: {
name: 'classIndex',
@@ -196,6 +217,7 @@ export const commands: Commands = {
description:
'Optional 0-based index of the class in the summary list to filter results, showing individual objects.',
required: false,
+ positional: false,
},
maxNameLength: {
name: 'maxNameLength',
@@ -203,6 +225,7 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
},
},
@@ -215,18 +238,21 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
from_uid: {
name: 'from_uid',
type: 'string',
description: 'The uid of the element to drag',
required: true,
+ positional: true,
},
to_uid: {
name: 'to_uid',
type: 'string',
description: 'The uid of the element to drop into',
required: true,
+ positional: true,
},
includeSnapshot: {
name: 'includeSnapshot',
@@ -234,6 +260,7 @@ export const commands: Commands = {
description:
'Whether to include a snapshot in the response. Default is false.',
required: false,
+ positional: false,
},
},
},
@@ -247,12 +274,14 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
networkConditions: {
name: 'networkConditions',
type: 'string',
description: 'Throttle network. Omit to disable throttling.',
required: false,
+ positional: false,
enum: ['Offline', 'Slow 3G', 'Fast 3G', 'Slow 4G', 'Fast 4G'],
},
cpuThrottlingRate: {
@@ -261,6 +290,7 @@ export const commands: Commands = {
description:
'Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling',
required: false,
+ positional: false,
},
geolocation: {
name: 'geolocation',
@@ -268,6 +298,7 @@ export const commands: Commands = {
description:
'Geolocation (`<latitude>,<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.',
required: false,
+ positional: false,
},
userAgent: {
name: 'userAgent',
@@ -275,6 +306,7 @@ export const commands: Commands = {
description:
'User agent to emulate. Omit or set to empty string to clear the user agent override.',
required: false,
+ positional: false,
},
colorScheme: {
name: 'colorScheme',
@@ -282,6 +314,7 @@ export const commands: Commands = {
description:
'Emulate the dark or the light mode. Omit or set to "auto" to reset to the default.',
required: false,
+ positional: false,
enum: ['dark', 'light', 'auto'],
},
forcedColors: {
@@ -290,6 +323,7 @@ export const commands: Commands = {
description:
'Emulate the `forced-colors` CSS media feature. Omit or set to "auto" to reset to the default.',
required: false,
+ positional: false,
enum: ['active', 'none', 'auto'],
},
prefersContrast: {
@@ -298,6 +332,7 @@ export const commands: Commands = {
description:
'Emulate the `prefers-contrast` CSS media feature. Omit or set to "auto" to reset to the default.',
required: false,
+ positional: false,
enum: ['more', 'less', 'custom', 'no-preference', 'auto'],
},
prefersReducedMotion: {
@@ -306,6 +341,7 @@ export const commands: Commands = {
description:
'Emulate the `prefers-reduced-motion` CSS media feature. Omit or set to "auto" to reset to the default.',
required: false,
+ positional: false,
enum: ['reduce', 'no-preference', 'auto'],
},
viewport: {
@@ -314,6 +350,7 @@ export const commands: Commands = {
description:
"Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode. Omit to clear the viewport override.",
required: false,
+ positional: false,
},
extraHttpHeaders: {
name: 'extraHttpHeaders',
@@ -321,6 +358,7 @@ export const commands: Commands = {
description:
'Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.',
required: false,
+ positional: false,
},
},
},
@@ -335,6 +373,7 @@ export const commands: Commands = {
description:
'Targets a specific page by ID. Required when not evaluating in a service worker.',
required: false,
+ positional: false,
},
function: {
name: 'function',
@@ -342,6 +381,7 @@ export const commands: Commands = {
description:
'JavaScript source to execute in the target page. Provide either this or sourcePath, but not both. The source is interpreted according to format.\nExample without arguments: `() => document.title` or `async () => await fetch("example.com")`.\nExample with arguments: `(el) => el.innerText`\n',
required: false,
+ positional: true,
},
sourcePath: {
name: 'sourcePath',
@@ -349,6 +389,7 @@ export const commands: Commands = {
description:
"The absolute or relative path to a JavaScript file on the MCP server's local filesystem. Provide either this or function, but not both.",
required: false,
+ positional: false,
},
format: {
name: 'format',
@@ -356,6 +397,7 @@ export const commands: Commands = {
description:
'How to interpret the source. "function" treats it as a function declaration and supports args. "script" evaluates it as classic JavaScript and does not support args. Defaults to "function". ECMAScript modules are not supported.',
required: false,
+ positional: false,
enum: ['function', 'script'],
},
args: {
@@ -364,6 +406,7 @@ export const commands: Commands = {
description:
'An optional list of arguments (element uids from the page content snapshot) to pass to the function.',
required: false,
+ positional: false,
},
filePath: {
name: 'filePath',
@@ -371,6 +414,7 @@ export const commands: Commands = {
description:
'The absolute or relative path to a file to save the script output to. If omitted, the output is returned inline.',
required: false,
+ positional: false,
},
dialogAction: {
name: 'dialogAction',
@@ -378,6 +422,7 @@ export const commands: Commands = {
description:
'Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.',
required: false,
+ positional: false,
},
waitForStableDom: {
name: 'waitForStableDom',
@@ -385,6 +430,7 @@ export const commands: Commands = {
description:
'Whether to wait for the DOM to settle. Pass false if the script only reads data. Defaults to true.',
required: false,
+ positional: false,
},
serviceWorkerId: {
name: 'serviceWorkerId',
@@ -392,6 +438,7 @@ export const commands: Commands = {
description:
"The optional service worker id to evaluate the script in. If provided, 'pageId' should be omitted. Note: 'args' (element UIDs) cannot be used when evaluating in a service worker.",
required: false,
+ positional: false,
},
},
},
@@ -405,18 +452,21 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
toolName: {
name: 'toolName',
type: 'string',
description: 'The name of the tool to execute',
required: true,
+ positional: true,
},
params: {
name: 'params',
type: 'string',
description: 'The JSON-stringified parameters to pass to the tool',
required: false,
+ positional: false,
},
},
},
@@ -430,12 +480,14 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
toolName: {
name: 'toolName',
type: 'string',
description: 'The name of the WebMCP tool to execute',
required: true,
+ positional: true,
},
input: {
name: 'input',
@@ -443,6 +495,7 @@ export const commands: Commands = {
description:
'The JSON-stringified parameters to pass to the WebMCP tool',
required: false,
+ positional: false,
},
},
},
@@ -456,6 +509,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
uid: {
name: 'uid',
@@ -463,6 +517,7 @@ export const commands: Commands = {
description:
'The uid of an element on the page from the page content snapshot',
required: true,
+ positional: true,
},
value: {
name: 'value',
@@ -470,6 +525,7 @@ export const commands: Commands = {
description:
'The value to fill in. "true" or "false" for checkboxes and toggles, "true" for radio buttons.',
required: true,
+ positional: true,
},
includeSnapshot: {
name: 'includeSnapshot',
@@ -477,6 +533,7 @@ export const commands: Commands = {
description:
'Whether to include a snapshot in the response. Default is false.',
required: false,
+ positional: false,
},
},
},
@@ -490,6 +547,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
msgid: {
name: 'msgid',
@@ -497,6 +555,7 @@ export const commands: Commands = {
description:
'The msgid of a console message on the page from the listed console messages',
required: true,
+ positional: true,
},
},
},
@@ -510,6 +569,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
uid: {
name: 'uid',
@@ -517,6 +577,7 @@ export const commands: Commands = {
description:
'The uid of the element on the page from the page content snapshot to inspect CSS styles for',
required: true,
+ positional: true,
},
pageSize: {
name: 'pageSize',
@@ -524,6 +585,7 @@ export const commands: Commands = {
description:
'Maximum number of CSS rules to return per page. Defaults to 10.',
required: false,
+ positional: false,
default: 10,
},
pageIdx: {
@@ -532,6 +594,7 @@ export const commands: Commands = {
description:
'Page number to return (0-based). Defaults to 0 (the first page).',
required: false,
+ positional: false,
default: 0,
},
},
@@ -546,18 +609,21 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
id: {
name: 'id',
type: 'number',
description: 'The ID for the class, obtained from details.',
required: true,
+ positional: true,
},
filterName: {
name: 'filterName',
type: 'string',
description: 'An optional filter to apply to the nodes.',
required: false,
+ positional: false,
enum: [
'objectsRetainedByDetachedDomNodes',
'objectsRetainedByConsole',
@@ -574,6 +640,7 @@ export const commands: Commands = {
description:
'The object ID (nodeId) of the specific native context to filter by when filterName is attributedToSpecificNativeContext.',
required: false,
+ positional: false,
},
maxNameLength: {
name: 'maxNameLength',
@@ -581,18 +648,21 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
pageIdx: {
name: 'pageIdx',
type: 'integer',
description: 'The page index for pagination.',
required: false,
+ positional: false,
},
pageSize: {
name: 'pageSize',
type: 'integer',
description: 'The page size for pagination.',
required: false,
+ positional: false,
},
},
},
@@ -606,12 +676,14 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
filterName: {
name: 'filterName',
type: 'string',
description: 'An optional filter to apply to the aggregates.',
required: false,
+ positional: false,
enum: [
'objectsRetainedByDetachedDomNodes',
'objectsRetainedByConsole',
@@ -628,6 +700,7 @@ export const commands: Commands = {
description:
'The object ID (nodeId) of the specific native context to filter by when filterName is attributedToSpecificNativeContext.',
required: false,
+ positional: false,
},
maxNameLength: {
name: 'maxNameLength',
@@ -635,18 +708,21 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
pageIdx: {
name: 'pageIdx',
type: 'integer',
description: 'The page index for pagination of aggregates.',
required: false,
+ positional: false,
},
pageSize: {
name: 'pageSize',
type: 'integer',
description: 'The page size for pagination of aggregates.',
required: false,
+ positional: false,
},
},
},
@@ -660,12 +736,14 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
nodeId: {
name: 'nodeId',
type: 'number',
description: 'The node ID to get the dominator chain for.',
required: true,
+ positional: true,
},
maxNameLength: {
name: 'maxNameLength',
@@ -673,6 +751,7 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
},
},
@@ -686,18 +765,21 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
pageIdx: {
name: 'pageIdx',
type: 'integer',
description: 'The page index for pagination.',
required: false,
+ positional: false,
},
pageSize: {
name: 'pageSize',
type: 'integer',
description: 'The page size for pagination.',
required: false,
+ positional: false,
},
maxNameLength: {
name: 'maxNameLength',
@@ -705,6 +787,7 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
},
},
@@ -718,18 +801,21 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
nodeId: {
name: 'nodeId',
type: 'number',
description: 'The node ID to get outgoing edges for.',
required: true,
+ positional: true,
},
sortBy: {
name: 'sortBy',
type: 'string',
description: 'Sort order for edges. Default is retainedSize.',
required: false,
+ positional: false,
enum: ['retainedSize', 'selfSize', 'name'],
},
retainedSize: {
@@ -738,6 +824,7 @@ export const commands: Commands = {
description:
'Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-") for target nodes. A single value is treated as a minimum. Currently, only the lower bound is applied.',
required: false,
+ positional: false,
},
excludePrimitives: {
name: 'excludePrimitives',
@@ -745,6 +832,7 @@ export const commands: Commands = {
description:
'Whether to exclude primitive target nodes. Default is true.',
required: false,
+ positional: false,
},
maxNameLength: {
name: 'maxNameLength',
@@ -752,18 +840,21 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
pageIdx: {
name: 'pageIdx',
type: 'integer',
description: 'The page index for pagination.',
required: false,
+ positional: false,
},
pageSize: {
name: 'pageSize',
type: 'integer',
description: 'The page size for pagination.',
required: false,
+ positional: false,
},
},
},
@@ -777,12 +868,14 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
nodeId: {
name: 'nodeId',
type: 'number',
description: 'The node ID to get object details for.',
required: true,
+ positional: true,
},
maxNameLength: {
name: 'maxNameLength',
@@ -790,6 +883,7 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
},
},
@@ -803,12 +897,14 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
nodeId: {
name: 'nodeId',
type: 'number',
description: 'The node ID to get retainers for.',
required: true,
+ positional: true,
},
maxNameLength: {
name: 'maxNameLength',
@@ -816,18 +912,21 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
pageIdx: {
name: 'pageIdx',
type: 'integer',
description: 'The page index for pagination.',
required: false,
+ positional: false,
},
pageSize: {
name: 'pageSize',
type: 'integer',
description: 'The page size for pagination.',
required: false,
+ positional: false,
},
},
},
@@ -841,30 +940,35 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
nodeId: {
name: 'nodeId',
type: 'number',
description: 'The node ID to get retaining paths for.',
required: true,
+ positional: true,
},
maxDepth: {
name: 'maxDepth',
type: 'number',
description: 'The maximum depth to search for retaining paths.',
required: false,
+ positional: false,
},
maxNodes: {
name: 'maxNodes',
type: 'number',
description: 'The maximum number of nodes to return.',
required: false,
+ positional: false,
},
maxSiblings: {
name: 'maxSiblings',
type: 'number',
description: 'The maximum number of siblings to return.',
required: false,
+ positional: false,
},
maxNameLength: {
name: 'maxNameLength',
@@ -872,6 +976,7 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
},
},
@@ -885,6 +990,7 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
maxNameLength: {
name: 'maxNameLength',
@@ -892,6 +998,7 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
},
},
@@ -905,6 +1012,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
reqid: {
name: 'reqid',
@@ -912,6 +1020,7 @@ export const commands: Commands = {
description:
'The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.',
required: false,
+ positional: false,
},
requestFilePath: {
name: 'requestFilePath',
@@ -919,6 +1028,7 @@ export const commands: Commands = {
description:
'The absolute or relative path to a .network-request file to save the request body to. If omitted, the body is returned inline.',
required: false,
+ positional: false,
},
responseFilePath: {
name: 'responseFilePath',
@@ -926,6 +1036,7 @@ export const commands: Commands = {
description:
'The absolute or relative path to a .network-response file to save the response body to. If omitted, the body is returned inline.',
required: false,
+ positional: false,
},
},
},
@@ -940,6 +1051,7 @@ export const commands: Commands = {
description:
'The manifest ID of the web app: the resolved `id` member of its manifest. If `id` is omitted, it defaults to the resolved `start_url` (e.g. "https://example.com/"). See https://w3c.github.io/manifest/#id-member.',
required: true,
+ positional: true,
},
},
},
@@ -953,12 +1065,14 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
action: {
name: 'action',
type: 'string',
description: 'Whether to dismiss or accept the dialog',
required: true,
+ positional: true,
enum: ['accept', 'dismiss'],
},
promptText: {
@@ -966,6 +1080,7 @@ export const commands: Commands = {
type: 'string',
description: 'Optional prompt text to enter into the dialog.',
required: false,
+ positional: false,
},
},
},
@@ -978,6 +1093,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
uid: {
name: 'uid',
@@ -985,6 +1101,7 @@ export const commands: Commands = {
description:
'The uid of an element on the page from the page content snapshot',
required: true,
+ positional: true,
},
includeSnapshot: {
name: 'includeSnapshot',
@@ -992,6 +1109,7 @@ export const commands: Commands = {
description:
'Whether to include a snapshot in the response. Default is false.',
required: false,
+ positional: false,
},
},
},
@@ -1005,6 +1123,7 @@ export const commands: Commands = {
type: 'string',
description: 'Absolute path to the unpacked extension folder.',
required: true,
+ positional: true,
},
},
},
@@ -1019,6 +1138,7 @@ export const commands: Commands = {
description:
'The manifest ID of the web app: the resolved `id` member of its manifest. If `id` is omitted, it defaults to the resolved `start_url` (e.g. "https://example.com/"). See https://w3c.github.io/manifest/#id-member.',
required: true,
+ positional: true,
},
installUrlOrBundleUrl: {
name: 'installUrlOrBundleUrl',
@@ -1026,6 +1146,7 @@ export const commands: Commands = {
description:
'The location of the app or bundle. For a normal site this is the page URL; for an Isolated Web App it can be a file:// or http(s):// signed web bundle.',
required: true,
+ positional: true,
},
displayMode: {
name: 'displayMode',
@@ -1033,6 +1154,7 @@ export const commands: Commands = {
description:
'Optional user display mode preference applied after install. "standalone" opens the app in its own window; "browser" opens it as a tab. Installs via the PWA CDP domain default to "browser" because they do not simulate the install dialog, so pass "standalone" to get an app-window experience.',
required: false,
+ positional: false,
enum: ['standalone', 'browser'],
},
},
@@ -1048,6 +1170,7 @@ export const commands: Commands = {
description:
'The manifest ID of the web app: the resolved `id` member of its manifest. If `id` is omitted, it defaults to the resolved `start_url` (e.g. "https://example.com/"). See https://w3c.github.io/manifest/#id-member.',
required: true,
+ positional: true,
},
url: {
name: 'url',
@@ -1055,6 +1178,7 @@ export const commands: Commands = {
description:
'Optional URL within the app to open instead of the default start URL.',
required: false,
+ positional: false,
},
},
},
@@ -1068,6 +1192,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
mode: {
name: 'mode',
@@ -1075,6 +1200,7 @@ export const commands: Commands = {
description:
'"navigation" reloads & audits. "snapshot" analyzes current state.',
required: false,
+ positional: false,
default: 'navigation',
enum: ['navigation', 'snapshot'],
},
@@ -1083,6 +1209,7 @@ export const commands: Commands = {
type: 'string',
description: 'Device to emulate.',
required: false,
+ positional: false,
default: 'desktop',
enum: ['desktop', 'mobile'],
},
@@ -1091,6 +1218,7 @@ export const commands: Commands = {
type: 'string',
description: 'Directory for reports. If omitted, uses temporary files.',
required: false,
+ positional: false,
},
},
},
@@ -1104,6 +1232,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
},
},
@@ -1117,6 +1246,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
pageSize: {
name: 'pageSize',
@@ -1124,6 +1254,7 @@ export const commands: Commands = {
description:
'Maximum number of messages to return. When omitted, returns all messages.',
required: false,
+ positional: false,
},
pageIdx: {
name: 'pageIdx',
@@ -1131,6 +1262,7 @@ export const commands: Commands = {
description:
'Page number to return (0-based). When omitted, returns the first page.',
required: false,
+ positional: false,
},
types: {
name: 'types',
@@ -1138,6 +1270,7 @@ export const commands: Commands = {
description:
'Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.',
required: false,
+ positional: false,
},
includePreservedMessages: {
name: 'includePreservedMessages',
@@ -1145,6 +1278,7 @@ export const commands: Commands = {
description:
'Set to true to return the preserved messages over the last 3 navigations.',
required: false,
+ positional: false,
default: false,
},
includeStackTraces: {
@@ -1153,6 +1287,7 @@ export const commands: Commands = {
description:
'Set to true to include the stack trace for each message when available. Increases the response size.',
required: false,
+ positional: false,
default: false,
},
serviceWorkerId: {
@@ -1161,6 +1296,7 @@ export const commands: Commands = {
description:
'Filter messages to only return messages of the specified service worker.',
required: false,
+ positional: false,
},
},
},
@@ -1180,6 +1316,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
pageSize: {
name: 'pageSize',
@@ -1187,6 +1324,7 @@ export const commands: Commands = {
description:
'Maximum number of requests to return. When omitted, returns all requests.',
required: false,
+ positional: false,
},
pageIdx: {
name: 'pageIdx',
@@ -1194,6 +1332,7 @@ export const commands: Commands = {
description:
'Page number to return (0-based). When omitted, returns the first page.',
required: false,
+ positional: false,
},
resourceTypes: {
name: 'resourceTypes',
@@ -1201,6 +1340,7 @@ export const commands: Commands = {
description:
'Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.',
required: false,
+ positional: false,
},
includePreservedRequests: {
name: 'includePreservedRequests',
@@ -1208,6 +1348,7 @@ export const commands: Commands = {
description:
'Set to true to return the preserved requests over the last 3 navigations.',
required: false,
+ positional: false,
default: false,
},
},
@@ -1228,6 +1369,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
},
},
@@ -1241,6 +1383,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
type: {
name: 'type',
@@ -1248,6 +1391,7 @@ export const commands: Commands = {
description:
'Navigate the page by URL, back or forward in history, or reload.',
required: false,
+ positional: false,
enum: ['url', 'back', 'forward', 'reload'],
},
url: {
@@ -1255,12 +1399,14 @@ export const commands: Commands = {
type: 'string',
description: 'Target URL (only type=url)',
required: false,
+ positional: false,
},
ignoreCache: {
name: 'ignoreCache',
type: 'boolean',
description: 'Whether to ignore cache on reload.',
required: false,
+ positional: false,
},
handleBeforeUnload: {
name: 'handleBeforeUnload',
@@ -1268,6 +1414,7 @@ export const commands: Commands = {
description:
'Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.',
required: false,
+ positional: false,
enum: ['accept', 'dismiss'],
},
initScript: {
@@ -1276,6 +1423,7 @@ export const commands: Commands = {
description:
'A JavaScript script to be executed on each new document before any other scripts for the next navigation.',
required: false,
+ positional: false,
},
timeout: {
name: 'timeout',
@@ -1283,6 +1431,7 @@ export const commands: Commands = {
description:
'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.',
required: false,
+ positional: false,
},
},
},
@@ -1296,6 +1445,7 @@ export const commands: Commands = {
type: 'string',
description: 'URL to load in a new page.',
required: true,
+ positional: true,
},
background: {
name: 'background',
@@ -1303,6 +1453,7 @@ export const commands: Commands = {
description:
'Whether to open the page in the background without bringing it to the front. Default is false (foreground).',
required: false,
+ positional: false,
},
isolatedContext: {
name: 'isolatedContext',
@@ -1310,6 +1461,7 @@ export const commands: Commands = {
description:
'If specified, the page is created in an isolated browser context with the given name. Pages in the same browser context share cookies and storage. Pages in different browser contexts are fully isolated (useful for clean-slate testing of cookies and authentication).',
required: false,
+ positional: false,
},
timeout: {
name: 'timeout',
@@ -1317,6 +1469,7 @@ export const commands: Commands = {
description:
'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.',
required: false,
+ positional: false,
},
},
},
@@ -1330,6 +1483,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
insightSetId: {
name: 'insightSetId',
@@ -1337,6 +1491,7 @@ export const commands: Commands = {
description:
'The id for the specific insight set. Only use the ids given in the "Available insight sets" list.',
required: true,
+ positional: true,
},
insightName: {
name: 'insightName',
@@ -1344,6 +1499,7 @@ export const commands: Commands = {
description:
'The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"',
required: true,
+ positional: true,
},
},
},
@@ -1357,6 +1513,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
reload: {
name: 'reload',
@@ -1364,6 +1521,7 @@ export const commands: Commands = {
description:
'Determines if, once tracing has started, the target page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.',
required: false,
+ positional: false,
default: true,
},
autoStop: {
@@ -1372,6 +1530,7 @@ export const commands: Commands = {
description:
'Determines if the trace recording should be automatically stopped.',
required: false,
+ positional: false,
default: true,
},
ignoreCache: {
@@ -1380,6 +1539,7 @@ export const commands: Commands = {
description:
'Whether to bypass the HTTP cache when reloading the page, to measure a cold page load. Only applies if reload is true.',
required: false,
+ positional: false,
},
filePath: {
name: 'filePath',
@@ -1387,6 +1547,7 @@ export const commands: Commands = {
description:
'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).',
required: false,
+ positional: false,
},
},
},
@@ -1400,6 +1561,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
filePath: {
name: 'filePath',
@@ -1407,6 +1569,7 @@ export const commands: Commands = {
description:
'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).',
required: false,
+ positional: false,
},
},
},
@@ -1420,6 +1583,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
key: {
name: 'key',
@@ -1427,6 +1591,7 @@ export const commands: Commands = {
description:
'A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta',
required: true,
+ positional: true,
},
includeSnapshot: {
name: 'includeSnapshot',
@@ -1434,6 +1599,7 @@ export const commands: Commands = {
description:
'Whether to include a snapshot in the response. Default is false.',
required: false,
+ positional: false,
},
},
},
@@ -1447,12 +1613,14 @@ export const commands: Commands = {
type: 'string',
description: 'A path to a .heapsnapshot file to read.',
required: true,
+ positional: true,
},
className: {
name: 'className',
type: 'string',
description: 'Optional regex or text matching object class name.',
required: false,
+ positional: false,
},
propertyName: {
name: 'propertyName',
@@ -1460,6 +1628,7 @@ export const commands: Commands = {
description:
'Optional property name filter for outgoing reference edges.',
required: false,
+ positional: false,
},
nodeType: {
name: 'nodeType',
@@ -1467,6 +1636,7 @@ export const commands: Commands = {
description:
'Optional V8 node type filter (e.g. object, closure, string, array, code).',
required: false,
+ positional: false,
},
retainedSize: {
name: 'retainedSize',
@@ -1474,6 +1644,7 @@ export const commands: Commands = {
description:
'Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.',
required: false,
+ positional: false,
},
selfSize: {
name: 'selfSize',
@@ -1481,18 +1652,21 @@ export const commands: Commands = {
description:
'Inclusive self size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.',
required: false,
+ positional: false,
},
isDetached: {
name: 'isDetached',
type: 'boolean',
description: 'Whether to filter for detached DOM nodes.',
required: false,
+ positional: false,
},
sortBy: {
name: 'sortBy',
type: 'string',
description: 'Sort order for results. Default is retainedSize.',
required: false,
+ positional: false,
enum: ['retainedSize', 'selfSize', 'id'],
},
pageIdx: {
@@ -1500,12 +1674,14 @@ export const commands: Commands = {
type: 'integer',
description: 'The page index for pagination.',
required: false,
+ positional: false,
},
pageSize: {
name: 'pageSize',
type: 'integer',
description: 'The page size for pagination.',
required: false,
+ positional: false,
},
maxNameLength: {
name: 'maxNameLength',
@@ -1513,6 +1689,7 @@ export const commands: Commands = {
description:
'Maximum length of names before truncation. Defaults to 100.',
required: false,
+ positional: false,
},
},
},
@@ -1526,6 +1703,7 @@ export const commands: Commands = {
type: 'string',
description: 'ID of the extension to reload.',
required: true,
+ positional: true,
},
},
},
@@ -1539,18 +1717,21 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
width: {
name: 'width',
type: 'integer',
description: 'Page width',
required: true,
+ positional: true,
},
height: {
name: 'height',
type: 'integer',
description: 'Page height',
required: true,
+ positional: true,
},
},
},
@@ -1563,6 +1744,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
filePath: {
name: 'filePath',
@@ -1570,6 +1752,7 @@ export const commands: Commands = {
description:
'Output file path (.mp4). Uses mkdtemp to generate a unique path if not provided.',
required: false,
+ positional: false,
},
},
},
@@ -1582,6 +1765,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
},
},
@@ -1595,12 +1779,14 @@ export const commands: Commands = {
description:
'The ID of the page to select. Call list_pages to get available pages.',
required: true,
+ positional: true,
},
bringToFront: {
name: 'bringToFront',
type: 'boolean',
description: 'Whether to focus the page and bring it to the top.',
required: false,
+ positional: false,
},
},
},
@@ -1614,6 +1800,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
filePath: {
name: 'filePath',
@@ -1621,6 +1808,7 @@ export const commands: Commands = {
description:
'A path to a .heapsnapshot file to save the heapsnapshot to.',
required: true,
+ positional: true,
},
},
},
@@ -1633,6 +1821,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
format: {
name: 'format',
@@ -1640,6 +1829,7 @@ export const commands: Commands = {
description:
'Type of format to save the screenshot as. Default is "png"',
required: false,
+ positional: false,
default: 'png',
enum: ['png', 'jpeg', 'webp'],
},
@@ -1649,6 +1839,7 @@ export const commands: Commands = {
description:
'Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.',
required: false,
+ positional: false,
},
uid: {
name: 'uid',
@@ -1656,6 +1847,7 @@ export const commands: Commands = {
description:
'The uid of an element on the page from the page content snapshot. If omitted, takes a page screenshot.',
required: false,
+ positional: false,
},
fullPage: {
name: 'fullPage',
@@ -1663,6 +1855,7 @@ export const commands: Commands = {
description:
'If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.',
required: false,
+ positional: false,
},
filePath: {
name: 'filePath',
@@ -1670,6 +1863,7 @@ export const commands: Commands = {
description:
'The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.',
required: false,
+ positional: false,
},
},
},
@@ -1683,6 +1877,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
verbose: {
name: 'verbose',
@@ -1690,6 +1885,7 @@ export const commands: Commands = {
description:
'Whether to include all possible information available in the full a11y tree. Default is false.',
required: false,
+ positional: false,
},
filePath: {
name: 'filePath',
@@ -1697,6 +1893,7 @@ export const commands: Commands = {
description:
'The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.',
required: false,
+ positional: false,
},
},
},
@@ -1710,6 +1907,7 @@ export const commands: Commands = {
type: 'string',
description: 'ID of the extension to trigger the action for.',
required: true,
+ positional: true,
},
},
},
@@ -1722,12 +1920,14 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
text: {
name: 'text',
type: 'string',
description: 'The text to type',
required: true,
+ positional: true,
},
submitKey: {
name: 'submitKey',
@@ -1735,6 +1935,7 @@ export const commands: Commands = {
description:
'Optional key to press after typing. E.g., "Enter", "Tab", "Escape"',
required: false,
+ positional: false,
},
},
},
@@ -1748,6 +1949,7 @@ export const commands: Commands = {
type: 'string',
description: 'ID of the extension to uninstall.',
required: true,
+ positional: true,
},
},
},
@@ -1762,6 +1964,7 @@ export const commands: Commands = {
description:
'The manifest ID of the web app: the resolved `id` member of its manifest. If `id` is omitted, it defaults to the resolved `start_url` (e.g. "https://example.com/"). See https://w3c.github.io/manifest/#id-member.',
required: true,
+ positional: true,
},
},
},
@@ -1774,6 +1977,7 @@ export const commands: Commands = {
type: 'number',
description: 'Targets a specific page by ID.',
required: true,
+ positional: true,
},
uid: {
name: 'uid',
@@ -1781,6 +1985,7 @@ export const commands: Commands = {
description:
'The uid of the file input element or an element that will open file chooser on the page from the page content snapshot',
required: true,
+ positional: true,
},
filePaths: {
name: 'filePaths',
@@ -1788,6 +1993,7 @@ export const commands: Commands = {
description:
'One or more files paths to upload. File paths have to be local to the browser instance (not the MCP).',
required: true,
+ positional: true,
},
includeSnapshot: {
name: 'includeSnapshot',
@@ -1795,6 +2001,7 @@ export const commands: Commands = {
description:
'Whether to include a snapshot in the response. Default is false.',
required: false,
+ positional: false,
},
},
},
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
index a5b09392..80c7a7be 100644
--- a/tests/cli.test.ts
+++ b/tests/cli.test.ts
@@ -14,7 +14,11 @@ import {
mcpOptions,
DEFAULT_FILESYSTEM_ROOT,
} from '../src/config/mcp-options.js';
-import {buildCommand} from '../src/config/cli-commands.js';
+import {
+ buildCommand,
+ getCommandArgSpec,
+ shieldLiteralArgs,
+} from '../src/config/cli-commands.js';
import {commands} from '../src/config/cli-options.js';
import {computeFlagUsage} from '../src/telemetry/flagUtils.js';
import {puppeteerOptions} from '../src/config/puppeteer-options.js';
@@ -1264,19 +1268,26 @@ describe('cli args parsing', () => {
});
describe('cli command strings', () => {
+ const required = {description: '', required: true, positional: true};
const dummyArgsVariadic = {
- arg1: {name: 'arg1', type: 'string', description: '', required: true},
- arrArg: {name: 'arrArg', type: 'array', description: '', required: true},
+ arg1: {name: 'arg1', type: 'string', ...required},
+ arrArg: {name: 'arrArg', type: 'array', ...required},
};
const dummyArgsPlain = {
- arg1: {name: 'arg1', type: 'string', description: '', required: true},
- arg2: {name: 'arg2', type: 'string', description: '', required: true},
+ arg1: {name: 'arg1', type: 'string', ...required},
+ arg2: {name: 'arg2', type: 'string', ...required},
};
const dummyArgsOptional = {
- arg1: {name: 'arg1', type: 'string', description: '', required: true},
- optArg: {name: 'optArg', type: 'boolean', description: '', required: false},
+ arg1: {name: 'arg1', type: 'string', ...required},
+ optArg: {
+ name: 'optArg',
+ type: 'boolean',
+ description: '',
+ required: false,
+ positional: false,
+ },
};
it('renders a required array arg as a variadic positional', () => {
@@ -1336,6 +1347,129 @@ describe('cli command strings', () => {
});
});
+describe('cli literal args', () => {
+ const getSpec = (name: string) =>
+ name in commands ? getCommandArgSpec(commands[name].args) : undefined;
+
+ function shield(argv: string[]) {
+ const {argv: shielded, restore} = shieldLiteralArgs(argv, getSpec);
+ return {
+ shielded,
+ restored: shielded.map(restore),
+ literalIndexes: shielded.flatMap((t, i) => (t !== argv[i] ? [i] : [])),
+ };
+ }
+
+ it('passes regular args through unchanged', () => {
+ const input = ['fill', '1', '1_1', 'a-b', '-5', '--output-format', 'json'];
+ assert.deepStrictEqual(shield(input).shielded, input);
+ });
+
+ it('shields a lone dash', () => {
+ const {shielded, restored} = shield(['fill', '1', '1_1', '-']);
+ assert.ok(!shielded[3].startsWith('-'));
+ assert.deepStrictEqual(restored, ['fill', '1', '1_1', '-']);
+ });
+
+ it('shields unknown dash tokens in unfilled positional slots', () => {
+ for (const value of ['--weird', '-abc', '- item', '--pageId=2']) {
+ const {shielded, restored} = shield(['fill', '1', '1_1', value]);
+ assert.ok(!shielded[3].startsWith('-'), value);
+ assert.deepStrictEqual(restored, ['fill', '1', '1_1', value]);
+ }
+ });
+
+ it('leaves unknown dash tokens alone once positionals are filled', () => {
+ const input = ['fill', '1', '1_1', 'x', '--pageid', '2'];
+ assert.deepStrictEqual(shield(input).shielded, input);
+ });
+
+ it('skips known options and their values', () => {
+ const input = [
+ '--sessionId',
+ 'abc',
+ 'click',
+ '--dblClick',
+ 'true',
+ '--output-format=json',
+ '1',
+ '1_1',
+ '--help',
+ ];
+ assert.deepStrictEqual(shield(input).shielded, input);
+
+ const {restored, literalIndexes} = shield([
+ 'evaluate_script',
+ '--pageId',
+ '1',
+ '--args',
+ 'a',
+ 'b',
+ '--weird',
+ ]);
+ assert.deepStrictEqual(literalIndexes, [6]);
+ assert.strictEqual(restored[6], '--weird');
+ });
+
+ it('accepts kebab-case and negated forms of known options', () => {
+ const input = ['click', '1', '1_1', '--dbl-click', '--no-dblClick'];
+ assert.deepStrictEqual(shield(input).shielded, input);
+ });
+
+ it('fills a variadic positional with any dash tokens', () => {
+ const {restored, literalIndexes} = shield([
+ 'upload_file',
+ '1',
+ '1_1',
+ '-',
+ '--a',
+ '-b',
+ ]);
+ assert.deepStrictEqual(literalIndexes, [3, 4, 5]);
+ assert.deepStrictEqual(restored, [
+ 'upload_file',
+ '1',
+ '1_1',
+ '-',
+ '--a',
+ '-b',
+ ]);
+ });
+
+ it('shields every token after -- and drops the separator', () => {
+ const {argv, restore} = shieldLiteralArgs(
+ ['fill', '1', '--', '--weird', '- item', '--', '-abc'],
+ getSpec,
+ );
+ assert.strictEqual(argv.length, 6);
+ assert.deepStrictEqual(argv.slice(0, 2), ['fill', '1']);
+ for (const token of argv.slice(2)) {
+ assert.ok(!token.startsWith('-'), `unexpected token ${token}`);
+ }
+ assert.deepStrictEqual(argv.slice(2).map(restore), [
+ '--weird',
+ '- item',
+ '--',
+ '-abc',
+ ]);
+ });
+
+ it('does not shield unknown flags of non-tool commands', () => {
+ const input = ['start', '--weird', 'status', '-x'];
+ assert.deepStrictEqual(shield(input).shielded, input);
+ });
+
+ it('restores values nested in arrays and leaves other values alone', () => {
+ const {argv, restore} = shieldLiteralArgs(
+ ['cmd', '--', '-a', '-b'],
+ getSpec,
+ );
+ assert.deepStrictEqual(restore([argv[1], argv[2], 'x']), ['-a', '-b', 'x']);
+ assert.strictEqual(restore(42), 42);
+ assert.strictEqual(restore(undefined), undefined);
+ });
+});
+
describe('flag usage telemetry', () => {
it('reports the stable channel for a default launch', async () => {
const usage = computeFlagUsage(parseConfig([]), mcpOptions);
diff --git a/tests/e2e/chrome-devtools-hyphen-positionals.test.ts b/tests/e2e/chrome-devtools-hyphen-positionals.test.ts
new file mode 100644
index 00000000..8190bef0
--- /dev/null
+++ b/tests/e2e/chrome-devtools-hyphen-positionals.test.ts
@@ -0,0 +1,147 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import crypto from 'node:crypto';
+import {describe, it, afterEach, beforeEach} from 'node:test';
+
+import {assertDaemonIsNotRunning, runCli} from '../utils.js';
+
+describe('chrome-devtools positional values starting with a hyphen', () => {
+ let sessionId: string;
+
+ beforeEach(async () => {
+ sessionId = crypto.randomUUID();
+ await runCli(['stop'], sessionId);
+ await assertDaemonIsNotRunning(sessionId);
+ });
+
+ afterEach(async () => {
+ await runCli(['stop'], sessionId);
+ await assertDaemonIsNotRunning(sessionId);
+ });
+
+ async function startDaemon(): Promise<void> {
+ const startResult = await runCli(['start'], sessionId);
+ assert.strictEqual(
+ startResult.status,
+ 0,
+ `start command failed: ${startResult.stderr}`,
+ );
+ }
+
+ /** Starts the daemon, opens a page with a textarea and returns its uid. */
+ async function startWithTextarea(): Promise<string> {
+ await startDaemon();
+
+ const navigateResult = await runCli(
+ [
+ 'navigate_page',
+ '1',
+ '--url',
+ 'data:text/html,<textarea id="t">x</textarea>',
+ ],
+ sessionId,
+ );
+ assert.strictEqual(
+ navigateResult.status,
+ 0,
+ `navigate_page command failed: ${navigateResult.stderr}`,
+ );
+
+ const snapshotResult = await runCli(['take_snapshot', '1'], sessionId);
+ assert.strictEqual(
+ snapshotResult.status,
+ 0,
+ `take_snapshot command failed: ${snapshotResult.stderr}`,
+ );
+ const uidMatch = snapshotResult.stdout.match(/uid=(\S+) textbox/);
+ assert.ok(
+ uidMatch,
+ 'textarea uid not found in snapshot: ' + snapshotResult.stdout,
+ );
+ return uidMatch[1];
+ }
+
+ async function readTextareaValue(): Promise<string> {
+ const result = await runCli(
+ [
+ 'evaluate_script',
+ '() => document.getElementById("t").value',
+ '--pageId',
+ '1',
+ ],
+ sessionId,
+ );
+ assert.strictEqual(
+ result.status,
+ 0,
+ `evaluate_script command failed: ${result.stderr}`,
+ );
+ const match = result.stdout.match(/"(.*)"/);
+ assert.ok(match, 'unexpected evaluate_script output: ' + result.stdout);
+ return JSON.parse(`"${match[1]}"`);
+ }
+
+ const fillCases: Array<{value: string[]; expected: string}> = [
+ {value: ['-'], expected: '-'},
+ {value: ['-5'], expected: '-5'},
+ {value: ['a-b'], expected: 'a-b'},
+ {value: ['--weird'], expected: '--weird'},
+ {value: ['- item'], expected: '- item'},
+ {value: ['-abc'], expected: '-abc'},
+ {value: ['--', '--weird'], expected: '--weird'},
+ ];
+ for (const {value, expected} of fillCases) {
+ it(`fill passes ${JSON.stringify(value.join(' '))} through`, async () => {
+ const uid = await startWithTextarea();
+
+ const args = ['fill', '1', uid, ...value];
+ const result = await runCli(args, sessionId);
+ assert.strictEqual(
+ result.status,
+ 0,
+ `${args.join(' ')} failed: ${result.stderr}`,
+ );
+ assert.strictEqual(await readTextareaValue(), expected);
+ });
+ }
+
+ it('type_text passes a lone hyphen through', async () => {
+ await startDaemon();
+
+ const result = await runCli(['type_text', '1', '-'], sessionId);
+ assert.strictEqual(
+ result.status,
+ 0,
+ `type_text command failed: ${result.stderr}`,
+ );
+ assert.match(result.stdout, /Typed text "-"/);
+ });
+
+ it('press_key passes a lone hyphen through', async () => {
+ await startDaemon();
+
+ const result = await runCli(['press_key', '1', '-'], sessionId);
+ assert.strictEqual(
+ result.status,
+ 0,
+ `press_key command failed: ${result.stderr}`,
+ );
+ assert.match(result.stdout, /Successfully pressed key: -/);
+ });
+
+ it('rejects unknown flags that are not preceded by --', async () => {
+ await startDaemon();
+
+ const result = await runCli(
+ ['fill', '1', 'x', 'x', '--pageid', '2'],
+ sessionId,
+ );
+ assert.strictEqual(result.status, 1);
+ assert.match(result.stderr, /Unknown arguments?: .*pageid/);
+ });
+});
diff --git a/tests/utils.ts b/tests/utils.ts
index 3ea02db3..e9c93377 100644
--- a/tests/utils.ts
+++ b/tests/utils.ts
@@ -438,7 +438,8 @@ export async function runCli(
return await new Promise((resolve, reject) => {
const finalArgs = [...args];
if (sessionId) {
- finalArgs.push('--sessionId', sessionId);
+ // Prepend so that the flag is not swallowed by a trailing `--`.
+ finalArgs.unshift('--sessionId', sessionId);
}
const child = spawn('node', [CLI_PATH, ...finalArgs], {
env: process.env,