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

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)

Filter Modes

Search Modes

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

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.

Atuin Commands Reference

Complete CLI reference for all Atuin commands.

Command Overview

atuin <COMMAND>

Commands:
  history      Manipulate shell history
  search       Interactive history search
  sync         Sync with the server
  login        Login to the sync server
  logout       Logout from the sync server
  register     Register with the sync server
  status       Show sync status
  stats        Show command statistics
  doctor       Run diagnostic checks
  info         Show system information
  daemon       Manage the background daemon
  import       Import shell history
  gen-completions  Generate shell completions
  account      Manage account settings
  dotfiles     Manage synced dotfiles
  help         Print help information

history

Manipulate shell history entries.

history list

# List all history
atuin history list

# Last N entries
atuin history list --limit 50

# Commands only (no metadata)
atuin history list --cmd-only

# Reverse order (oldest first)
atuin history list --reverse

# Custom format
atuin history list --format "{time}\t{duration}\t{command}"

# Filter by session
atuin history list --session

# Filter by directory
atuin history list --cwd /path/to/dir

Format placeholders:

history prune

# Prune with interactive confirmation
atuin history prune

# Prune entries older than duration
atuin history prune --older-than "6 months"

# Prune by hostname
atuin history prune --hostname old-machine

# Dry run (show what would be deleted)
atuin history prune --dry-run

history delete

# Delete specific entry by ID
atuin history delete <ID>

# Delete without confirmation
atuin history delete <ID> --force

search

Interactive history search.

# Open interactive search
atuin search

# Search with initial query
atuin search "git push"

# Force interactive mode
atuin search --interactive "query"

# Non-interactive (print best match)
atuin search --cmd-only "query"

Search Filters

# Filter by exit code
atuin search --exit 0 "make"        # Successful only
atuin search --exit 1 "test"        # Failed only

# Time-based filters
atuin search --after "yesterday"
atuin search --after "2024-01-01"
atuin search --after "1 week ago"
atuin search --after "3pm yesterday"
atuin search --before "2024-06-01"

# Directory filter
atuin search --cwd /path/to/project

# Hostname filter
atuin search --host my-laptop

# Session filter
atuin search --session

# Combine filters
atuin search --exit 0 --after "1 week ago" --cwd ~/projects "docker"

Search Options

# Search mode override
atuin search --search-mode prefix "git"
atuin search --search-mode fuzzy "git"

# Filter mode override
atuin search --filter-mode global
atuin search --filter-mode host
atuin search --filter-mode session
atuin search --filter-mode directory

# Limit results
atuin search --limit 20 "query"

# Output format
atuin search --format "{command}" "query"

sync

Synchronize history with the server.

# Standard sync
atuin sync

# Force full sync (re-download everything)
atuin sync --force

# Verbose output
atuin sync -v

status

Show sync and account status.

# Show sync status
atuin status

# Output includes:
# - Username
# - Server address
# - Last sync time
# - Record counts
# - Sync status

stats

Show command usage statistics.

# Show stats
atuin stats

# Top N commands
atuin stats --count 25

# Period filter
atuin stats --period day
atuin stats --period week
atuin stats --period month
atuin stats --period year
atuin stats --period all

# Example output:
# Total commands:   50,234
# Unique commands:  12,456
#
# Top 10 commands:
#  1. git status          (2,345)
#  2. cd                   (1,890)
#  3. ls                   (1,654)
#  4. git diff             (1,234)
#  5. docker ps            (987)
#  6. kubectl get pods     (876)
#  7. vim                  (765)
#  8. cat                  (654)
#  9. grep                 (543)
# 10. make                 (432)

doctor

Run diagnostic checks.

# Run all diagnostics
atuin doctor

# Checks include:
# - Shell integration
# - Database integrity
# - Sync configuration
# - Network connectivity
# - Key file status

info

Display system and configuration information.

# Show info
atuin info

# Output includes:
# - Atuin version
# - Shell
# - Database path
# - Config path
# - Sync status
# - Record counts

Account Commands

register

# Register new account
atuin register -u <USERNAME> -e <EMAIL>

# With password prompt
atuin register -u myuser -e me@example.com

# Will prompt for password

login

# Login to existing account
atuin login -u <USERNAME>

# Login with specific key file
atuin login -u <USERNAME> --key /path/to/key

logout

# Logout (clears session)
atuin logout

account

# Show account info
atuin account

# Delete account (DESTRUCTIVE)
atuin account delete

import

Import history from various sources.

# Auto-detect and import
atuin import auto

# Specific shell imports
atuin import zsh           # ~/.zsh_history
atuin import bash          # ~/.bash_history
atuin import fish          # Fish history
atuin import resh          # RESH history
atuin import zsh-hist-db   # zsh-histdb SQLite

# Import from specific file
atuin import zsh --file /path/to/.zsh_history

daemon

Manage background daemon for continuous sync.

# Start daemon
atuin daemon

# Start in foreground
atuin daemon --foreground

# Check daemon status
atuin daemon status

# Stop daemon (if running in background)
# Use system process management or Ctrl+C

gen-completions

Generate shell completion scripts.

# Zsh completions
atuin gen-completions --shell zsh > _atuin
sudo mv _atuin /usr/local/share/zsh/site-functions/_atuin

# Bash completions
atuin gen-completions --shell bash > atuin.bash
sudo mv atuin.bash /etc/bash_completion.d/

# Fish completions
atuin gen-completions --shell fish > atuin.fish
mv atuin.fish ~/.config/fish/completions/

# PowerShell completions
atuin gen-completions --shell powershell > _atuin.ps1

dotfiles (v18.1+)

Manage synced aliases and shell configuration.

# Enable dotfiles sync (requires sync v2)
# Add to config.toml: [dotfiles] enabled = true

# Set an alias
atuin dotfiles alias set ll "ls -la"
atuin dotfiles alias set k "kubectl"
atuin dotfiles alias set g "git"

# List all aliases
atuin dotfiles alias list

# Get specific alias
atuin dotfiles alias get ll

