Sync and search shell history across machines with atuin

Tools used

• 

  atuin

  Shell history management with SQLite storage, search interface, and encrypted sync across machines

  32.1kRust

Before you start

• -zsh, bash, fish, nushell, xonsh or PowerShell
• -For bash: ble.sh 0.4+ is recommended; bash-preexec also works with some limits
• -An email address and username if you want to use sync

Steps

1. 1Step 1: Install atuin

   The official install script puts the binary in ~/.atuin/bin, sets up the shell plugin and walks you through import and sync interactively. Package managers install only the binary, so you also need step 2.

   sh

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

   sh

   # or, with a package manager
   $ brew install atuin
   $ pacman -S atuin
   $ cargo install atuin --locked

2. 2Step 2: Load the shell plugin

   Add the line for your shell to its rc file, then open a new terminal. atuin init installs the hooks that record each command and the key bindings.

   In bash, atuin 18.18.0 and newer loads a bundled copy of bash-preexec automatically if neither ble.sh nor bash-preexec is already loaded. ble.sh gives more accurate durations and exit codes.

   zsh

   # ~/.zshrc
   $ eval "$(atuin init zsh)"

   bash

   # ~/.bashrc
   $ eval "$(atuin init bash)"

   fish

   # ~/.config/fish/config.fish, inside the is-interactive block
   $ atuin init fish | source

3. 3Step 3: Import your existing history

   atuin only records new commands through the plugin. atuin import auto reads your current shell's history file, detected from $SHELL. Name the shell explicitly if detection picks the wrong one, and set HISTFILE to read a non-default file.

   Imported entries lack exit codes and durations because the old file never stored them. Your old history file is not replaced and keeps being written by the shell.

   sh

   $ atuin import auto

   sh

   $ atuin import zsh
   $ HISTFILE=~/backup/.zsh_history atuin import zsh

4. 4Step 4: Search with Ctrl-R and the up arrow

   Press Ctrl-R and type part of a command. Inside the search UI, Ctrl-R cycles the filter mode, such as global, host, session or directory, Enter runs the selected command, Tab puts it on the prompt for editing, and Alt-1 to Alt-9 pick an entry by its number.

   atuin search runs the same queries non-interactively, with filters such as exit code and time.

   sh

   # successful make commands run after 3pm yesterday
   $ atuin search --exit 0 --after "yesterday 3pm" make

5. 5Step 5: Change or disable the up-arrow binding

   By default the up arrow also opens atuin. To keep Ctrl-R but give the up arrow back to your shell, pass --disable-up-arrow to atuin init. --disable-ctrl-r does the reverse, and setting ATUIN_NOBIND before atuin init binds nothing so you can bind keys yourself.

   If you want to keep the up arrow but scope it, set filter_mode_shell_up_key_binding in ~/.config/atuin/config.toml; for example directory shows only commands run in the current directory.

   zsh

   # ~/.zshrc: Ctrl-R only
   $ eval "$(atuin init zsh --disable-up-arrow)"

   zsh

   # ~/.zshrc: bind keys yourself
   $ export ATUIN_NOBIND="true"
   $ eval "$(atuin init zsh)"
   $ bindkey '^r' atuin-search

   toml

   # ~/.config/atuin/config.toml
   filter_mode_shell_up_key_binding = "directory"

6. 6Step 6: Register and run the first sync

   On your first machine, register an account. Leave out -p and atuin prompts for the password, which keeps it out of your history. Registration generates an encryption key and stores it locally; print it with atuin key and save it in a password manager. Nobody can recover it for you.

   After that, sync runs automatically in the background. Run atuin sync to trigger it by hand.

   sh

   $ atuin register -u <USERNAME> -e <EMAIL>
   $ atuin key
   $ atuin sync

7. 7Step 7: Log in on your other machines

   Install atuin and the shell plugin on the next machine, optionally import its local history, then log in. atuin asks for your password and the key from atuin key. If entries seem to be missing after the first sync, atuin sync -f forces a full sync.

   sh

   $ atuin import auto
   $ atuin login -u <USERNAME>
   $ atuin sync

8. 8Step 8: Optional: use a self-hosted server

   The server is a separate binary, atuin-server, backed by PostgreSQL, MySQL or SQLite. It reads ~/.config/atuin/server.toml; db_uri is required and open_registration defaults to false, so set it to true while you create accounts. The project recommends tracking tagged releases rather than main or latest.

   On each client, set sync_address to your server before you run atuin register or atuin login. The ATUIN_SYNC_ADDRESS environment variable works too.

   toml

   # server: ~/.config/atuin/server.toml
   host = "0.0.0.0"
   port = 8888
   open_registration = true
   db_uri = "postgres://user:password@hostname/database"

   sh

   $ atuin-server start

   toml

   # client: ~/.config/atuin/config.toml
   sync_address = "https://atuin.example.com"