Imported from cellebrite-labs/ghidra-rpc (SKILL.md). Install upstream with npx skills add cellebrite-labs/ghidra-rpc. Copyright stays with the author.

Ghidra RPC

A CLI daemon that exposes Ghidra reverse engineering capabilities over a Unix domain socket. You interact with it by running ghidra-rpc commands via the bash tool - every command outputs JSON to stdout.

Running Commands

All ghidra-rpc commands must be run with uv run from the ghidra-rpc skill directory (the directory containing this SKILL.md file):

cd <skill-dir> && uv run ghidra-rpc <command> ...

Prerequisites Check

Before using any commands, verify the setup:

1. Is the daemon running? Run uv run ghidra-rpc status --project <path>. If not running, the user needs to start it in a separate terminal: uv run ghidra-rpc start --project /path/to/project.gpr (blocking, human-only). The --headless flag skips the GUI. For non-blocking / automated startup use start --detach --headless or restart --headless. Both commands accept --timeout SECS (default: 60 s headless, 180 s GUI) and log daemon output to /tmp/ghidra-rpc-<hash>.log.
2. GUI mode: verify the correct project is active. The daemon passes the --project path directly to GhidraRun so Ghidra opens the requested project immediately. After start --detach (GUI mode), confirm the right project is loaded before issuing any analysis commands:

   uv run ghidra-rpc list-project-programs --project /path/to/project.gpr

   Cross-check the returned binary names against what you expect. If the names don't match (or a warning field appears in the response), stop and ask the user to open the correct project in Ghidra's Project window before proceeding.
3. GUI mode: open the binary in CodeBrowser. In GUI mode the daemon discovers programs via the running CodeBrowser tool. If the binary is in the project but not currently open in CodeBrowser, list-binaries will return empty and all commands will fail with "Binary not found". Use list-project-programs to see what's stored in the project, then double-click the program in Ghidra's Project window to open it.
4. Is GHIDRA_INSTALL_DIR set? The daemon will fail loudly if this is missing.

Once the daemon is running, all commands below work automatically. If the daemon dies, commands will attempt auto-restart from the saved session.

Command Reference

Every command accepts --project <path> (or reads GHIDRA_RPC_PROJECT env var). All output is JSON. Exit code 0 = success, 1 = error.

Project Management

status output: {running, socket, mode, mode_source, project, binaries}. binaries is the loaded-binary list when the daemon is running, null when stopped (one-shot health check without a second list-binaries call). mode_source is "running" when the daemon is live, "session" when the mode is from the saved session only (daemon stopped), and null if no session exists. | ghidra-rpc restart --project <gpr> [--headless] [--timeout SECS] [--ghidra-install-dir DIR] | Restart daemon in background (--headless to override mode) | ghidra-rpc restart -p /tmp/re.gpr --headless | | ghidra-rpc list-binaries --project <gpr> | List binaries loaded in daemon | ghidra-rpc list-binaries -p /tmp/re.gpr | | ghidra-rpc list-project-programs --project <gpr> | List all programs stored in the project repo (reads project folder, not CodeBrowser live state; returns warning if the active Ghidra project doesn't match) | ghidra-rpc list-project-programs -p /tmp/re.gpr | | ghidra-rpc save [binary] --project <gpr> | Save program(s) to disk (auto-save also runs after every write) | ghidra-rpc save -p /tmp/re.gpr |

Loading & Analysis

load flags:

• --no-analyze - skip auto-analysis entirely (fast; useful when you only need the listing or plan to run analysis later via Ghidra GUI).
• --analysis-timeout SECS - abort auto-analysis after the given wall-clock budget (best-effort); the binary is saved with whatever analysis completed in time.

Listing

Decompilation

<func> can be a function name or hex address (e.g., main or 0x401000). If the name is ambiguous, the error message lists matches so you can use the address instead.

search-decompiled is especially useful on multidex Android projects, where xrefs-to on a method only sees callers within the same DEX program (see the Android APK/DEX section) — use it in place of a symbols+decompile+grep loop, e.g. search-decompiled app.apk targetF1 --class com::example::Foo. --max-scan (default 5000) bounds how many functions get decompiled when --class isn't given, so a search on a 50k+-function binary can't run away; raise --socket-timeout (default 1800s) alongside it if you do widen the scan.

Search

symbols normalizes literal spaces and underscores as equivalent before matching, so a query pasted straight from strings output (real spaces) still finds the corresponding label even though Ghidra auto-generates labels from string content by turning each space into _ (and leaving every other character, including non-ASCII/CJK text, untouched).

Cross-References

Ghidra's reference manager is per-binary: a call whose caller and target live in two different loaded binaries is invisible to a single-binary xrefs-to lookup (most commonly hit on multidex Android projects, where a method in one classesN.dex is called from another, but this isn't DEX-specific — it applies to any project with more than one binary loaded in the daemon). Pass --all-binaries to also search every other currently loaded binary for a symbol with the same fully-qualified name and merge in real callers found there; each merged entry carries a binary field so you can tell which binary it came from.

