Atuin: The Magical Shell History Tool That Will Change How You Work

Why I Can't Imagine Working Without It Anymore

Image generated by DALL-E

Picture this: You're debugging a production issue at 2 AM.
You vaguely remember running a complex kubectl command with specific flags a few days ago, but you can't quite recall the exact syntax.

You start typing kubectl get... and frantically pressing ↑ to scroll through your shell history, passing hundreds of ls, cd, and git status commands.

Twenty seconds later, you give up and open your notes app — if you even took notes.

Sound familiar? This was my daily workflow until I discovered Atuin.

What is Atuin?

Atuin replaces your existing shell history with a SQLite database, and records additional context for your commands. With this context, Atuin gives you faster and better search of your shell history. — Atuin Documentation

Atuin is a Rust-powered CLI tool that transforms your mundane shell history into a searchable, queryable database. But calling it just a "history replacement" doesn't do it justice. It's more like giving your shell a photographic memory with advanced search capabilities.

Named after "The Great A'Tuin" — the giant turtle from Terry Pratchett's Discworld series that carries four elephants on its back, who in turn support the entire world — this tool lives up to its namesake by carrying your entire command history universe.

With 28.5k+ stars on GitHub and support for bash, zsh, fish, nushell, xonsh, and even powershell, Atuin has become an essential part of my development toolkit.

Installation: One Command to Rule Them All

Getting started with Atuin is refreshingly simple. The recommended installation method uses a single curl command:

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

The script automatically:

Downloads the appropriate binary for your platform
Installs it to ~/.atuin/bin
Sets up shell integration for your current shell

For Windows users, winget is the way to go:

winget install -e Atuinsh.Atuin

After installation, restart your shell (or source your shell config), and you're ready to go. The entire process takes less than a minute.

Core Features: What Makes Atuin Special

1. SQLite-Powered History Database

Unlike traditional shell history, which stores commands in plain-text files, Atuin uses SQLite as its backend. This seemingly simple change unlocks powerful capabilities:

Structured storage: Each command is stored with rich metadata
Fast queries: SQLite's indexing makes searching lightning-fast
Data integrity: No more corrupted history files

Let's look at what Atuin actually records for each command:

FieldDescriptioncommandThe actual command you typedcwdCurrent working directorytimestampWhen you ran it (nanosecond precision)durationHow long the command tookexitExit code (0 for success, non-zero for failures)hostnameWhich machine you ran it onsessionShell session identifier

This metadata transforms your history from a simple command log into a queryable database of your development workflow.

2. Powerful Search Interface

Here's where Atuin truly shines. Press Ctrl+R (or ↑ arrow) and you're greeted with a beautiful TUI interface:

The interface shows:

Timestamp: When you ran the command
Command: The full command with syntax highlighting
Duration: How long it took (great for identifying slow commands)
Working directory: Where you ran it

But the real magic is in the search capabilities. Atuin supports multiple filter modes that you can cycle through by pressing Ctrl+R:

ModeDescriptionUse CaseglobalSearch the entire historyFinding any command you've ever runhostOnly this machineCommands from your current workstationsessionCurrent shell session Recent commands in this terminaldirectoryCurrent directoryCommands relevant to this projectworkspaceCurrent git repository Commands within this codebase

And multiple search modes (cycle with Ctrl+S):

ModeDescriptionfuzzyFuzzy matching like fzfprefixCommands starting with your queryfulltextSubstring matchingskimSkim-style fuzzy finding

3. Command-Line Search with Filters

Beyond the TUI, Atuin's CLI search is incredibly powerful. Let me demonstrate with some real examples:

Basic search:

$ atuin search docker

Find successful git commits from yesterday:

$ atuin search --exit 0 --after "yesterday" "git commit"

Find commands that failed in the current directory:

$ atuin search --exclude-exit 0 --cwd .

Find long-running commands from last week:

$ atuin search --before "last monday" --after "last week"

The query syntax is intuitive and incredibly powerful when combined:

$ atuin search --exit 0 --after "yesterday 3pm" cargo

This finds all successful cargo commands run after 3 PM yesterday. Isn't it fascinating?

4. History Statistics

Ever wondered what commands you run most frequently? Atuin's stats command gives you insights into your command-line habits:

$ atuin stats

The output shows:

Command frequency: Visual bar chart of your most-used commands
Total commands: How many commands have you recorded
Unique commands: How many distinct commands

You can also get stats for specific time periods:

$ atuin stats last friday 
 $ atuin stats "last week" 
 $ atuin stats 2026-03-01

This feature has helped me identify repetitive tasks that could be automated. For instance, seeing docker-compose up in my top 5 led me to create shell aliases.

