julianobarbosa/atuin

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 [email protected]
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 with intent-to-config mapping
• references/commands.md - Full CLI command reference
• references/search-reference.md - Search flags, TUI shortcuts, Vim mode, format variables
• references/sync-setup.md - Detailed sync configuration
• references/troubleshooting.md - Common issues and fixes
• references/workflows.md - Advanced usage patterns
• references/tips-and-tricks.md - Power user patterns, fzf coexistence, dotfiles sync, tmux

External Links

• Official Docs: https://docs.atuin.sh
• GitHub: https://github.com/atuinsh/atuin
• Forum: https://forum.atuin.sh
• Discord: Community support

---

Gotchas

• Sync over captive-portal Wi-Fi: atuin status reports ok, but inserts buffer locally only. History looks fine until you check on another machine.
• Encryption key is per-machine — losing it locks you out of synced history irrecoverably. Back up ~/.local/share/atuin/key.
• Search mode fuzzy vs prefix: match counts differ subtly; switching modes confuses muscle memory at 2am.
• Atuin history is NOT shared with shell history file — ~/.zsh_history and atuin's DB drift; history builtin and atuin search return different results.
• Self-hosted server needs PostgreSQL — SQLite is single-user only. The error mentioning "embedded mode" doesn't surface the issue clearly.