# Delete alias
atuin dotfiles alias delete ll

config

Manage configuration values.

# Set a config value
atuin config set search_mode fuzzy
atuin config set sync_frequency "30m"
atuin config set auto_sync true

# These modify ~/.config/atuin/config.toml

Global Options

Available for all commands:

# Verbose output
atuin -v <command>
atuin --verbose <command>

# Help
atuin --help
atuin <command> --help

# Version
atuin --version

Exit Codes

Environment Variables for Commands

# Debug logging
ATUIN_LOG=debug atuin sync

# Custom config directory
ATUIN_CONFIG_DIR=/custom/path atuin search

# Custom data directory
ATUIN_DATA_DIR=/custom/data atuin history list

Atuin Configuration Reference

Complete reference for all Atuin configuration options.

File Locations

~/.config/atuin/config.toml       # Main configuration
~/.local/share/atuin/history.db   # SQLite history database
~/.local/share/atuin/key          # Encryption key (BACKUP THIS!)
~/.local/share/atuin/session      # Server session token

Environment Variables

Intent-to-Config Quick Reference

Quick lookup: what the user wants -> which config key to change.

Core Configuration

Path Settings

# ~/.config/atuin/config.toml

# Database location
db_path = "~/.local/share/atuin/history.db"

# Encryption key location
key_path = "~/.local/share/atuin/key"

# Session token location
session_path = "~/.local/share/atuin/session"

Search Configuration

# Search algorithm
search_mode = "fuzzy"
# Options:
#   prefix   - Match from start (fastest)
#   fulltext - Substring match anywhere
#   fuzzy    - Fuzzy matching (default)
#   skim     - Skim-style fuzzy finder

# Default filter scope
filter_mode = "global"
# Options:
#   global    - All history across all machines
#   host      - Current hostname only
#   session   - Current terminal session only
#   directory - Current working directory only
#   workspace - Git repository root

# Separate modes for shell up-key binding
search_mode_shell_up_key_binding = "fuzzy"
filter_mode_shell_up_key_binding = "session"

UI Configuration

# Display style
style = "compact"
# Options:
#   auto    - Automatic based on terminal
#   full    - Full metadata display
#   compact - Condensed view (default)

# Invert UI (search bar at top)
invert = false

# Maximum lines for inline mode (0 = full screen)
inline_height = 40

# Show command preview
show_preview = true

# Maximum preview lines
max_preview_height = 4

# Show keybinding help
show_help = true

# Show filter mode tabs
show_tabs = true

# Exit behavior on Escape
exit_mode = "return-original"
# Options:
#   return-original - Return original command
#   return-query    - Return search query

Input Configuration

# Execute on Enter (vs select and confirm)
enter_accept = false

# Command chaining with && and ||
command_chaining = false

# Keymap mode
keymap_mode = "emacs"
# Options:
#   emacs      - Emacs-style (default)
#   vim-normal - Vim normal mode
#   vim-insert - Vim insert mode
#   auto       - Detect from shell

# Cursor styles per keymap
[keymap_cursor]
emacs = "blink-block"
vim_insert = "blink-bar"
vim_normal = "steady-block"

# Use Ctrl+N instead of Alt+N for quick select (macOS)
ctrl_n_shortcuts = true

History Configuration

# Store commands that failed (non-zero exit)
store_failed = true

# Default output format for history list
history_format = "{time}\t{command}\t{duration}"

Privacy & Filtering

# Enable automatic secrets filtering
# Filters: AWS keys, GitHub tokens, passwords, etc.
secrets_filter = true

# Regex patterns to exclude from history
history_filter = [
  "^password",
  "^secret",
  ".*--password.*",
  "^export.*API_KEY",
  "^export.*SECRET",
  "mysql.*-p[^ ]*",
  "psql.*password"
]

# Directories to exclude from history
cwd_filter = [
  "^/tmp",
  "^/private/tmp",
  "^/var/folders"
]

Sync Configuration

Basic Sync Settings

# Sync server address
sync_address = "https://api.atuin.sh"

# Automatic sync when logged in
auto_sync = true

# Sync frequency (human-readable: 10s, 20m, 1h)
sync_frequency = "1h"

Sync v2 (Recommended)

# Enable sync v2 protocol (faster, more efficient)
[sync]
records = true

Network Settings

# Request timeout (seconds)
network_timeout = 30

# Connection timeout (seconds)
network_connect_timeout = 5

# Local database timeout (seconds)
local_timeout = 5

Daemon Configuration (v18.3+)

[daemon]
# Enable background daemon
enabled = true

# Sync frequency in seconds (daemon mode)
sync_frequency = 300

# Socket path (Unix)
socket_path = "/tmp/atuin-daemon.sock"

# Enable systemd socket activation
systemd_socket = false

# TCP port (alternative to socket)
tcp_port = 0  # 0 = disabled

Stats Configuration

[stats]
# Commands where subcommands are significant
common_subcommands = [
  "cargo",
  "git",
  "go",
  "kubectl",
  "docker",
  "docker-compose",
  "npm",
  "yarn",
  "pnpm",
  "bun",
  "make",
  "just",
  "systemctl",
  "apt",
  "brew",
  "pip",
  "poetry"
]

# Prefixes to strip from stats (e.g., sudo)
common_prefix = [
  "sudo",
  "doas",
  "time"
]

Theme Configuration (v18.4+)

[theme]
# Theme name (empty = default)
name = ""

# Debug theme loading
debug = false

# Maximum inheritance depth
max_depth = 5

Dotfiles Sync (v18.1+)

[dotfiles]
# Enable alias synchronization
enabled = true

Then use:

# Set an alias
atuin dotfiles alias set ll "ls -la"

# List aliases
atuin dotfiles alias list

# Get alias
atuin dotfiles alias get ll

# Delete alias
atuin dotfiles alias delete ll

Complete Example Configuration

# ~/.config/atuin/config.toml

## Core paths (usually defaults are fine)
# db_path = "~/.local/share/atuin/history.db"
# key_path = "~/.local/share/atuin/key"
# session_path = "~/.local/share/atuin/session"