Navigation (GUI mode only)

Memory & Disassembly

Modifications

Comment types: plate, pre, post, eol (default), repeatable.

Signature input is sanitised automatically: trailing semicolons are stripped, whitespace is trimmed, and inline calling conventions (__thiscall, __fastcall, __stdcall, __cdecl, __vectorcall, __pascal) are extracted from the string and applied via the proper Ghidra API. So you can paste a C prototype directly (e.g. void __thiscall Foo::Bar(int x); works without manual cleanup).

Type expressions for set-data-type, retype-variable, and struct field types:

• Built-ins: byte, char, int, uint, short, long, float, double, void, string, unicode
• Pointer: char *, void *, int **
• Array: char[11], int[4]
• Any type in the program's data type manager by name or path: MyStruct, /POSIX/size_t

Order of operations — set signatures/types before naming locals. Each of set-signature, set-data-type, retype-variable, and rename-variable re-runs the decompiler, which re-numbers the remaining auto-named locals (uVar1, dVar2, …). So chaining single-variable edits is fragile: after renaming dVar1, the old dVar2 may now be dVar1. Do all signature/this-typing first, then name locals — or, better, use batch-edit-variable to apply every rename and retype against a single decompiler snapshot in one call (it also lets you address a variable by its stable storage string instead of the volatile auto name).

Bookmarks

Bookmark types: Note (default), Warning, Error, Info, Analysis.

--category is a case-insensitive substring filter. On heavily auto-analyzed binaries (large native programs, and especially DEX/Dalvik — 50k+ functions is normal), Ghidra generates many Analysis-type bookmarks (commonly category Address Table) that can bury a handful of your own; filter them out with --category (or --type to isolate your own type, e.g. Note) instead of paging through the unfiltered list.

Bookmarks are visible in the Ghidra GUI's Bookmarks window. Use them to persistently mark interesting locations, track analysis progress, or flag findings for human review.

Function Tags

Tags are string labels (e.g. crypto, vuln-sink, analyzed, needs-review) visible in Ghidra's Function Tags window. Use them to classify functions and track analysis progress.

Data-Type Authoring

Version Tracking & Diff

decompile-all's default --socket-timeout (1800s) assumes a bulk sweep can take much longer than any single function's --timeout; raise it further for binaries with tens of thousands of functions (e.g. large DEX/APK programs).

For the full patch-diff workflow see docs/flows/patch-analysis.md.

Error Handling

Error responses look like:

{"id": "...", "ok": false, "error": "FunctionNotFound", "message": "Function 'foo' not found."}

Common errors:

• DaemonNotRunning: Daemon isn't started. Tell the user to run ghidra-rpc start.
• ValueError: Bad argument (ambiguous name, invalid address). The message usually tells you what to do - e.g., use a more specific name or an address.
• RuntimeError: Ghidra-level error. For GUI-only commands in headless mode, the error says so explicitly.

All CLI output is JSON, including usage errors. A malformed invocation (unknown option, invalid --type choice, unknown subcommand, missing required argument) is also reported as {"ok": false, "error": "...", "message": "..."} on stdout, with a nonzero exit code — never a plain-text Click usage string. Scripted callers can always json.loads() stdout unconditionally, without special-casing argument errors.

