ghidra-cli

Rust CLI that drives Ghidra headlessly via a persistent Java bridge process. Sub-second queries because Ghidra stays loaded in memory between commands.

Architecture

ghidra-cli  ──TCP──▶  GhidraCliBridge.java (Ghidra JVM, auto-started)

One bridge per project, keyed by

~/.local/share/ghidra-cli/bridge-{md5}.port

. Commands auto-start the bridge if it isn't running.

First-Time Setup

# Verify everything is found
ghidra-cli doctor

On NixOS,

GHIDRA_INSTALL_DIR

and

java

in PATH are injected automatically by the Nix wrapper — no manual config needed.

doctor

should show all green out of the box.

Typical Workflow

# 1. Import binary and run analysis (bridge auto-starts)
ghidra-cli import ./target --project myproject --program target
ghidra-cli analyze --project myproject --program target

# 2. Explore
ghidra-cli stats
ghidra-cli function list
ghidra-cli find interesting

# 3. Drill into a function
ghidra-cli decompile main
ghidra-cli disasm 0x401000 --instructions 30

# 4. Trace references
ghidra-cli x-ref to 0x401000
ghidra-cli graph callers main --depth 2

# 5. Patch and export
ghidra-cli patch nop 0x401234 --count 3
ghidra-cli patch export -o patched.bin

Commands

Project & Program

ghidra-cli project create <name>
ghidra-cli project list
ghidra-cli import <binary> --project <p> --program <name>
ghidra-cli analyze --project <p>

Function Analysis

ghidra-cli function list
ghidra-cli function list --filter "size > 100"
ghidra-cli decompile <name-or-addr>        # pseudocode
ghidra-cli disasm <addr> --instructions 20 # raw disassembly

Symbols & Types

ghidra-cli symbol list
ghidra-cli symbol create <addr> <name>
ghidra-cli symbol rename <old> <new>
ghidra-cli type list
ghidra-cli type get <name>

Cross-References

ghidra-cli x-ref to <addr>     # what calls/references this address
ghidra-cli x-ref from <addr>   # what this address calls/references

Search

ghidra-cli find string "password"
ghidra-cli find bytes "90 90 90"
ghidra-cli find function "*crypt*"
ghidra-cli find crypto           # known crypto constants
ghidra-cli find interesting      # suspicious patterns (good starting point)

Call Graphs

ghidra-cli graph callers <func> --depth 3   # who calls this?
ghidra-cli graph callees <func> --depth 3   # what does this call?
ghidra-cli graph export dot                 # export full graph as DOT

Patching

ghidra-cli patch bytes <addr> "90 90"
ghidra-cli patch nop <addr> --count 5
ghidra-cli patch export -o patched.bin

Comments

ghidra-cli comment get <addr>
ghidra-cli comment set <addr> "note" --comment-type EOL
ghidra-cli comment list

Scripts

ghidra-cli script list
ghidra-cli script run myscript.py
ghidra-cli script python "print(currentProgram)"

Bridge Control

ghidra-cli start --project <p> --program <name>   # explicit start
ghidra-cli status --project <p>
ghidra-cli stop --project <p>
ghidra-cli restart --project <p> --program <name>

Misc

ghidra-cli stats                   # function/string/symbol counts
ghidra-cli summary                 # program metadata
ghidra-cli batch commands.txt      # run commands from file

Filtering

Append

--filter "<expr>"

to list commands:

ghidra-cli function list --filter "size > 100"
ghidra-cli function list --filter "name contains 'main'"
ghidra-cli strings list --filter "length > 20"

Output Formats

• TTY (default): compact human-readable
• Pipe (default): compact JSON

• --json

  : force compact JSON

• --pretty

  : force indented JSON

• --fields "name,address,size"

  : select specific fields

ghidra-cli function list --pretty
ghidra-cli function list --json | jq '.[] | select(.size > 500)'

Multi-Project Concurrent Analysis

Each project runs its own bridge, so you can analyze multiple binaries in parallel:

ghidra-cli import ./a --project projA && ghidra-cli analyze --project projA &
ghidra-cli import ./b --project projB && ghidra-cli analyze --project projB &
wait
ghidra-cli function list --project projA
ghidra-cli function list --project projB

AI-Assisted RE Workflow

Effective pattern for agent-driven analysis:

1. ghidra-cli find interesting

   — get a quick map of suspicious areas

2. ghidra-cli decompile <func>

   — read pseudocode of suspicious functions

3. ghidra-cli x-ref to <addr>

   — trace who reaches interesting code

4. ghidra-cli graph callers <func> --depth 3

   — understand call context

5. ghidra-cli comment set <addr> "..."

   — annotate findings inline

6. ghidra-cli patch nop <addr>

   +

   patch export

   — apply fixes

Common Pitfalls

• Binary not imported yet: run

  import

  +

  analyze

  before querying. The bridge auto-starts but won't auto-import.

• --project

  flag: most commands accept

  --project

  to target a specific project; omit it only when there's a single active one.

• patch nop --count

  : parsed by CLI but bridge currently applies single-address NOP — patch each address explicitly if needed.

• --comment-type

  : only

  EOL

  is reliably supported; other types fall back silently.
• Missing Java: Ghidra needs JDK 17+, not just a JRE. On NixOS the

  ghidra

  package bundles its own JDK.