Interactive Mode

Interactive mode provides a guided, prompt-based workflow for running architecture analysis. Perfect for beginners, exploratory analysis, or when you don’t remember all the CLI options.

Overview

Instead of memorizing flags and options, interactive mode asks you questions:

arxo analyze --interactive

What it prompts for:

Project path - Directory to analyze
Analysis preset - Which preset to use (quick, ci, risk, etc.)
Output file - Where to save results (optional)

Getting Started

Basic Interactive Analysis

arxo analyze --interactive

Example session:

🔍 Arxo Interactive Analysis

? Select project directory:
  > . (current directory)
    Browse...
    Enter path manually

? Select analysis preset:
  > quick       - Fast feedback (1-5s)
    ci          - CI/CD checks (10-30s)
    risk        - Technical debt audit (30-60s)
    coupling    - Dependency analysis (30-60s)
    security    - Security review (30-90s)
    runtime     - Operational analysis (requires telemetry)
    ai          - AI/LLM projects (30-60s)
    full        - Comprehensive (2-5min)

? Save report to file?
  > No, display in terminal
    Yes, save as JSON
    Yes, save as HTML
    Yes, save as YAML snapshot

🚀 Starting analysis...
✓ Parsed 247 files
✓ Built import graph (183 nodes, 412 edges)
✓ Computed 8 metrics

📊 Results:
...

Features

1. Smart Path Selection

Interactive mode offers multiple ways to select the project:

Option 1: Current Directory

? Select project directory:
  > . (current directory)

Option 2: Browse Filesystem

? Select project directory:
    . (current directory)
  > Browse...

Opens a file browser to select a directory.

Option 3: Manual Entry

? Select project directory:
    . (current directory)
    Browse...
  > Enter path manually

? Enter project path: /path/to/my-app

2. Preset Descriptions

Each preset shows:

Name - Preset identifier
Description - What it does
Speed - Estimated runtime

? Select analysis preset:
  > quick       - Fast feedback (1-5s)
                  Metrics: SCC, L1 Overview

    ci          - CI/CD checks (10-30s)
                  Metrics: SCC, Propagation Cost, Smells, Hierarchy

    risk        - Technical debt audit (30-60s)
                  Metrics: SCC, Propagation Cost, Smells, Centrality,
                           MSR, Change Coupling

3. Output Format Selection

Choose how to view results:

? Save report to file?
  > No, display in terminal
    Yes, save as JSON          → report.json
    Yes, save as HTML          → report.html
    Yes, save as YAML snapshot → report.yaml
    Yes, save as SARIF         → report.sarif
    Yes, save as MessagePack   → report.mpk

Custom filename:

? Save report to file?
    No, display in terminal
  > Yes, save as JSON

? Output filename: my-analysis.json

4. Configuration Detection

If .arxo.yaml exists in the project:

✓ Found configuration: .arxo.yaml

? Use existing config or select preset?
  > Use .arxo.yaml config
    Ignore config, use preset

Use Cases

1. First-Time User

Scenario: New to Arxo, want to explore

arxo analyze --interactive

Select current directory (.)
Choose quick preset
Display in terminal
Review results
Re-run with risk or full for deeper analysis

2. Evaluating a New Project

Scenario: Downloaded a project, want quick assessment

cd ~/Downloads/new-project
arxo analyze --interactive

Current directory is auto-selected
Choose quick for fast overview
Save as HTML to share with team

3. Comparative Analysis

Scenario: Compare multiple projects

arxo analyze --interactive

Run multiple times:

First run: Select project-a/, preset coupling, save as project-a.json
Second run: Select project-b/, preset coupling, save as project-b.json
Compare: Use jq to compare results

4. No Config File

Scenario: Quick analysis without creating config

# Instead of:
arxo analyze --preset ci --format json --output report.json

# Use interactive mode:
arxo analyze --interactive

Faster for one-off analysis.

5. Teaching/Demos

Scenario: Teaching Arxo to team members

Interactive mode is self-documenting:

Shows all available presets
Explains what each preset does
Guides through output options

Keyboard Shortcuts

During interactive prompts:

Key	Action
`↑` / `↓`	Navigate options
`Enter`	Select option
`Space`	Toggle checkbox (multi-select)
`Ctrl+C`	Cancel and exit
`Ctrl+D`	Cancel and exit
`/`	Search/filter (in long lists)

Advanced Usage

Skip Prompts with Flags

You can pre-fill some answers:

# Pre-select path, prompt for preset and output
arxo analyze --interactive --path ./my-project

# Pre-select path and preset, prompt for output only
arxo analyze --interactive --path ./my-project --preset ci

# Pre-select everything (no prompts)
arxo analyze --path ./my-project --preset ci --output report.json

When does interactive mode activate?

Explicit: --interactive flag
Implicit: Missing required arguments (not in all versions)

Multi-Select (Advanced)

Some prompts support multi-select:

