Suvadu CLI Documentation

Suvadu is a shell history replacement and AI agent memory tool, built in Rust with SQLite. It records every command you run, enriches it with metadata (directory, duration, exit code, git branch, executor), and gives you a powerful TUI to search, replay, and analyze your terminal activity. All data stays 100% local on your machine.

Quick Install

The fastest way to install Suvadu is via Homebrew:

brew tap AppachiTech/suvadu && brew install suvadu

See the full Installation guide for Cargo, manual downloads, and the install script.

Quick Start

Get up and running in four steps:

Install Suvadu using Homebrew, Cargo, or a manual download.
```
brew tap AppachiTech/suvadu && brew install suvadu
```

Set up shell integration so commands are recorded automatically.

# Zsh
echo 'eval "$(suv init zsh)"' >> ~/.zshrc && source ~/.zshrc

# Bash
echo 'eval "$(suv init bash)"' >> ~/.bashrc && source ~/.bashrc

Verify everything works by checking status.
```
suv status
```
You should see "Recording: enabled" and your detected shell.
Search your history with the interactive TUI.
```
suv search
```

Commands by Category

Getting Started

Command	Description	Docs
`suv init <shell>`	Output shell hooks for Zsh or Bash to enable automatic recording	Shell Integration
`suv status`	Show current recording state, database path, shell, and version	Shell Integration

Core Features

Command	Description	Docs
`suv search`	Interactive fuzzy search TUI with filters, Smart mode, and frecency ranking	Search
`suv replay`	Chronological timeline of commands with date, directory, and executor filters	Session Replay
`suv session`	Interactive session browser TUI	Session Replay
`suv stats`	Shell usage statistics: top commands, daily activity, error rates	Statistics
`suv settings`	View and modify Suvadu configuration	Settings

Organization

Command	Description	Docs
`suv bookmark`	Bookmark important commands for quick access	Bookmarks
`suv note`	Attach notes to commands for future reference	Notes
`suv tag`	Tag sessions for categorization and filtering	Tags
`suv alias`	Create named aliases for frequently used commands	Aliases

AI Agent Integration

Command	Description	Docs
`suv agent`	AI agent tracking setup and configuration	Agent Setup
`suv agent dashboard`	Interactive dashboard for AI agent activity	Agent Dashboard
`suv agent stats`	Statistics on AI agent command usage and patterns	Agent Stats
`suv prompt`	Browse and search AI agent prompts	Prompt Explorer
`suv agent report`	Generate reports on agent activity	Agent Reports
`suv mcp-server`	Start the Model Context Protocol server for AI tool integration	MCP Server

Data Management

Command	Description	Docs
`suv import`	Import history from Zsh, Bash, Atuin, or other shells	Import & Export
`suv export`	Export history to JSON or CSV	Import & Export
`suv delete`	Delete individual entries or purge history by criteria	Delete & Cleanup

Maintenance

Command	Description	Docs
`suv update`	Check for and install Suvadu updates	Update & Uninstall
`suv completions <shell>`	Generate shell completions for Zsh, Bash, or Fish	Completions
`suv pause`	Pause recording for the current shell session	Shell Integration
`suv enable` / `suv disable`	Globally enable or disable command recording	Shell Integration

What's Unique About Suvadu

Most shell history tools stop at recording commands. Suvadu goes further:

AI agent tracking — Suvadu automatically detects when commands are executed by AI coding agents (Claude Code, Cursor, Windsurf, Copilot, Aider, etc.) versus by you. Every entry records which executor ran it, so you can audit, review, and understand agent behavior alongside your own shell activity.
MCP server built in — Suvadu ships with a Model Context Protocol (MCP) server. AI agents that support MCP can query your shell history, check what commands failed, see what changed in a directory, and get context-aware suggestions — all from your local database with zero cloud dependencies.
Rich metadata on every command — Each entry captures the working directory, duration, exit code, git branch, hostname, session ID, and timestamp. This makes filtering, replaying, and analyzing your history far more powerful than plain-text history files.
100% local and private — All data is stored in a local SQLite database. No accounts, no cloud sync, no telemetry. Your shell history never leaves your machine.
Built in Rust — Suvadu is a single compiled binary with no runtime dependencies. Shell hooks add sub-millisecond overhead. The search TUI renders instantly even with hundreds of thousands of entries.