Operating modes

visao ships as a single binary that operates in one of two modes. Each invocation selects the mode, and one binary covers both modes.

• Console mode (default): one-shot CLI. Pass a list of files (or a compile_commands.json), the analyser writes findings to the terminal, the process exits. Best fit for git hooks, CI jobs, local “what did I break?” runs, ad-hoc cross-target probing.

• Server mode (--server <url>): long-lived service that speaks the Analysis Server Protocol (ASP) over NNG REQ/REP sockets. Clients explicitly manage workspaces and analyses, reuse the in-memory toolchain pool, and stream state updates as long-running jobs progress. Best fit for IDE integrations, desktop GUIs, “background analyzer” daemons, batch services that analyse hundreds of files per minute.

Which one to pick

Concern	Console	Server
Startup cost paid per file	Yes (one cold load per run)	No (load once, serve N requests)
Toolchain probe cost	Cached across runs on disk	Cached on disk and kept hot in process memory
Output channel	stdout/stderr, structured for humans	JSON responses on a socket
Persistence of results	None — re-run to re-see	Optional MongoDB backend (--enable-database, requires ENABLE_DAL build)
Concurrency model	Single analyzer thread, parallel parsing inside	In-tree actor framework: NetworkReceiver → RequestProcessor → AnalysisWorker(s) → ResponseSender; see Server mode
Cancellation	SIGINT kills the process	Per-analysis AnalysisDestroy request; SIGINT drains and shuts down cleanly with --server-graceful
Typical client	You at a shell, CI runner	IDE plug-in, GUI, daemon — usually through libasp
Multiple endpoints	One process, one run	Multiple --server flags bind multiple endpoints in one process, sharing state

Both modes share the same toolchain pool. They also share the same language plugins, the same analysis domains, and the CLI options that apply to both modes.

Mode-specific flags

Server-only:

--server <url>

Bind here. Repeatable.

--server-max-analyses <N>

Concurrent-worker cap.

--server-response-tick-ms <N>

Sender drain interval.

--server-log-traffic

Log every Request/Response.

--server-graceful / --server-no-graceful

SIGINT handling.

Console-only:

Positional file list and compile_commands.json

Input files for one-shot analysis.

--dep-graph-out, --dep-graph-out-png

Dependency-graph artefacts.

For the full inventory see CLI reference. The mode-specific pages walk through each mode hands-on:

• Console mode covers the output structure, the common flags and the use notes.

• Server mode covers the actor architecture, the tuning flags and libasp.