What causes "query is required" in jackwener/OpenCLI?

Pass a non-empty query string, e.g. niko

jackwener/OpenCLI · error · ArgumentError

query is required

Error message

query is required

What it means

The hltv search command requires a non-empty positional 'query'. After trimming, an empty/missing query throws this ArgumentError before any navigation happens. It is an input-validation error, not a scrape failure.

Source

Thrown at clis/hltv/search.js:24

cli({
  site: 'hltv',
  name: 'search',
  description: 'Search HLTV players, teams, events, and articles',
  access: 'read',
  example: 'opencli hltv search niko --limit 10 -f json',
  domain: 'www.hltv.org',
  strategy: Strategy.UI,
  browser: true,
  navigateBefore: false,
  args: [
    { name: 'query', type: 'string', positional: true, required: true, help: 'Search keyword, e.g. niko' },
    { name: 'limit', type: 'int', default: 10, help: 'Maximum rows per result type (max 50)' },
  ],
  columns: ['rank', 'type', 'id', 'name', 'title', 'date', 'author', 'url'],
  func: async (page, args) => {
    const query = String(args.query ?? '').trim();
    if (!query) throw new ArgumentError('query is required');
    const limit = normalizeLimit(args.limit, 10, 50);
    const url = new URL('/search', BASE);
    url.searchParams.set('query', query);

    await gotoAndWait(page, url, 'table', 'hltv search page');

    const rows = await page.evaluate((payload) => {
      const clean = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
      const absolutize = (value) => (value ? new URL(value, payload.base).toString() : null);
      const extractId = (value, kind) => {
        if (!value) return null;
        const path = new URL(value, payload.base).pathname;
        const patterns = {
          player: /^\/player\/(\d+)\//,
          team: /^\/team\/(\d+)\//,
          event: /^\/events\/(\d+)\//,
          article: /^\/news\/(\d+)\//,
        };

View on GitHub (pinned to 49907e53dc)

Solutions

Pass a non-empty query string, e.g. niko
Trim and check the query before invoking the command
Ensure the args object actually contains the query key
Show CLI usage/help when the positional argument is absent

Example fix

// before
await run('search', { query: userInput, limit: 10 }); // userInput may be ''
// after
const query = String(userInput ?? '').trim();
if (!query) throw new Error('search query must be non-empty');
await run('search', { query, limit: 10 });

Defensive patterns

Strategy: validation

Validate before calling

const query = String(args.query ?? '').trim();
if (!query) throw new Error('query is required before calling search');

Type guard

function hasQuery(args) { return typeof args.query === 'string' && args.query.trim().length > 0; }

Try / catch

try {
  await searchCommand(page, args);
} catch (err) {
  if (err instanceof ArgumentError && /query is required/.test(err.message)) return printUsage();
  throw err;
}

Prevention

Always pass the positional query explicitly
Trim user input and reject empty strings at the CLI boundary
Add a usage/help message when required args are missing
Never build args objects dynamically without checking required keys

When it happens

Trigger: Invoking the search command without the positional query, or with query='' or whitespace-only; programmatically calling with args.query undefined or null.

Common situations: Script builds args dynamically and query ends up undefined; CLI call missing the positional argument; user pastes only spaces; wiring bug drops the query field from the args object.

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

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