jackwener/OpenCLI · error · ArgumentError

key is required

Error message

key is required

What it means

storage-get requires a non-empty positional --key argument naming the storage entry to read. The command trims the value and throws ArgumentError when it is empty or whitespace. Unlike the CLI's declared 'required: true', the func defensively re-validates because empty strings can slip through argument parsing.

Source

Thrown at clis/antigravity/storage.js:129

// ====== Renderer-side: storage-get ======
cli({
    site: 'antigravity',
    name: 'storage-get',
    access: 'read',
    description: 'Read a single localStorage / sessionStorage value on the Antigravity renderer.',
    domain: '127.0.0.1',
    strategy: Strategy.UI,
    browser: true,
    args: [
        { name: 'key', positional: true, required: true, help: 'Storage key name' },
        { name: 'storage', required: false, default: 'local', help: '"local" or "session"' },
        { name: 'max-bytes', type: 'int', required: false, default: 4000, help: 'Truncate value to this many chars' },
    ],
    columns: STORAGE_COLUMNS,
    func: async (page, kwargs) => {
        const key = String(kwargs?.key || '').trim();
        if (!key) throw new ArgumentError('key', 'is required');
        const s = String(kwargs?.storage || 'local').trim().toLowerCase();
        const store = s === 'session' ? 'sessionStorage' : 'localStorage';
        const raw = unwrapEvaluateResult(await page.evaluate(`${store}.getItem(${JSON.stringify(key)})`));
        if (raw === null) throw new CommandExecutionError(`Key not found in ${store}: ${key}`, '');
        const max = Number.isInteger(kwargs['max-bytes']) && kwargs['max-bytes'] > 0 ? kwargs['max-bytes'] : 4000;
        let parsed = raw, kind = 'string';
        try { parsed = JSON.parse(raw); kind = Array.isArray(parsed) ? 'array' : typeof parsed; } catch {}
        const text = kind === 'string' ? parsed : JSON.stringify(parsed, null, 2);
        const truncated = text.length > max;
        return [
            { Field: 'Key', Value: key },
            { Field: 'Store', Value: store },
            { Field: 'Type', Value: kind },
            { Field: 'Size', Value: `${text.length} chars${truncated ? ' (truncated)' : ''}` },
            { Field: 'Value', Value: truncated ? text.slice(0, max) + '\n...(truncated)' : text },
        ];
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass the key as a positional argument: `opencli antigravity storage-get my.key`.
2. Quote keys containing spaces or dots in your shell.
3. Verify the variable holding the key is non-empty before invoking.
4. Use storage-keys first to confirm the exact key name.

Example fix

// before
opencli antigravity storage-get --key "$KEY"   # KEY empty
// after
: "${KEY:?KEY must be set}"
opencli antigravity storage-get "$KEY"

const key = process.argv[2];
if (typeof key !== 'string' || !key.trim()) throw new Error('storage-get requires a non-empty key, e.g. opencli antigravity storage-get my.key');

function hasKey(args) {
  return typeof args?.key === 'string' && args.key.trim().length > 0;
}

try {
  execSync(`opencli antigravity storage-get ${JSON.stringify(key)}`);
} catch (e) {
  if (/key is required/.test(e.message)) {
    console.error('Pass the key positionally: storage-get <key>');
  } else throw e;
}

When it happens

Trigger: Calling `opencli antigravity storage-get` with no positional key, `--key ''`, `--key ' '`, or invoking the underlying func programmatically with kwargs lacking a key field.

Common situations: Shell variables that expand to empty ($KEY unset), copy/paste losing the key token, or wrapping scripts that drop positional args when forwarding options.

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 不能为空
• storage must be "local" or "session"

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