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. Since 0.5.0, Homebrew's post-install note gives the hook line for both Zsh and Bash, says to open a new terminal and check with suv status, and links the setup guide on suvadu.sh.

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 and verifies its SHA-256 checksum. If minisign is installed, it also verifies the release's minisign signature against the same public key suv update uses; without minisign it says the signature was not checked. Either failure aborts before anything is installed. It then puts suv and a suvadu link in /usr/local/bin/, using sudo only when that directory is not writable. You can read the script before running it.

To install somewhere else, pass an option after bash -s --:

# Into ~/.local/bin, without sudo
curl -fsSL https://downloads.appachi.tech/suvadu/install.sh | bash -s -- --user

# Into a directory you choose (sudo only if it is not writable)
curl -fsSL https://downloads.appachi.tech/suvadu/install.sh | bash -s -- --dir DIR

Setting SUVADU_INSTALL_DIR=DIR is the same as --dir DIR, and --help lists every option. If the directory is not on your PATH, the script says so and shows the line to add to your shell startup file.

Adding the shell hook. Run at a terminal, the script offers to add the hook line for your shell to its startup file (~/.zshrc, or ~/.bashrc on Linux). It shows the exact line and file first, writes nothing unless you type y, saves the previous file as .suvadu-backup, and never adds the hook twice. It does not ask when a hook is already in ~/.zshrc, ~/.bashrc or ~/.bash_profile, when the suv on your PATH is not the one it just installed, when ZDOTDIR points elsewhere, for Bash on macOS (whose login shells may not read ~/.bashrc), or when you pass --no-modify-rc. suv uninstall removes the line again. If you say no, or it does not ask, add the line yourself as described in Activate Shell Integration.

Re-running the script updates a suv it installed itself — recognised by the suvadu link beside it — in the directory it is already in; when nothing has changed it downloads nothing but still repairs that link. If the suv on your PATH came from Homebrew or Cargo, the script stops and prints brew upgrade suvadu or cargo install suvadu instead, and any other suv it did not install is left alone; --user or --dir installs a separate copy on purpose. The new binary is copied in under a temporary name and renamed into place, so a failed install leaves the previous one working.

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.5.0). If you see “command not found”, add the directory containing suv to your PATH (for example, /usr/local/bin/, ~/.local/bin/ after --user, 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. If the install script offered to add the line and you typed y, it is already there: open a new terminal instead.

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. Since 0.4.2 suv status reports configuration and capture as two separate lines — Recording: what the config says, and Capture: whether a record actually arrived and from which shell — so a terminal with no hook loaded is visible rather than implied. The history check above still proves it end to end.

Import Existing History

Suvadu 0.5.0 can import four formats:

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

What each source can carry differs. A Bash history file written without HISTTIMEFORMAT has no timestamps and no multi-line command boundaries, so each line arrives with an explicit 1970-01-01 placeholder time, and directory, exit code, duration and executor are stored as unknown. The Atuin database is opened read-only and keeps time, directory, exit code, duration, session, host and author. 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, Cargo and (since 0.5.0) install-script installations, asks for confirmation, removes the binary — for a script install, suv and its suvadu link, using sudo only if that directory is not writable — removes the hook line from ~/.zshrc and ~/.bashrc, and removes Codex hook registrations and the other agent integrations. For a manual install 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 and manual downloads suit servers or environments without Homebrew; the script's --user option installs without sudo.

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 (~/.local/bin with --user, or the directory you passed to --dir), 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.