Find the command you already ran
Atuin makes shell history searchable across sessions, with context such as the directory and exit status. Start with local search; add synchronization only if you want history available on other machines.
What Atuin changes
The CLI stores command history in a local SQLite database and integrates with your shell. Its interactive search replaces the usual reverse-history lookup. It does not require a Python runtime, a sync account, or a server running on your laptop.
The useful distinction is between recording a command and sharing it: local history works on its own, while sync is an optional service with separate authentication and encryption settings.
Install the CLI and enable Zsh integration
On macOS with Homebrew:
brew install atuin
atuin --version
For Linux, Windows, or another package manager, use the platform instructions in the official installation guide. The supported installation routes change over time; pip install atuin is not the installation method for this CLI.
For Zsh, add this line once to ~/.zshrc:
eval "$(atuin init zsh)"
Open a new shell, then import existing history:
atuin import auto
The argument to atuin init identifies the shell. Bash, Fish, and PowerShell have different integration instructions; do not paste the Zsh line into those startup files.
Configure the search interface
Atuin uses TOML. Current documentation places the main file at ~/.atuin/config.toml; older installations may still use ~/.config/atuin/config.toml or an XDG location. ATUIN_HOME and ATUIN_CONFIG_DIR can override the defaults. Check your installation before editing a file. For example:
search_mode = "fuzzy"
filter_mode = "global"
Change one setting at a time and open a new search session to check the result. See the configuration reference for the options supported by your installed version. A YAML file with a similar name will not configure the CLI.
Search and reuse commands
Press Ctrl+R in an integrated shell to open interactive history search. Search for part of a command, inspect the selected entry, and check the current directory and arguments before executing it. History can contain commands aimed at a different environment.
The CLI is also useful for inspection:
atuin history list
atuin search "git"
atuin search --help
If Ctrl+R still opens the original shell search, check that the initialization line runs in your interactive shell and that another plugin does not rebind the key afterward.
Narrow a large history
Use the interactive filters to focus on a directory, session, or host rather than inventing a separate tagging workflow. For scripted searches, check atuin search --help for the filters and date syntax available in your release. A small, precise query is easier to review than an unfiltered history dump.
For supported filters and examples, consult the search reference.
What is useful in everyday work
The local database keeps searches independent of a single shell session. Directory and host context help distinguish similar deployment, Git, and database commands. Interactive search is especially useful when you remember the task but not the exact flag sequence.
Atuin records what happened; it cannot determine whether replaying an old command is appropriate now. Treat a history entry as a draft to inspect, especially when it includes credentials, a production hostname, or a destructive flag.
Optional encrypted synchronization
Follow the official sync guide to register or log in and configure another machine. Keep the encryption key recoverable in a secure place; a login password and a history encryption key serve different purposes.
Self-hosting a sync server is a separate deployment. The current server setup guide uses the atuin-server binary. Decide what you want to synchronize before enabling sync, and review Atuin’s history filtering settings if commands may contain sensitive values.
A practical first session
Install the CLI, enable the integration for your actual shell, import existing history, and find three commands you use frequently. If that already solves the problem, leave the setup local. Add sync later when sharing history between machines has a clear benefit.
For the implementation and supported commands, consult the Atuin repository. Documentation links and command syntax were checked on October 16, 2026; shell behavior still depends on the installed release and your key bindings.