atuin

Atuin スキル

すべてのマシン間で暗号化同期できる、魔法のようなシェル履歴です。

概要

Atuin はシェル履歴を SQLite データベースに置き換え、次の機能を提供します。

• 全画面の履歴検索 UI（Ctrl+R／上矢印）
• マシン間のエンドツーエンド暗号化同期
• コンテキストの記録（終了コード、作業ディレクトリ、ホスト名、実行時間）
• 統計と分析
• フィルターモード（セッション、ディレクトリ、グローバル）
• Alt+数字キーによるクイックナビゲーション

対応シェル

シェル	サポートレベル
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

シェル統合

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	検索 UI を開く
Up/Down	履歴を移動
Tab	実行せずに選択
Enter	コマンドを実行
Alt+1-9	項目をクイック選択
Ctrl+R（UI 内）	フィルターモードを切り替え

フィルターモード

モード	説明
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 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

セルフホストサーバー

# 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 ファイルのシェル統合を確認してください
同期に失敗する	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 の履歴はシェルの履歴ファイルと共有されません — ~/.zsh_history と atuin の DB は次第に食い違い、history 組み込みコマンドと atuin の検索で異なる結果が返されます。
• セルフホストのサーバーには PostgreSQL が必要です — SQLite は単一ユーザー専用です。「embedded mode」に関するエラーでは、問題が明確に示されません。