ICB – User Guide

icb‑cli

The command‑line interface parses a C/C++ or Python project and prints call‑graph information in a human‑readable format. It is the simplest way to get a quick overview of a codebase without starting a server.

cargo run -p icb-cli -- [OPTIONS]

CLI flags

Flag	Description
--project <PATH>	Path to the project directory or source file to analyze.
--language <LANG>	Language of the source files: cpp, c++, python, rust, go, ruby, javascript, or auto (auto‑detect).
--cache <PATH>	Path to a graph cache file. If the file exists, the graph is loaded from it instead of parsing again. After building, the graph is saved to this file for future use.
--cache-dir <DIR>	Directory for incremental per‑file fact caching. On the first run, facts are saved per source file with a SHA‑256 hash. On subsequent runs, only changed files are re‑parsed. Dramatically speeds up repeated analysis of large projects.
--no-system-headers	Exclude nodes that belong to system headers (C/C++ only, Clang backend). Recommended for keeping the graph focused on user code.
--compile-commands <PATH>	Path to a compile_commands.json file (C/C++). If not provided, a default command line -std=c++17 is used.
--cpp-std <STANDARD>	C++ standard version, e.g. c++17, c++20. Used when no compile_commands.json is given (default: c++17).
--output-format <FORMAT>	Output format: text, json, or dot (for Graphviz).
--max-depth <N>	Maximum directory depth when scanning for source files. Helps limit analysis to a specific subtree.

Example

cargo run -p icb-cli -- \
  --project ./my_project \
  --language cpp \
  --no-system-headers \
  --cache ./graph.cache \
  --cache-dir ./.icb_cache

The first run will parse everything and populate the caches. The second run will load unchanged files from the incremental cache and reuse the saved graph if --cache is provided, resulting in near‑instant startup.

icb‑server

The web server starts an HTTP API and serves the ICB dashboard. It can analyze a project at startup or dynamically load projects via the REST API end‑points.

cargo run -p icb-server -- [OPTIONS]

Server flags

Flag	Description
--project <PATH>	Optional. Path to a project directory to analyze at startup. If omitted, the server starts with an empty graph and projects can be loaded later via the /api/load or /api/upload endpoints.
--language <LANG>	Language of the initial project (default: python). Same values as the CLI.
--cache <PATH>	Path to a graph cache file (see CLI description). The server will try to load the graph from this file at startup and save it after building.
--cache-dir <DIR>	Directory for incremental per‑file fact caching (see CLI description). Highly recommended for large projects.
--no-system-headers	Exclude system header nodes from the graph (C/C++ Clang backend).
--port <PORT>	Port to listen on (default: 8080).
--static-dir <DIR>	Directory containing the frontend static files (default: web). Must contain an index.html file.
--compile-commands <PATH>	Same as CLI.
--cpp-std <STANDARD>	Same as CLI (default: c++17).
--max-depth <N>	Same as CLI – limit directory scan depth.

Example

cargo run -p icb-server -- \
  --project ../Vizora \
  --language cpp \
  --cache ./graph.cache \
  --cache-dir ./.icb_cache \
  --no-system-headers \
  --port 8080

When the server starts, open http://localhost:8080 in your browser. The dashboard will show an interactive call graph, function metrics, and cycle detection. You can load additional projects via the UI or REST API without restarting the server.

Server API (brief)

The server exposes the following REST end‑points under /api:

GET /api/graph	Subgraph filtered by kind, focus, depth, max nodes, cycle/dead highlights.
GET /api/node	Detailed information about a single function.
GET /api/functions	All function metrics.
GET /api/classes	All class metrics.
GET /api/files	Per‑file aggregate metrics.
GET /api/diff	Compare two projects or cached graphs.
POST /api/load	Load a new project, auto‑detecting its language.
POST /api/upload	Upload a ZIP archive and analyze it.

See the icb-server rustdoc for full details.