Write Operations & Persistence

Write operations (rename, create-label, create-function, delete-function, set-comment, batch-rename, batch-set-comment, set-signature, set-data-type, retype-variable, rename-variable, batch-edit-variable, set-calling-convention, set-thunk, set-flow-override, set-processor-context, create-struct, create-union, modify-struct, create-enum, modify-enum, set-equate, set-bookmark, clear-data-range, apply-data-type-range, write-bytes, assemble, tag-function, untag-function, create-namespace) use Ghidra transactions internally. Every write is automatically saved to the project database on disk after the transaction commits, so changes survive daemon restarts and are visible when the project is reopened in the Ghidra GUI.

Every write response includes a verified boolean that confirms whether the change was read back successfully after committing.

You can also save explicitly at any time:

ghidra-rpc save              # saves all loaded programs
ghidra-rpc save <binary>     # saves one program

On clean shutdown (stop or Ctrl+C), all programs are saved automatically.

Patch / Diff Analysis Quick Start

# 1. Load both versions
ghidra-rpc load /path/to/binary_v1 -p project.gpr
ghidra-rpc load /path/to/binary_v2 -p project.gpr

# 2. Find changed functions (summary counts all changes; matched list is filtered)
ghidra-rpc version-track binary_v1 binary_v2 --changed-only

# 3. Diff a specific changed function
ghidra-rpc function-diff binary_v1 <func> binary_v2 <func>

Full workflow — correlator details, unmatched analysis, bulk decompile: read docs/flows/patch-analysis.md.

Android APK / DEX Analysis

Ghidra has built-in APK and DEX support (Dalvik processor + FileFormats loaders) — no extension install needed. load a .dex or .apk directly and the usual commands (decompile, functions, strings, xrefs-*, …) work on the Dalvik program, which decompiles to Java-like pseudocode. Note the multi-dex caveat: load app.apk imports only the primary classes.dex.

For the full workflow — multi-dex extraction, class-qualified :: symbols and ambiguous methods, the DEX string-vs-xrefs-to gotcha, minified apps, and manifest/.so extraction — read docs/flows/android-apk.md.

Typical Workflow

1. User starts daemon: cd <skill-dir> && uv run ghidra-rpc start --project /path/to/project.gpr --headless For automation / non-blocking start: uv run ghidra-rpc start --project /path/to/project.gpr --headless --detach
2. Load binary: uv run ghidra-rpc load /path/to/binary -p /path/to/project.gpr Response includes short_name (usable alias in all subsequent commands). (add --no-analyze to skip analysis, --analysis-timeout SECS to cap it)
3. Get overview: metadata, functions, imports, exports
4. Investigate: decompile interesting functions, xrefs-to to trace callers
5. Annotate: rename-function, set-comment to document findings
6. Search: strings for hardcoded values, symbols for specific patterns

FAQ / Common Gotchas

create-label properly replaces DEFAULT (auto-analysis) symbols: create-label creates a USER_DEFINED label and sets it as the primary symbol at the address. If a DEFAULT symbol (e.g. DAT_00418138) already exists, it is demoted to secondary. The decompiler will then use the new name. rename-symbol renames in place but requires an existing symbol; create-label is preferred for annotating addresses regardless of existing symbols.

Annotating an address with no existing symbol (rename-symbol fails with "No symbol found"): rename-symbol requires a symbol to already exist at the address. Auto-analysis only places DAT_ symbols where it detects data; inside arrays or dense struct regions many addresses have no symbol. Use create-label instead - it creates a new USER_DEFINED label if none exists, or renames the existing one:

ghidra-rpc create-label <binary> 0x0040e4ac topPtrErrorMsg

You can also add --create to rename-symbol for the same upsert behaviour.

Defining and applying a struct across a memory region: Full workflow to stamp a struct across a repeated data table:

# 1. Create the struct type in the DTM (--if-not-exists makes the call idempotent)
ghidra-rpc create-struct binary ErrorEntry int errorNumber "char *" ptrErrorMsg --if-not-exists

