How to Install and Use Atuin in Linux to Supercharge Shell History with SQLite

The standard history mechanism in Linux shells like Bash and Zsh relies on flat text files (such as ~/.bash_history or ~/.zsh_history). While simple, flat-file history suffers from major shortcomings: commands executed across concurrent terminal tabs overwrite each other, multi-line scripts are mangled, exit codes are forgotten, and searching via Ctrl + R is clunky and limited to linear reverse matching.

Atuin modernises command-line history by replacing standard flat files with a local, high-performance SQLite database. It records rich command metadata—including exit status, execution duration, timestamp, and working directory—and provides a full-screen, interactive fuzzy search interface. Furthermore, Atuin offers optional end-to-end encrypted synchronisation across multiple Linux machines.

Why SQLite Backing Matters for Shell History

Traditional shell history merely saves a string. When you recall a command with reverse-search, you cannot tell whether the command succeeded, how long it took to execute, or which project directory it was run inside. Atuin captures this critical context automatically:

• Exit Status Tracking: Atuin flags failed commands with red indicators and successful ones with green, helping you avoid repeating broken one-liners.
• Execution Duration: It measures how long long-running builds, database migrations, or sync operations took down to the millisecond.
• Directory-Scoped Filtering: You can filter history specifically to commands executed inside your current working directory rather than searching through global noise.
• Rich Fuzzy Search: You can query commands using fuzzy substrings without remembering the exact initial syntax or flags.

Installing Atuin on Linux

Atuin is packaged across several distribution repositories and provides a verified installer script.

Installing on Arch Linux and Manjaro

Arch Linux provides Atuin in the official extra repository:

sudo pacman -S atuin

Installing on Ubuntu, Debian, and Fedora via Official Script

On Debian, Ubuntu, Fedora, and openSUSE, install the compiled binary via the official script:

curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh | sh

The script detects your Linux distribution, downloads the matching release binary, places it in ~/.atuin/bin, and configures the binary path.

Installing via Cargo (Rust Toolchain)

If you have Rust installed, compile Atuin directly from crates.io:

cargo install atuin

Configuring Shell Integration

To let Atuin intercept and record commands, initialise its shell hook in your user profile.

Configuring Bash

Add the initialisation hook to your ~/.bashrc:

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

Configuring Zsh

Append the hook to ~/.zshrc:

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

Configuring Fish

For Fish shell users, add the initialisation hook to your config directory:

echo 'atuin init fish | source' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Importing Your Existing Shell History

You do not need to start with an empty database. Atuin includes an automated import tool that reads your historical ~/.bash_history or ~/.zsh_history files and injects them into your local SQLite store:

atuin import auto

Atuin parses your past commands, assigns estimated timestamps where available, and stores them in ~/.local/share/atuin/history.db.

Using the Interactive Fuzzy Search Interface

Once initialised, press Ctrl + R or the Up Arrow key in your terminal. Instead of standard reverse-search, Atuin presents an intuitive visual terminal user interface (TUI).

• Navigation: Use the Up and Down arrow keys to scroll through past commands.
• Filtering: Type any search term to immediately filter your history using fuzzy matching.
• Inspecting Details: Each entry displays the command text, execution time, timestamp (e.g. 2 hours ago), and exit code (0 for success, non-zero in red for failure).
• Execution: Press Enter to run the selected command immediately, or press Tab to populate the command into your shell prompt for editing.

Switching Search Scopes and Modes

While inside Atuin’s interactive search interface, press Ctrl + R repeatedly to cycle through different search filters:

1. GLOBAL: Searches through every command executed across all terminals and directories on your system.
2. DIRECTORY: Restricts the search solely to commands that were executed in your current working directory.
3. SESSION: Limits results to commands executed within the active shell session or terminal tab.

Filtering by DIRECTORY is particularly helpful when working inside complex software projects where you only want to recall build commands, test runs, and container invocations specific to that repository.

Executing Terminal Queries via the CLI

In addition to the interactive TUI, Atuin allows you to query your command database directly from scripts or command pipelines:

# Search for docker commands that returned an error
atuin search --exit 1 docker

# View commands executed within the current directory
atuin search --cwd .

# Output raw command text formatted for piping
atuin search -f '{command}' nginx

Optional End-to-End Encrypted Sync

If you manage multiple Linux servers, laptops, or workstations, Atuin allows you to securely synchronise your command history across all devices using client-side encryption.

1. Register an account using Atuin’s community sync server (or host your own private instance):

   atuin register -u yourusername -e [email protected]

2. Atuin generates a cryptographically secure encryption key. Save this key in a secure password manager.
3. On your other Linux machines, log in and supply your key:

   atuin login -u yourusername
   atuin sync

All command history is encrypted locally on your machine before transmission, ensuring that sensitive flags, credentials, and paths remain completely private.