analyze

analyze

Analyze a codebase to compute architecture metrics (agent_architecture, openclaw_architecture), 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

arxo analyze --config arxo.yaml --fail-fast

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

Output format and file

• --format (global) — Report format: console, json, or html. Default is console.
• --output — Optional file path to write the report (used with json or html).
• --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)
--config	Path to configuration YAML file
--output	Write report to file (use with --format json or html)
--json	Shortcut for --format json
--fail-fast	Stop on first policy violation (for CI)
--metric	Run only these metrics by ID; repeatable (e.g. --metric agent_architecture)
--analysis-cache	Enable analysis cache (off by default)
--clear-cache	Clear analysis cache before running
--open-browser	Open HTML report in default browser after run
--interactive	Prompt for path 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 --fail-fast --quiet

Output JSON Report

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

Interactive Mode

arxo analyze --interactive

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

Sandboxed Analysis (Linux)

arxo analyze --path . --sandbox
arxo analyze --path . --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
Non-zero	Analysis failed or policy violation with --fail-fast

Common failures: invalid or missing --path, config not found or invalid YAML. For diagnostics, run arxo doctor and arxo config validate. See Troubleshooting for more.

See also

• Output formats — Console, JSON, HTML
• CI integration — Pipelines and --fail-fast
• Running Analysis — Config and defaults
• MCP: analyze_architecture — CLI equivalent from MCP