atuin

Atuin 技能

神奇的 Shell 历史记录，可在所有设备间加密同步。

概述

Atuin 使用 SQLite 数据库替代 Shell 历史记录，并提供：

• 全屏历史记录搜索界面（Ctrl+R / 向上箭头）
• 设备间端到端加密同步
• 上下文日志记录（退出代码、当前工作目录、主机名、耗时）
• 统计信息和分析
• 筛选模式（会话、目录、全局）
• 使用 Alt+数字键快速导航

支持的 Shell

Shell	支持级别
Zsh	完全支持
Bash	完全支持
Fish	完全支持
Nushell	完全支持
Xonsh	完全支持

快速开始

安装

# 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 集成

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

首次设置

# Import existing history
atuin import auto

# Optional: Register for sync
atuin register -u <USERNAME> -e <EMAIL>

# Verify setup
atuin doctor

搜索模式

交互式搜索（Ctrl+R）

按键	操作
Ctrl+R	打开搜索界面
Up/Down	浏览历史记录
Tab	选择但不执行
Enter	执行命令
Alt+1-9	快速选择条目
Ctrl+R（在界面中）	切换筛选模式

筛选模式

模式	描述
global	所有设备上的全部历史记录
host	仅当前设备
session	当前终端会话
directory	当前工作目录
workspace	Git 仓库根目录

搜索模式

模式	描述
prefix	匹配命令开头
fulltext	匹配任意位置的子字符串
fuzzy	模糊匹配（默认）
skim	Skim 风格的模糊查找器

命令行搜索

# 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"

同步设置

云同步（Atuin 服务）

# 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

自托管服务

# 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（更快）

# ~/.config/atuin/config.toml
[sync]
records = true  # Enable sync v2

配置

配置文件位置

~/.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

基本设置

# ~/.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

隐私筛选器

# ~/.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

按键绑定

# ~/.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"

命令参考

核心命令

# 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

导入命令

# 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

守护进程模式

# Start daemon (background sync)
atuin daemon

# Check daemon status
atuin daemon status

统计信息

查看统计信息

# 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)
#  ...

配置统计信息

# ~/.config/atuin/config.toml

[stats]
# Commands where subcommands matter
common_subcommands = [
  "cargo",
  "git",
  "kubectl",
  "docker",
  "npm"
]

# Prefixes to strip from stats
common_prefix = [
  "sudo"
]

工作流

日常开发工作流

# 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

多设备工作流

# 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

故障排除工作流

# 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

性能提示

优化搜索速度

# ~/.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

减少同步流量

# ~/.config/atuin/config.toml

# Sync less frequently
sync_frequency = "4h"

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

守护进程模式（v18.3+）

# ~/.config/atuin/config.toml

[daemon]
enabled = true
sync_frequency = 300  # seconds

迁移

从 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

从其他历史记录工具迁移

# mcfly: Export first, then import
mcfly export > history.txt
# Manual import needed

# hstr: Standard history import works
atuin import auto

安全

加密

• 所有同步数据均经过端到端加密
• 服务端无法读取你的历史记录
• 密钥存储在本地（~/.local/share/atuin/key）

密钥备份

# Backup your encryption key
cp ~/.local/share/atuin/key ~/atuin-key.backup

# Restore on new machine
cp ~/atuin-key.backup ~/.local/share/atuin/key

密钥筛选

# ~/.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.*"
]

故障排除

常见问题

问题	解决方案
Ctrl+R 无法使用	检查 rc 文件中的 Shell 集成
同步失败	运行 atuin doctor，检查网络
缺少历史记录	运行 atuin import auto
搜索缓慢	切换到 prefix 搜索模式
历史记录重复	检查是否多次导入

诊断命令

# 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

重置所有内容

# 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/configuration.md - 完整的配置参考，包含意图到配置的映射
• references/commands.md - 完整的 CLI 命令参考
• references/search-reference.md - 搜索标志、TUI 快捷键、Vim 模式、格式变量
• references/sync-setup.md - 详细的同步配置
• references/troubleshooting.md - 常见问题和解决方法
• references/workflows.md - 高级用法模式
• references/tips-and-tricks.md - 高级用户模式、与 fzf 共存、dotfiles 同步、tmux

外部链接

• 官方文档：https://docs.atuin.sh
• GitHub：https://github.com/atuinsh/atuin
• 论坛：https://forum.atuin.sh
• Discord：社区支持

---

注意事项

• 在使用强制门户的 Wi-Fi 下同步：atuin status 会报告正常，但只会在本地插入缓冲区。历史记录看起来没问题，直到你在另一台机器上检查。
• 加密密钥因机器而异——丢失密钥会导致你无法恢复已同步的历史记录。请备份 ~/.local/share/atuin/key。
• 搜索模式 fuzzy 与 prefix：匹配数量会有细微差异；凌晨 2 点切换模式会让肌肉记忆失灵。
• Atuin 历史记录不会与 shell 历史文件共享——~/.zsh_history 与 atuin 的数据库会逐渐不一致；history 内置命令和 atuin 搜索会返回不同结果。
• 可自托管的服务需要 PostgreSQL——SQLite 仅支持单用户。提及“embedded mode”的错误信息无法清楚地指出问题所在。