## Search behavior
search_mode = "fuzzy"
filter_mode = "global"
filter_mode_shell_up_key_binding = "session"

## UI
style = "compact"
inline_height = 40
show_preview = true
show_help = true
show_tabs = true
enter_accept = false
invert = false

## Input
keymap_mode = "emacs"
ctrl_n_shortcuts = true

## Privacy
secrets_filter = true
store_failed = true
history_filter = [
  "^password",
  ".*--password.*",
  "^export.*KEY",
  "^export.*SECRET",
  "^export.*TOKEN"
]

## Sync
sync_address = "https://api.atuin.sh"
auto_sync = true
sync_frequency = "1h"

[sync]
records = true

## Network
network_timeout = 30
network_connect_timeout = 5

## Daemon (optional)
[daemon]
enabled = false
sync_frequency = 300

## Stats
[stats]
common_subcommands = [
  "cargo",
  "git",
  "kubectl",
  "docker",
  "npm"
]
common_prefix = ["sudo"]

## Dotfiles (optional)
[dotfiles]
enabled = false

Configuration Validation

# Check configuration
atuin doctor

# Show current config values
atuin info

# Debug config loading
ATUIN_LOG=debug atuin search

Shell-Specific Integration Options

Zsh

# Basic init
eval "$(atuin init zsh)"

# With options
eval "$(atuin init zsh --disable-up-arrow)"
eval "$(atuin init zsh --disable-ctrl-r)"

Bash

# Basic init
eval "$(atuin init bash)"

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

Fish

# Basic init
atuin init fish | source

# With options
atuin init fish --disable-up-arrow | source

Init Options

Environment-Specific Configs

Minimal (Performance Focus)

search_mode = "prefix"
filter_mode = "session"
style = "compact"
inline_height = 20
show_preview = false
show_help = false
auto_sync = false

Privacy-Focused (No Sync)

auto_sync = false
sync_address = ""
secrets_filter = true
store_failed = false
history_filter = [
  ".*password.*",
  ".*secret.*",
  ".*token.*",
  ".*key.*"
]

Multi-Machine (Heavy Sync)

auto_sync = true
sync_frequency = "15m"
filter_mode = "global"

[sync]
records = true

[daemon]
enabled = true
sync_frequency = 60

Search Reference

Complete reference for Atuin's search capabilities — CLI flags, TUI shortcuts, search syntax, and practical patterns.

CLI Search

atuin search [OPTIONS] [QUERY]...

Flags

Format Variables

Use with --format / -f:

Time Expressions

The --before and --after flags accept natural language:

"yesterday 3pm"
"last friday"
"2024-04-01"
"April 1"
"01/04/22"          # US=Jan 4, UK=Apr 1 (depends on dialect setting)
"last thursday 3pm"

TUI Keyboard Shortcuts

Navigation

Actions

Inspector Mode

Vim Mode (when keymap_mode = "vim-normal")

Practical Search Patterns

Find Successful Commands

atuin search --exit 0 make
atuin search --exit 0 --after "yesterday 3pm" cargo build

Find Failed Commands

atuin search --exclude-exit 0 --cwd .
atuin search --exit 1 "docker build"

Directory-Scoped Search

atuin search --cwd /path/to/project git
atuin search --exclude-cwd /tmp

Custom Output Formats

atuin search -f "{time} [{duration}] [{exit}] {directory}\t{command}" git
atuin search --cmd-only docker
atuin search --cmd-only --print0 "npm run" | xargs -0 echo

History Maintenance

atuin search --delete "^rm -rf /"
atuin search --delete "password="
atuin search --limit 1 --reverse ""    # Oldest command
atuin history dedup
atuin history prune --dry-run
atuin history prune

History Listing

atuin history list --human
atuin history list --cwd
atuin history list --session
atuin history list -f "{time} {duration} {command}"
atuin history last

Statistics

atuin stats
atuin stats -c 20
atuin stats "last week"
atuin stats "last friday"
atuin stats -n 2    # N-gram pairs
atuin stats -n 3    # N-gram triplets

Wildcard Search

Atuin supports * and % as wildcards in search queries. Prefix search mode auto-appends a wildcard.

Atuin Sync Setup Guide

Complete guide for setting up history synchronization across machines.

Overview

Atuin sync provides:

• End-to-end encrypted history synchronization
• Cross-machine history access
• Automatic background sync
• Self-hosting option for privacy

Quick Setup (Cloud Sync)

Step 1: Register Account

# Create account
atuin register -u <USERNAME> -e <EMAIL>

# You'll be prompted for a password
# Email is used for account recovery only

Step 2: Import Existing History

# Auto-detect and import
atuin import auto

# Check import results
atuin stats

Step 3: Sync

# Initial sync (uploads history)
atuin sync

# Verify sync status
atuin status

Step 4: Setup on Additional Machines

# Install Atuin (same as first machine)
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh

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

# Login to existing account
atuin login -u <USERNAME>

# You'll be prompted for password

# Sync to download history
atuin sync

# Now history is shared!

Encryption Key Management

How It Works

1. Encryption key generated on first registration 2. Key stored locally at ~/.local/share/atuin/key 3. All history encrypted before leaving your machine 4. Server cannot read your history

Key Backup (CRITICAL)

# Backup key file
cp ~/.local/share/atuin/key ~/atuin-key-backup.txt

# Store securely (password manager, encrypted drive, etc.)

# The key looks like:
# aGVsbG8gd29ybGQgdGhpcyBpcyBhIHRlc3QgYmFzZTY0

Restoring Key on New Machine

# Before login, restore key
mkdir -p ~/.local/share/atuin
cp ~/atuin-key-backup.txt ~/.local/share/atuin/key

# Then login
atuin login -u <USERNAME>

# Sync will now work with your existing history

Key Lost?

If you lose your key:

• Existing synced history cannot be recovered
• You must delete account and re-register
• Start with fresh sync

# Delete account (if key lost)
atuin account delete

# Re-register
atuin register -u <USERNAME> -e <EMAIL>

