ida-cli

Headless IDA CLI and skill-first toolkit for binary analysis on macOS and Linux. ida-cli auto-selects a runtime backend, auto-starts a local server when needed, and exposes the same surface as a flat CLI, a stdio MCP transport, and a Streamable HTTP MCP transport.

中文说明

Two User-Facing Entrypoints

• the local ida-cli binary (client + service in one executable)
• the installable ida-cli skill (skill/SKILL.md) for agent environments

The underlying worker / router service layer is started and shut down by the CLI automatically. You only need to run serve / serve-http explicitly when you actually want a long-lived, externally addressable service.

Support Matrix

Host Platforms

• Supported: macOS, Linux
• Not supported: Windows

IDA Runtime Policy

Backend selection is made at runtime by probe-runtime. Building still requires an IDA SDK because the vendored native layer is linked against it; at runtime the CLI opens IDA itself from IDADIR or a normalised common install path.

Current Capabilities

On supported IDA 9.x runtimes, ida-cli can:

• open raw PE / ELF / Mach-O binaries and reuse cached .i64 databases
• list and resolve functions, disassemble by address or name, decompile via Hex-Rays
• query segments, strings, imports, exports, entry points, global symbols
• resolve address ↔ segment / function / symbol context
• read bytes / strings / integers, apply read_* and convert_number helpers
• query xrefs to / from an address (including xrefs to strings and struct fields)
• build callgraphs, basic blocks, and control-flow paths
• search text, immediates, bytes, instructions, operands, pseudocode
• declare / apply types, rename symbols and locals, set comments
• run IDAPython snippets via run_script

Open items: some write-heavy and advanced type-editing operations are still partial on idat-compat. See docs/TOOLS.md for the generated tool list.

Quick Start

Recommended: Install the Skill

The default entrypoint is the ida-cli skill, not a manual CLI install.

# list the skill exposed by this repository
npx -y skills add https://github.com/cpkt9762/ida-cli --list

# install the ida-cli skill for Codex
npx -y skills add https://github.com/cpkt9762/ida-cli --skill ida-cli --agent codex --yes --global

After install, the skill ships its own bootstrap wrapper:

~/.agents/skills/ida-cli/scripts/ida-cli.sh --help
~/.agents/skills/ida-cli/scripts/ida-cli.sh probe-runtime
~/.agents/skills/ida-cli/scripts/ida-cli.sh --path /path/to/binary list-functions --limit 20

If ida-cli is missing, the wrapper installs it through the repository installer before forwarding the command.

Direct CLI Install (Optional)

Use this only if you want the standalone CLI without going through the skill.

curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --add-path

Useful variants:

# install a specific release
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --tag v0.9.3 --add-path

# build directly from a branch or ref
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --ref master --build-from-source --add-path

Notes:

• The installer places the launcher in ~/.local/bin/ida-cli by default.
• --add-path appends that bin directory to your shell rc file.
• If neither IDASDKDIR nor IDALIB_SDK is set and a local build is required, the installer clones the open-source HexRaysSA/ida-sdk automatically.
• When multiple IDA installations are present, export IDADIR explicitly before installing or running ida-cli.

Build from Source

git clone https://github.com/cpkt9762/ida-cli.git
cd ida-cli

export IDADIR="/Applications/IDA Professional 9.4.app/Contents/MacOS"   # or a Linux install
export IDASDKDIR="/path/to/ida-sdk"                                     # root or ida-sdk/src

cargo build --bin ida-cli
./target/debug/ida-cli --help

Use the CLI

ida-cli is client-first. Any client subcommand auto-starts a local Streamable-HTTP server bound to a random port and writes /tmp/ida-cli.socket for discovery:

./target/debug/ida-cli --path /path/to/sample.bin list-functions --limit 20
./target/debug/ida-cli --path /path/to/sample.bin decompile --addr 0x140001000
./target/debug/ida-cli --path /path/to/sample.bin raw '{"method":"get_xrefs_to","params":{"address":"0x140001000"}}'

Commands whose first argument is a service subcommand (serve, serve-http, serve-worker, probe-runtime) enter service mode instead:

./target/debug/ida-cli serve                          # stdio MCP transport
./target/debug/ida-cli serve-http --bind 127.0.0.1:8765
./target/debug/ida-cli probe-runtime

Example backend-probe output:

{"runtime":{"major":9,"minor":1,"build":250226},"backend":"idat-compat","supported":true,"reason":null}

{"runtime":{"major":9,"minor":4,"build":260610},"backend":"native-linked","supported":true,"reason":null}

For the complete CLI surface see skill/references/cli-tool-reference.md.

Build Requirements

• Rust 1.87+
• LLVM / Clang
• macOS or Linux host
• An IDA installation via IDADIR (runtime support starts at IDA 9.0)
• An IDA SDK via IDASDKDIR or IDALIB_SDK

The SDK path may point to either layout:

• /path/to/ida-sdk
• /path/to/ida-sdk/src

Runtime Notes

idat-compat

IDA 9.0–9.2 compatibility backend. It shells out to idat, runs short IDAPython scripts, and returns structured JSON back to the CLI runtime.

native-linked

IDA 9.3+ backend. Links against the vendored idalib line and opens databases in-process.

Cache and Local Runtime Paths

• Database cache: ~/.ida/idb/
• Logs: ~/.ida/logs/server.log
• Server Unix socket: ~/.ida/server.sock
• Server PID file: ~/.ida/server.pid
• CLI discovery file (maps the flat CLI to the live socket): /tmp/ida-cli.socket
• Large JSON response cache: /tmp/ida-cli-out/

CI and Releases

GitHub Actions compiles and tests the tree on hosted runners against the open-source HexRaysSA/ida-sdk, so CI does not depend on any private machine layout.

Current workflow behavior:

• pushes and pull requests against master run validation
• tagged pushes like v0.9.3 build release archives for Linux and macOS
• releases attach install.sh plus platform archives

Release binaries are built against SDK stubs. At install time the launcher generated by install.sh resolves your local IDA runtime through IDADIR or a normalised set of common install paths before invoking ida-cli.

Documentation

• docs/BUILDING.md — build from source
• docs/ARCHITECTURE.md — router, backends, federation
• docs/TRANSPORTS.md — stdio, streamable HTTP, multi-IDB
• docs/TOOLS.md — generated tool catalog
• docs/TESTING.md — integration and unit tests
• skill/SKILL.md — skill bootstrap and usage policy
• skill/references/cli-tool-reference.md — complete CLI surface

License

MIT