# 2. Stamp the struct across the range with --clear to atomically clear + apply
#    (23 × 8-byte ErrorEntry structs, both endpoints inclusive)
ghidra-rpc apply-data-type-range binary 0x0040e4a8 0x0040e55f ErrorEntry --clear

After this, each address 0x0040e4a8, 0x0040e4b0, ... has type ErrorEntry. Without --clear, apply-data-type-range skips positions where existing data conflicts and reports them in the errors list. Use clear-data-range first if you need finer control over which region is cleared.

Discovering what labels exist at an address or range:

# Single address
ghidra-rpc list-labels binary 0x0040e4a8

# Range
ghidra-rpc list-labels binary 0x0040e4a8 --end 0x0040e55f --limit 50

Using the binary name after load: load returns both a full key (binary) with a hash suffix and a short_name (the original filename). Use short_name in all subsequent commands - it works because commands match binary names by substring:

# Load response: {"binary": "/WinHelloCPP.exe-85cbcc", "short_name": "WinHelloCPP.exe", ...}
ghidra-rpc decompile WinHelloCPP.exe main        # short_name works
ghidra-rpc decompile WinHelloCPP main            # even without extension, if unambiguous

If two binaries share the same stem, use the full key to disambiguate.

Trailing semicolons in signatures: Ghidra's parser rejects C prototypes that end with ;. ghidra-rpc strips trailing semicolons automatically, so you can paste verbatim.

list-binaries is empty but I loaded a binary: In GUI mode, the binary must be open in CodeBrowser. Use list-project-programs to see what's stored in the project repo, then open it in CodeBrowser's Project window.

Daemon log file: When started in the background (start --detach or restart), logs are written to /tmp/ghidra-rpc-<hash>.log (same directory and stem as the Unix socket). If the daemon fails to start or become responsive, check that file first:

tail -50 /tmp/ghidra-rpc-*.log

The timeout error message always prints the exact log path.

GHIDRA_INSTALL_DIR not found after backgrounding: Environment variables may be lost when daemonising (nohup, cron, systemd units, etc.). Fix options, in order of preference:

1. Pass --ghidra-install-dir /path/to/ghidra to start or restart - the value is persisted in the session file and forwarded to every subsequent restart automatically.
2. Export GHIDRA_INSTALL_DIR in your shell profile (~/.bashrc, ~/.zshrc) so it survives login sessions.
3. Use start --detach --headless from the same terminal where the env var is set.

Session file location: By default the session file (.ghidra-rpc-<hash>.json) is written alongside the .gpr project file, keeping all state self-contained. To use a custom directory (e.g. a shared location or a RAM-disk), set GHIDRA_RPC_STATE_DIR:

export GHIDRA_RPC_STATE_DIR=/tmp/ghidra-sessions

Changes not visible in the Ghidra GUI: Make sure you open the project copy (e.g. basic_code-501243 in the Project window), not the raw binary via File → Open. Also ensure you are not running two separate Ghidra instances on the same project (causes lock conflicts). Changes made by ghidra-rpc are auto-saved to disk and will be visible the next time the program is opened in the GUI.

restart without a prior session: Pass --headless so restart can create a fresh headless session instead of requiring a prior start.

Decompiler timeout on certain functions: Some functions trigger expensive decompiler analysis paths and time out even with simple assembly. Use decompile --timeout 300 (or higher) for stubborn functions. The default timeout is 120 s (increased from 60 s to handle large firmware functions). The retype-variable and rename-variable commands also accept --timeout since it triggers an internal decompilation pass.

decompile returns bad-instruction warnings — use pcode --high as fallback: When decompile produces output like "Bad instruction data" or fails to decode a function body (common on ARM Thumb code in regions that auto-analysis mis-classified as data), try pcode --high instead:

ghidra-rpc pcode binary 0x03288102 --high

The P-code engine re-decodes bytes from the function object's context rather than from the listing-level disassembler, so it often succeeds where decompile fails. High P-code also reveals all CALL / CALLIND / BRANCHIND targets and data flow, making it useful for tracing arguments even without valid decompilation. Fix the root cause with set-processor-context (see below).

