/ghidra-cli

name: ghidra-cli
description: >
    Use ghidra-cli for reverse engineering tasks: binary analysis, decompilation, function inspection, cross-reference analysis, pattern discovery, binary patching, and type system management.
    Activate when the user requests:
    - Binary analysis or reverse engineering
    - Decompilation or disassembly
    - Function listing, inspection, or renaming
    - Cross-reference or call graph analysis
    - String or byte pattern searches
    - Binary patching or modification
    - Ghidra project management
    - Type management (structs, enums, typedefs, struct fields)
    - Function signature editing (return type, calling convention, full signature)
    - Variable retyping in decompiled functions

ghidra-cli Agent Reference

Rust CLI for Ghidra reverse engineering. Binary name: `ghidra`.

Architecture

CLI (Rust/clap) ──TCP──► GhidraCliBridge.java (GhidraScript in Ghidra JVM)

• **Direct bridge**: no daemon process. The Java bridge IS the persistent server.
• One bridge per project, keyed by `~/.local/share/ghidra-cli/bridge-{md5}.port`
• Import/Analyze/query commands **auto-start** the bridge if not running
• Sequential command processing (Ghidra API is not thread-safe)

Global Flags

| Flag | Effect | |------|--------| | `--json` | Compact JSON output (single line) | | `--pretty` | Pretty-printed JSON | | `--project P` / `--program PROG` | Target project/program; global, so they may precede the subcommand | | `--projects-dir DIR` | Where Ghidra projects are stored (overrides `ghidra_project_dir`) | | `--java-home PATH` | Full JDK for Ghidra (overrides auto-detection) | | `-v` / `-vv` / `-vvv` | Log verbosity: warn / info / debug | | `-q` / `--quiet` | Suppress non-essential stderr |

All flags are global, so `ghidra --project P --program bin function list` works the same as putting them after the subcommand.

**Format auto-detection**: TTY → compact human-readable; pipe → json-compact. Override with `--json`, `--pretty`, or `-o FORMAT`.

Ghidra 12.1+ rejects project dirs with a dot-prefixed component (e.g. `~/.cache`); on Linux the default falls back to `~/ghidra-cli-projects`. Use `--projects-dir` to override.

Quick Start

# Fastest path: import runs auto-analysis automatically; bridge starts on demand
ghidra import ./binary --project myproject

# All subsequent queries reuse the running bridge
ghidra function list --project myproject
ghidra decompile main --project myproject

Command Reference

Bridge Lifecycle

ghidra start [--project P] [--program PROG]
ghidra stop [--project P]
ghidra restart [--project P] [--program PROG]
ghidra status [--project P]
ghidra ping [--project P]
ghidra jobs [JOB_ID] [--project P]      # bridge queue + recent jobs, or one job by ID
ghidra cancel [JOB_ID] [--project P]    # cooperatively cancel active (or given) job

`ping`, `status`, `jobs`, and `cancel` answer immediately on the control plane. Program jobs run in lanes: `read` (cheap reads, concurrent), `read-heavy` (decompile/find/graph/stats/`script run --read-only`, concurrent but capped at pool size − 1) and `exclusive` (writes, open/close, analyze, import, plain `script run`). `ghidra jobs` shows each job's `lane`, `queue_position` and `blocked_by`, and `abandoned` jobs (client disconnected; skipped or cancelled). The read pool size is `GHIDRA_CLI_READ_THREADS` (default `min(8, cores/2)`, `0` = all exclusive). The CLI never auto-restarts a bridge; if it is older than the CLI, run `ghidra restart` when no other clients use it.

Project Management

ghidra project create NAME
ghidra project list
ghidra project info [NAME]
ghidra project delete NAME

Import & Analysis

ghidra import BINARY [--project P] [--program PROG] [--no-analyze] [--detach]
ghidra analyze [--project P] [--program PROG] [--detach]

Both auto-start the bridge. `ghidra import` runs auto-analysis by default (and persists the program); pass `--no-analyze` for a raw import without analysis. `--detach` returns immediately.

Program Management

ghidra program list [--project P]          # alias: prog, programs
ghidra program open --program PROG [--project P]   # --program required by runtime
ghidra program close [--project P]
ghidra program delete --program PROG [--project P]
ghidra program info [--project P]
ghidra program export FORMAT [--project P] [-o OUTPUT]   # FORMAT: json, xml, c/cpp, binary/bin, gzf, ascii/asm, hex, html

Function Operations

ghidra function list [QUERY_OPTS]           # aliases: fn, func, functions
ghidra function get TARGET [QUERY_OPTS]     # TARGET = name or 0xADDRESS
ghidra function decompile TARGET [--with-vars] [--with-params] [QUERY_OPTS]
ghidra function disasm TARGET [QUERY_OPTS]   # whole body; --limit N (default 1000, 0 = all); truncation warned on stderr
ghidra function calls TARGET [QUERY_OPTS]   # outgoing calls
ghidra function xrefs TARGET [QUERY_OPTS]   # incoming references
ghidra function rename OLD NEW [--project P] [--program PROG]
ghidra function create ADDRESS [NAME] [--project P] [--program PROG]
ghidra function delete TARGET [QUERY_OPTS]
ghidra function set-signature TARGET --signature "int foo(int x, char *y)" [--project P] [--program PROG]
ghidra function set-return-type TARGET --type TYPE [--project P] [--program PROG]
ghidra function set-calling-convention TARGET --convention CC [--project P] [--program PROG]
ghidra function set-var-type TARGET --var VARNAME --type TYPE [--project P] [--program PROG]

Top-level Shortcuts

ghidra decompile TARGET [--with-vars] [--with-params] [QUERY_OPTS]   # aliases: decomp, dec
ghidra disasm TARGET [-n COUNT] [QUERY_OPTS]   # TARGET = name or 0xADDRESS; aliases: disassemble, dis

`--with-vars` includes local variable details (name, type, storage) in the response. `--with-params` includes parameter details (name, type, storage) in the response. Both flags add structured data alongsi