CLI Comparison

CLI Comparison

This page maps Arxo CLI commands to their MCP equivalents, helping you transition between the command-line interface and the MCP server.

---

Quick Reference

CLI Command	MCP Equivalent	Notes
arxo analyze	analyze_architecture	Full analysis
arxo analyze --preset ci	analyze_architecture({ preset: "ci" })	Preset support
arxo analyze --baseline main	analyze_with_baseline({ baseline_ref: "main" })	⚠️ Requires Pro
arxo doctor	check_cycles	Fast health check
arxo init	N/A	CLI only
arxo cache clear	N/A	Restart MCP server instead
arxo metrics list	list_presets	Lists presets, not individual metrics
arxo config validate	N/A	CLI only

---

Analysis Commands

Full Analysis

CLI:

arxo analyze

MCP:

analyze_architecture({ "project_path": "." })

Output:

• CLI: Human-readable text or JSON (with --format json)
• MCP: Always JSON with structured metrics and violations

---

Analysis with Preset

CLI:

arxo analyze --preset quick

MCP:

analyze_architecture({
  "project_path": ".",
  "preset": "quick"
})

Available presets: quick, ci, risk, coupling, security, runtime, ai, rag, full

---

Analysis with Custom Config

CLI:

arxo analyze --config custom-config.yaml

MCP:

analyze_architecture({
  "project_path": ".",
  "config_path": "/path/to/custom-config.yaml"
})

---

Baseline Comparison

CLI:

arxo analyze --baseline main

MCP:

analyze_with_baseline({
  "project_path": ".",
  "baseline_ref": "main"
})

Caution

The analyze_with_baseline tool currently requires the full arxo binary with git worktree support. It may return an error directing you to use the CLI instead.

---

Health Checks

Quick Cycle Check

CLI:

arxo doctor

MCP:

check_cycles({ "project_path": "." })

Output:

• CLI: Exit code 0 if no cycles, 1 if cycles detected
• MCP: JSON with { scc: { component_count, cycle_count, max_cycle_size, total_nodes_in_cycles }, violations_count }

---

LLM Integration Health

CLI:

arxo analyze --preset ai

MCP:

check_llm_integration({ "project_path": "." })

Difference:

• CLI: Runs the full ai preset (all AI/ML metrics)
• MCP: Focused on llm_integration metric only

---

Policy Enforcement

Evaluate Policy from Config

CLI:

arxo analyze --policy

MCP:

evaluate_policy({ "project_path": "." })

---

Evaluate Inline Policy

CLI:

echo "policy:
  invariants:
    - metric: scc.max_cycle_size
      op: '<='
      value: 0" > temp-policy.yaml

arxo analyze --config temp-policy.yaml --policy

MCP:

evaluate_policy({
  "project_path": ".",
  "policy_yaml": "policy:\n  invariants:\n    - metric: scc.max_cycle_size\n      op: '<='\n      value: 0"
})

---

Hotspots and Refactoring

Get Hotspots

CLI:

arxo analyze --preset risk --format json | jq '.findings'

MCP:

get_hotspots({ "project_path": "." })

Difference:

• CLI: Returns all findings from the risk preset
• MCP: Returns filtered hotspots with severity and evidence count

---

Refactoring Suggestions

CLI:

arxo analyze --preset risk --format json | jq '.recommendations'

MCP:

suggest_refactors({ "project_path": "." })

Caution

The suggest_refactors tool is currently a stub. Use the CLI for full refactoring recommendations.

---

File Impact Analysis

No Direct CLI Equivalent

MCP:

analyze_file_impact({
  "project_path": ".",
  "file_paths": ["src/core/auth.ts"]
})

CLI Workaround:

# Run full analysis and grep for the file
arxo analyze --format json | jq '.results[] | select(.evidence[]?.file | contains("auth.ts"))'

The MCP tool is more efficient because it runs incremental analysis for the specified files only.

---

Preset Discovery

List Presets

CLI:

arxo metrics list

MCP:

list_presets()

Output:

• CLI: Lists individual metrics
• MCP: Lists presets (groups of metrics)

---