# Import local history again
atuin import auto
atuin sync

Sync Configuration

Basic Settings

# ~/.config/atuin/config.toml

# Sync server (default: Atuin cloud)
sync_address = "https://api.atuin.sh"

# Enable automatic sync
auto_sync = true

# Sync frequency (human-readable)
sync_frequency = "1h"
# Options: 10s, 5m, 1h, 4h, 1d

Sync v2 Protocol (Recommended)

# ~/.config/atuin/config.toml

[sync]
records = true  # Enable sync v2

# Benefits:
# - Faster sync
# - More efficient data transfer
# - Better conflict resolution

Network Tuning

# ~/.config/atuin/config.toml

# Request timeout (seconds)
network_timeout = 30

# Connection timeout (seconds)
network_connect_timeout = 5

Daemon Mode (Continuous Sync)

Enable Daemon

# ~/.config/atuin/config.toml

[daemon]
enabled = true
sync_frequency = 300  # seconds (5 minutes)

Manual Daemon Control

# Start daemon
atuin daemon

# Check status
atuin daemon status

# Run in foreground (for debugging)
atuin daemon --foreground

Systemd Service (Linux)

# Create service file
cat > ~/.config/systemd/user/atuin-daemon.service << 'EOF'
[Unit]
Description=Atuin Daemon
After=network.target

[Service]
ExecStart=/usr/bin/atuin daemon
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user daemon-reload
systemctl --user enable atuin-daemon
systemctl --user start atuin-daemon

# Check status
systemctl --user status atuin-daemon

launchd Service (macOS)

# Create plist
cat > ~/Library/LaunchAgents/sh.atuin.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>sh.atuin.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/atuin</string>
        <string>daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/atuin-daemon.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/atuin-daemon.error.log</string>
</dict>
</plist>
EOF

# Load service
launchctl load ~/Library/LaunchAgents/sh.atuin.daemon.plist

# Check status
launchctl list | grep atuin

Self-Hosted Server

Docker Deployment

# Create data directory
mkdir -p ~/.atuin-server

# Run server
docker run -d \
  --name atuin-server \
  -p 8888:8888 \
  -v ~/.atuin-server:/data \
  -e ATUIN_HOST=0.0.0.0 \
  -e ATUIN_PORT=8888 \
  -e ATUIN_OPEN_REGISTRATION=true \
  -e ATUIN_DB_URI=sqlite:///data/atuin.db \
  ghcr.io/atuinsh/atuin:latest \
  server start

# Check logs
docker logs atuin-server

Docker Compose

# docker-compose.yml
version: '3'
services:
  atuin:
    image: ghcr.io/atuinsh/atuin:latest
    command: server start
    ports:
      - "8888:8888"
    volumes:
      - ./data:/data
    environment:
      ATUIN_HOST: "0.0.0.0"
      ATUIN_PORT: "8888"
      ATUIN_OPEN_REGISTRATION: "true"
      ATUIN_DB_URI: "sqlite:///data/atuin.db"
    restart: unless-stopped

PostgreSQL Backend (Production)

# docker-compose.yml
version: '3'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: atuin
      POSTGRES_PASSWORD: secretpassword
      POSTGRES_DB: atuin
    volumes:
      - postgres_data:/var/lib/postgresql/data

  atuin:
    image: ghcr.io/atuinsh/atuin:latest
    command: server start
    depends_on:
      - postgres
    ports:
      - "8888:8888"
    environment:
      ATUIN_HOST: "0.0.0.0"
      ATUIN_PORT: "8888"
      ATUIN_OPEN_REGISTRATION: "true"
      ATUIN_DB_URI: "postgresql://atuin:secretpassword@postgres/atuin"
    restart: unless-stopped

volumes:
  postgres_data:

Server Configuration

# Environment variables for server
ATUIN_HOST=0.0.0.0          # Listen address
ATUIN_PORT=8888             # Listen port
ATUIN_OPEN_REGISTRATION=true # Allow new users
ATUIN_DB_URI=sqlite:///data/atuin.db  # Database URI
ATUIN_MAX_HISTORY_LENGTH=8192  # Max command length
ATUIN_PAGE_SIZE=1000        # Pagination size

Client Configuration for Self-Hosted

# ~/.config/atuin/config.toml

# Point to your server
sync_address = "https://atuin.yourdomain.com"
# Or for local: sync_address = "http://localhost:8888"

HTTPS with Reverse Proxy