? Select metrics to run:
  ◉ scc
  ◯ propagation_cost
  ◉ centrality
  ◯ modularity
  ◯ smells

(Use Space to toggle, Enter to confirm)

Access multi-select:

arxo analyze --interactive --custom-metrics

Configuration Wizard

Interactive mode can generate config files:

arxo init --interactive

Prompts:

Project type (TypeScript, Python, Rust, etc.)
Analysis goals (CI, security, coupling, etc.)
Policy strictness (Strict, Moderate, Lenient)
Output preferences

Generates: .arxo.yaml with recommended settings

Comparison with CLI Flags

Task	Interactive Mode	CLI Flags
New users	✅ Beginner-friendly	❌ Must learn flags
Speed	⏱️ Slower (prompts)	⚡ Faster (direct)
Discoverability	✅ Shows all options	❌ Must read docs
Automation	❌ Not scriptable	✅ Fully scriptable
Memory	✅ No flags to remember	❌ Must remember flags
CI/CD	❌ Not suitable	✅ Perfect for CI

Recommendation:

Development/Exploration: Use --interactive
Scripts/CI/CD: Use explicit flags

Troubleshooting

Terminal Not Supported

Error: “Interactive mode not supported in this terminal”

Cause: Running in non-interactive environment (CI, cron, etc.)

Solution: Use explicit flags:

arxo analyze --preset ci --format json

Prompt Doesn’t Appear

Issue: Hangs after running --interactive

Causes:

Stdin not connected: Redirected input
Terminal emulator: Some terminals don’t support interactive prompts

Solutions:

Check stdin:

# ❌ Won't work
echo "" | arxo analyze --interactive

# ✅ Works
arxo analyze --interactive

Use explicit flags:
Terminal window
```
arxo analyze --path . --preset quick
```

Slow Browsing

Issue: File browser is slow

Solution: Enter path manually:

? Select project directory:
  > Enter path manually

Can’t Find Project

Issue: Project not listed in browse mode

Solution: Use absolute path:

? Enter project path: /full/path/to/project

Examples

Example 1: Quick Health Check

$ arxo analyze --interactive

? Select project directory: . (current directory)
? Select analysis preset: quick
? Save report to file? No, display in terminal

✓ Analysis complete!
✓ No circular dependencies
✓ System coupling: 0.12 (good)

Example 2: Generate HTML Report

$ arxo analyze --interactive

? Select project directory: ./frontend
? Select analysis preset: risk
? Save report to file? Yes, save as HTML
? Output filename: risk-report.html

✓ Report saved to: risk-report.html

$ open risk-report.html

Example 3: Security Audit

$ arxo analyze --interactive

? Select project directory: Browse...
  [File browser opens]
  Selected: /path/to/api-service

? Select analysis preset: security
? Save report to file? Yes, save as JSON
? Output filename: security-audit.json

✓ Analysis complete
⚠️ 3 policy violations detected
✓ Report saved to: security-audit.json

Example 4: Custom Metrics (Advanced)

$ arxo analyze --interactive --custom-metrics

? Select project directory: .
? Select metrics to run:
  ◉ scc
  ◉ propagation_cost
  ◉ smells
  ◯ hierarchy
  ◯ modularity

? Save report to file? Yes, save as JSON

✓ Running 3 metrics...

Tips and Best Practices

1. Start with Quick Preset

For new projects:

arxo analyze --interactive
# Choose "quick" first
# Then re-run with "risk" or "full" if needed

HTML reports are self-contained and easy to share:

arxo analyze --interactive
# Choose "Yes, save as HTML"
# Email/Slack the HTML file to team

3. Use for Teaching

Interactive mode is self-documenting:

Team onboarding: Walk through options together
Workshops: Demonstrate each preset
Documentation: Screenshot the prompts

4. Combine with Config Files

Best of both worlds:

# Create config with interactive wizard
arxo init --interactive

# Run analysis with interactive preset selection
arxo analyze --interactive
# Choose "Use .arxo.yaml config"

5. Bookmark Common Workflows

Create shell aliases:

# ~/.bashrc or ~/.zshrc
alias arxoi='arxo analyze --interactive'
alias arxoq='arxo analyze --preset quick'
alias arxor='arxo analyze --preset risk --format html'

Usage:

arxoi           # Interactive mode
arxoq           # Quick check
arxor           # Risk report (HTML)

Scripting with Interactive Mode

While interactive mode isn’t designed for automation, you can use expect or yes for demos:

Using `yes` (Limited)

# Auto-select first option for all prompts (not recommended)
yes "" | arxo analyze --interactive

Using `expect` (Advanced)

#!/usr/bin/expect -f

spawn arxo analyze --interactive

# Select current directory
expect "Select project directory:"
send "\r"

# Select "quick" preset
expect "Select analysis preset:"
send "\r"

# Don't save to file
expect "Save report to file?"
send "\r"

expect eof

Note: For real automation, use CLI flags instead.