disassemble starts from the wrong address (B2 warning): If disassemble is called at an address with no instruction (e.g. an address that is mid-instruction or undefined), the response now includes a warning field explaining that disassembly started from the next available instruction. Check for warning in the JSON response when the listing looks wrong.

ARM Thumb mis-classification — set-processor-context is the fix (F1/F5): When ARM auto-analysis classifies Thumb code as data, the listing disassembler decodes it as 32-bit ARM (TMode=0) and produces garbage. The full recovery workflow:

# 1. Diagnose: check TMode at the affected address
ghidra-rpc get-processor-context binary 0x03288100 --register TMode
# Expected: {"TMode": 0}  ← this is the problem

# 2. Clear the bad data/code classification
ghidra-rpc clear-data-range binary 0x03288100 0x032883ff

# 3. Set Thumb mode for the range
ghidra-rpc set-processor-context binary 0x03288100 TMode 1 --end 0x032883ff

# 4. Verify disassembly now shows Thumb-2 instructions
ghidra-rpc disassemble binary 0x03288100 --count 20

# 5. Re-create the function
ghidra-rpc create-function binary 0x03288100

If create-function fails because a bad stub still exists at the address, use delete-function first to remove it.

Bad stubs blocking re-creation — use delete-function (F2): If create-function 0x03288103 (wrong parity) left a stub, and now create-function 0x03288102 (correct address) fails with "already exists at overlapping address", delete the bad stub first:

ghidra-rpc delete-function binary 0x03288103
ghidra-rpc create-function  binary 0x03288102

Batch rename / comment 40+ functions without round-trip overhead (F7): Use batch-rename and batch-set-comment to apply many annotations in a single server round-trip and Ghidra transaction:

# Rename functions from a JSON file
ghidra-rpc batch-rename binary --json-file renames.json

# Or inline
ghidra-rpc batch-rename binary --json \
  '[{"target":"sub_401234","new_name":"init_uart"},{"target":"0x400200","new_name":"isr_handler"}]'

# Label-mode (symbol/label rename by address)
ghidra-rpc batch-rename binary --mode label --json \
  '[{"address":"0x0333afcc","new_name":"g_debugStr"}]'

# Batch comments
ghidra-rpc batch-set-comment binary --json \
  '[{"address":"0x03288102","comment":"Thumb ISR entry","comment_type":"plate"}]'

All items that succeed are committed in one transaction; failed items are reported per-item in results[].ok=false and do not roll back the successes.

Concurrent write operations are serialised: The daemon serialises all command handler invocations internally to prevent Ghidra transaction conflicts. You do not need to serialize write commands externally — parallel writes are queued automatically. This is slightly slower than concurrent execution but eliminates silent partial failures.

Reporting Bugs and Missing Features

While using ghidra-rpc you may encounter bugs, errors, or missing capabilities. Please report them - real-world usage drives continuous improvement.

At the end of any analysis session where you hit a problem, save a brief report:

cat > /tmp/ghidra-rpc-issues-$(date +%Y%m%d-%H%M%S).md << 'EOF'
## ghidra-rpc Issue Report

**Date:** $(date)
**Binary:** <name of binary analysed>

### Bugs encountered
<!-- Describe: command used, error message / unexpected output, expected behaviour -->

### Missing features
<!-- Describe what you needed but couldn't do with the current command set -->

### Suggestions
<!-- Any UX improvements or new commands that would have helped -->
EOF

Then inform the user:

"I saved a ghidra-rpc issue report to /tmp/ghidra-rpc-issues-<timestamp>.md. If you'd like to submit it, run: cat /tmp/ghidra-rpc-issues-*.md"

The report is written to /tmp so it stays local to the machine and is lost on reboot - it is never sent anywhere automatically.

Further Documentation

For detailed guidance on specific workflows:

• Installation & setup: read docs/install.md
• Quick start tutorial: read docs/quickstart.md
• Troubleshooting: read docs/troubleshooting.md
• Binary audit workflow: read docs/flows/binary-audit.md
• Vulnerability research: read docs/flows/vulnerability-research.md
• Patch/diff analysis: read docs/flows/patch-analysis.md
• Android APK / DEX analysis: read docs/flows/android-apk.md