Basic Usage
Now that you’ve installed Atuin, let’s go over the basics of using Atuin.
What does Atuin record?
Section titled “What does Atuin record?”While you work, Atuin can record:
- The terminal commands that run on your computer, the directories they ran in, when the commands were started, and how long these commands lasted, and other metadata.
- The output of all your terminal commands.
- Your agent threads, ie. the full transcripts, tool calls, and behavior of any coding agent.
All this data is searchable.
History
Section titled “History”If you want to capture commands your agents ran, make sure atuin setup --agent-history is enabled.
Atuin makes searching through your history easy and fast.
Interactive Usage
Section titled “Interactive Usage”At any time in the terminal, you can open Atuin’s TUI with either the ↑ arrow, or with CTRL-R.
Some default keybindings are:
| Keybinding | Description |
|---|---|
| Return | Execute the highlighted command. |
| CTRL-R | Cycle through filter modes. |
| ALT-1 to 9 | Execute one of the most recent-commands. |
| CTRL-O | Open the inspector. |
Filter Modes
Section titled “Filter Modes”Hitting CTRL-R again, while the TUI is open, allows you to filter through different modes, which control what Atuin searches through:
| Mode | Search domain |
|---|---|
GLOBAL |
All your history, across all your machines. |
HOST |
The active computer’s history. |
SESSION |
The history of the active shell session. |
WORKSPACE |
Commands ran in the active VCS workspace. |
DIRECTORY |
Commands ran in the current working directory. |
SESSION+ |
The active session, and commands before it was started. |
Search Modes
Section titled “Search Modes”Hitting CTRL-S allows you control how Atuin matches search results:
| Mode | Description |
|---|---|
DAEMON (default) |
Atuin uses its in-memory index held in a daemon. |
PREFIX |
Atuin matches on the start of the result. |
FULLTXT |
Atuin does a full-text search of all the search results. |
Search syntax
Section titled “Search syntax”The search syntax for DAEMON follows the
fzf search syntax:
| Token | Match type | Description |
|---|---|---|
sbtrkt |
fuzzy-match | Items that match sbtrkt |
'wild |
exact-match (quoted) | Items that include wild |
^music |
prefix-exact-match | Items that start with music |
.mp3$ |
suffix-exact-match | Items that end with .mp3 |
!fire |
inverse-exact-match | Items that don’t include fire |
!^music |
inverse-prefix-exact-match | Items that don’t start with music |
!.mp3$ |
inverse-suffix-exact-match | Items that don’t end with .mp3 |
You can create and and or search queries by combining these basic tokens:
| Expression | Example | Description |
|---|---|---|
A | B |
^foo | $bar |
Starts with foo or ends with bar. |
A B |
^foo bar$ |
Starts with foo and ends with bar. |
Inspector
Section titled “Inspector”Atuin’s inspector allows you to get additional information on a command. After opening the inspector, you can see when you ran a particular command. You can see your runs by pressing R, what commands you ran during the session via S and get stats on the command via T.
In the Runs view, you can press Return to get the command output of a command:
Command-Line Usage
Section titled “Command-Line Usage”You can search through your history via the atuin search command:
If you want to search for a command via the output capture, use atuin output search:
Threads
Section titled “Threads”Atuin also captures everything your agents did. We call this feature Atuin Threads.
Resuming Threads
Section titled “Resuming Threads”You can resume a thread started in one harness in another harness, be it on the
same machine, or across multiple machines by running atuin thread resume:
Command-line Usage
Section titled “Command-line Usage”With atuin threads search, you can perform a full-text search for a
session you had with an AI agent:
Using atuin threads tail allows you to see everything your agents are doing
in real-time:
MCP Support
Section titled “MCP Support”All of Atuin’s features are available to your agents.
Agents have access to your history, and our MCPs enable them to find information across your whole cluster of computers.
Atuin can sync all your data across all your computers. With sync enabled, Atuin periodically synchronizes the data it captured with a sync server.
Atuin offers a free sync server at https://atuin.sh. atuin setup offers to sign
you in when it sets Atuin up. To create an account or sign in later, run:
atuin setup --sync cloudSetup opens your browser, where you can create an account or sign in.
TODO CLAUDE VHS TAPE HERE