{"record":{"id":"e7edd9e4a1fa4d46","repo":"openai/codex-plugin-cc","slug":"usage-node-scripts-app-server-broker-mjs-serve","errorCode":null,"errorMessage":"Usage: node scripts/app-server-broker.mjs serve --endpoint <value> [--cwd <path>] [--pid-file <path>]","messagePattern":"Usage: node scripts/app-server-broker\\.mjs serve --endpoint <value> \\[--cwd <path>\\] \\[--pid-file <path>\\]","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugins/codex/scripts/app-server-broker.mjs","lineNumber":51,"sourceCode":"  socket.write(`${JSON.stringify(message)}\\n`);\n}\n\nfunction isInterruptRequest(message) {\n  return message?.method === \"turn/interrupt\";\n}\n\nfunction writePidFile(pidFile) {\n  if (!pidFile) {\n    return;\n  }\n  fs.mkdirSync(path.dirname(pidFile), { recursive: true });\n  fs.writeFileSync(pidFile, `${process.pid}\\n`, \"utf8\");\n}\n\nasync function main() {\n  const [subcommand, ...argv] = process.argv.slice(2);\n  if (subcommand !== \"serve\") {\n    throw new Error(\"Usage: node scripts/app-server-broker.mjs serve --endpoint <value> [--cwd <path>] [--pid-file <path>]\");\n  }\n\n  const { options } = parseArgs(argv, {\n    valueOptions: [\"cwd\", \"pid-file\", \"endpoint\"]\n  });\n\n  if (!options.endpoint) {\n    throw new Error(\"Missing required --endpoint.\");\n  }\n\n  const cwd = options.cwd ? path.resolve(process.cwd(), options.cwd) : process.cwd();\n  const endpoint = String(options.endpoint);\n  const listenTarget = parseBrokerEndpoint(endpoint);\n  const pidFile = options[\"pid-file\"] ? path.resolve(options[\"pid-file\"]) : null;\n  writePidFile(pidFile);\n\n  const appClient = await CodexAppServerClient.connect(cwd, { disableBroker: true });\n  let activeRequestSocket = null;","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/openai/codex-plugin-cc/blob/db52e28f4d9ded852ab3942cea316258ae4ef346/plugins/codex/scripts/app-server-broker.mjs#L33-L69","documentation":"The app-server-broker.mjs script accepts exactly one subcommand, 'serve', as its first positional argument. If process.argv[2] is anything else (including undefined), the script throws this usage error and exits non-zero via the top-level main().catch handler. This is a hard CLI contract enforcement, not a recoverable runtime condition.","triggerScenarios":"Running `node scripts/app-server-broker.mjs` with no arguments, with a typo'd subcommand like `start`, or with flags before the subcommand so parseArgs consumes 'serve'. The check is `subcommand !== 'serve'` so any other string (e.g. 'server', '--help') triggers it.","commonSituations":"Manual invocation for debugging where the developer forgets 'serve', copy-paste from docs that omit the subcommand, or an orchestration wrapper that passes flags in the wrong position so argv[2] is a flag instead of the literal 'serve'.","solutions":["Always invoke as: node scripts/app-server-broker.mjs serve --endpoint <value>","If calling from a wrapper, ensure 'serve' is the first element after the script path, before any flags.","Run with no args to reproduce, then add 'serve' as the explicit first positional."],"exampleFix":"// before\nnode scripts/app-server-broker.mjs --endpoint unix:///tmp/broker.sock\n// after\nnode scripts/app-server-broker.mjs serve --endpoint unix:///tmp/broker.sock","handlingStrategy":"validation","validationCode":"const sub = process.argv[2];\nif (sub !== 'serve') {\n  console.error('First arg must be \"serve\".');\n  process.exit(2);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Wrap broker invocation in a shell function that always inserts 'serve'.","Assert process.argv[2] === 'serve' at the top of any caller script."],"tags":["cli","usage","broker","argv"],"backgroundTag":null,"analyzedSha":"db52e28f4d9ded852ab3942cea316258ae4ef346","analyzedAt":"2026-08-13T05:13:20.855Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}