koala73/worldmonitor · error · UsageError

`${command}` needs <${a.name}>. Usage: worldmonitor ${comman

Error message

`${command}` needs <${a.name}>. Usage: worldmonitor ${command} <${a.name}>

What it means

Curated convenience commands declare an ordered list of positional args. After binding positionals and --key value flags, every arg marked required must be present; the first missing one raises this UsageError naming the command and the missing placeholder (exit code 2).

Source

Thrown at cli/src/core.mjs:297

      throw new UsageError(
        '`call` needs a tool name, e.g. `worldmonitor call get_country_risk --country_code IR`',
      );
    }
    return mcpPlan('tools/call', { name: tool, arguments: collectArgs(parsed) }, options, config, {
      needsKey: true,
    });
  }

  if (Object.hasOwn(CURATED_COMMANDS, command)) {
    const spec = CURATED_COMMANDS[command];
    const args = {};
    for (const [k, v] of Object.entries(params)) args[k] = v === true ? true : String(v);
    spec.args.forEach((a, idx) => {
      if (positionals[idx] !== undefined) args[a.name] = positionals[idx];
    });
    for (const a of spec.args) {
      if (a.required && args[a.name] === undefined) {
        throw new UsageError(`\`${command}\` needs <${a.name}>. Usage: worldmonitor ${command} <${a.name}>`);
      }
    }
    return mcpPlan('tools/call', { name: spec.tool, arguments: args }, options, config, {
      needsKey: true,
    });
  }

  throw new UsageError(`Unknown command: ${command || '(none)'}. Run \`worldmonitor --help\`.`);
}

export function formatOutput(value, options = {}) {
  if (options.raw && typeof value === 'string') return value;
  if (options.compact) return JSON.stringify(value);
  return JSON.stringify(value, null, 2);
}

// Flatten an OpenAPI document into printable operation rows, optionally scoped
// to one service (the first path segment after /api/).

View on GitHub (pinned to eeab0a219f)

Solutions

1. Run `worldmonitor --help` to see each curated command's positional argument order
2. Supply the required positional exactly: worldmonitor <command> <value>
3. In scripts, guard empty variables before invoking: [ -n "$CC" ] || { echo 'missing CC'; exit 1; }

Example fix

# before
CC=''
worldmonitor country-risk "$CC" 2>/dev/null || worldmonitor country-risk
# UsageError: `country-risk` needs <country_code>. Usage: worldmonitor country-risk <country_code>

# after — validate inputs, then pass the required positional
[ -n "$CC" ] || exit 1
worldmonitor country-risk "$CC"

// Fill every required positional before invoking a curated command
const spec = CURATED[command];            // e.g. { args: [{ name: 'country_code', required: true }] }
const missing = spec.args.filter((a) => a.required && values[a.name] == null).map((a) => a.name);
if (missing.length) throw new Error(`${command}: missing ${missing.join(', ')}`);

When it happens

Trigger: Invoking a curated command with no or too few positionals; passing the required value as a flag with a different name; an empty-string positional or unset shell variable leaving args[name] undefined.

Common situations: Running curated commands from memory without checking --help; scripted invocations where a variable expanded to empty.

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

• `get` needs an API path, e.g. `worldmonitor get /api/health`
• `call` needs a tool name, e.g. `worldmonitor call get_countr
• --args must be valid JSON: ${err.message}
• Unknown command: ${command || '(none)'}. Run `worldmonitor -
• global fetch is unavailable — Node 18+ is required

AI-assisted analysis of koala73/worldmonitor@eeab0a219f (2026-08-21). Data as JSON: /api/errors/281f525bd31c70e8. Report an issue: GitHub.