@trace/cli

AI-Powered Web Debugging from the Terminal

Command-line interface for Trace, providing access to all 79 debugging tools. Analyze pages, find errors, check performance, and debug interactively - all from your terminal.

Installation

npm install -g @trace/cli

Or run with npx:

npx @trace/cli analyze https://example.com

Commands

trace analyze <url> - Analyze a page

# Basic analysis
trace analyze https://example.com

# Ask specific question
trace analyze https://example.com -q "Why is the page slow?"

# JSON output
trace analyze https://example.com --json

Options:

• -q, --query <query> - Specific question to ask
• --api-url <url> - API endpoint
• --api-key <key> - API key
• --headless / --no-headless - Browser visibility
• --json - Output as JSON
• -v, --verbose - Verbose output

trace debug <url> - Full debug scan

trace debug https://example.com

Runs a comprehensive debug scan checking console, network, DOM, and performance.

trace errors <url> - Get console errors

# Show errors
trace errors https://example.com

# JSON output
trace errors https://example.com --json

trace network <url> - Network analysis

# Full network summary
trace network https://example.com

# Failed requests only
trace network https://example.com --failed

# JSON output  
trace network https://example.com --json

trace perf <url> - Performance metrics

trace perf https://example.com

Shows:

• DOM Content Loaded time
• First Contentful Paint
• JS Heap Size
• DOM Nodes count
• Layout count
• Performance issues

trace a11y <url> - Accessibility check

trace a11y https://example.com

Finds accessibility issues like:

• Missing alt text
• Low contrast
• Missing labels
• Keyboard issues

trace health <url> - Quick health check

# Check health (exits with code 1 if unhealthy)
trace health https://example.com

# Use in CI
trace health https://example.com || echo "Site has issues!"

trace inspect <url> <selector> - Inspect element

trace inspect https://example.com "#my-button"

Shows:

• Element info (tag, id, class)
• Visibility status
• Box model dimensions

trace tool <url> <toolName> - Run specific tool

# Run any of the 79 tools
trace tool https://example.com get_console_errors
trace tool https://example.com get_performance_metrics
trace tool https://example.com inspect_element -i '{"selector": "#app"}'

trace tools - List all tools

trace tools

Lists all 79 available debugging tools by category.

trace screenshot <url> [output] - Take screenshot

# Default filename
trace screenshot https://example.com

# Custom filename
trace screenshot https://example.com page.png

trace watch <url> - Real-time monitoring

# Watch for 30 seconds
trace watch https://example.com

# Watch for 60 seconds
trace watch https://example.com -d 60

Monitors console errors and failed network requests in real-time.

trace repl <url> - Interactive session

trace repl https://example.com

Opens an interactive debugging session with commands:

Commands:
  /debug       - Full debug scan
  /errors      - Get console errors
  /network     - Network summary
  /perf        - Performance metrics
  /a11y        - Accessibility check
  /tool <name> - Run a specific tool
  /eval <expr> - Evaluate JavaScript
  /nav <url>   - Navigate to URL
  /reload      - Reload page
  /screenshot  - Take screenshot
  /help        - Show all commands
  /exit        - Exit REPL

Or just type a question to ask the AI!

Example REPL session:

trace> /errors
[]

trace> Why is the page loading slowly?
🔄 Analyzing...

📊 Analysis Results
─────────────────────────

Summary:
  The page has 3 performance issues...

Issues (3):
  🟠 [HIGH] Large JavaScript Bundle
     The main.js file is 2.5MB uncompressed
     Fix: Enable code splitting and tree shaking

trace> /perf
{
  "DOMContentLoaded": 1234,
  "FirstContentfulPaint": 2100,
  ...
}

trace> /exit

CI/CD Integration

GitHub Actions

- name: Check site health
  run: |
    npx @trace/cli health https://myapp.com
    
- name: Run debug analysis
  run: |
    npx @trace/cli analyze https://myapp.com --json > debug-report.json

Exit Codes

• 0 - Success / Healthy
• 1 - Errors found / Unhealthy

Configuration

Environment Variables

export TRACE_API_URL="https://your-api.com"
export TRACE_API_KEY="your-key"

API Key

trace analyze https://example.com --api-key YOUR_KEY

All 79 Tools

Run trace tools to see all available tools:

Console (6): get_console_logs, get_console_errors, get_error_groups, get_exception_details, clear_console, get_log_count

Network (10): get_network_requests, get_network_failed, get_network_summary, get_request_details, get_cached_requests, get_request_timing, get_request_body, get_response_body, get_redirect_chain, replay_request

DOM (16): inspect_element, get_element_styles, get_element_box_model, query_selector, get_dom_tree, get_element_attributes, get_element_events, analyze_visibility, get_element_accessibility, check_accessibility, highlight_element, scroll_to_element, get_element_screenshot, get_computed_style, get_element_hierarchy, measure_element

Debugger (24): get_debug_state, set_breakpoint, remove_breakpoint, get_breakpoints, set_conditional_breakpoint, set_logpoint, pause_execution, resume_execution, step_over, step_into, step_out, get_call_stack, get_scope_variables, get_variable_value, set_variable_value, evaluate_expression, evaluate_on_frame, get_this_object, add_watch, remove_watch, get_watches, enable_debugger, disable_debugger, get_possible_breakpoints

Source (8): get_scripts, get_script_source, search_scripts, get_script_parsed, set_script_source, blackbox_script, unblackbox_script, get_script_coverage

Performance (4): get_performance_metrics, start_performance_profile, stop_performance_profile, get_heap_snapshot

Timeline (5): get_timeline_events, start_timeline, stop_timeline, get_event_listeners_timeline, take_timeline_snapshot

Tracing (3): start_trace, stop_trace, get_trace_events

License

MIT