How to Install Atuin on Debian: Magical Shell History with Sync and Search

Atuin replaces your shell’s plain-text history file with an indexed SQLite database and gives you a fast, fuzzy, full-screen search over everything you have ever typed. Instead of scrolling blindly through thousands of lines with the up arrow, you press ctrl-r and instantly filter by command, directory, exit code, or time.

Atuin also records context that a normal history file throws away: the working directory, the hostname, the session, how long each command took, and whether it succeeded. That turns your history into something you can actually query. On top of that, Atuin offers optional end-to-end encrypted sync, so the same searchable history follows you across every machine you own.

Debian does not package Atuin in its official repositories, which usually leaves you running the upstream install script and wiring up shell integration by hand. The unofficial deb.griffo.io repository provides an up-to-date .deb, so you can install Atuin with apt and keep it current through normal system upgrades.

What Makes Atuin Special?

🔍 Full-screen fuzzy search — replace ctrl-r with an interactive search over your entire history
🗄️ SQLite-backed storage — history lives in a real database you can query and filter
📌 Rich context — every command records its directory, exit code, duration, host, and session
🔐 End-to-end encrypted sync — share history across machines without the server ever seeing plaintext
📊 Usage statistics — atuin stats surfaces your most-used commands and habits
🐚 Multi-shell support — works with Bash, Zsh, Fish, and Nushell
⬆️ Smarter up-arrow — optionally rebind the up key to context-aware history navigation
📥 Seamless import — pulls your existing shell history in on first run

Why Use the deb.griffo.io Repository?

The deb.griffo.io repository is the low-friction way to run Atuin on Debian:

Easy installation and updates through the APT package manager
Automatic dependency management so nothing has to be resolved by hand
Always tracks upstream releases so new features arrive quickly
No compiling from source and no Rust toolchain to maintain
Works across supported Debian releases including Bookworm, Trixie, and Sid

Prerequisites

Before starting, make sure you have:

A Debian-based system (Bookworm 12, Trixie 13, or Sid)
sudo privileges
curl installed (sudo apt install curl if needed)
A supported shell such as Bash or Zsh where you can add an init line

Step 1: Add the deb.griffo.io Repository

Add the signing key and repository with the following commands:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

What each command does:

Keyrings directory — creates /etc/apt/keyrings with correct permissions to hold the key
GPG key — downloads and de-armors the repository signing key for APT
Repository entry — adds the source, auto-filling your Debian codename with lsb_release -sc
Package list — updates APT so Atuin becomes available to install

Step 2: Update the Package List

If you did not run the last command above, refresh the index:

sudo apt update

Step 3: Install Atuin

Install the package:

sudo apt install atuin

This installs the atuin binary and its dependencies.

Step 4: Verify the Installation

Confirm Atuin is installed and reports a version:

atuin --version

You should see something like:

atuin 18.4.0

At this point the binary is present, but Atuin is not yet hooked into your shell — that is the crucial next step.

Getting Started with Atuin

Atuin only takes over history once you add its init line to your shell. This section covers the setup that makes it useful.

Shell Integration (Required)

Atuin works by installing a shell hook. Add the appropriate init line to your shell’s startup file.

For Bash, Atuin recommends ble.sh for the best experience, but the plain init also works. Append this to ~/.bashrc:

eval "$(atuin init bash)"

For Zsh, add this to ~/.zshrc:

eval "$(atuin init zsh)"

Then reload your shell:

exec bash

After this, pressing ctrl-r opens Atuin’s full-screen search instead of the default reverse-i-search. By default Atuin also binds the up arrow; if you would rather keep the native up-arrow behaviour, disable it:

eval "$(atuin init bash --disable-up-arrow)"

Importing Existing History

Bring your old shell history into Atuin’s database so nothing is lost:

atuin import auto

The auto argument detects your shell and imports from the right history file. You can also target a specific shell with atuin import bash or atuin import zsh.

Searching and Querying History

Beyond the interactive ctrl-r interface, Atuin has a scriptable search command:

# Search for commands containing "docker"
atuin search docker

# Show the last 10 commands you ran in this directory
atuin search --cwd . --limit 10

# Find failed commands (non-zero exit code)
atuin search --exit 1

# Filter by time range
atuin search --before "1 day ago" --after "1 week ago" git

Inside the interactive search you can toggle filter modes to scope results to the current directory, session, or host.

Statistics

Atuin can summarise how you use the shell:

# Overall stats: most-used commands and totals
atuin stats

# Stats for a specific period
atuin stats last week

Optional Encrypted Sync

If you want the same history across several machines, register an account and sync:

# Create an account (choose a username, email, and password)
atuin register -u <username> -e <email>

# Sync your local history up to the server
atuin sync

# On another machine, log in and pull history down
atuin login -u <username>
atuin sync

Sync is end-to-end encrypted with a key that never leaves your machines, so the server only stores ciphertext. You can also self-host the Atuin server if you prefer to keep everything in-house.

Keeping Atuin Updated

Because Atuin is a managed package, updates arrive with your normal maintenance:

sudo apt update && sudo apt upgrade

This keeps the atuin binary current alongside the rest of your Debian system.

Other Tools from deb.griffo.io

The repository packages many other terminal tools for Debian:

zoxide — a smarter cd that learns your most-used directories
Starship — a fast, customizable prompt for any shell
fzf — a command-line fuzzy finder that pairs well with history search
Nushell — a structured-data shell that Atuin also supports

Troubleshooting

GPG or Key Errors

If APT reports the repository is not signed, re-add the key and refresh:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot find atuin:

Run sudo apt update again to refresh the index
Confirm your release is supported (Bookworm, Trixie, or Sid)
Inspect the source entry: cat /etc/apt/sources.list.d/deb.griffo.io.list

`ctrl-r` Still Shows the Old History

If pressing ctrl-r opens the default reverse search rather than Atuin, the shell hook is not loaded. Confirm the init line is present and that you reloaded the shell:

grep atuin ~/.bashrc
exec bash

Make sure the eval "$(atuin init bash)" line is near the end of ~/.bashrc, after any other tool that also binds ctrl-r, so Atuin wins the keybinding.

Uninstalling

To remove Atuin, first delete the init line from your shell config, then remove the package:

sudo apt remove atuin

To remove the repository as well:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Your Atuin database remains at ~/.local/share/atuin unless you delete it manually.

Conclusion

Atuin turns your shell history from a forgettable text file into a searchable, context-rich database, and its optional encrypted sync means that knowledge follows you everywhere. On Debian, the deb.griffo.io repository makes installation a single apt install atuin, and normal apt upgrade runs keep it current.

Install the package, add the init line to your shell, run atuin import auto, and press ctrl-r. It is one of those tools you stop noticing precisely because it works so well.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream Atuin project.