Installation

Install Suvadu on macOS or Linux, enable recording in Zsh or Bash, and confirm that your first command was recorded. Suvadu is a single binary with SQLite bundled, so it has no runtime dependencies to install.

Requirements

• Operating system: macOS (Apple Silicon or Intel) or Linux (x86_64 or ARM64)
• Shell: Zsh 5.1+ or Bash 4.0+. Recording and Ctrl+R search are available only in these shells. Fish is not supported for recording (suv completions fish only generates tab completions).
• macOS Bash: the system /bin/bash is 3.2, which is too old for the Bash hook. Use Zsh (the macOS default), or install a newer Bash.

For terminals, tmux, and AI agents, see Compatibility.

Homebrew (Recommended)

The simplest way to install Suvadu on macOS or Linux with Homebrew:

brew tap AppachiTech/suvadu && brew install suvadu

This installs the suv binary (and a suvadu alias) for your platform. Update it with brew upgrade suvadu.

Cargo (Rust Package Manager)

If you have the Rust toolchain installed, you can build from source via Cargo:

cargo install suvadu

This compiles Suvadu from source and installs the suv binary into ~/.cargo/bin/. Make sure ~/.cargo/bin is in your PATH.

Install Script

A one-line install script that detects your OS and architecture:

curl -fsSL https://downloads.appachi.tech/suvadu/install.sh | bash

The script downloads the binary for your platform, verifies its SHA-256 checksum, and installs it in /usr/local/bin/ using sudo. You can read the script before running it.

Manual Download — macOS

Apple Silicon (arm64):

curl -sL https://downloads.appachi.tech/macos/suv-macos-latest.tar.gz | tar xz suv && sudo mv suv /usr/local/bin/

Intel (x86_64):

curl -sL https://downloads.appachi.tech/macos/suv-macos-x86_64-latest.tar.gz | tar xz suv && sudo mv suv /usr/local/bin/

Manual Download — Linux x86_64

Download the pre-built binary for Linux on x86_64 (AMD64):

curl -sL https://downloads.appachi.tech/linux/suv-linux-latest.tar.gz | tar xz suv && sudo mv suv /usr/local/bin/

Manual Download — Linux ARM64

Download the pre-built binary for Linux on ARM64 (aarch64):

curl -sL https://downloads.appachi.tech/linux/suv-linux-aarch64-latest.tar.gz | tar xz suv && sudo mv suv /usr/local/bin/

Each archive also has a .sha256 checksum file at the same URL with .sha256 added.

Verify Installation

After installing with any method, check that your shell can find the binary:

suv --version

This prints the installed version (for example, suvadu 0.4.1). If you see “command not found”, add the directory containing suv to your PATH (for example, /usr/local/bin/ or ~/.cargo/bin/), then open a new terminal.

Activate Shell Integration

Installing the binary does not record anything yet. Add one line to your shell's startup file, then reload it.

Zsh (add to ~/.zshrc):

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

Bash 4.0+ (add to ~/.bashrc):

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

Add the line once; if it is already in the file, keep the existing line. The hook records each command after it finishes and binds Ctrl+R to suv search. For Bash login shells, make sure ~/.bash_profile sources ~/.bashrc. See Shell Integration for details and options.

Record and Find Your First Command

In the terminal where you just reloaded your startup file, run:

echo hello-suvadu
suv history -n 5

The newest entry is listed first. It should show the time, status, duration, directory, and your command:

2026-09-19 10:42:07  ✓        2ms  ~/projects/app        echo hello-suvadu

Now press Ctrl+R and type hello. Select the result to put it back on your prompt; press Enter to run it.

If the command does not appear, run suv doctor, then follow Confirm Recording Works. suv status can say “History IS being recorded” even in a terminal where the hook did not load, so the history check above is the reliable test.

Import Existing History

Suvadu 0.4.1 can import two formats:

Add --dry-run to preview an import without writing to the database. Duplicate entries are skipped.

There is no Bash history or Atuin importer in 0.4.1. Suvadu records new Bash commands after you enable the hook, but it does not parse ~/.bash_history or Atuin's database. See Import & Export for the formats in detail.

Troubleshooting

• A new command is not recorded: open a new terminal, run suv doctor, and follow the repair steps. See also history is enabled but a new command does not appear.
• Ctrl+R opens the old search: see Ctrl+R opens the wrong tool.
• “suv binary not found” after moving or reinstalling: open a new terminal (or run exec zsh / exec bash) so the hook can find the new binary. Then rerun any suv init <agent> commands you used. See stale binary path.
• For every other symptom, see Troubleshooting.

Next Steps

• Search — filters, Smart mode, and keyboard shortcuts.
• Agent Setup — record commands and prompts from Claude Code, Codex, Cursor, OpenCode, pi.dev, or Antigravity.
• Agent Sessions — inspect captured agent sessions and saved summaries.
• FAQ — shell support, privacy, performance, and what each integration captures.

Uninstall

Run suv uninstall. It detects Homebrew and Cargo installations, asks for confirmation, removes the binary, removes the hook line from ~/.zshrc and ~/.bashrc, and removes Codex hook registrations. For install-script or manual installs, it only prints the binary's path; delete the binary and remove the eval "$(suv init …)" line yourself. Your database and config are not removed. See Update & Uninstall for the full steps, including where your data is stored.

Frequently Asked Questions

Which installation method should I use?

Homebrew is the recommended path on macOS and Linux — it installs the correct binary for your CPU and keeps it current with brew upgrade suvadu. Use Cargo if you already have the Rust toolchain and prefer building from source. The install script (on Linux) and manual downloads suit servers or environments without Homebrew.

Do I need Rust installed to use Suvadu?

No. The pre-built binaries include SQLite and need no other runtime. You only need the Rust toolchain if you choose cargo install suvadu, which builds from source.

Does Suvadu run on Windows?

Not natively. Suvadu targets macOS and Linux. The Linux build may run inside WSL2 with Zsh or Bash, but WSL2 is not part of the release test matrix.

How do I fix "suv: command not found"?

This means the directory containing the suv binary isn't in your PATH. Add the directory where your install method put it: /usr/local/bin for the install script or manual installs, Homebrew's bin directory (brew --prefix shows it), or ~/.cargo/bin for Cargo. Then open a new terminal and run suv --version again.

How do I update or uninstall Suvadu later?

With Homebrew, run brew upgrade suvadu. For other install methods and uninstall instructions, see Update & Uninstall.