Configuration

Initialize Config

CLI:

arxo init

MCP: No equivalent. Generate a config file using the CLI, then reference it in MCP tools.

---

Validate Config

CLI:

arxo config validate

MCP: No equivalent. The MCP server validates config implicitly when loading it for analysis.

---

Cache Management

Clear Cache

CLI:

arxo cache clear

MCP: Restart the MCP server. The cache is in-memory and cleared on restart.

---

View Cache Stats

CLI:

arxo cache stats

MCP: Enable debug logging and look for cache hit/miss messages:

[INFO] Cache hit for project: ...
[INFO] Cache miss, running analysis for project: ...

---

Output Formats

JSON Output

CLI:

arxo analyze --format json

MCP: All MCP tools return JSON by default.

---

Human-Readable Output

CLI:

arxo analyze

MCP: No equivalent. MCP tools return structured JSON. The AI assistant formats it for the user.

---

Report Generation

CLI:

arxo analyze --format html > report.html

MCP: No equivalent. Use the CLI for report generation.

---

Features Only Available in CLI

These features have no MCP equivalent:

Feature	CLI Command	Why MCP Doesn’t Support It
Config initialization	arxo init	One-time setup, not interactive
Report generation	arxo analyze --format html	MCP clients handle presentation
Cache persistence	arxo cache	MCP cache is in-memory
Shell completions	arxo completions	Client-specific
Git worktree creation	arxo analyze --baseline	Requires filesystem manipulation
Refactoring execution	Future CLI feature	MCP is read-only analysis

---

Features Only Available in MCP

These features have no direct CLI equivalent:

Feature	MCP Tool	Why CLI Doesn’t Support It
File-scoped impact analysis	analyze_file_impact	Designed for AI assistant context
Hotspot summarization	get_hotspots	CLI returns raw findings
Resource URIs	metrics://current/...	MCP-specific protocol

---

Workflow Comparison

Pre-Commit Hook (CLI)

#!/bin/bash
arxo doctor || exit 1
arxo analyze --preset ci --policy || exit 1

Pre-Commit Workflow (MCP)

The AI assistant runs:

1. check_cycles({ "project_path": "." })
2. evaluate_policy({ "project_path": "." })
3. Blocks commit if violations found

---

CI Pipeline (CLI)

- name: Architecture Analysis
  run: |
    arxo analyze --preset ci --baseline main --format json > analysis.json
    arxo analyze --policy || exit 1

CI Pipeline (MCP)

Not recommended. Use the CLI in CI for:

• Baseline comparison
• Report artifacts
• Policy gates with exit codes

Use MCP for interactive development workflows.

---

When to Use CLI vs MCP

Scenario	Use CLI	Use MCP
CI/CD pipeline	✅	❌
Pre-commit hooks	✅	❌
Interactive development (IDE)	❌	✅
AI assistant queries	❌	✅
One-time reports	✅	❌
Exploring codebase with AI	❌	✅
Baseline comparison	✅	⚠️ (Limited)
Policy evaluation	✅ Both	✅

---

Migration Tips

From CLI to MCP

1. Replace shell scripts with AI assistant workflows:

   • CLI: arxo doctor && arxo analyze --preset ci
   • MCP: Ask AI to “check for cycles and run CI preset”

2. Use resources for quick checks:

   • CLI: arxo analyze --format json | jq '.violations'
   • MCP: Read policy://violations/. resource

3. Let AI assistants handle formatting:

   • CLI: --format json, --format html
   • MCP: Tools return JSON, AI formats for user

From MCP to CLI

1. When you need baseline comparison:

   • MCP: analyze_with_baseline (limited support)
   • CLI: arxo analyze --baseline main

2. When you need reports:

   • MCP: No report generation
   • CLI: arxo analyze --format html

3. When you need persistent cache:

   • MCP: In-memory cache (cleared on restart)
   • CLI: Persistent cache in ~/.cache/arxo

---

Related Pages

• Tools — Full MCP tool reference
• Workflows — Common MCP workflows
• CLI Reference — Full CLI documentation
• Troubleshooting — Debugging MCP issues