Getting Started
This guide walks through setting Atuin up properly, one step at a time. If you just want the commands, the quickstart on the home page has them.
Setup takes four steps, and only the first is required:
- Install Atuin and its shell plugin
- Import your existing history
- Set up sync, if you want your history on more than one machine
- Learn the TUI
1. Install
The install script handles the binary and the shell plugin, and walks you through the rest:
Then restart your shell. Prefer a package manager, or want to install the pieces yourself? See Installation.
At this point Atuin is recording new commands. Press Ctrl+R or the Up arrow to search them.
2. Import your existing history
Atuin only records commands run after it's installed, so bring the old ones in:
This detects your shell and imports from its history file, which stays untouched — your shell keeps writing to it as usual. See Import existing history for importing from a specific shell or a non-default file.
3. Set up sync (optional)
Sync backs your history up and shares it between machines, end-to-end encrypted. You can use our server or host your own.
Registration generates an encryption key. Save it somewhere safe — you'll need it to log in on any other machine, and it can't be recovered. See Setting up sync for the details, including logging in elsewhere.
Skipping this step is fine. Your history stays on this machine, not backed up and not synchronized.
4. Make it yours
Once you're up and running:
- Basic usage — what Atuin records, and how to drive the TUI
- Filter and search modes — narrow searches to this directory, this machine, or this session
- Key bindings — including how to disable the up arrow binding if it isn't for you
- Config — every setting, including an inline window instead of full screen
Getting help
Open a topic on the forum, join our Discord, or file an issue. Running atuin doctor collects the information we'll ask for.