{"record":{"id":"63b669fdeffe9312","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-retain-values-options-path","errorCode":null,"errorMessage":"Usage: ghidra trace retain-values [OPTIONS] PATH [KEYS...]","messagePattern":"Usage: ghidra trace retain-values \\[OPTIONS\\] PATH \\[KEYS\\.\\.\\.\\]","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":1287,"sourceCode":"                               result: lldb.SBCommandReturnObject,\n                               internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Retain only those keys listed, setting all others to null.\n\n    Usage: ghidra trace retain-values [OPTIONS] PATH [KEYS...]\n\n    OPTIONS may be one of:\n\n        --elements To set all other elements to null (default)\n        --attributes To set all other attributes to null\n        --both To set all other values (elements and attributes) to null\n\n    KEYS is a space-separated list of keys to keep. This list may be empty, in\n    which case, all keys of the specified kind are removed.\n    \"\"\"\n\n    options, args = retain_values_parser.parse_args(shlex.split(command))\n    if len(args) < 1:\n        raise RuntimeError(\n            \"Usage: ghidra trace retain-values [OPTIONS] PATH [KEYS...]\")\n    path = args[0]\n    keys = args[1:]\n\n    trace, tx = STATE.require_tx()\n    trace.proxy_object_path(path).retain_values(keys, kinds=options.kinds)\n\n\n@convert_errors\ndef ghidra_trace_get_obj(debugger: lldb.SBDebugger, command: str,\n                         result: lldb.SBCommandReturnObject,\n                         internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Get an object descriptor by its canonical path.\n\n    Usage: ghidra trace get-obj PATH\n\n    This isn't the most informative, but it will at least confirm whether an\n    object exists and provide its id.","sourceCodeStart":1269,"sourceCodeEnd":1305,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L1269-L1305","documentation":"Usage error raised by ghidra_trace_retain_values when, after retain_values_parser.parse_args, fewer than one positional argument remains. retain_values keeps the named KEYS on the object at PATH and nulls the rest; PATH is mandatory, KEYS may be empty.","triggerScenarios":"Passing only options (--elements/--attributes/--both) with no PATH; passing an option the parser does not recognize so PATH is consumed as an option; empty command string.","commonSituations":"User forgets PATH and supplies only flags; user misspells an option so the parser treats PATH as an unknown option argument.","solutions":["Always supply a PATH token, even if KEYS is empty.","Use only supported options: --elements, --attributes, --both.","Place options before PATH to avoid the parser consuming PATH as an option value."],"exampleFix":"// before\nghidra trace retain-values --attributes\n// after\nghidra trace retain-values --attributes Processes[0].Threads[1]","handlingStrategy":"validation","validationCode":"from ghidralldb.commands import retain_values_parser\nimport shlex\n\ndef validate_retain_values(command: str) -> None:\n    opts, args = retain_values_parser.parse_args(shlex.split(command))\n    if len(args) < 1:\n        raise ValueError('retain-values needs a PATH (KEYS optional)')","typeGuard":null,"tryCatchPattern":"try:\n    ghidra_trace_retain_values(debugger, command, result, internal_dict)\nexcept RuntimeError as e:\n    if str(e).startswith('Usage:'):\n        result.SetError(str(e))\n    else:\n        raise","preventionTips":["Always supply PATH even when KEYS is empty.","Use only --elements/--attributes/--both options.","Place options before PATH."],"tags":["ghidra-trace","argument-validation","retain-values","cli-usage"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}