dotfiles/docs/shell/atuin.mdx

---
title: atuin
description: Shell history search for bash with a daemon, directory-scoped up-arrow, tmux popups, and a cyberdream theme.
---

[atuin](https://atuin.sh) replaces shell history search in bash. fish and zsh do not use it: [iris](/shell/iris) wraps both and takes <kbd>up</kbd>, <kbd>down</kbd>, and <kbd>ctrl-r</kbd> itself, so the two fought over the same keys.

| Source (repo) | Target | Notes |
| --- | --- | --- |
| `dot_config/atuin/private_config.toml` | `~/.config/atuin/config.toml` | `private_`: written as a regular `0600` file, not a symlink |
| `dot_config/atuin/themes/cyberdream.toml` | `~/.config/atuin/themes/cyberdream.toml` | symlink |
| `dot_config/atuin/atuin-receipt.json` | `~/.config/atuin/atuin-receipt.json` | symlink |

chezmoi runs in symlink mode, but `private_` files are written as real files, so edits to `~/.config/atuin/config.toml` do not reach the repo on their own. Copy them back with `chezmoi re-add` (or `czs`, see [fish](/shell/fish#functions)). None of the files are templates, and they apply on every role.

## Installation

`atuin` is listed in `.chezmoidata/packages.yaml` for pacman and Homebrew. bash also expects atuin's standalone installer layout in `~/.atuin/bin`: it runs `. "$HOME/.atuin/bin/env"` just before `atuin init`.

That line does not check that the file exists, so a machine without `~/.atuin/bin` prints a sourcing error at shell start.

### atuin-receipt.json

The receipt that atuin's [cargo-dist](https://opensource.axo.dev/cargo-dist/) installer writes. It records how atuin was installed, which the self-updater (`atuin update`) needs:

| Field | Value |
| --- | --- |
| `binaries` | `["atuin"]` |
| `install_prefix` | `~/.atuin/bin` (stored as an absolute path under `/home/prad`) |
| `install_layout` | `flat` |
| `modify_path` | `true` |
| `provider` | cargo-dist `0.31.0` |
| `source` | GitHub release `atuinsh/atuin` |
| `version` | `18.19.0` |

## Shell integration

| Shell | Where | What |
| --- | --- | --- |
| bash | end of `~/.bashrc` | `eval "$(atuin init bash)"` |

### Key bindings

| Key | Shells | Action |
| --- | --- | --- |
| <kbd>ctrl-r</kbd> | bash | Interactive search (`_atuin_search`) |
| <kbd>up</kbd> | bash | Search opened from the up arrow. `filter_mode_shell_up_key_binding = "directory"` limits it to history from the current directory |
| <kbd>ctrl+shift+p</kbd> | kitty | [`atuin-pick`](/shell/scripts#atuin-pick): directory-filtered search in a split, running the pick in a fresh fish |

Under tmux, atuin's `[tmux]` settings open the search in a tmux popup (80% wide, 60% tall) instead of inline.

## AI inline

`atuin ai` is enabled in the config (`[ai] enabled = true`), but no shell loads `atuin ai init` or binds a key to it any more: the fish integration (<kbd>?</kbd> and <kbd>ctrl-w</kbd>) was removed with the move to iris. Run `atuin ai inline` by hand to use it.

## Configuration

`config.toml` is atuin's generated sample with a few keys set. The rest are commented-out defaults. The settings that take effect:

| Key | Value | Effect |
| --- | --- | --- |
| `filter_mode_shell_up_key_binding` | `"directory"` | Up-arrow search shows only the current directory's history |
| `dotfiles.enabled` | `true` | Enables atuin's dotfiles feature (aliases and vars managed by atuin) |
| `daemon.enabled` | `true` | Uses the background daemon |
| `daemon.autostart` | `true` | atuin starts and manages the daemon itself |
| `pty_proxy.enabled` | `false` | `atuin init` does not re-exec the shell inside `atuin pty-proxy` |
| `theme.name` | `"cyberdream"` | Loads `themes/cyberdream.toml` |
| `tmux.enabled` | `true` | Search opens in a tmux popup when inside tmux (tmux 3.2+) |
| `tmux.width` / `tmux.height` | `"80%"` / `"60%"` | Popup size |
| `ai.enabled` | `true` | Enables `atuin ai` |

No sync server, key, or session is configured in the repo. atuin keeps its encryption key and session under `~/.local/share/atuin`, outside chezmoi, and uses the default sync server.

:::warning[Misplaced keys]
Several keys sit after the `[dotfiles]` table header, so TOML puts them inside `[dotfiles]` rather than at the top level, and atuin ignores them. `atuin config get --resolved` confirms it:

| Key as written | Intended | Resolved |
| --- | --- | --- |
| `search_mode` | `"daemon-fuzzy"` | `fuzzy` |
| `enter_accept` | `true` | `false` |
| `workspaces` | `true` | `false` |
| `style` | `"auto"` | `compact` |
| `inline_height_shell_up_key_binding` | `20` | unknown key |
| `auto_sync` | `true` | `true` (the default) |
| `update_check` | `true` | `true` (the default) |

`syntax_highlight = true` has the same problem: it sits under `[ai]`, while the comment block above it documents the `[ui]` table.

To apply these settings, move the keys above `[dotfiles]` (and `syntax_highlight` under `[ui]`) in `dot_config/atuin/private_config.toml`.
:::

## Theme

`themes/cyberdream.toml` defines a theme named `cyberdream`, using the palette shared with [fish](/shell/fish#theme) and [Starship](/shell/starship#palette):

| Key | Color |
| --- | --- |
| `AlertInfo` | `#5ef1ff` |
| `AlertWarn` | `#f1ff5e` |
| `AlertError` | `#ff6e5e` |
| `Annotation` | `#7b8496` |
| `Guidance` | `#5ea1ff` |
| `Important` | `#ff5ef1` |
| `Title` | `#5ef1ff` |
| `Muted` | `#7b8496` |
| `SyntaxCommand` | `#5ea1ff` |
| `SyntaxFlag` | `#5ef1ff` |
| `SyntaxString` | `#5eff6c` |
| `SyntaxVariable` | `#ff5ef1` |
| `SyntaxOperator` | `#ff5ea0` |
| `SyntaxComment` | `#7b8496` |