CLI Reference

Command-line interface for querying sessions, analyzing costs, debugging agents, and managing operations.

Global Options

All commands accept these options:

Configuration

agentlens config show              # Show current config
agentlens config set <key> <value> # Set a config value
agentlens config unset <key>       # Remove a config value
agentlens config reset             # Reset to defaults
agentlens config path              # Print config file path

Set endpoint and api_key to avoid passing them on every command:

agentlens config set endpoint http://localhost:3000
agentlens config set api_key your-secret-key

Session Commands

List Sessions

agentlens sessions [--limit N]

Session Detail

agentlens session <session_id>

Session Costs

agentlens costs <session_id>

List Events

agentlens events [--session SESSION] [--type TYPE] [--model MODEL] [--limit N]

Export Session

agentlens export <session_id> [--format json|csv] [--output FILE]

Analysis Commands

Analytics Overview

agentlens analytics

Health Score

agentlens health <session_id>

Compare Sessions

agentlens compare <session_a> <session_b>

Session Diff

agentlens diff <session_a> <session_b> [--label-a LABEL] [--label-b LABEL] [--no-color] [--json]

Agent Profile

agentlens profile <agent_name> [--days N] [--json]

Trends

agentlens trends [--period day|week|month] [--metric METRIC|all] [--agent NAME] [--limit N] [--json]

Correlation Analysis

agentlens correlate [--metrics METRICS] [--limit N] [--min-sessions N] [--format table|json|csv] [--output FILE]

Leaderboard

agentlens leaderboard [--sort efficiency|speed|reliability|cost|volume] [--days N] [--limit N] [--min-sessions N] [--order asc|desc] [--json]

Bottleneck Detection

agentlens bottleneck [--by agent|model|type] [--metric latency|cost|errors] [--limit N] [--min-sessions N] [--format table|json] [--output FILE]

Outlier Detection

agentlens outlier [--metric cost|tokens|duration|errors|all] [--limit N] [--threshold F] [--format table|json] [--top N]

Visualization Commands

Flamegraph

agentlens flamegraph <session_id> [--output FILE] [--open] [--stats]

Generates an interactive HTML flamegraph of a session's event hierarchy.

Gantt Chart

agentlens gantt <session_id> [--output FILE] [--open] [--format html|json|ascii]

Heatmap

agentlens heatmap [--metric sessions|cost|tokens|events] [--weeks N] [--limit N]

Scatter Plot

agentlens scatter [--x METRIC] [--y METRIC] [--limit N] [--width W] [--height H] [--agent NAME] [--no-trend] [--format ascii|json] [--output FILE]

Trace View

agentlens trace <session_id> [--no-color] [--json] [--type TYPE] [--min-ms N]

Session Replay

agentlens replay <session_id> [--speed N] [--type TYPES] [--exclude TYPES] [--format text|json|markdown] [--live] [--no-color] [--output FILE]

Event Funnel

agentlens funnel [--stages TYPES] [--limit N] [--format table|json|html] [--output FILE] [--open]

Dependency Map

agentlens depmap [--limit N] [--format ascii|json|html] [--output FILE] [--open]

Monitoring Commands

Live Tail

agentlens tail [--session SESSION] [--type TYPE] [--interval SECS]

Streams events in real-time (like tail -f).

Top (Live Dashboard)

agentlens top [--sort cost|tokens|events] [--limit N] [--interval SECS]

Live-updating view of the most active/expensive sessions.

Watch

agentlens watch [--interval SECS] [--metric METRIC] [--agent NAME] [--alert-threshold N] [--compact] [--no-spark] [--duration MINS]

Continuous metric monitoring with spark lines and threshold alerts.

Status

agentlens status

Check backend connectivity and database stats.

Cost & Budget Commands

Cost Forecast

agentlens forecast [--days N] [--metric cost|tokens|sessions] [--model MODEL] [--format table|json|chart] [--output FILE]

Budget Management

agentlens budget list [--json]
agentlens budget set <scope> <period> <limit_usd> [--warn-pct N]
agentlens budget check <session_id> [--json]
agentlens budget delete <scope> [<period>]

Scope can be global or an agent name. Period is daily, weekly, or monthly.

Alert Commands

agentlens alert history [--severity LEVEL] [--since HOURS] [--limit N] [--ack|--unack] [--format table|json]
agentlens alert rules [--format table|json]
agentlens alert test <rule_id> <session_id>
agentlens alert ack <alert_id> [--note TEXT]
agentlens alert silence <rule_id> [--duration MINUTES]
agentlens alert unsilence <rule_id>
agentlens alert stats [--period day|week|month] [--format table|json]

SLA Commands

agentlens sla [--policy production|development] [--latency MS] [--error-rate PCT] [--token-budget N] [--slo PCT] [--agent NAME] [--limit N] [--verbose] [--json]

Built-in policies: production (strict) and development (relaxed). Override individual thresholds with flags.

Reporting Commands

Summary Report

agentlens report [--period day|week|month] [--format table|json|markdown] [--output FILE]

Digest

agentlens digest [--period day|week|month] [--format text|markdown|html|json] [--output FILE] [--open] [--top N]

Dashboard (HTML)

agentlens dashboard [--limit N] [--output FILE] [--open]

Generates a standalone HTML dashboard.

Operational Commands

Audit Log

agentlens audit [ENTRY_ID] [--agent NAME] [--action TYPE] [--severity LEVEL] [--model MODEL] [--session ID] [--since HOURS] [--limit N] [--format table|csv|json] [--output FILE] [--stats] [--no-color]

Postmortem

agentlens postmortem <session_id>
agentlens postmortem candidates [--min-errors N] [--limit N]

Snapshots

agentlens snapshot [--label LABEL] [--output FILE] [--limit N] [--format json|table]
agentlens snapshot diff <file_a> <file_b> [--format table|json]

Baseline Management

agentlens baseline list [--json]
agentlens baseline show <agent_name> [--json]
agentlens baseline record <session_id>
agentlens baseline check <session_id> [--json]
agentlens baseline delete <agent_name>

Data Retention

agentlens retention [--limit N] [--format table|json|chart] [--output FILE] [--open]
agentlens retention policy [--keep-days N] [--dry-run] [--json]
agentlens retention purge --older-than DAYS [--dry-run] [--yes]

Examples

# Quick health check
agentlens status

# See today's most expensive sessions
agentlens leaderboard --sort cost --days 1

# Debug a slow session
agentlens trace sess_abc123 --min-ms 500
agentlens flamegraph sess_abc123 --open

# Set a daily budget and check it
agentlens budget set global daily 50.00 --warn-pct 80
agentlens budget check sess_abc123

# Monitor agents in real-time
agentlens watch --metric cost --alert-threshold 10

# Generate a weekly report
agentlens digest --period week --format markdown --output weekly.md