# /etc/nginx/sites-available/atuin
server {
    listen 443 ssl http2;
    server_name atuin.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8888;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Sync Troubleshooting

Check Sync Status

# Detailed status
atuin status

# Should show:
# - Username
# - Last sync time
# - Record counts
# - Any errors

Force Full Resync

# Force re-upload/download
atuin sync --force

Debug Sync

# Enable debug logging
ATUIN_LOG=debug atuin sync

# Check for errors in output

Network Issues

# Test connectivity
curl https://api.atuin.sh/healthz

# Or for self-hosted:
curl http://localhost:8888/healthz

# Increase timeouts if slow network
# In config.toml:
# network_timeout = 60
# network_connect_timeout = 10

Reset Sync State

# Logout
atuin logout

# Clear local session
rm ~/.local/share/atuin/session

# Login again
atuin login -u <USERNAME>

# Resync
atuin sync --force

Conflict Resolution

Sync v2 handles conflicts automatically:

• Newer timestamps win
• Both machines' history preserved
• No data loss

If issues persist:

# Export local history
atuin history list --cmd-only > history-backup.txt

# Clear and reimport
rm ~/.local/share/atuin/history.db
atuin import auto
atuin sync

Offline Mode

Disable Sync Entirely

# ~/.config/atuin/config.toml

auto_sync = false
# Leave sync_address empty or remove it

Temporary Offline

Atuin works fully offline:

• History stored locally
• Search works without network
• Sync when reconnected

Security Considerations

What's Encrypted

• Command text
• Working directory
• Hostname
• Session ID
• Timestamp
• Duration
• Exit code

What Server Sees

• Encrypted blobs
• Account email/username
• Sync timestamps
• Record counts

Best Practices

1. Backup your key - Essential for recovery 2. Use strong password - Protects account access 3. Self-host for sensitive work - Full control 4. Use secrets_filter - Prevent sensitive data in history

# Enable built-in secrets filtering
secrets_filter = true

# Add custom filters
history_filter = [
  ".*password.*",
  ".*secret.*",
  ".*API_KEY.*"
]

Tips and Tricks

Community-sourced tips, power user patterns, and best practices.

Top Productivity Patterns

1. Context-Aware Up Arrow (Most Loved Feature)

Configure Up Arrow and Ctrl+R to behave differently:

# Up Arrow: prefix search, only this directory
search_mode_shell_up_key_binding = "prefix"
filter_mode_shell_up_key_binding = "directory"

# Ctrl+R: fuzzy search, global scope
search_mode = "fuzzy"
filter_mode = "global"

Why: Up Arrow feels like enhanced readline (muscle memory), while Ctrl+R gives you full-power global search.

2. Workspace-Aware Filtering

workspaces = true

Automatically filters history to the current git repository. Perfect for project-specific command recall — no more seeing production commands while in your dev repo.

3. Enter to Execute, Tab to Edit

enter_accept = true

Press Enter to immediately run the selected command. Press Tab to place it on the command line for editing. Much faster than the default where both insert for editing.

4. Compact Style with Host Column (Multi-Machine)

style = "compact"

[ui]
columns = ["exit", "duration", "host", "command"]

Shows exit codes and which machine a command was run on — essential for multi-machine setups.

5. Use Stats to Discover Alias Candidates

atuin stats -c 20

If you see git status 500 times, create alias gs="git status". Atuin's stats make this data-driven.

6. N-gram Analysis for Workflow Patterns

atuin stats -n 2    # Common command pairs
atuin stats -n 3    # Common triplets

Discover patterns like git add -> git commit -> git push to create shell functions.

Security Best Practices

Save Your Encryption Key Immediately

atuin key
# Copy this to 1Password/Bitwarden NOW
# It CANNOT be recovered if lost

Filter Secrets Automatically

secrets_filter = true    # Default, keeps it enabled

Auto-blocks: AWS keys, GitHub PATs, Slack tokens, Stripe keys, GitLab PATs, npm tokens, Azure storage keys, Google service account keys.

Custom History Exclusions

history_filter = [
  ".*password=.*",
  ".*secret=.*",
  "^mysql.*-p.*",
  "^curl.*-u .*:.*",
  "^export (AWS_|GITHUB_|STRIPE_|DATABASE_URL)",
  "^ssh-keygen",
  "^openssl.*-passout",
]

Prune After Adding Filters

atuin history prune --dry-run    # Preview what will be deleted
atuin history prune              # Actually delete matching entries

Shell Integration Tips

fzf Coexistence

Load Atuin after fzf in your shell config so Atuin takes Ctrl+R precedence:

# ~/.zshrc
source <(fzf --zsh)           # fzf keeps Ctrl+T and Alt+C
eval "$(atuin init zsh)"       # Atuin takes Ctrl+R (loaded last = wins)

Custom Keybindings

export ATUIN_NOBIND="true"
eval "$(atuin init zsh)"

# Custom bindings
bindkey '^r' atuin-search           # Ctrl+R for search
bindkey '^[[A' atuin-up-search      # Up arrow for contextual
bindkey '^f' atuin-search           # Ctrl+F as additional binding

macOS Alt Key Fix

Alt+1-9 quick-select doesn't work on macOS Terminal. Fix:

ctrl_n_shortcuts = true    # Use Ctrl+1-9 instead of Alt+1-9

Recommended .zshrc Order

# 1. Plugin manager
source ~/.sheldon/init.zsh

# 2. Prompt
eval "$(starship init zsh)"

# 3. fzf (for files, NOT history)
source <(fzf --zsh)

# 4. Zoxide
eval "$(zoxide init --cmd cd zsh)"

# 5. Atuin (LAST — takes Ctrl+R from fzf)
eval "$(atuin init zsh)"

Sync Strategies

Aggressive Sync (Low Latency)

sync_frequency = "0"    # Sync after every command

Background Daemon Sync

[daemon]
enabled = true
sync_frequency = 60     # Every minute

Best for: ZFS filesystems (avoids SQLite write issues), SSH sessions where you want history ready on arrival.

Force Full Re-sync

atuin sync -f    # Re-download everything

Dotfiles Sync (Aliases Across Machines)

[sync]
records = true

[dotfiles]
enabled = true

# Set aliases that sync everywhere
atuin dotfiles alias set k 'kubectl'
atuin dotfiles alias set g 'git'
atuin dotfiles alias set dc 'docker compose'
atuin dotfiles alias set ll 'ls -lah'
atuin dotfiles alias set tf 'terraform'

# Set environment variables
atuin dotfiles var set EDITOR 'nvim'
atuin dotfiles var set PAGER 'less'

# List what's synced
atuin dotfiles alias list
atuin dotfiles var list

Restart shell after changes.

Performance Tips

ZFS Users: Enable Daemon

SQLite has compatibility issues with ZFS. The daemon takes writes off the hot path:

[daemon]
enabled = true

Large History (60K+ entries)

Upgrade to v15+ which uses variable page sizes (1100 default vs old 100), dramatically improving sync speed.

Reduce Empty Query Lag

The first search keystroke is always slower than subsequent ones. Type at least one character quickly to avoid the empty-query delay.

History Dedup

atuin history dedup    # Remove duplicates (same command + cwd + hostname)

Tmux Integration

[tmux]
enabled = true
width = "80%"
height = "60%"

Opens Atuin in a tmux popup window (requires tmux >= 3.2). Supported in zsh, bash, and fish. Does not work with iTerm's native tmux integration.

Complementary Tool Stack

Comparison Quick Reference

Atuin Troubleshooting Guide

Common issues and solutions for Atuin.

Diagnostic Commands

# Run full diagnostics
atuin doctor

# Show system information
atuin info

# Debug mode
ATUIN_LOG=debug atuin search
ATUIN_LOG=debug atuin sync

Installation Issues

Shell Integration Not Working

Symptom: Ctrl+R doesn't open Atuin, or uses default history search.

Solution:

# 1. Check if atuin is installed
which atuin
atuin --version

# 2. Check shell integration
grep atuin ~/.zshrc    # For Zsh
grep atuin ~/.bashrc   # For Bash

# 3. Add integration if missing
# Zsh:
echo 'eval "$(atuin init zsh)"' >> ~/.zshrc

# Bash:
echo 'eval "$(atuin init bash)"' >> ~/.bashrc

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

# 4. Reload shell
exec $SHELL

ATUIN_SESSION Not Set

Symptom: atuin doctor shows ATUIN_SESSION not set.

Solution:

# Shell integration must be loaded
# Check rc file includes atuin init

# Reload shell
exec zsh  # or exec bash

# Verify
echo $ATUIN_SESSION
# Should output a UUID

Command Not Found

Symptom: atuin: command not found

Solution:

# Check PATH
echo $PATH | grep -E "(\.cargo/bin|\.local/bin)"

# Add to PATH if missing
# For cargo install:
export PATH="$HOME/.cargo/bin:$PATH"

# For system install:
export PATH="$HOME/.local/bin:$PATH"

# Add to shell rc file
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc

Search Issues

Ctrl+R Opens Wrong Search

Symptom: Ctrl+R opens fzf or default history instead of Atuin.

Solution:

# Check for conflicting bindings
bindkey | grep "\\^R"

# Remove fzf history binding if present
# In .zshrc, remove or comment:
# source /path/to/fzf/shell/key-bindings.zsh

# Or disable fzf history specifically
export FZF_CTRL_R_COMMAND=""

# Ensure atuin init is AFTER fzf setup in .zshrc

No History Showing

Symptom: Search shows no results.

Solution:

# Check if history exists
atuin history list --limit 10

# If empty, import history
atuin import auto

# Check import results
atuin stats

# Verify database exists
ls -la ~/.local/share/atuin/history.db

Search Is Slow

Symptom: Noticeable delay when opening search.

Solution:

# ~/.config/atuin/config.toml

# Use faster search mode
search_mode = "prefix"

# Limit to session by default
filter_mode = "session"

# Reduce preview
show_preview = false

# Smaller inline height
inline_height = 20

Fuzzy Search Not Matching

Symptom: Expected results not appearing.

Solution:

# Try different search modes
atuin search --search-mode fulltext "query"
atuin search --search-mode prefix "query"

# Change default in config
# search_mode = "fulltext"

Sync Issues

Sync Failing

Symptom: atuin sync returns error.

Solution:

# 1. Check network
curl https://api.atuin.sh/healthz

# 2. Check login status
atuin status

# 3. Re-login if needed
atuin logout
atuin login -u <USERNAME>

# 4. Force sync
atuin sync --force

# 5. Debug mode
ATUIN_LOG=debug atuin sync

Authentication Failed

Symptom: Login fails or sync returns 401.

Solution:

# Clear session and re-login
rm ~/.local/share/atuin/session
atuin login -u <USERNAME>

# If password forgotten:
# Use email recovery or create new account

Sync Conflict / Duplicate History

Symptom: Same commands appearing multiple times.

Solution:

# Enable sync v2 (handles conflicts better)
# In config.toml:
# [sync]
# records = true

# Force full resync
atuin sync --force

Self-Hosted Server Connection Failed

Symptom: Can't connect to self-hosted server.

Solution:

# 1. Check server is running
curl http://your-server:8888/healthz

# 2. Check config
grep sync_address ~/.config/atuin/config.toml

# 3. Ensure correct URL format
# sync_address = "http://localhost:8888"
# NOT: sync_address = "localhost:8888"

# 4. Check firewall/port
nc -zv your-server 8888

Database Issues

Corrupted Database

Symptom: Errors about database corruption.

Solution:

# 1. Check database integrity
sqlite3 ~/.local/share/atuin/history.db "PRAGMA integrity_check"

# 2. If corrupt, backup and recreate
mv ~/.local/share/atuin/history.db ~/.local/share/atuin/history.db.bak

# 3. Reimport history
atuin import auto

# 4. Resync (if using sync)
atuin sync

Database Locked

Symptom: "database is locked" errors.

Solution:

# 1. Check for multiple atuin processes
pgrep -a atuin

# 2. Kill daemon if running
pkill atuin

# 3. Try again
atuin search

Large Database / Slow Performance

Symptom: Database file very large, operations slow.

Solution:

# Check database size
ls -lh ~/.local/share/atuin/history.db

# Optimize database
sqlite3 ~/.local/share/atuin/history.db "VACUUM"

# Prune old history
atuin history prune --older-than "1 year"

# Check entry count
sqlite3 ~/.local/share/atuin/history.db "SELECT COUNT(*) FROM history"

Key and Encryption Issues

Lost Encryption Key

Symptom: Can't decrypt history after reinstall.

Solution:

# If you have backup:
cp /path/to/backup/key ~/.local/share/atuin/key

# If no backup - must start fresh:
atuin logout
rm ~/.local/share/atuin/key
rm ~/.local/share/atuin/session

# Delete server account
atuin account delete

# Re-register
atuin register -u <USERNAME> -e <EMAIL>

Key Mismatch Between Machines

Symptom: Sync works but can't decrypt history from other machine.

Solution:

# All machines must use the SAME key

# On working machine, backup key:
cat ~/.local/share/atuin/key
# Save this value securely

# On broken machine:
# Replace key with the correct one
echo "your-key-value" > ~/.local/share/atuin/key

# Resync
atuin sync --force

Shell-Specific Issues

Zsh: Slow Startup

Symptom: Shell takes long to start after adding Atuin.

Solution:

# Time the init
time (eval "$(atuin init zsh)")

# If slow, check for issues:
atuin doctor

# Use lazy loading (add to .zshrc):
atuin-init() {
  eval "$(atuin init zsh)"
  unfunction atuin-init
}
# Bind to first Ctrl+R
zle -N atuin-init
bindkey '^R' atuin-init

Bash: History Not Saving

Symptom: Commands not appearing in Atuin history.

Solution:

# Check PROMPT_COMMAND
echo $PROMPT_COMMAND
# Should include atuin

# Ensure proper init
eval "$(atuin init bash)"

# Check for conflicting PROMPT_COMMAND settings
# Atuin needs to be included

Fish: Errors on Init

Symptom: Fish shows errors on startup.

Solution:

# Check Fish version (needs 3.0+)
fish --version

# Correct init syntax
atuin init fish | source

# NOT:
# eval "$(atuin init fish)"  # Wrong for Fish!

Import Issues

Import Not Finding History

Symptom: atuin import auto imports nothing.

Solution:

# Check history file exists
ls -la ~/.zsh_history
ls -la ~/.bash_history

# Check history file format
file ~/.zsh_history

# Try specific import
atuin import zsh
atuin import bash

# Check for extended history format (Zsh)
head ~/.zsh_history
# Should show timestamps if extended history is on

Duplicate Entries After Import

Symptom: Same command appears multiple times.

Solution:

# Import is idempotent - running twice shouldn't duplicate
# But if you have duplicates from before:

# Export unique commands
atuin history list --cmd-only | sort -u > unique_cmds.txt

# Clear and reimport (drastic)
rm ~/.local/share/atuin/history.db
atuin import auto

Performance Optimization

General Slowness

# ~/.config/atuin/config.toml

# Faster search
search_mode = "prefix"
filter_mode = "session"

# Minimal UI
show_preview = false
show_help = false
inline_height = 15
style = "compact"

# Reduce sync
sync_frequency = "4h"
auto_sync = false  # Manual sync only

Large History Database

# Check size
du -h ~/.local/share/atuin/history.db

# Prune old entries
atuin history prune --older-than "6 months"

# Vacuum database
sqlite3 ~/.local/share/atuin/history.db "VACUUM"

Reset Everything

Complete Reset

# 1. Logout
atuin logout

# 2. Remove all local data
rm -rf ~/.local/share/atuin
rm -rf ~/.config/atuin

# 3. Remove shell integration
# Edit .zshrc/.bashrc and remove atuin lines

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

# 5. Reconfigure
eval "$(atuin init zsh)"
atuin import auto
# Optionally: atuin register / atuin login

Uninstall Completely

# Remove binary
rm $(which atuin)

# Remove data
rm -rf ~/.local/share/atuin
rm -rf ~/.config/atuin

# Remove shell integration
# Edit .zshrc/.bashrc and remove:
# eval "$(atuin init zsh)"

# Reload shell
exec $SHELL

Getting Help

Resources

• Doctor: atuin doctor - Built-in diagnostics
• Docs: https://docs.atuin.sh
• Forum: https://forum.atuin.sh
• Discord: Community support
• GitHub Issues: https://github.com/atuinsh/atuin/issues

Reporting Bugs

# Include this info in bug reports:
atuin --version
atuin info
atuin doctor

# System info
uname -a
echo $SHELL

Atuin Workflows Reference

Advanced usage patterns and workflow automation with Atuin.

Daily Development Workflow

Morning Startup

# Sync history from other machines
atuin sync

# Quick check of yesterday's work
atuin search --after "yesterday" --cwd $(pwd)

# Find that command you were running
atuin search --filter-mode directory "docker"

During Development

# Search within current project
# Press Ctrl+R, type query
# Press Ctrl+R again to cycle: session → directory → host → global

# Find successful builds only
atuin search --exit 0 "make build"

# Find all test runs
atuin search "pytest\|npm test\|cargo test"

End of Day

# Review what you did
atuin history list --after "today 9am" --cmd-only

# Check your patterns
atuin stats --period day

# Ensure sync is up to date
atuin sync

Multi-Machine Workflow

Primary Workstation Setup

# Register account (first time)
atuin register -u myuser -e me@example.com

# Import all history
atuin import auto

# Enable sync v2 for efficiency
cat >> ~/.config/atuin/config.toml << 'EOF'
[sync]
records = true
EOF

# Initial sync
atuin sync

Secondary Machine Setup

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

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

# Login (use same credentials)
atuin login -u myuser

# Sync to get all history
atuin sync

# Now you have unified history across machines!

Laptop + Desktop + Server

# All machines use same account
# History automatically syncs

# On any machine, search global history:
atuin search --filter-mode global "kubectl"

# Filter to specific host:
atuin search --host my-server "systemctl"

# See where a command was run:
atuin history list --format "{hostname}\t{command}" | grep "docker"

Project-Specific Workflows

Per-Project History

# Navigate to project
cd ~/projects/myapp

# Search only this directory's history
atuin search --filter-mode directory "npm"

# Or set as default (press Ctrl+R repeatedly to cycle modes)
# Config: filter_mode_shell_up_key_binding = "directory"

# Find all commands run in this repo (workspace mode)
atuin search --filter-mode workspace "git"

Monorepo Navigation

# In monorepo root
cd ~/projects/monorepo

# Find commands in specific subdirectory
atuin search --cwd ~/projects/monorepo/packages/api "test"

# Search across workspace (git root)
atuin search --filter-mode workspace "build"

Debugging & Investigation

Find the Failing Command

# Find recent failures
atuin search --exit 1 --after "1 hour ago"

# Find specific failing command
atuin search --exit 1 "make"

# See exit codes in output
atuin history list --format "{exit}\t{command}" --limit 20

Recreate Environment

# Find all commands run in a directory
atuin search --cwd /path/to/project --after "yesterday"

# Export for documentation
atuin history list --cwd /path/to/project --after "yesterday" --cmd-only > commands.txt

Incident Response

# What happened in the last hour?
atuin history list --after "1 hour ago"

# Find all commands on production server
atuin search --host prod-server-01 --after "today"

# Successful commands only
atuin search --host prod-server-01 --exit 0 --after "today"

Pipeline & Automation

CI/CD History Preservation

# In CI, set unique session
export ATUIN_SESSION="ci-$(date +%Y%m%d-%H%M%S)"

# Initialize without binding keys
eval "$(atuin init bash --disable-up-arrow --disable-ctrl-r)"

# Commands now recorded with CI session identifier

Scripted History Analysis

# Export history for analysis
atuin history list --cmd-only > all_commands.txt

# Find most used commands
atuin stats --count 50 > top_commands.txt

# Commands per day
atuin history list --format "{time}" | cut -d' ' -f1 | uniq -c

# Export specific time range
atuin history list --after "2024-01-01" --before "2024-02-01" --cmd-only > january.txt

Backup Workflow

# Backup encryption key (CRITICAL)
cp ~/.local/share/atuin/key ~/backups/atuin-key-$(date +%Y%m%d).txt

# Backup database
cp ~/.local/share/atuin/history.db ~/backups/atuin-history-$(date +%Y%m%d).db

# Backup config
cp ~/.config/atuin/config.toml ~/backups/atuin-config.toml

Power User Workflows

Quick Command Replay

# Ctrl+R → search → Tab (select without execute)
# Edit the command, then Enter

# Alt+1 through Alt+9 for quick select
# Shows last 9 commands, Alt+N to select Nth

Context-Aware Search

# Automatic context (in git repo)
# Up arrow defaults to session history
# Ctrl+R opens full search

# Change default behavior:
# filter_mode_shell_up_key_binding = "directory"
# Now up arrow shows directory history

Statistics-Driven Optimization

# Review your patterns
atuin stats

# If certain commands are frequent, create aliases
# Example output shows:
#  1. git status     (2,345)
#  2. cd             (1,890)
#  3. git diff       (1,234)

# Create aliases for top commands
alias gs="git status"
alias gd="git diff"

# Sync aliases across machines (v18.1+)
atuin dotfiles alias set gs "git status"
atuin dotfiles alias set gd "git diff"

Shell Integration Customization

# Custom keybindings in .zshrc

# Keep up arrow for local history
eval "$(atuin init zsh --disable-up-arrow)"
bindkey '^[[A' up-line-or-history

# Custom binding for Atuin
bindkey '^[r' atuin-search  # Alt+R instead of Ctrl+R

Team Workflows

Shared Self-Hosted Server

# Team server setup (admin)
docker run -d \
  --name atuin-team \
  -p 8888:8888 \
  -v /data/atuin:/data \
  -e ATUIN_OPEN_REGISTRATION=true \
  ghcr.io/atuinsh/atuin:latest server start

# Team members configure
# sync_address = "https://atuin.company.internal"

# Each member has separate account
# No history shared between accounts (privacy preserved)

Documentation from History

# Generate runbook from actual commands
atuin search --cwd /path/to/project --cmd-only | \
  grep -E "^(docker|kubectl|make|npm)" > runbook-commands.md

# Add context
echo "# Deployment Commands" > runbook.md
echo "" >> runbook.md
atuin search --exit 0 "kubectl apply" --cmd-only >> runbook.md

Integration with Other Tools

Atuin + fzf (Hybrid)

# Use Atuin for command history
# Use fzf for file/directory finding

# In .zshrc
eval "$(atuin init zsh)"
# fzf bindings except Ctrl+R
source /path/to/fzf/shell/completion.zsh
# Don't source key-bindings.zsh (conflicts with Atuin)

# Manual fzf file finding
bindkey '^T' fzf-file-widget

Atuin + tmux

# Each tmux pane gets unique ATUIN_SESSION
# History automatically separated by session

# Search across all tmux sessions
atuin search --filter-mode host "query"

# Search current pane only
atuin search --filter-mode session "query"

Atuin + direnv

# direnv sets project-specific env
# Atuin tracks per-directory history

# Natural workflow:
cd ~/project  # direnv loads env
# Press Ctrl+R → shows project history
# Ctrl+R again → switches to global

Security-Conscious Workflows

Sensitive Project

# ~/.config/atuin/config.toml

# Strong filtering
secrets_filter = true
history_filter = [
  ".*password.*",
  ".*secret.*",
  ".*token.*",
  ".*api.key.*",
  "^vault.*",
  "^aws configure.*"
]

# Filter sensitive directories
cwd_filter = [
  "/projects/classified",
  "/secrets"
]

Air-Gapped / Offline Mode

# ~/.config/atuin/config.toml

# Disable all sync
auto_sync = false
sync_address = ""

# Local-only usage
# Full functionality without network

Audit Trail

# Export for compliance
atuin history list \
  --format "{time}\t{hostname}\t{user}\t{cwd}\t{exit}\t{command}" \
  --after "2024-01-01" \
  --before "2024-02-01" \
  > audit-january-2024.tsv

# Include in audit logs

Troubleshooting Workflow

Performance Issues

# 1. Check database size
du -h ~/.local/share/atuin/history.db

# 2. Check entry count
sqlite3 ~/.local/share/atuin/history.db "SELECT COUNT(*) FROM history"

# 3. Prune if large
atuin history prune --older-than "1 year"

# 4. Vacuum
sqlite3 ~/.local/share/atuin/history.db "VACUUM"

# 5. Use faster settings
# search_mode = "prefix"
# filter_mode = "session"

Sync Debugging

# 1. Check status
atuin status

# 2. Debug sync
ATUIN_LOG=debug atuin sync 2>&1 | tee sync-debug.log

# 3. Force full resync
atuin sync --force

# 4. Re-authenticate if needed
atuin logout
atuin login -u <USERNAME>
atuin sync

History Recovery

# If database corrupted:
# 1. Backup current
mv ~/.local/share/atuin/history.db ~/.local/share/atuin/history.db.bak

# 2. If using sync, re-download
atuin sync

# 3. If no sync, reimport
atuin import auto

# 4. Restore from backup if available
cp ~/backups/atuin-history.db ~/.local/share/atuin/history.db