analyze

analyze

Analyze a codebase to compute architecture metrics, detect issues, and generate reports.

Output format and quiet mode are global options: use --format and --quiet with any command.

Basic Usage

arxo analyze --path ./my-project

arxo analyze --repo https://github.com/user/repo

arxo analyze --preset ci --fail-fast

arxo analyze --quick

Output format and file

• --format (global) — Chooses report format: console, json, html, snapshot, sarif, or msgpack. Default is console.
• --output — Optional file path to write the report (used with json, html, snapshot, or sarif).
• --json — Shortcut for --format json; output results as JSON.

To write a JSON report to a file: arxo analyze --format json --output report.json or arxo analyze --json --output report.json.

Parameters

Parameter	Description
--path	Path to project directory (default: current directory)
--repo	Git repository URL to analyze
--ref	Git reference (branch, tag, or commit) when using --repo
--config	Path to configuration YAML file
--preset	Run metrics from preset (quick, ci, risk, coupling, security, runtime, full)
--quick	Shortcut for --preset quick
--output	Write report to file (use with --format json/html/snapshot/sarif)
--json	Shortcut for --format json
--fail-fast	Stop on first policy violation (for CI)
--baseline	Compare metrics against baseline ref (e.g. main)
--metric	Run only these metrics by ID; repeatable (e.g. --metric scc --metric propagation_cost)
--only-changed [REF]	Only report context for files changed vs ref (default: HEAD)
--no-cache	Bypass clone cache and clone fresh (with --repo)
--no-analysis-cache	Disable analysis cache for this run only
--clear-cache	Clear analysis cache before running
--metric-timings	Include per-metric run time in report
--estimated-timings	Show estimated run time for metrics in console
--list-presets	Print preset names and descriptions, then exit
--report-timings	Emit one-line JSON build timings (CPU/memory) to stderr after report
--open-browser	Open HTML report in default browser after run
--interactive	Prompt for path, preset, and save-to-file (TTY only)
--sandbox	(Linux only) Restrict engine with Landlock: read-only project, writable cache only, no network. Best-effort; ignored on macOS/Windows.

Sandbox (Linux)

On Linux you can run the engine in a Landlock self-sandbox so it cannot access anything except the project directory (read-only) and the cache directory:

arxo analyze --path . --sandbox

The engine restricts itself before any file I/O:

• Project path — Read-only (canonicalized).
• Cache — Only ~/.cache/arxo (or ARCH0_CACHE_DIR) is writable.
• System — Read access to /usr, /lib, /etc, etc. for runtime.
• Network — Not allowed when the kernel supports Landlock ABI v4+.

If Landlock is unavailable (e.g. kernel < 5.13), the run continues without sandbox and a message is printed. On macOS and Windows, --sandbox is accepted but has no effect.

Use --sandbox when you want to verify that the engine cannot read or write outside the project and cache, or when analyzing untrusted code.

Docker (cross-platform)

Run Arxo in a sandboxed container with no network access and read-only filesystem. Works on any host (Linux, macOS, Windows) with Docker:

docker run --rm --read-only --network=none --cap-drop=ALL \
  --security-opt=no-new-privileges \
  -v $(pwd):/workspace:ro -v /tmp/arxo-cache:/home/arxouser/.cache:rw \
  arxo/arxo analyze --path /workspace

Or use the helper script: ./releases/docker/run-sandboxed.sh analyze --path .

Security flags: --read-only (container FS), --network=none, --cap-drop=ALL, --security-opt=no-new-privileges. See releases/docker/README.md for full details.

Examples

CI Pipeline

arxo analyze --preset ci --fail-fast --quiet

Output JSON Report

arxo analyze --path . --format json --output report.json

Compare Against Main Branch

arxo analyze --path . --baseline main

Only Changed Files (e.g. PR)

arxo analyze --only-changed origin/main
arxo analyze --preset ci --only-changed HEAD~1

Interactive Mode

arxo analyze --interactive

Prompts for path, preset, and save-to-file when run in a TTY.

Sandboxed Analysis (Linux)

arxo analyze --path . --sandbox
arxo analyze --path . --preset ci --sandbox --quiet

Restricts the engine with Landlock on Linux; ignored on other platforms.

Sandboxed Analysis (Docker, cross-platform)

./releases/docker/run-sandboxed.sh analyze --path . --format json
docker run --rm --read-only --network=none --cap-drop=ALL \
  -v $(pwd):/workspace:ro -v /tmp/arxo-cache:/home/arxouser/.cache:rw \
  arxo/arxo analyze --path /workspace

Exit codes and errors

Exit code	Meaning
0	Analysis completed; no policy violations (or violations reported but not fatal)
Non-zero	Analysis failed or policy violation with --fail-fast

Common failures: invalid or missing --path, config not found or invalid YAML, unknown preset, or (with --repo) clone or ref errors. For diagnostics, run arxo doctor and arxo config validate. See Troubleshooting for more.

See also

• Output formats — JSON, HTML, snapshot, SARIF, msgpack
• CI integration — Pipelines and --fail-fast
• Presets — quick, ci, risk, coupling, full
• Breaking cycles — Using --only-changed to verify progress
• Remote analysis — --repo and --ref
• Architecture overview: Security & Privacy — Local-only analysis, Landlock and Docker sandbox
• MCP: analyze_architecture — CLI equivalent from MCP