jackwener/OpenCLI · error · BrowserSessionArgvError

The `--session` flag is no longer a public option. Use the p

Error message

The `--session` flag is no longer a public option. Use the positional form: opencli browser <session> <command>

What it means

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.

Source

Thrown at src/cli-argv-preprocess.ts:111

    if (!tok.startsWith('-')) break;
    // `--flag=value` consumes one slot regardless of whether the flag expects a value.
    if (tok.includes('=')) {
      i += 1;
      continue;
    }
    if (ROOT_VALUE_FLAGS.has(tok) && i + 1 < result.length) {
      i += 2;
    } else {
      i += 1;
    }
  }
  if (result[i] !== 'browser') return result;
  const sessionIdx = i + 1;
  const next = result[sessionIdx];
  if (next === undefined) return result;
  // The retired `--session` flag must not be a working public entrance.
  if (next === '--session' || next === '--session=' || next.startsWith('--session=')) {
    throw new BrowserSessionArgvError(
      'The `--session` flag is no longer a public option. Use the positional form: opencli browser <session> <command>',
    );
  }
  if (next.startsWith('-')) return result;
  if (BROWSER_SUBCOMMAND_NAMES.has(next)) return result;
  // Splice in --session <name> in place of the positional.
  result.splice(sessionIdx, 1, '--session', next);
  // `--window` is a browser namespace option, so commander accepts it before the
  // leaf command. Users naturally put it at the end:
  // `browser work open https://x.com --window background`. Hoist that public
  // form into the namespace-option slot instead of mirroring the option onto
  // every browser leaf command.
  hoistBrowserWindowOption(result, sessionIdx + 2);
  return result;
}

/**
 * Move one trailing `--window <mode>` / `--window=<mode>` from after the browser

View on GitHub (pinned to 49907e53dc)

Solutions

1. Use the positional form: `opencli browser <session> <command>` (drop the --session flag).
2. Update CI scripts and aliases to the new syntax.
3. Run `opencli browser --help` to confirm the current argument layout.

Example fix

// before
opencli browser --session main tab list
// after
opencli browser main tab list

function assertNoSessionFlag(argv) {
  if (argv[0] === 'browser' && argv[1]?.startsWith('--session')) {
    throw new Error('use positional form: opencli browser <session> <command>');
  }
  return argv;
}

const usesPositionalSession = (argv: string[]): boolean =>
  argv[0] === 'browser' && argv.length > 1 && !argv[1].startsWith('-');

try {
  const argv = rewriteBrowserArgv(process.argv.slice(2));
} catch (err) {
  if (err instanceof BrowserSessionArgvError) {
    console.error(err.message);
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Not a git repository
• Working tree not clean: ${status}
• Stale .git/index.lock found — remove it first
• 12306 whoami failed: ${probe.detail}
• <train-no> "${trainNo}" does not look like a 12306 internal

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/2612e634bda501e3. Report an issue: GitHub.