{"record":{"id":"f0a86641ee636cbb","repo":"jackwener/OpenCLI","slug":"key-required","errorCode":null,"errorMessage":"key required","messagePattern":"key required","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/trae-solo/state-fs.js","lineNumber":97,"sourceCode":"\n// -------- state-get --------\ncli({\n    site: 'trae-solo',\n    name: 'state-get',\n    access: 'read',\n    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.',\n    domain: 'localhost',\n    browser: false,\n    strategy: Strategy.LOCAL,\n    args: [\n        { name: 'key', positional: true, required: true, help: 'State key (use state-keys to discover)' },\n        { name: 'workspace', required: false, help: 'Workspace id (from workspaces-list) to query a per-workspace DB' },\n        { name: 'max-bytes', type: 'int', required: false, default: 8000, help: 'Truncate value to this many bytes' },\n    ],\n    columns: ['Field', 'Value'],\n    func: async (args) => {\n        const key = String(args.key || '').trim();\n        if (!key) throw new ArgumentError('key required');\n        const db = resolveStateDb(args);\n        const val = getValue(db, key);\n        if (val === null) {\n            throw new CommandExecutionError(`Key not found: ${key}`, 'List available keys with `opencli trae-solo state-keys`.');\n        }\n        const max = Number.isInteger(args['max-bytes']) && args['max-bytes'] > 0 ? args['max-bytes'] : 8000;\n        const valStr = typeof val === 'string' ? val : JSON.stringify(val, null, 2);\n        const truncated = valStr.length > max;\n        return [\n            { Field: 'Key', Value: key },\n            { Field: 'Type', Value: typeof val === 'string' ? 'string' : (Array.isArray(val) ? 'array' : typeof val) },\n            { Field: 'Size', Value: `${valStr.length} chars${truncated ? ' (truncated)' : ''}` },\n            { Field: 'Value', Value: truncated ? valStr.slice(0, max) + '\\n...(truncated, use --max-bytes to read more)' : valStr },\n        ];\n    },\n});\n\n// -------- recent-workspaces --------","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/trae-solo/state-fs.js#L79-L115","documentation":"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.","triggerScenarios":"Invoking state-get without --key, with --key \"\", or with only spaces; scripting the CLI where a variable holding the key expanded to empty.","commonSituations":"Shell variable unset ($KEY empty); quoting mistake drops the argument; copying a command template without filling the placeholder.","solutions":["Pass a non-empty --key <name> on the command line.","Run state-keys first to copy an exact key name.","In scripts, guard: [ -n \"$KEY\" ] || exit 1 before invoking."],"exampleFix":"// before\nKEY=\"\"; opencli trae-solo state-get --key \"$KEY\"\n// after\nKEY=\"history.recentlyOpenedPathsList\"; [ -n \"$KEY\" ] && opencli trae-solo state-get --key \"$KEY\"","handlingStrategy":"validation","validationCode":"const key = String(process.argv.key || '').trim();\nif (!key) { console.error('usage: state-get --key <name>'); process.exit(2); }","typeGuard":"function hasKeyArg(args) { return typeof args.key === 'string' && args.key.trim().length > 0; }","tryCatchPattern":"try {\n  await stateGet(args);\n} catch (e) {\n  if (/^key required$/.test(e.message)) { console.error('Provide --key <name>; see state-keys'); }\n  throw e;\n}","preventionTips":["Always pass --key explicitly; never rely on possibly-empty shell variables","Quote the key value in shells to avoid word-splitting","Validate args in wrapper scripts before invoking the CLI","Use state-keys output as the source of key names"],"tags":["argument-validation","cli","missing-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}