jackwener/OpenCLI · error · ArgumentError

twitter tweets --page-delay must be an integer between 0 and

Error message

twitter tweets --page-delay must be an integer between 0 and 60 seconds

What it means

normalizePageDelaySeconds in clis/twitter/tweets.js:98 validates the --page-delay flag, defaulting to DEFAULT_PAGE_DELAY_SECONDS. It must be an integer between 0 and 60 (seconds of wait between paginated UserTweets fetches); otherwise ArgumentError is thrown. The delay throttles requests so scraping does not trip x.com rate limits.

Source

Thrown at clis/twitter/tweets.js:98

    visit(instructions);
    return { tweets, nextCursor };
}

function normalizeLimit(rawLimit) {
    const limit = rawLimit ?? 20;
    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_TWEETS_LIMIT) {
        throw new ArgumentError(
            `twitter tweets --limit must be an integer between 1 and ${MAX_TWEETS_LIMIT}`,
            'Example: opencli twitter tweets @jack --limit 250',
        );
    }
    return limit;
}

function normalizePageDelaySeconds(rawDelay) {
    const delay = rawDelay ?? DEFAULT_PAGE_DELAY_SECONDS;
    if (!Number.isInteger(delay) || delay < 0 || delay > 60) {
        throw new ArgumentError(
            'twitter tweets --page-delay must be an integer between 0 and 60 seconds',
            'Example: opencli twitter tweets @jack --limit 250 --page-delay 2',
        );
    }
    return delay;
}

cli({
    site: 'twitter',
    name: 'tweets',
    access: 'read',
    description: "Fetch a Twitter user's most recent tweets (chronological, excludes pinned; defaults to the logged-in user when no username is given)",
    domain: 'x.com',
    strategy: Strategy.COOKIE,
    browser: true,
    args: [
        { name: 'username', type: 'string', positional: true, help: 'Twitter screen name (with or without @). Defaults to the logged-in user when omitted.' },
        { name: 'limit', type: 'int', default: 20, help: `Max tweets to return (1-${MAX_TWEETS_LIMIT}; fetched across cursor pages)` },

View on GitHub (pinned to 49907e53dc)

Solutions

Pass an integer number of seconds from 0 to 60, e.g. --page-delay 2
Clamp computed values: Math.min(60, Math.max(0, Math.round(raw))) before invoking
If you need longer waits, run multiple invocations or add sleep between separate CLI calls rather than exceeding the cap
Remember 0 is valid (no delay) if you intentionally want fastest (riskier) fetching

Example fix

// before
opencli twitter tweets @jack --page-delay 1.5
// after
opencli twitter tweets @jack --page-delay 2

Defensive patterns

Strategy: validation

Validate before calling

function assertPageDelay(v) {
  const n = Number(v);
  if (!Number.isInteger(n) || n < 0 || n > 60) {
    throw new Error('--page-delay must be an integer 0..60 seconds');
  }
  return n;
}

Type guard

function isValidPageDelay(v) {
  return Number.isInteger(v) && v >= 0 && v <= 60;
}

Try / catch

import { ArgumentError } from '@jackwener/opencli/errors';
try {
  await run(['twitter', 'tweets', '@jack', '--page-delay', String(delay)]);
} catch (e) {
  if (e instanceof ArgumentError && e.message.includes('--page-delay')) {
    console.error('Use integer seconds 0..60; clamp longer waits outside the CLI.');
    process.exitCode = 2;
  } else throw e;
}

Prevention

Round computed delays with Math.round and clamp to 0..60 before invoking
Don't pass milliseconds — the flag is seconds
For waits over 60s, sleep between separate CLI invocations instead
Document defaults in wrapper scripts so operators don't guess bounds

When it happens

Trigger: Calling `opencli twitter tweets <user> --page-delay <n>` with a non-integer (e.g. 1.5), a negative number, or a value above 60 seconds.

Common situations: Scripts computing the delay from averages (producing floats); users trying --page-delay 120 to be polite, unaware of the 60s cap; unit confusion (passing milliseconds like 2000); copied config from older versions with different bounds.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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