Skip to content
Atuin

Basic Usage

Now that you’ve installed Atuin, let’s go over the basics of using Atuin.

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.

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.

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.

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.

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.

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.

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:

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:

Atuin also captures everything your agents did. We call this feature Atuin 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:

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:

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:

Terminal window
atuin setup --sync cloud

Setup opens your browser, where you can create an account or sign in.

TODO CLAUDE VHS TAPE HERE