Atuin: Supercharge Your Shell Command History

Ever felt like your shell history is a tangled mess of forgotten commands and dead‑ends? You type a long pipeline, hit Enter, and later wish you could instantly recall every flag you used. That’s where Atuin steps in – it transforms your linear, volatile history into a searchable, sync‑able knowledge base. In this guide we’ll explore how Atuin works under the hood, get it up and running, and supercharge your daily terminal workflow.

What Is Atuin?

Atuin is an open‑source, drop‑in replacement for the traditional shell history file. Instead of appending raw strings to ~/.bash_history, Atuin stores each command as a structured record in an SQLite database. This enables timestamps, exit codes, working directories, and even Git branch information to be attached to every entry.

Because the data lives in a relational database, you can query it with full‑text search, filter by date, or group by project. At the same time, Atuin remains lightweight – the core is written in Rust, and the client ships as a tiny binary that you can invoke just like history or fc.

Core Features at a Glance

• Rich Metadata: Every command records its exit status, execution time, and the directory you were in.
• Fuzzy Search: Instantly find past commands with a few keystrokes, thanks to an integrated fuzzy finder.
• Cross‑Device Sync: Keep the same history on your laptop, desktop, and server using encrypted cloud storage.
• Custom Hooks: Run user‑defined scripts before or after a command is logged.
• Privacy‑First: All data is encrypted locally; you control the encryption key.

Installing Atuin

Installation is straightforward on most platforms. The Atuin team provides pre‑compiled binaries, Homebrew formulas for macOS, and a Cargo package for Linux users who prefer building from source.

# macOS – Homebrew
brew install atuin

# Linux – Cargo (requires Rust toolchain)
cargo install atuin

# One‑liner for any Unix‑like system
curl -sSL https://github.com/ellie/atuin/releases/latest/download/atuin-installer.sh | sh

After the binary lands in /usr/local/bin (or your Cargo bin directory), verify the installation by running atuin --version. You should see the current version number, confirming that the tool is ready to be configured.

Getting Started

The first thing Atuin needs is a place to store its SQLite database. By default it creates ~/.local/share/atuin/history.db, but you can override this location via the ATUIN_DB_PATH environment variable.

Initializing the Database

# Initialize the database (run once)
atuin init

# Verify the schema
sqlite3 ~/.local/share/atuin/history.db ".schema"

Running atuin init also generates a default configuration file at ~/.config/atuin/config.toml. Open it in your favorite editor to tweak sync settings, encryption keys, or the prompt style.

Using Atuin in Your Daily Workflow

Once initialized, Atuin automatically intercepts every command you type, provided you add its hook to your shell’s startup file. For Bash, append the following line to ~/.bashrc:

eval "$(atuin init bash)"

For Zsh, use eval "$(atuin init zsh)". After reloading the shell, you’ll notice a subtle change: the history command now pulls results from the SQLite store instead of the flat file.

Search and Filter on the Fly

Atuin’s search subcommand launches an interactive fuzzy finder (powered by fzf if available). Type a few characters and watch matching commands appear instantly.

# Quick fuzzy search
atuin search

# Search only commands from the last 7 days
atuin search --since "7 days ago"

# Filter by exit status (e.g., only failed commands)
atuin search --exit-code 1

The results are displayed with timestamps and the working directory, making it trivial to locate the exact command you need. Press Enter to paste the selected entry back into your prompt.

Advanced Customization

Beyond basic search, Atuin shines when you start customizing its behavior. Two powerful features are sync across machines and user‑defined hooks that run automatically before or after a command is logged.

Syncing Across Machines

Atuin supports syncing via any Git remote, S3 bucket, or custom HTTP endpoint. The simplest setup uses a private Git repository. First, generate an encryption key (Atuin will prompt you for a passphrase).

# Generate a new encryption key
atuin key generate

# Add a remote repository (replace with your own URL)
git remote add origin git@github.com:youruser/atuin-sync.git

# Enable sync in the config
cat >> ~/.config/atuin/config.toml <

# ~/.config/atuin/hooks/post_command.sh
#!/usr/bin/env bash
# Append commands that took >5 seconds to a special log
if [ "$ATUIN_DURATION" -gt 5 ]; then
  echo "$ATUIN_TIMESTAMP $ATUIN_CMD" >> ~/.atuin/slow_commands.log
fi

[hooks]
post_command = "~/.config/atuin/hooks/post_command.sh"