tools-only Atuin Skill
Magical shell history with encrypted sync across all your machines.
Overview
Atuin replaces your shell history with a SQLite database and provides:
- Full-screen history search UI (Ctrl+R / Up arrow)
- End-to-end encrypted sync across machines
- Context logging (exit code, cwd, hostname, duration)
- Statistics and analytics
- Filter modes (session, directory, global)
- Quick navigation with Alt+number keys
Supported Shells
| Shell | Support Level |
|---|---|
| Zsh | Full |
| Bash | Full |
| Fish | Full |
| Nushell | Full |
| Xonsh | Full |
Quick Start
Installation
# Official installer (recommended)
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh
# macOS (Homebrew)
brew install atuin
# Cargo
cargo install atuin
# Arch Linux
pacman -S atuin
Shell Integration
Zsh (~/.zshrc):
eval "$(atuin init zsh)"
Bash (~/.bashrc):
eval "$(atuin init bash)"
Fish (~/.config/fish/config.fish):
atuin init fish | source
Nushell (config.nu):
source ~/.local/share/atuin/init.nu
First-Time Setup
# Import existing history
atuin import auto
# Optional: Register for sync
atuin register -u <USERNAME> -e <EMAIL>
# Verify setup
atuin doctor
Search Modes
Interactive Search (Ctrl+R)
| Key | Action |
|---|---|
Ctrl+R |
Open search UI |
Up/Down |
Navigate history |
Tab |
Select without executing |
Enter |
Execute command |
Alt+1-9 |
Quick select item |
Ctrl+R (in UI) |
Cycle filter modes |
Filter Modes
| Mode | Description |
|---|---|
global |
All history across machines |
host |
Current machine only |
session |
Current terminal session |
directory |
Current working directory |
workspace |
Git repository root |
Search Modes
| Mode | Description |
|---|---|
prefix |
Match from start of command |
fulltext |
Substring match anywhere |
fuzzy |
Fuzzy matching (default) |
skim |
Skim-style fuzzy finder |
Command Line Search
# Basic search
atuin search "git push"
# Filter by exit code (successful only)
atuin search --exit 0 "make"
# Time-based filtering
atuin search --after "yesterday 3pm" "docker"
atuin search --before "2024-01-01" "npm"
# Combine filters
atuin search --exit 0 --after "1 week ago" "kubectl"
# Directory filter
atuin search --cwd /path/to/project "test"
Sync Setup
Cloud Sync (Atuin Server)
# 1. Register account
atuin register -u <USERNAME> -e <EMAIL>
# 2. Login (creates session)
atuin login -u <USERNAME>
# 3. Import existing history
atuin import auto
# 4. Sync
atuin sync
# Check sync status
atuin status
Self-Hosted Server
# Using Docker
docker run -d \
-p 8888:8888 \
-v $HOME/.atuin-server:/data \
ghcr.io/atuinsh/atuin:latest \
server start
# Configure client
atuin config set sync_address "http://localhost:8888"
Sync v2 (Faster)
# ~/.config/atuin/config.toml
[sync]
records = true # Enable sync v2
Configuration
Config File Location
~/.config/atuin/config.toml # Main config
~/.local/share/atuin/history.db # History database
~/.local/share/atuin/key # Encryption key
~/.local/share/atuin/session # Server session
Essential Settings
# ~/.config/atuin/config.toml
# Search behavior
search_mode = "fuzzy" # prefix, fulltext, fuzzy, skim
filter_mode = "global" # global, host, session, directory, workspace
# Shell key binding defaults
filter_mode_shell_up_key_binding = "session" # Up arrow default
# UI settings
style = "compact" # auto, full, compact
inline_height = 40 # Max lines (0 = full screen)
show_preview = true # Show command preview
show_help = true # Show keybind help
enter_accept = false # true = execute immediately
# Sync settings
auto_sync = true # Sync automatically
sync_frequency = "1h" # How often to sync
sync_address = "https://api.atuin.sh" # Server URL
# Privacy
secrets_filter = true # Auto-filter sensitive data
store_failed = true # Store failed commands
Privacy Filters
# ~/.config/atuin/config.toml
# Regex patterns to exclude from history
history_filter = [
"^password",
"^secret",
"^export.*API_KEY",
".*--password.*"
]
# Directories to exclude
cwd_filter = [
"^/tmp",
"^/private"
]
# Built-in secrets filter (AWS keys, tokens, etc.)
secrets_filter = true
Key Bindings
# ~/.config/atuin/config.toml
# Vim-style navigation
keymap_mode = "vim-normal" # emacs, vim-normal, vim-insert, auto
# Cursor style per mode
[keymap_cursor]
emacs = "blink-block"
vim_insert = "blink-bar"
vim_normal = "steady-block"
Commands Reference
Core Commands
# History operations
atuin history list # List all history
atuin history list --cmd-only # Commands only (no metadata)
atuin history prune # Remove entries
# Search
atuin search [query] # Interactive search
atuin search --interactive # Force interactive mode
# Sync
atuin sync # Manual sync
atuin sync --force # Force full sync
atuin status # Sync status
# Statistics
atuin stats # Usage statistics
atuin stats --count 20 # Top 20 commands
# Account
atuin register # Create account
atuin login # Login to sync server
atuin logout # Logout
atuin account delete # Delete account
# Maintenance
atuin doctor # Diagnostic checks
atuin info # System information
atuin gen-completions # Generate shell completions
Import Commands
# Auto-detect and import
atuin import auto
# Specific shells
atuin import zsh
atuin import bash
atuin import fish
atuin import resh
# Import zsh_history file
atuin import zsh-hist-db
Daemon Mode
# Start daemon (background sync)
atuin daemon
# Check daemon status
atuin daemon status
Statistics
View Stats
# Basic stats
atuin stats
# Top N commands
atuin stats --count 25
# Example output:
# Total commands: 50,234
# Unique commands: 12,456
#
# Top 10:
# 1. git status (2,345)
# 2. cd (1,890)
# 3. ls (1,654)
# 4. git diff (1,234)
# ...
Configure Stats
# ~/.config/atuin/config.toml
[stats]
# Commands where subcommands matter
common_subcommands = [
"cargo",
"git",
"kubectl",
"docker",
"npm"
]
# Prefixes to strip from stats
common_prefix = [
"sudo"
]
Workflows
Daily Development Workflow
# Morning: Sync history from other machines
atuin sync
# During work: Search across all history
# Press Ctrl+R, type query
# Use Ctrl+R to cycle: session → directory → global
# Find that command you ran last week
atuin search --after "1 week ago" "docker-compose"
# Check your patterns
atuin stats
Multi-Machine Workflow
# On Machine A: Register and setup
atuin register -u myuser -e me@example.com
atuin import auto
atuin sync
# On Machine B: Login and sync
atuin login -u myuser
atuin sync
# History now shared between machines
# Search finds commands from both
Troubleshooting Workflow
# Check installation
atuin doctor
# Verify shell integration
echo $ATUIN_SESSION # Should be set
# Test search
atuin search "test"
# Check sync status
atuin status
# Force resync if needed
atuin sync --force
Performance Tips
Optimize Search Speed
# ~/.config/atuin/config.toml
# Use prefix mode for faster matching
search_mode = "prefix"
# Limit to session by default
filter_mode = "session"
# Reduce preview height
max_preview_height = 2
Reduce Sync Traffic
# ~/.config/atuin/config.toml
# Sync less frequently
sync_frequency = "4h"
# Enable sync v2 (more efficient)
[sync]
records = true
Daemon Mode (v18.3+)
# ~/.config/atuin/config.toml
[daemon]
enabled = true
sync_frequency = 300 # seconds
Migration
From fzf/history
# 1. Install atuin
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh
# 2. Import existing history
atuin import auto
# 3. Add shell integration (replaces fzf Ctrl+R)
echo 'eval "$(atuin init zsh)"' >> ~/.zshrc
# 4. Remove fzf history binding (if any)
# Remove: bindkey '^R' fzf-history-widget
From Other History Tools
# mcfly: Export first, then import
mcfly export > history.txt
# Manual import needed
# hstr: Standard history import works
atuin import auto
Security
Encryption
- All sync data is end-to-end encrypted
- Server cannot read your history
- Key stored locally (
~/.local/share/atuin/key)
Key Backup
# Backup your encryption key
cp ~/.local/share/atuin/key ~/atuin-key.backup
# Restore on new machine
cp ~/atuin-key.backup ~/.local/share/atuin/key
Secrets Filtering
# ~/.config/atuin/config.toml
# Enable automatic secrets filtering
secrets_filter = true # Blocks AWS keys, GitHub tokens, etc.
# Add custom patterns
history_filter = [
".*password=.*",
".*secret=.*",
"^mysql.*-p.*"
]
Troubleshooting
Common Issues
| Issue | Solution |
|---|---|
| Ctrl+R not working | Check shell integration in rc file |
| Sync failing | Run atuin doctor, check network |
| Missing history | Run atuin import auto |
| Slow search | Switch to prefix search mode |
| Duplicate history | Check if imported multiple times |
Diagnostic Commands
# Full diagnostics
atuin doctor
# System info
atuin info
# Check database
sqlite3 ~/.local/share/atuin/history.db "SELECT COUNT(*) FROM history"
# Debug mode
ATUIN_LOG=debug atuin sync
Reset Everything
# Logout and clear local data
atuin logout
rm -rf ~/.local/share/atuin
rm -rf ~/.config/atuin
# Reinstall
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh
References
- references/configuration.md - Complete configuration reference
- references/commands.md - Full CLI command reference
- references/sync-setup.md - Detailed sync configuration
- references/troubleshooting.md - Common issues and fixes
- references/workflows.md - Advanced usage patterns
External Links
- Official Docs: https://docs.atuin.sh
- GitHub: https://github.com/atuinsh/atuin
- Forum: https://forum.atuin.sh
- Discord: Community support