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.
Setting Atuin up takes four steps, and only the first is required. The install script runs atuin setup, which walks you through the first three:
- 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 installs the binary, then runs atuin setup, which installs 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. After installing the binary another way, run atuin setup to do the rest.
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 setup brings the old ones in. Setup imports your current shell's history file, which stays untouched — your shell keeps writing to it as usual.
If you skipped the import, or your sync account already had history, import this machine's history with:
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.
Setup offers to sign you in to Atuin Cloud. If you skipped sync, sign in through your browser with:
Atuin encrypts your history with a key that it keeps on this machine. Run atuin key to show the key. Save the key 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 with
atuin setup --only --no-up-arrowif 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.