Skip to content
Atuin

Configuration reference

Every setting Atuin reads from config.toml, generated from the source of this release. Atuin looks for the file in ~/.atuin/, in $ATUIN_HOME when that is set, or in $ATUIN_CONFIG_DIR when that is. ATUIN_HOME must be an absolute path, or Atuin ignores it. Each setting can also be set through an ATUIN_ environment variable, such as ATUIN_SEARCH_MODE, or ATUIN_LOGS__LEVEL for one in a table.

Editors that read JSON Schemas, such as VS Code with Even Better TOML, can complete and check the file. Add this line at the top of it:

#:schema https://docs.atuin.sh/schemas/config.schema.json

A path may start with ~ and use environment variables, such as $XDG_RUNTIME_DIR/atuin.sock. ${XDG_RUNTIME_DIR:-/tmp}/atuin.sock falls back to /tmp where the variable isn’t set, and $$ is a literal $. Atuin warns about a variable that isn’t set, and uses the path as written.

A relative path is relative to the directory that holds config.toml, wherever Atuin runs. This holds for paths set through ATUIN_ environment variables too. An empty path is the setting’s default. A database path may also be SQLite’s :memory:, or a sqlite: or file: URI, which SQLite opens as written.

A duration takes a unit, such as 500ms, 30s, 5m or 4d. The settings that took a bare number before still do, but that form is deprecated.

Table Description
Top-level settings Settings outside any table.
[stats] What atuin stats counts.
[keys] How the arrow keys, backspace and the prefix key behave in interactive search.
[keymap] Your own key bindings for interactive search, per keymap.
[preview] The preview of the selected command in interactive search.
[daemon] The background daemon, which can record history and sync in place of each shell.
[pty_proxy] atuin pty-proxy, which wraps your shell so Atuin can capture command output.
[output] Capturing the output of the commands you run.
[teams] Atuin for Teams.
[search] Interactive search: its filters and how it ranks results.
[theme] The colors of interactive search.
[ui] The layout of interactive search.
[scripts] Scripts saved with atuin scripts.
[kv] The key-value store behind atuin kv.
[tmux] Opening interactive search in a tmux popup.
[logs] Atuin’s log files.
[meta] Atuin’s own state, such as your Hub session.
[threads] AI agent threads, which atuin threads lists and resumes.
[security] Credentials of your own for Atuin to redact.
server.toml The sync server’s settings.