Ghidra Agent CLI

ghidra-agent-cli

Description

ghidra-agent-cli is the bundled helper for the Headless Ghidra skill family. It owns the command tree, workspace layout, YAML artifact semantics, output envelope, and runtime behavior for supported Ghidra, Frida, progress, and gate operations.

This skill documents the helper command semantics for agents. It does not define the P0–P4 workflow order, stage routing, or orchestration policy. Those are defined by headless-ghidra/SKILL.md and the per-phase skills. Normal users install and use the skill family; they do not manually install, build, or run this CLI during the workflow.

Prerequisites

• Node.js >= 18
• Local Ghidra installation discoverable by ghidra-agent-cli ghidra discover
• Optional Frida installation for frida * commands

Availability

The helper is installed with the skill family and must remain a sibling of headless-ghidra and the phase skills. If ghidra-agent-cli is unavailable, ask the user to reinstall or refresh the whole skill family rather than installing a separate CLI package inside the target workspace.

Release-managed helper package version: ghidra-agent-cli@1.8.0. This marker is packaging metadata; do not ask users to install it manually during an analysis workflow.

Invocation

ghidra-agent-cli [GLOBAL FLAGS] <COMMAND> [COMMAND FLAGS]

Input

Global flags:

• --format yaml|json|toml — Output format (default: yaml)
• --target <id> — Target selector
• --workspace <path> — Workspace root path
• --config-dir <PATH> — Override config directory
• --data-dir <PATH> — Override data directory
• --state-dir <PATH> — Override state directory
• --cache-dir <PATH> — Override cache directory
• --log-dir <PATH> — Override log directory
• --lock-timeout <SECS> — Lock acquisition timeout in seconds (default: 30)
• --no-wait — Do not wait for lock acquisition
• --help — Show help text

Most commands require --target <id> or an active context set via context use.

Output

Commands emit a structured envelope in the selected format:

status: ok
message: "<summary>"
data: <structured payload>

Errors

Errors are structured and stable:

{
  "code": "E_ERROR",
  "message": "description of what went wrong",
  "source": "main",
  "format": "json"
}

Known codes:

• E_ERROR — General error
• E_GATE_FAILED — Gate check failed
• E_LOCK_TIMEOUT — Lock acquisition timed out

Command Groups

Workspace Model

ghidra-agent-cli uses this active workspace layout:

targets/<target-id>/
└── ghidra-projects/

artifacts/<target-id>/
├── pipeline-state.yaml
├── scope.yaml
├── intake/
├── baseline/
│   ├── functions.yaml
│   ├── callgraph.yaml
│   ├── types.yaml
│   ├── vtables.yaml
│   ├── constants.yaml
│   ├── strings.yaml
│   └── imports.yaml
├── runtime/
│   ├── project/
│   ├── fixtures/
│   ├── run-manifest.yaml
│   ├── run-records/
│   └── hotpaths/call-chain.yaml
├── third-party/
│   ├── identified.yaml
│   ├── pristine/<library>@<version>/
│   └── compat/<library>@<version>/
├── metadata/
│   ├── renames.yaml
│   ├── signatures.yaml
│   ├── types.yaml
│   ├── constants.yaml
│   ├── strings.yaml
│   └── apply-records/
├── substitution/
│   ├── template/
│   ├── next-batch.yaml
│   └── functions/<fn_id>/
│       ├── capture.yaml
│       └── substitution.yaml
├── gates/
└── scripts/

workspace init creates the base workspace structure and initializes pipeline-state.yaml plus scope.yaml. Later phases populate the remaining artifacts.

Artifact Semantics

Examples

# Initialize a target
ghidra-agent-cli workspace init --target libfoo --binary ./libfoo.so

# Set scope and inspect state
ghidra-agent-cli --target libfoo scope set --mode full --entries 0x1000,0x2000
ghidra-agent-cli --target libfoo workspace state show

# Export and inspect baseline YAML
ghidra-agent-cli --target libfoo ghidra import
ghidra-agent-cli --target libfoo ghidra auto-analyze
ghidra-agent-cli --target libfoo ghidra export-baseline
ghidra-agent-cli --target libfoo functions list

# Import custom headers and signatures into the current Ghidra program
ghidra-agent-cli --target libfoo ghidra import-types-and-signatures --header ./include/custom_types.h --header ./include/custom_api.h

# Runtime, metadata, substitution, and gate checks
ghidra-agent-cli --target libfoo runtime record --key entrypoint --value 0x401000
ghidra-agent-cli --target libfoo hotpath add --addr 0x401000 --reason runtime
ghidra-agent-cli --target libfoo metadata enrich-function --addr 0x401000 --name main --prototype 'int(void)'
ghidra-agent-cli --target libfoo substitute add --fn-id fn_001 --addr 0x401000 --replacement 'return 0;'
ghidra-agent-cli --target libfoo gate check --phase P1

# Frida helpers
ghidra-agent-cli frida device-list
ghidra-agent-cli frida trace --target ./bin/app --functions open,read

Boundary

• Use this skill to answer: command names, flags, output shape, artifact paths, file semantics, and CLI behavior.
• Do not use this skill as the source of truth for P0–P4 sequencing, stage ownership, or workflow decisions. Those live in the headless-ghidra skill family.