Usage Guide

Usage Guide

Two Ways to Use BGP Explorer

Option 1: Standalone Chat (API Key Required)

uv run bgp-explorer chat

This starts an interactive session using your Anthropic API key. All tools including real-time monitoring.

Option 2: Claude Code Integration (No API Key)

claude mcp add bgp-explorer -- bgp-explorer mcp
claude

Use BGP tools with your Claude Code subscription. 8 composite tools available. See Claude Code Integration for details.

---

CLI Commands

Start Interactive Chat

uv run bgp-explorer chat

This starts an interactive session where you can ask questions in natural language.

Assess Network Resilience

uv run bgp-explorer assess <asn>

Assess network resilience for any ASN directly from the command line (no API key required).

Example:

$ uv run bgp-explorer assess 15169

🛡️ Network Resilience Assessment: AS15169 (GOOGLE)

Overall Score: 10.0/10 🟢

Component Scores:
  Transit Diversity: 10.0/10 (10 upstreams)
  Peering Breadth:   10.0/10 (500+ peers)
  IXP Presence:      10.0/10 (150+ IXPs)
  Path Redundancy:   10.0/10

✅ No critical issues found

Start MCP Server

uv run bgp-explorer mcp

Start the MCP server for Claude Code integration. See Claude Code Integration for details.

Install Dependencies

uv run bgp-explorer install-deps

Auto-install Go, Rust, bgp-radar, and monocle dependencies.

---

Chat Mode Options

uv run bgp-explorer chat [OPTIONS]

Option	Description	Default
--model [sonnet|opus]	Claude model tier	sonnet
--api-key TEXT	Anthropic API key	env variable
--bgp-radar-path TEXT	Path to bgp-radar binary	PATH lookup
--collectors TEXT	Comma-separated RIS collectors	rrc00
--output [text|json|both]	Output format	text
--save PATH	Save conversation to file	-
--thinking-budget INT	Max tokens for AI thinking (1024-16000)	8000

Examples

# Basic usage
uv run bgp-explorer chat

# Use opus model with higher thinking budget
uv run bgp-explorer --model opus --thinking-budget 12000 chat

# Save output and use multiple collectors
uv run bgp-explorer --save output.txt --collectors rrc00,rrc01 chat

# JSON output for scripting
uv run bgp-explorer --output json chat

Interactive Commands

During a chat session, use these commands:

Command	Description
/monitor start	Start real-time BGP monitoring
/monitor stop	Stop monitoring
/monitor status	Check monitoring status
/thinking [budget]	View or set AI thinking budget
/export [path]	Export conversation to JSON
/clear	Clear conversation history
/help	Show help message
exit	Exit the application

Monitoring Commands

> /monitor start
BGP Monitoring Started
Now watching for anomalies from collectors: rrc00
Events (hijacks, route leaks, blackholes) will be displayed in real-time.

> /monitor status
Monitoring: Active
Collectors: rrc00
Events detected: 3

> /monitor stop
BGP Monitoring Stopped

Thinking Budget Commands

> /thinking
Current thinking budget: 8000 tokens

> /thinking 12000
Thinking budget set to 12000 tokens

Export Command

> /export
Conversation exported to: bgp-explorer-conversation-2024-01-15.json

> /export /path/to/custom.json
Conversation exported to: /path/to/custom.json

Asking Questions

BGP Explorer understands natural language. Here are some patterns:

Direct Lookups

> Who originates 8.8.8.0/24?
> What prefixes does AS15169 announce?
> Give me details about AS13335

By Company Name

> Show me Google's prefixes
> What are Cloudflare's upstream providers?
> Find ASNs for Microsoft

Analysis Questions

> Analyze the AS paths to 1.1.1.0/24
> Compare how different collectors see 8.8.8.0/24
> Is this prefix being hijacked?

Investigation Questions

> Our customers can't reach 203.0.113.0/24 - what's happening?
> Why is traffic taking weird paths to 8.8.8.0/24?
> Should we peer with AS64496?

Understanding Output

Thinking Summaries

Before each response, you'll see a brief summary of Claude's reasoning:

[Thinking: Looking up prefix 8.8.8.0/24 to find origin ASN,
checking RPKI validation status, analyzing path diversity...]

**Prefix: 8.8.8.0/24**
Origin ASN: AS15169 (Google)
RPKI Status: ✅ Valid
...

Tool Status Messages

When Claude calls tools, you'll see status updates:

Looking up prefix 8.8.8.0/24...
Getting details for AS15169...
Validating RPKI for 8.8.8.0/24...

Risk Indicators

Security-related output uses visual indicators:

Indicator	Meaning
✅	Valid/OK
❌	Invalid/Problem
❓	Unknown/Not found
⚠️	Warning/Attention needed

Next Steps

• Examples - See detailed example queries
• Tools Reference - Learn about available tools
• Real-time Monitoring - Set up anomaly detection