jackwener/OpenCLI · error · ArgumentError

key required

Error message

key required

What it means

An ArgumentError thrown by the state-get command when the --key argument is missing, empty, or whitespace-only after trimming. The command cannot look up a value without a key, so it fails fast before touching the DB.

Source

Thrown at clis/trae-solo/state-fs.js:97

// -------- state-get --------
cli({
    site: 'trae-solo',
    name: 'state-get',
    access: 'read',
    description: 'Read a single key from Trae SOLO\'s globalStorage state.vscdb. Pass --workspace <ws-id> to query a per-workspace DB instead. Returns parsed JSON if the value is JSON.',
    domain: 'localhost',
    browser: false,
    strategy: Strategy.LOCAL,
    args: [
        { name: 'key', positional: true, required: true, help: 'State key (use state-keys to discover)' },
        { name: 'workspace', required: false, help: 'Workspace id (from workspaces-list) to query a per-workspace DB' },
        { name: 'max-bytes', type: 'int', required: false, default: 8000, help: 'Truncate value to this many bytes' },
    ],
    columns: ['Field', 'Value'],
    func: async (args) => {
        const key = String(args.key || '').trim();
        if (!key) throw new ArgumentError('key required');
        const db = resolveStateDb(args);
        const val = getValue(db, key);
        if (val === null) {
            throw new CommandExecutionError(`Key not found: ${key}`, 'List available keys with `opencli trae-solo state-keys`.');
        }
        const max = Number.isInteger(args['max-bytes']) && args['max-bytes'] > 0 ? args['max-bytes'] : 8000;
        const valStr = typeof val === 'string' ? val : JSON.stringify(val, null, 2);
        const truncated = valStr.length > max;
        return [
            { Field: 'Key', Value: key },
            { Field: 'Type', Value: typeof val === 'string' ? 'string' : (Array.isArray(val) ? 'array' : typeof val) },
            { Field: 'Size', Value: `${valStr.length} chars${truncated ? ' (truncated)' : ''}` },
            { Field: 'Value', Value: truncated ? valStr.slice(0, max) + '\n...(truncated, use --max-bytes to read more)' : valStr },
        ];
    },
});

// -------- recent-workspaces --------

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a non-empty --key <name> on the command line.
2. Run state-keys first to copy an exact key name.
3. In scripts, guard: [ -n "$KEY" ] || exit 1 before invoking.

Example fix

// before
KEY=""; opencli trae-solo state-get --key "$KEY"
// after
KEY="history.recentlyOpenedPathsList"; [ -n "$KEY" ] && opencli trae-solo state-get --key "$KEY"

const key = String(process.argv.key || '').trim();
if (!key) { console.error('usage: state-get --key <name>'); process.exit(2); }

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

try {
  await stateGet(args);
} catch (e) {
  if (/^key required$/.test(e.message)) { console.error('Provide --key <name>; see state-keys'); }
  throw e;
}

When it happens

Trigger: Invoking state-get without --key, with --key "", or with only spaces; scripting the CLI where a variable holding the key expanded to empty.

Common situations: Shell variable unset ($KEY empty); quoting mistake drops the argument; copying a command template without filling the placeholder.

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/f0a86641ee636cbb. Report an issue: GitHub.