Using Atuin Shell History by Search Scope

Searching shell history by command text alone becomes harder to interpret as the history grows.

Looking into Atuin showed me that search quality is not only about a more powerful matcher.

The matching mode and the history scope are separate settings.

The useful part for me was using Ctrl-R to switch between history near the current project and history from everywhere.

First identify the difference from standard history

Atuin’s official README describes recording context such as the working directory, exit code, duration, host, and session alongside shell commands.

I broke the behavior into three questions:

How should the input match?
Which history should be included?
Which key should open the search and with what initial scope?

Mixing these questions makes it difficult to tell whether a large result set comes from matching or from scope.

Atuin stores history in SQLite, so its storage location also differs from a shell that only reads a history file.

Encrypted synchronization is available, but local-only use is also possible.

For that reason, it is safer to verify local search behavior before deciding to synchronize history.

Separate search mode from history scope

Atuin’s configuration can be understood through several independent axes.

Axis	Examples	Question
Search mode	`prefix`, `fulltext`, `fuzzy`, `daemon-fuzzy`	How should input match?
History scope	`global`, `host`, `session`, `directory`, `workspace`	Which records are candidates?
Shell scope	`auto`, `all`, or an array of shell names	Should bash and zsh history be mixed?
Entry point	`Ctrl-R`, up arrow	Which initial scope should each key use?

fuzzy, for example, defines matching behavior.

directory narrows candidates to history associated with the current location.

Changing the former does not change the latter, so matching and scope can be debugged separately.

Choose a history scope

Scope	What it searches	Useful when
`global`	History across terminals and directories	You do not remember where a command ran
`directory`	History related to the current directory	You want tests or Git commands used there
`workspace`	History across a Git repository	You move among monorepo subdirectories
`session`	History from the current shell session	You want a command from the current investigation
`host`	History from the current host	WSL and server environments differ

global is broadest, but requires more work to interpret similar candidates.

directory changes as you move among project subdirectories.

The official configuration makes workspace useful when the whole Git repository should be searchable.

After incident work, session is often easier to scan than global when looking for a command from a moment ago.

When synchronized history spans WSL and servers, host helps avoid selecting a command with the wrong path.

Assign scope roles to key bindings

Atuin’s key-binding configuration has separate settings for the initial filter and the filter used by the up arrow.

The first two settings to inspect are:

filter_mode = "global"
filter_mode_shell_up_key_binding = "directory"

With this combination, Ctrl-R starts with history from everywhere and the up arrow starts near the current location.

After opening the search UI, pressing Ctrl-R again can cycle through filter modes.

If the changed up-arrow behavior does not fit, disable that binding and use only Ctrl-R.

The goal is not to add more keys, but to give each scope a predictable entry point.

Start with fuzzy matching

For comparing search modes, start with fuzzy and adjust the scope when there are too many candidates.

pnpm test     # ordinary fuzzy search
^git          # commands beginning with git
!docker       # exclude candidates containing docker
'.env         # candidates containing the literal .env

Search syntax varies by mode.

When switching to daemon-fuzzy, verify that the syntax you rely on is supported as well as checking response time.

There is no need to add a daemon before history size or latency creates a problem.

Check candidate provenance with multiple shells

Atuin’s current configuration reference documents [search].shells values for the current shell, all shells, or selected shells.

[search]
shells = "auto"

When bash, zsh, and fish have substantially different syntax, starting with auto reduces accidental reuse.

all can be useful for cross-shell search, but PowerShell and WSL may produce candidates with incompatible paths and command names.

tmux panes may be recorded as part of the same shell session.

During a long investigation, start with session, then widen to workspace or global if necessary.

Start with a minimal configuration

Adding many settings at once makes it difficult to identify which one changed the experience.

Begin by defining the entry points:

filter_mode = "global"
filter_mode_shell_up_key_binding = "directory"
search_mode = "fuzzy"
workspaces = true

[search]
shells = "auto"

Add workspace, session, or host only when the initial setup is insufficient.

The availability and names of workspaces and [search].shells can depend on the Atuin version.

Before copying a configuration into place, check the installed version’s reference and atuin --help.

Treat history as potentially sensitive

Atuin makes history searchable; it does not automatically make secrets safe.

Do not design commands such as these to remain in history:

curl URLs containing tokens
CLIs receiving passwords as arguments
Commands expanding temporary cloud credentials
SQL or file paths containing customer data

For secrets already recorded, combine deletion or exclusion with credential rotation.

When synchronization is enabled, verify which devices receive the history and who administers the sync account.

Summary

The practical result of examining Atuin is to treat matching mode and history scope as separate problems.

Start with fuzzy and global, then use directory or workspace when the current project should take priority.

Use session to return to recent investigation commands and host when WSL or server environments differ.

Verify local behavior first, then add only the synchronization or other features whose need you can explain.