{"record":{"id":"2612e634bda501e3","repo":"jackwener/OpenCLI","slug":"the-session-flag-is-no-longer-a-public-option","errorCode":null,"errorMessage":"The `--session` flag is no longer a public option. Use the positional form: opencli browser <session> <command>","messagePattern":"The `--session` flag is no longer a public option\\. Use the positional form: opencli browser <session> <command>","errorType":"exception","errorClass":"BrowserSessionArgvError","httpStatus":null,"severity":"error","filePath":"src/cli-argv-preprocess.ts","lineNumber":111,"sourceCode":"    if (!tok.startsWith('-')) break;\n    // `--flag=value` consumes one slot regardless of whether the flag expects a value.\n    if (tok.includes('=')) {\n      i += 1;\n      continue;\n    }\n    if (ROOT_VALUE_FLAGS.has(tok) && i + 1 < result.length) {\n      i += 2;\n    } else {\n      i += 1;\n    }\n  }\n  if (result[i] !== 'browser') return result;\n  const sessionIdx = i + 1;\n  const next = result[sessionIdx];\n  if (next === undefined) return result;\n  // The retired `--session` flag must not be a working public entrance.\n  if (next === '--session' || next === '--session=' || next.startsWith('--session=')) {\n    throw new BrowserSessionArgvError(\n      'The `--session` flag is no longer a public option. Use the positional form: opencli browser <session> <command>',\n    );\n  }\n  if (next.startsWith('-')) return result;\n  if (BROWSER_SUBCOMMAND_NAMES.has(next)) return result;\n  // Splice in --session <name> in place of the positional.\n  result.splice(sessionIdx, 1, '--session', next);\n  // `--window` is a browser namespace option, so commander accepts it before the\n  // leaf command. Users naturally put it at the end:\n  // `browser work open https://x.com --window background`. Hoist that public\n  // form into the namespace-option slot instead of mirroring the option onto\n  // every browser leaf command.\n  hoistBrowserWindowOption(result, sessionIdx + 2);\n  return result;\n}\n\n/**\n * Move one trailing `--window <mode>` / `--window=<mode>` from after the browser","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/cli-argv-preprocess.ts#L93-L129","documentation":"rewriteBrowserArgv rewrites positional session names into --session flags for `opencli browser` commands. The --session flag itself was retired as a public entrance, so if the user types --session explicitly it throws BrowserSessionArgvError directing them to the positional form. This ensures the old flag is never silently accepted.","triggerScenarios":"Running `opencli browser --session <name> <command>` or `opencli browser --session=<name> <command>` — any argv where the token after `browser` is --session in bare, `=`, or prefixed form.","commonSituations":"Older scripts or docs written before the CLI changed to positional sessions; muscle memory from other tools; CI configs pinned to the old syntax after a CLI upgrade.","solutions":["Use the positional form: `opencli browser <session> <command>` (drop the --session flag).","Update CI scripts and aliases to the new syntax.","Run `opencli browser --help` to confirm the current argument layout."],"exampleFix":"// before\nopencli browser --session main tab list\n// after\nopencli browser main tab list","handlingStrategy":"validation","validationCode":"function assertNoSessionFlag(argv) {\n  if (argv[0] === 'browser' && argv[1]?.startsWith('--session')) {\n    throw new Error('use positional form: opencli browser <session> <command>');\n  }\n  return argv;\n}","typeGuard":"const usesPositionalSession = (argv: string[]): boolean =>\n  argv[0] === 'browser' && argv.length > 1 && !argv[1].startsWith('-');","tryCatchPattern":"try {\n  const argv = rewriteBrowserArgv(process.argv.slice(2));\n} catch (err) {\n  if (err instanceof BrowserSessionArgvError) {\n    console.error(err.message);\n    process.exit(2);\n  }\n  throw err;\n}","preventionTips":["Update legacy scripts and CI configs to the positional session syntax.","Alias the old invocation if you must (alias ob='opencli browser main').","Search codebases/docs for '--session' before upgrading the CLI.","Run `opencli browser --help` after upgrades to see current syntax."],"tags":["cli","api-misuse","breaking-change","argv"],"backgroundTag":"deprecated-flag-removed","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}