Statistics
Launch an interactive analytics dashboard that reveals how you use your shell — top commands, success rates, busiest hours, and more.
Quick Start
Run suv stats with no arguments to open the full interactive analytics dashboard covering the last 7 days of shell activity.
suv statsWhat the Dashboard Shows
The statistics dashboard aggregates your shell history into several insight panels. Every metric is computed locally from your SQLite database — nothing leaves your machine.
Summary Metrics
- Total commands — the number of commands recorded in the selected time window.
- Unique commands — the number of distinct command strings, ignoring duplicates.
- Success rate — percentage of commands that exited with code 0.
- Average duration — mean execution time across all recorded commands.
Top Commands
A ranked list of your most frequently used commands. By default the top 10 are shown; use -n to adjust. Each entry includes the command string and its run count.
Busiest Hours
A histogram showing which hours of the day you run the most commands. Useful for spotting productivity patterns or audit windows.
Top Directories
The working directories where you spend the most time, ranked by command count. Helps identify your most active projects.
Executor Breakdown
A breakdown of commands by executor type — human, agent, ide, or ci. Shows how much of your shell activity comes from AI agents versus manual work.
Flags
| Flag | Description |
|---|---|
-d, --days <N> | Number of days of history to include. Defaults to 7. |
-n, --top <N> | Number of top commands to display. Defaults to 10. |
--text | Output the dashboard as plain text instead of the interactive TUI. Useful for piping or logging. |
--json | Output all statistics as a JSON object. Ideal for scripts, automation, or feeding data into other tools. |
--tag | Filter statistics to commands associated with a specific tag. Combine with other flags for scoped insights. |
Examples
Last 30 days of stats
View a broader time window to spot monthly trends.
suv stats --days 30Top 5 commands as plain text
Output a concise text summary showing only the top 5 commands — great for embedding in reports or piping to other tools.
suv stats --top 5 --textMachine-readable JSON output
Export the full statistics payload as JSON for scripting, dashboards, or integration with monitoring tools.
suv stats --jsonStats filtered by tag
Scope statistics to a specific tag. For example, see stats for only your "work" sessions.
suv stats --tag workCombining flags
Flags compose freely. Get the top 3 commands from the last 14 days for sessions tagged "deploy", output as plain text.
suv stats --days 14 --top 3 --tag deploy --textHow It Works
The suv stats command queries your local SQLite history database directly. All aggregation — counts, averages, groupings, and histograms — is performed via SQL on your machine. No data is sent anywhere. The interactive dashboard renders in your terminal using a TUI; the --text and --json flags bypass the TUI for scriptable output.
suv stats --tag with tags and auto-tagging rules to get per-project or per-environment analytics without any manual work.