Skip to content
Get packs

Guide · Open source

How to use Atuin: install, search shell history and sync

Updated · written with AI from the project's own documentation and checked against our catalogue data

Atuin is an open-source tool, licensed under MIT and written in Rust, that replaces your shell's default history with a SQLite database and records extra details about each command, such as exit code, duration and directory. This guide is for developers who work in a terminal and often need to find past commands. After reading it, you will know how to install Atuin, import your existing history, search it, and optionally sync it between machines.

Atuinatuinsh/atuin · ★ 32.2k · MIT

Quick start

  1. 1Install Atuin. Run the README quickstart install command, then restart your shell.
  2. 2Register for sync (optional). Run atuin register with your chosen username and email if you want Atuin Cloud sync.
  3. 3Import history. Run atuin import auto to bring in your existing shell history.
  4. 4Sync. Run atuin sync to upload and download encrypted history between machines.
  5. 5Search. Press ctrl-r to open the search UI and filter by session, directory or globally.

What Atuin does to your shell history

Atuin replaces how your shell stores and searches history. Instead of the plain default history file, commands go into a SQLite database along with context such as exit code, working directory, hostname, session and command duration.

The old history file is not replaced, according to the project's feature list, so your original history stays in place.

  • Rebinds ctrl-r and up (configurable) to a full screen history search UI
  • Filters searches by current session, current directory, or globally (switch with ctrl-r)
  • Quick-jumps to previous items with Alt-<num>
  • Can calculate statistics such as most used command

Install Atuin

The README quickstart installs Atuin with a single shell command. Run it in your terminal, then restart your shell. The README lists no separate prerequisites.

The install script is fetched over HTTPS with TLS 1.2 or later enforced by the flags shown below.

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

Import your existing history

Once installed, you can bring in the history your shell already has. The README's quickstart uses the auto option, which detects the import source for you.

Your old history file is kept, so importing does not remove anything from your shell's default history.

atuin import auto

Search your history

Press ctrl-r to open the full screen search UI. Type part of a command to filter results, then press enter to run the selected command or tab to edit it first.

The README also shows a command-line search with filters. This example finds successful make commands recorded after 3pm yesterday.

  • enter executes the selected command
  • tab lets you edit it before running
  • ctrl-r switches between session, directory and global filter modes
atuin search --exit 0 --after "yesterday 3pm" make

Sync history between machines (optional)

Sync is optional. The quickstart signs you up for the Atuin Cloud sync server. The README states that all history sync is end-to-end encrypted. You can also host your own server or skip sync entirely; the docs cover offline and self-hosted setups.

Register with your username and email, then run a sync. Replace the placeholders with your own values.

  • Register: atuin register -u <USERNAME> -e <EMAIL>
  • Sync: atuin sync
atuin register -u <USERNAME> -e <EMAIL> atuin sync

Check which shells are supported

Atuin supports zsh, bash, fish, nushell, xonsh and PowerShell according to the README. Support is limited to these shells, so check the supported platforms page for the full matrix and what each tier means.

Bash users need extra care: the quickstart sets up bash-preexec for hooks, which has limitations described in the installation docs.

  • zsh, bash, fish, nushell, xonsh, PowerShell

What people use it for

  • Finding a long-ago command by a few characters of its text
  • Checking which commands succeeded using the exit code filter
  • Keeping the same shell history across a laptop and a desktop
  • Reviewing how long commands took or which command you use most

Frequently asked questions

Is Atuin free and what is its licence?

Atuin is open source under the MIT licence, according to the project's README. The README does not list prices for the Atuin Cloud sync server, so check the homepage at atuin.sh for current terms.

How do I install Atuin?

Run the quickstart command from the README: curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh, then restart your shell. The README lists no other prerequisites.

Is my synced shell history private?

The README says all history sync is fully encrypted end to end, and that the maintainer could not access your data. You can also run your own server or skip sync entirely.

Which shells does Atuin work with?

The README says Atuin supports zsh, bash, fish, nushell, xonsh and PowerShell. Shells not in that list are not supported.

What is Atuin an alternative to?

The project lists fzf, McFly, hstr and zsh-history-substring-search as comparable projects. Atuin differs by storing history in SQLite, recording extra context and offering optional encrypted sync.

Why is ctrl-r not opening Atuin after install?

The README says to restart your shell after installing. Bash users should also read the bash-preexec limitations in the installation docs, linked from the README quickstart.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Atuin suits developers who work in a terminal, search old commands often, or use several machines and want the same history on each. It is a poor fit if you want your default shell history left unchanged, or if you use a shell outside the supported list. The README points to docs for offline and self-hosted setups if you want sync without the cloud server.

Install options & downloads