5. Listing and Managing History

The history list command provides a clean view of your recent commands:

$ atuin history list --human

The --human flag formats durations in a readable way (e.g., "2s" instead of "2000ms"). You can also:

# Show only commands (no metadata) 
 $ atuin history list --cmd-only 
  
 # Reverse order (oldest first) 
 $ atuin history list --reverse 
  
 # Limit output 
 $ atuin history list --limit 10

Configuration: Make It Yours

Atuin's configuration file lives at ~/.config/atuin/config.toml. Here's my recommended starting configuration:

Key options to consider:

# Use inline mode for less screen takeover 
 inline_height = 20 
  
 # Show command previews 
 show_preview = true 
  
 # Press Enter to execute immediately 
 enter_accept = true 
  
 # Start in session mode for up-arrow 
 filter_mode_shell_up_key_binding = "session"

The enter_accept option is particularly interesting. When set to true, pressing Enter in the TUI immediately executes the selected command. Set it to false if you prefer to insert the command for editing first.

Sync: Your History Everywhere

One of Atuin's killer features is encrypted device synchronization. Here's how it works:

1. Register an account:

$ atuin register -u myusername -e [email protected]

2. Get your encryption key:

$ atuin key

⚠️ Important: This key is used to encrypt your history. Never share it, and store it somewhere safe. If you lose it, your synced history is unrecoverable.

3. Import existing history:

$ atuin import auto

This imports from your shell's native history file.

4. Sync:

$ atuin sync

On a new machine, simply:

$ atuin login -u myusername -p mypassword -k "your-encryption-key" 
 $ atuin sync

All your history is now available on the new machine. The sync is:

End-to-end encrypted: The server never sees your actual commands
Deduplicated: No duplicate entries across devices
Incremental: Only new commands are synced after the initial sync

You can use the official server at https://api.atuin.sh or self-host your own. Self-hosting is straightforward with Docker:

$ docker run -d -v atuin-data:/config -p 8888:8888 ghcr.io/atuinsh/atuin:latest

Real-World Use Cases

Let me share some scenarios where Atuin has saved me hours of frustration:

The "What Was That Command Again?" Problem

You ran a complex ffmpeg command three weeks ago to convert a video. You remember it had something to do with -c:v libx264 but can't recall the exact flags.

$ atuin search ffmpeg

Fuzzy search finds it instantly, even if you only remember fragments.

The "It Worked Yesterday" Debugging

Your build suddenly fails. You know it worked yesterday afternoon. Find what changed:

$ atuin search --after "yesterday 2pm" --before "yesterday 6pm" make

The "Which Directory Was I In?" Mystery

You remember running a script, but can't recall which project it was in:

$ atuin search deploy.sh 
 # Shows the cwd for each match

The "How Long Did That Take?" Question

Before optimizing, check how long commands actually take:

$ atuin stats 
 # Shows your slowest commands

Advanced Tips and Tricks

Disable up-arrow binding (if you prefer):

Some users find the up-arrow behavior intrusive. You can disable it:

# In your shell config 
 export ATUIN_NOBIND="true" 
 eval "$(atuin init bash)"

Then only Ctrl+R will trigger Atuin.

Use with fzf:

If you're already an fzf user, Atuin's skim search mode provides similar behavior:

search_mode = "skim"

Prune old history:

Keep your database lean by removing old entries:

$ atuin history prune --help

Check your setup:

The doctor command diagnoses common issues:

$ atuin doctor

Performance: How Fast Is It Really?

I tested Atuin with a database of 50,000+ commands on my MacBook Pro M1:

OperationTimeSearch (fuzzy)~50msList 1000 entries~30msStats calculation~100msSync (100 new commands)~2s

The SQLite backend and Rust implementation make it incredibly fast. Even with years of history, searches feel instantaneous.

Summary

Atuin has fundamentally changed how I interact with my shell. Here's what makes it indispensable:

Rich metadata: Every command is stored with context — when, where, how long, and whether it succeeded
Powerful search: Fuzzy finding, filters by time/directory/exit code, and multiple search modes
Beautiful TUI: The interface is fast, responsive, and shows exactly what you need
Cross-device sync: Your history follows you everywhere, encrypted and secure
Insightful stats: Understand your command-line habits and optimize your workflow
Shell agnostic: Works with bash, zsh, fish, and more

Is Atuin perfect? No tool is. The full-screen TUI can feel overwhelming on small screens (though inline_height helps), and the initial sync can be slow for massive histories. But these are minor quibbles in an otherwise exceptional tool.

If you spend significant time in a terminal, Atuin is one of the highest-ROI tools you can add to your workflow. It takes minutes to set up and pays dividends every time you press Ctrl+R.