jackwener/OpenCLI · error

<session> is a required positional argument: opencli browser

Error message

<session> is a required positional argument: opencli browser <session> <command>

What it means

The `opencli browser` command group requires a session name positional: `opencli browser <session> <command>`. main.ts rewrites argv to insert `--session <name>` before commander parses; this helper throws when that flag is absent or empty/whitespace. It guarantees every browser subcommand operates on an identified session.

Source

Thrown at src/cli.ts:680

}

function getCommandOption(command: Command | undefined, option: string): unknown {
  let current: Command | undefined = command;
  while (current) {
    const opts = current.opts();
    if (Object.prototype.hasOwnProperty.call(opts, option) && opts[option] !== undefined) return opts[option];
    current = current.parent as Command | undefined;
  }
  return undefined;
}

function getBrowserSession(command?: Command): string {
  // The CLI surface is `opencli browser <session> <subcommand>`. main.ts rewrites
  // argv to insert `--session <name>` before commander parses it; this helper
  // reads back the rewritten flag.
  const raw = getCommandOption(command, 'session');
  if (typeof raw === 'string' && raw.trim()) return raw.trim();
  throw new Error('<session> is a required positional argument: opencli browser <session> <command>');
}

function getBrowserProfileSelection(command?: Command): ProfileSelection | undefined {
  const raw = getCommandOption(command, 'profile');
  return resolveProfileSelection(typeof raw === 'string' && raw.trim() ? raw.trim() : undefined);
}

function getPageSession(page: import('./types.js').IPage): string {
  const session = (page as unknown as { session?: unknown }).session;
  if (typeof session === 'string' && session.trim()) return session.trim();
  throw new Error('Browser page is missing a session');
}

function getPageScope(page: import('./types.js').IPage): string {
  // Scope is keyed by the SELECTED profile (explicit or preferred), matching
  // getBrowserPage's targetScope — reading only the explicit contextId would
  // save and look up the remembered tab under different keys whenever the
  // profile came from the config default.

View on GitHub (pinned to 49907e53dc)

Solutions

1. Add the session positional: opencli browser <session> tab list
2. Verify the session name is non-empty (quotes around it in shell scripts)
3. Check how main.ts rewrites argv if invoking programmatically — ensure the session positional is present in raw argv
4. Run opencli browser --help to confirm the required positional syntax

Example fix

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

const args = ['browser', session, 'tab', 'list'];
if (!session || !session.trim()) throw new Error('browser commands require a non-empty <session> positional');

function hasSession(s: unknown): s is string {
  return typeof s === 'string' && s.trim().length > 0;
}

try {
  await run(['opencli', 'browser', session, 'tab', 'list']);
} catch (e) {
  if (String((e as Error).message).includes('required positional argument')) {
    console.error('Usage: opencli browser <session> <command>');
  }
  throw e;
}

When it happens

Trigger: Invoking a browser subcommand without the session positional, e.g. `opencli browser tab list` instead of `opencli browser mysession tab list`, or passing an empty/whitespace-only session value.

Common situations: Copy-pasted commands that dropped the session argument; scripting wrappers that build argv dynamically and skip an empty session; users of older CLI versions where session was optional.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• keyword must not be empty
• <from> station must not be empty
• <to> station must not be empty
• who 不能为空
• key is required

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