# Basic Usage

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

## 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](/guide/threads/), ie. the full transcripts, tool calls, and
behavior of any coding agent.

All this data is searchable.

:::note

You are in control of what you want to record. See [`atuin setup`](/reference/cli/setup/) to configure
what you want Atuin to manage.

:::

## History

:::info

If you want to capture commands your agents ran, make sure [`atuin setup
--agent-history`](/reference/cli/setup/) is enabled.

:::

Atuin makes searching through your history easy and fast.

### Interactive Usage

At any time in the terminal, you can open Atuin's TUI with either the
<kbd>↑</kbd> arrow, or with <kbd>CTRL</kbd>-<kbd>R</kbd>.

<VHSTape title="Pressing Ctrl-R opens Atuin's search. Typing narrows the history down, and Tab puts the selected command on the command line.">
  Sleep 600ms
  Ctrl+R
  Sleep 1.2s
  Type "git push"
  Sleep 1.5s
  Up
  Sleep 700ms
  Tab
  Sleep 2s
</VHSTape>

Some default keybindings are:

| Keybinding | Description |
|------------|-------------|
| <kbd>Return</kbd> | Execute the highlighted command. |
| <kbd>CTRL</kbd>-<kbd>R</kbd> | Cycle through [filter modes](#filter-modes). |
| <kbd>ALT</kbd>-<kbd>1</kbd> to <kbd>9</kbd> | Execute one of the most recent-commands. |
| <kbd>CTRL</kbd>-<kbd>O</kbd> | Open the [inspector](#inspector). |

:::tip[Configuration]

You can tweak the theme, keybindings and many other settings to make Atuin your
own. See the [configuration reference](/reference/config/) for more details.

Common changes to Atuin's configuration include

| Config | Description |
|--------|-------------|
| [`enter_accept = false`](/reference/config/general/#enter_accept) | <kbd>Return</kbd> inserts the command instead of executing it. |
| [`inline_height = 40`](/reference/config/general/#inline_height) | Atuin uses 40 rows to render the TUI. |
| [`style = "compact"`](/reference/config/general/#style) | Atuin uses a more compact-layout in the TUI. |

:::

:::tip[Tmux Compatibility]

Atuin supports `tmux` popups, if you enable [`[tmux.enabled] = true`](/reference/config/tmux/#tmuxenabled).

<VHSTape title="Inside tmux, with its popup on, Ctrl-R opens Atuin's search in a popup over the pane, and Escape closes it, leaving the pane as it was.">
  Set FontSize 20
  # Tall enough that the popup, at its default size, fits the search's input line.
  Set Height 800
  Env ATUIN_TMUX__ENABLED "true"
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  # A tmux server of the recording's own, without the build machine's config, running this zsh
  # rather than the machine's own shell. The status bar's right side would show the machine's name.
  Type ` SHELL="$commands[zsh]" tmux -L atuin-docs -f /dev/null new-session \; set -g status-right ''`
  Enter
  Sleep 2s
  Show
  Sleep 500ms
  Type "git status"
  Sleep 300ms
  Enter
  Sleep 1s
  Ctrl+R
  Sleep 1.5s
  Type "cargo"
  Sleep 2s
  Screenshot
  Escape
  Sleep 1.5s
  Hide
  Type " tmux -L atuin-docs kill-server"
  Enter
  Sleep 1s
</VHSTape>

TODO should this even exist?? TODO, should this even be here? i feel like this
isn't basic usage

:::

#### Filter Modes

Hitting <kbd>CTRL</kbd>-<kbd>R</kbd> 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. |

<VHSTape title="Pressing Ctrl-R again in Atuin's search cycles its filter: global, host, session, workspace, directory, and the session with what came before it.">
  Set FontSize 20
  Set Height 600
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  Show
  Sleep 500ms
  Ctrl+R
  Sleep 1.5s
  Ctrl+R
  Sleep 1.5s
  Ctrl+R
  Sleep 1.5s
  Ctrl+R
  Sleep 1.5s
  Ctrl+R
  Sleep 1.5s
  Screenshot
  Ctrl+R
  Sleep 1.5s
  Escape
  Sleep 500ms
</VHSTape>

#### Search Modes

Hitting <kbd>CTRL</kbd>-<kbd>S</kbd> 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. |

<VHSTape title="Pressing Ctrl-S cycles how a search for push matches: the daemon's index, then prefix, which finds nothing, then full text and fuzzy.">
  Set FontSize 20
  Set Height 600
  Env ATUIN_DAEMON__ENABLED "true"
  Env ATUIN_DAEMON__AUTOSTART "true"
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  Show
  Sleep 500ms
  Ctrl+R
  Sleep 1s
  Type "push"
  Sleep 2s
  Ctrl+S
  Sleep 2s
  Ctrl+S
  Sleep 2s
  Screenshot
  Ctrl+S
  Sleep 1.5s
  Escape
  Sleep 500ms
</VHSTape>

#### Search syntax

The search syntax for `DAEMON` follows the
[`fzf` search syntax](https://github.com/junegunn/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`. |

:::tip[Customization]

You can customize how atuin sorts the search results via the [`[search]`](/reference/config/search/)
configuration.

:::

#### 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 <kbd>R</kbd>, what commands you ran during the
session via <kbd>S</kbd> and get stats on the command via <kbd>T</kbd>.

<VHSTape title="Ctrl-O opens the inspector on kubectl get pods: its runs, the session it ran in, and its stats.">
  Set FontSize 20
  Set Height 600
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  Show
  Sleep 500ms
  Ctrl+R
  Sleep 1s
  Type "kubectl get"
  Sleep 1s
  Ctrl+O
  Sleep 2s
  Screenshot
  Type "s"
  Sleep 2s
  Type "t"
  Sleep 2s
  Type "r"
  Sleep 1.5s
  Escape
  Sleep 300ms
  Escape
  Sleep 500ms
</VHSTape>

In the _Runs_ view, you can press <kbd>Return</kbd> to get the command output
of a command:

<VHSTape title="Ctrl-O opens the inspector on kubectl get pods, and Return on its latest run shows what it printed: two api pods running, and a worker in CrashLoopBackOff.">
  Set FontSize 20
  Set Height 600
  # Output capture: the daemon stores what pty-proxy sees each command print.
  Env ATUIN_DAEMON__ENABLED "true"
  Env ATUIN_DAEMON__AUTOSTART "true"
  Env ATUIN_OUTPUT__ENABLED "true"
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  # pty-proxy only hands output to a daemon that's running when it starts, so it starts now.
  Type ` export ATUIN_PTY_PROXY__ENABLED=true && exec zsh`
  Enter
  Sleep 2s
  # Stands in for a cluster, so there's output to capture.
  Type ` kubectl() print -l 'NAME                     READY   STATUS             RESTARTS       AGE' 'api-7d9f8b6c5-x2k4q      1/1     Running            0              3d' 'api-7d9f8b6c5-p8w3n      1/1     Running            0              3d' 'worker-5c8d7e9f4-m7n2p   0/1     CrashLoopBackOff   12 (2m ago)    3d'`
  Enter
  Type "kubectl get pods -n prod"
  Enter
  Sleep 2s
  # The run just recorded carries the build machine's name; world.zsh renamed the rest.
  Type ` sqlite3 "$(atuin info | sed -n 's/^client db path: //p')" "update history set hostname = 'laptop:you'" && clear`
  Enter
  Sleep 1s
  Show
  Sleep 500ms
  Ctrl+R
  Sleep 1s
  Type "kubectl get"
  Sleep 1s
  Ctrl+O
  Sleep 1.5s
  Enter
  Sleep 3s
  Screenshot
  Escape
  Sleep 800ms
  Escape
  Sleep 300ms
  Escape
  Sleep 500ms
</VHSTape>

### Command-Line Usage

You can search through your history via the [`atuin search`](/reference/cli/search/) command:

<VHSTape title="atuin search finding every cargo test, then only the git commands that succeeded in this directory.">
  Set FontSize 20
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  Show
  Type "atuin search cargo test"
  Sleep 500ms
  Enter
  Sleep 2s
  Type "atuin search --exit 0 --cwd . git"
  Sleep 500ms
  Enter
  Sleep 2.5s
</VHSTape>

If you want to search for a command via the output capture, use [`atuin output
search`](/reference/cli/output/#atuin-output-search):

<VHSTape title="atuin output search for mismatched types finds the cargo test run that printed the error, with when it ran, how long it took, its exit code, and the lines that matched.">
  Set FontSize 20
  Set Height 600
  # Output capture: the daemon stores what pty-proxy sees each command print.
  Env ATUIN_DAEMON__ENABLED "true"
  Env ATUIN_DAEMON__AUTOSTART "true"
  Env ATUIN_OUTPUT__ENABLED "true"
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  # pty-proxy only hands output to a daemon that's running when it starts, so it starts now.
  Type ` export ATUIN_PTY_PROXY__ENABLED=true && exec zsh`
  Enter
  Sleep 2s
  # Stands in for a build that fails, so there's output to capture.
  Type ` cargo() ( print -l '   Compiling atuin-client v18.24.7' 'error[E0308]: mismatched types' '   --> crates/atuin-client/src/sync.rs:212:24' '    |' '212 |         let host: &str = record.host;' '    |                   ----   ^^^^^^^^^^^ expected &str, found String' '' 'error: could not compile atuin-client (lib) due to 1 previous error'; sleep 3; exit 101 )`
  Enter
  Type "cargo test"
  Enter
  # Past the 3s it takes, so nothing typed lands in what it printed.
  Sleep 4.5s
  Type " clear"
  Enter
  Sleep 1s
  Show
  Sleep 500ms
  Type "atuin output search mismatched types"
  Sleep 500ms
  Enter
  Sleep 3s
</VHSTape>

## Threads

Atuin also captures everything your agents did. We call this feature [Atuin
Threads](https://blog.atuin.sh/threads-agent-sessions/).

:::note[Opt-out]

We recognize many people do not want AI features in Atuin, and we actively
support this. Atuin **is yours**, and if you don't want Atuin to touch your
sessions, we do not expect you to.

See the [configuration](/reference/config/threads/) for more details.

:::

:::tip

Make sure threads are enabled by running [`atuin setup --threads`](/reference/cli/setup/).

:::

### 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`](/reference/cli/threads/#atuin-threads-resume):

<VHSTape title="atuin resume finds a Codex thread about atuin stats, and offers to resume it, fork it, or continue it in Claude Code or opencode.">
  Set FontSize 20
  Set Height 600
  Env ATUIN_DAEMON__ENABLED "true"
  Env ATUIN_DAEMON__AUTOSTART "true"
  Env ATUIN_THREADS__CAPTURE "true"
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  Show
  Type "atuin resume"
  Sleep 500ms
  Enter
  Sleep 2s
  Type "stats"
  Sleep 1.5s
  Enter
  Sleep 1.5s
  Down@600ms 2
  Sleep 2s
  Screenshot
  Escape
  Sleep 300ms
  Escape
  Sleep 500ms
</VHSTape>

### Command-line Usage

With [`atuin threads search`](/reference/cli/threads/#atuin-threads-search), you can perform a full-text search for a
session you had with an AI agent:

<VHSTape title="atuin threads search finds the thread whose messages mention upload batches.">
  Set FontSize 20
  Set Height 400
  Env ATUIN_DAEMON__ENABLED "true"
  Env ATUIN_DAEMON__AUTOSTART "true"
  Env ATUIN_THREADS__CAPTURE "true"
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  Show
  Type "atuin threads search upload batches"
  Sleep 500ms
  Enter
  Sleep 3s
</VHSTape>

Using `atuin threads tail` allows you to see everything your agents are doing
in real-time:

<VHSTape title="atuin threads tail shows a Claude Code thread's messages as the agent sends them.">
  Set FontSize 20
  Set Height 600
  Env ATUIN_DAEMON__ENABLED "true"
  Env ATUIN_DAEMON__AUTOSTART "true"
  Env ATUIN_THREADS__CAPTURE "true"
  Hide
  Type ` source "$ZDOTDIR/world.zsh" && clear`
  Enter
  Sleep 2s
  Show
  Hide
  Type " agent_working; clear"
  Enter
  Show
  Type "atuin threads tail"
  Sleep 300ms
  Enter
  Sleep 8s
  Ctrl+C
  Sleep 500ms
</VHSTape>

## MCP Support

All of Atuin's features are available to your agents.

:::note

Make sure the Atuin MCP is enabled by running [`atuin setup --only --mcp`](/reference/cli/setup/).

:::

Agents have access to your history, and our MCPs enable them to find
information across your whole cluster of computers.

<VHSTape title="atuin setup --only --mcp finds opencode and Kiro on this machine, and connects Atuin's MCP server to both.">
  Set FontSize 20
  Set Height 300
  Hide
  # Two agents for setup to find: stand-ins for opencode's and Kiro's programs, on a PATH of just
  # them, Atuin and the system's tools, so the agents of the machine running the build stay out.
  Type ` mkdir ~/agents && touch ~/agents/opencode ~/agents/kiro-cli && chmod +x ~/agents/* && export PATH="$HOME/agents:$commands[atuin]:h:/usr/bin:/bin" && clear`
  Enter
  Sleep 1s
  Show
  Sleep 500ms
  Type "atuin setup --only --mcp"
  Sleep 500ms
  Enter
  Sleep 3s
</VHSTape>

## Sync

Atuin can sync all your data across all your computers. With sync enabled,
Atuin periodically synchronizes the data it captured with a sync server.

:::tip[End-to-end encryption]

Atuin uses end-to-end encryption to make sure that only your computers have
access to your data. Even the sync server cannot see your data.

:::

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:

```bash
atuin setup --sync cloud
```

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

TODO CLAUDE VHS TAPE HERE

:::tip[Self-hosting]

Atuin also offers an open-source sync server you can self-host. For more
information on connecting to a self-hosted server, and hosting your own server,
see [our self-hosting docs](/guide/self-hosting/).

:::