# Config

Atuin maintains two configuration files in `~/.config/atuin/`, and stores data
in `~/.local/share/atuin` (unless overridden by XDG\_\*).

The full path to the config file would be `~/.config/atuin/config.toml`

The config location can be overridden with ATUIN_CONFIG_DIR

### `db_path`

Default: `~/.local/share/atuin/history.db`

The path to the Atuin SQLite database.

```toml
db_path = "~/.history.db"
```

### `key_path`

Default: `~/.local/share/atuin/key`

The path to the Atuin encryption key.

```toml
key_path = "~/.atuin-key"
```

### `session_path`

Default: `~/.local/share/atuin/session`

The path to the Atuin server session file.
This is essentially just an API token

```toml
session_path = "~/.atuin-session"
```

### `dialect`

Default: `us`

This configures how the [stats](../reference/stats.md) command parses dates. It has two
possible values

```toml
dialect = "uk"
```

or

```toml
dialect = "us"
```

### `auto_sync`

Default: `true`

Configures whether to automatically sync, when logged in.

```toml
auto_sync = true/false
```

### `update_check`

Default: `true`

Configures whether to automatically check for updates. When enabled, Atuin
checks `https://api.atuin.sh` for the latest release at most once per hour,
and prints a notice if you're out of date.

Set to `false` to disable. With the update check disabled and sync not set
up, Atuin makes no network requests of its own.

```toml
update_check = true/false
```

### `sync_address`

Default: `https://api.atuin.sh`

The address of the server to sync with!

```toml
sync_address = "https://api.atuin.sh"
```

### `sync_frequency`

Default: `1h`

How often to automatically sync with the server. This can be given in a
"human-readable" format. For example, `10s`, `20m`, `1h`, etc.

If set to `0`, Atuin will sync after every command. Some servers may rate limit
frequent syncs, but this won't cause any issues.

```toml
sync_frequency = "1h"
```

### `search_mode`

Default: `fuzzy`

Which search mode to use. Atuin supports `prefix`, `fulltext`, `fuzzy`, and
`daemon-fuzzy` search modes.

- `prefix` mode searches for "query\*".
- `fulltext` mode searches for "\*query\*".
- `fuzzy` applies the [fuzzy search syntax](#fuzzy-search-syntax).

```toml
search_mode = "fuzzy"
```

!!! note "daemon-fuzzy search mode"

    The "daemon-fuzzy" mode is new as of Atuin 18.13. This search mode uses an in-memory index, stored in the daemon, to perform fast and customizable searches.

    To use the new `"daemon-fuzzy"` mode, enable the daemon, set autostart to true (unless you manage its lifecycle yourself), and set the search mode:

    ```toml
    search_mode = "daemon-fuzzy"

    [daemon]
    enabled = true
    autostart = true
    ```

    You can customize the priority given to frequency, recency, and frecency scores in this mode. See [the score multipliers section](#score-multipliers) for more information.

    Note: in non-interactive searches (manually running `atuin search` from the command line), `daemon-fuzzy` behaves like `fuzzy`.

#### `fuzzy` search syntax

The `fuzzy` and `daemon-fuzzy` search syntax is based on 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`     |

A single bar character term acts as an OR operator. For example, the following
query matches entries that start with `core` and end with either `go`, `rb`,
or `py`.

```
^core go$ | rb$ | py$
```

!!! warning "Bar not supported in daemon-fuzzy"
    The "daemon-fuzzy" search mode doesn't currently support the bar character operator.

### `filter_mode`

Default: `global`

The filter mode that interactive search starts in. Accepted values are `global`,
`host`, `session`, `directory`, `workspace`, and `session-preload` — see
[Filter mode](../guide/advanced-usage.md#filter-mode) for what each one searches.

Whichever mode you start in, you can still cycle through the rest with ctrl-r.

```toml
filter_mode = "host"
```

### `search_mode_shell_up_key_binding`

Default: `fuzzy`

The default search mode to use when searching and being invoked from a shell up-key binding.

Accepts exactly the same options as `search_mode` above

```toml
search_mode_shell_up_key_binding = "fuzzy"
```

Defaults to the value specified for `search_mode`.

### `filter_mode_shell_up_key_binding`

Default: `global`

The default filter to use when searching and being invoked from a shell up-key binding.

Accepts exactly the same options as `filter_mode` above

```toml
filter_mode_shell_up_key_binding = "session"
```

Defaults to the value specified for `filter_mode`.

### `inline_height_shell_up_key_binding`

The maximum number of lines the interface should take up when `atuin` is invoked from a shell up-key binding.

The accepted values are identical to those of `inline_height`.

When unset, the value from `inline_height` is used.

```toml
inline_height_shell_up_key_binding = 10
```

### `workspaces`

Default: `false`

This flag enables a pseudo filter-mode named "workspace": the filter is automatically
activated when you're in a git repository.

With workspace filtering enabled, Atuin will filter for commands executed in any directory
within a git repository tree.

Filter modes can still be toggled via ctrl-r.

```toml
workspaces = false
```

### `style`

Default: `compact`

Which style to use. Possible values: `auto`, `full` and `compact`.

- `compact`:

![compact](https://user-images.githubusercontent.com/1710904/161623659-4fec047f-ea4b-471c-9581-861d2eb701a9.png)

- `full`:

![full](https://user-images.githubusercontent.com/1710904/161623547-42afbfa7-a3ef-4820-bacd-fcaf1e324969.png)

With `auto`, Atuin uses `full` mode, but automatically switches to `compact` mode when the terminal window is too short for `full` to display properly.

```toml
style = "compact"
```

### `invert`

Default: `false`

Invert the UI - put the search bar at the top.

```toml
invert = true/false
```

### `inline_height`

Default: `40`

Set the maximum number of lines Atuin's interface should take up.

If set to `0`, Atuin will always take up as many lines as available (full screen).

```toml
inline_height = 40
```

### `show_preview`

Default: `true`

Configure whether to show a preview of the selected command.

Useful when the command is longer than the terminal width and is cut off.

```toml
show_preview = true
```

### `max_preview_height`

Default: `4`

Configure the maximum height of the preview to show.

Useful when you have long scripts in your history that you want to distinguish by more than the first few lines.

```toml
max_preview_height = 4
```

### `show_help`

Default: `true`

Configure whether to show the help row, which includes the current Atuin version (and whether an update is available), a keymap hint, and the total amount of commands in your history.

```toml
show_help = true
```

### `show_tabs`

Default: `true`

Configure whether to show tabs for search and inspect.

```toml
show_tabs = true
```

### `auto_hide_height`

Default: `8`

Hide extra UI lines when the available height falls below this number of rows. This has no effect except
when `compact` style is being used (see `style` above), and currently applies to only the
interactive search and inspector. It can be turned off entirely by setting to `0`.

```toml
auto_hide_height = 8
```

### `exit_mode`

Default: `return-original`

What to do when the escape key is pressed when searching

| Value                     | Behaviour                                                        |
| ------------------------- | ---------------------------------------------------------------- |
| return-original (default) | Set the command-line to the value it had before starting search  |
| return-query              | Set the command-line to the search query you have entered so far |

Pressing ctrl+c or ctrl+d will always return the original command-line value.

```toml
exit_mode = "return-query"
```

### `history_format`

The default format used by `history list`. It can also be specified per invocation with the `--format` argument, which takes precedence over this config value.

More on [history list](../reference/list.md)

```toml
history_format = "{time}\t{command}\t{duration}"
```

### `history_filter`

Use the history filter to exclude commands from history tracking - maybe you want to keep ALL of your `curl` commands totally out of your shell history, or maybe just some matching a pattern.

This supports regular expressions, so you can hide pretty much whatever you want!

```toml
## Note that these regular expressions are unanchored, i.e. if they don't start
## with ^ or end with $, they'll match anywhere in the command.
history_filter = [
   "^secret-cmd",
   "^innocuous-cmd .*--secret=.+"
]
```

### `cwd_filter`

Use the `cwd` filter to exclude directories from history tracking.

This supports regular expressions, so you can hide pretty much whatever you want!

```toml
## Note that these regular expressions are unanchored, i.e. if they don't start
## with ^ or end with $, they'll match anywhere in the path.
# cwd_filter = [
#   "^/very/secret/directory",
# ]
```

After updating that parameter, you can run [the prune command](../reference/prune.md) to remove old history entries that match the new filters.

### `store_failed`

Default: `true`

```toml
store_failed = true
```

Configures whether to store commands that failed (those with non-zero exit status) or not.

### `secrets_filter`

Default: `true`

```toml
secrets_filter = true
```

Matches each command against a set of built-in regular expressions, and refuses
to save it if any of them match. The patterns currently cover:

| Service | Matches |
|---------|---------|
| AWS | Access key IDs, and commands setting `AWS_SECRET_ACCESS_KEY` or `AWS_SESSION_TOKEN` |
| Azure | Commands setting `AZURE_*_KEY` |
| Google Cloud | Commands setting `GOOGLE_SERVICE_ACCOUNT_KEY` |
| GitHub | Personal access tokens (old and new), OAuth access tokens (app and user), app installation tokens, and refresh tokens |
| GitLab | Personal access tokens |
| Slack | OAuth v2 bot and user tokens, and webhook URLs |
| Stripe | Live and test keys |
| Netlify | Authentication tokens |
| npm | Tokens |
| Pulumi | Personal access tokens |
| Atuin | `atuin login`, which takes your password and encryption key as arguments |

For the exact expressions, see
[`secrets.rs`](https://github.com/atuinsh/atuin/blob/main/crates/atuin-client/src/secrets.rs).

!!! note

    This is a safety net, not a guarantee. It only catches credentials in
    recognized formats — use [`history_filter`](#history_filter) for anything
    else you need kept out, and see
    [Excluding Commands from History](../guide/excluding-commands.md).

### macOS Ctrl-n key shortcuts

Default: `true`

macOS doesn't have an ++alt++ key, although terminal emulators can often be configured to map the ++option++ key to be used as ++alt++. _However_, remapping ++option++ this way may prevent typing some characters, such as using ++option+3++ to type `#` on the British English layout. For such a scenario, set the `ctrl_n_shortcuts` option to `true` in your config file to replace ++alt+0++ to ++alt+9++ shortcuts with ++ctrl+0++ to ++ctrl+9++ instead:

```toml
# Use Ctrl-0 .. Ctrl-9 instead of Alt-0 .. Alt-9 UI shortcuts
ctrl_n_shortcuts = true
```

### `show_numeric_shortcuts`

Default: `true`

Whether to show numeric shortcuts (1..9) beside list items in the TUI. Set this to `false` to hide the moving numbers if you find them distracting.

```toml
show_numeric_shortcuts = true
```

### `network_timeout`

Default: `30`

The max amount of time (in seconds) to wait for a network request. If any
operations with a sync server take longer than this, the code will fail -
rather than wait indefinitely.

```toml
network_timeout = 30
```

### `network_connect_timeout`

Default: `5`

The max time (in seconds) Atuin waits for a connection to become established with a
remote sync server. Any longer than this and the request will fail.

```toml
network_connect_timeout = 5
```

### `extra_headers`

Default: `{}`

Extra HTTP headers to send on every request to the sync server. This is useful
when a self-hosted server sits behind a proxy or access gateway that requires
its own authentication header — for example Cloudflare Access.

Headers that Atuin sets itself (such as `Authorization`) can't be overridden,
because Atuin's values always win.

To avoid leaking credentials, Atuin refuses to follow cross-origin redirects
when extra headers are configured — they're never sent to an origin other
than the one you configured.

```toml
extra_headers = { "CF-Access-Client-Id" = "...", "CF-Access-Client-Secret" = "..." }
```

### `local_timeout`

Default: `5`

Timeout (in seconds) for acquiring a local database connection (SQLite).

```toml
local_timeout = 5
```

### `command_chaining`

Default: `false`

Use this to build a command chain with the `&&` or `||` operator. When enabled, opening Atuin will search for the next command in the chain, and append to the current buffer.

```toml
command_chaining = false
```

### `enter_accept`

Default: `false`

When set to true, Atuin will default to immediately executing a command rather
than the user having to press enter twice. Pressing tab will return to the
shell and give the user a chance to edit.

This technically defaults to true for new users, but false for existing. We
have set `enter_accept = true` in the default config file. This is likely to
change to be the default for everyone in a later release.

```toml
enter_accept = false
```

### `keymap_mode`

Default: `emacs`

The initial keymap mode of the interactive Atuin search (for example, started by the
keybindings in the shells). Four values are supported: `"emacs"`,
`"vim-normal"`, `"vim-insert"`, and `"auto"`. The keymap mode `"emacs"` is the
most basic one. In the keymap mode `"vim-normal"`, you may use ++k++
and ++j++ to navigate the history list as in Vim, whilst pressing

++i++ changes the keymap mode to `"vim-insert"`. In the keymap mode `"vim-insert"`,
you can search for a string as in the keymap mode `"emacs"`, while pressing ++esc++
switches the keymap mode to `"vim-normal"`. When set to `"auto"`, the initial
keymap mode is automatically determined based on the shell's keymap that triggered
the Atuin search. `"auto"` isn't supported by Nushell at present, where it will
always trigger the Atuin search with the keymap mode `"emacs"`.

```toml
keymap_mode = "emacs"
```

### `keymap_cursor`

Default: `(empty dictionary)`

The terminal's cursor style associated with each keymap mode in the Atuin
search. This is specified by a dictionary whose keys and values being the
keymap names and the cursor styles, respectively. A key specifies one of the
keymaps from `emacs`, `vim_insert`, and `vim_normal`. A value is one of the
cursor styles, `default` or `{blink,steady}-{block,underline,bar}`. The
following is an example.

```toml
keymap_cursor = { emacs = "blink-block", vim_insert = "blink-block", vim_normal = "steady-block" }
```

If the cursor style is specified, the terminal's cursor style is changed to the
specified one when the Atuin search starts with or switches to the
corresponding keymap mode. Also, the terminal's cursor style is reset to the
one associated with the keymap mode corresponding to the shell's keymap on the
termination of the Atuin search.

### `prefers_reduced_motion`

Default: `false`

Enable this, and Atuin will reduce motion in the TUI as much as possible. Users
with motion sensitivity can find the live-updating timestamps distracting.

Alternatively, set env var NO_MOTION

```toml
prefers_reduced_motion = false
```

## search

### `filters`

The list of filter modes available in interactive search, in the order they cycle through when you press ctrl-r. By default, all modes are enabled. Removing a mode from this list disables it entirely. The `workspace` mode is skipped when not in a git repository or when `workspaces = false`. See [Filter mode](../guide/advanced-usage.md#filter-mode) for a description of each mode.

The `filter_mode` setting selects the initial mode from this list. If `filter_mode` is set to a mode not in the list, the first available mode is used instead.

```toml
[search]
filters = ["global", "host", "session", "directory"]
```

### Score multipliers

For the [`"daemon-fuzzy"` search mode](#search_mode), you can control the scoring of matched items. The system scores matches based on three numbers: frequency, recency, and frecency:

* Frequency — how often this exact match has been run, with diminishing returns
* Recency — how recently this exact match was last run
* Frecency — a combination of frequency and recency

The frecency calculation is `Recency Score * Recency Multiplier + Frequency Score * Frequency Multiplier`. By changing the options below, you can customize the relative importance of each part of the score calculation.

For each setting, a value of `1.0` (the default) means the score is used as-is. Values less than `1.0` decrease that score's influence, and values greater than `1.0` increase that score's influence.

For example, if you cared a lot about how frequently you run a command but not as much how recently, you could set `frequency_score_multiplier` to `10.0` and `recency_score_multiplier` to `0.1`.

!!! warning "daemon-fuzzy mode only"
    The score multiplier settings shown here only work with the `"daemon-fuzzy"` search mode.

#### `frequency_score_multiplier`

Default: `1.0`

The multiplier to apply to the frequency score in the frecency calculation. Setting this to `0` disables the frequency part of the frecency scoring altogether.

```toml
frequency_score_multiplier = 1.0
```

#### `recency_score_multiplier`

Default: `1.0`

The multiplier to apply to the recency score in the frecency calculation. Setting this to `0` disables the recency part of the frecency scoring altogether.

```toml
recency_score_multiplier = 1.0
```

#### `frecency_score_multiplier`

Default: `1.0`

The multiplier used for the final frecency score. Setting this to `0` disables frecency scoring altogether, relying solely on the fuzzy matcher's score.

```toml
frecency_score_multiplier = 1.0
```

Example:

```toml
search_mode = "daemon-fuzzy"

[daemon]
enabled = true
autostart = true

[search]
recency_score_multiplier = 10.0
frequency_score_multiplier = 0.8
frecency_score_multiplier = 2.0
```

### Filtering by author

Interactive search shows only commands you ran yourself, hiding those recorded
by AI coding agents through [agent hooks](../guide/agent-hooks.md). This isn't
currently configurable in `config.toml`.

To filter by author on the command line, use `atuin search --author`. See
[Filtering by Author](../guide/agent-hooks.md#filtering-by-author) for the
available values.

#### `shells`

Atuin version: >= 18.18

Default: `"auto"`

Filter interactive search results by the shell that was used to run each command.

| Value  | Meaning |
|--------|---------|
| `"all"` | Show commands from all shells. |
| `"auto"` | Show commands from the current shell, or commands that have no recorded shell (for example, from an older version of Atuin). |
| array of strings | Show commands run by any shell in the array. `""` includes commands that have no shell recorded. |

The current shell is detected from the `ATUIN_SHELL` environment variable (set by the shell init script).

```toml
[search]
# Default: show commands from the current shell. Atuin will show Bash commands
# when invoked from Bash, Zsh commands when invoked from Zsh, etc. Also
# includes commands that have no shell recorded (most likely from an older
# version of Atuin).
shells = "auto"

# Show commands from all shells.
# shells = "all"

# Show only Bash and Zsh commands.
# shells = ["bash", "zsh"]
```

## Stats

This section of client config is specifically for configuring Atuin stats calculations

```toml
[stats]
common_subcommands = [...]
common_prefix = [...]
```

### `common_subcommands`

Default:

```toml
common_subcommands = [
  "apt",
  "cargo",
  "composer",
  "dnf",
  "docker",
  "git",
  "go",
  "ip",
  "jj",
  "kubectl",
  "nix",
  "nmcli",
  "npm",
  "pecl",
  "pnpm",
  "podman",
  "port",
  "systemctl",
  "tmux",
  "yarn",
]
```

Configures commands where Atuin should consider the subcommand as part of the statistics. For example, consider `kubectl get` rather than just `kubectl`.

### `common_prefix`

Default:

```toml
common_prefix = [
  "sudo",
]
```

Configures commands that should be totally stripped from stats calculations. For example, 'sudo' should be ignored.

## `dotfiles`

Default: `false`

To enable sync of shell aliases between hosts.

Add the new section to the bottom of your config file, for every machine you use Atuin with

```toml
[dotfiles]
enabled = true
```

Manage aliases using the command line options

```shell
# Alias 'k' to 'kubectl'
atuin dotfiles alias set k kubectl

# List all aliases
atuin dotfiles alias list

# Delete an alias
atuin dotfiles alias delete k
```

After setting an alias, you will either need to restart your shell or source the init file for the change to take effect

## keys

This section of the client config is specifically for configuring key-related settings.

```toml
[keys]
scroll_exits = [...]
prefix = 'a'
```

### `scroll_exits`

Default: `true`

Configures whether the TUI exits, when scrolled past the last or first entry.

```toml
scroll_exits = true
```

### `prefix`

Default: `a`

Which key to use as the prefix. Prefix mode is a two-step shortcut system: you press ++ctrl++ and the prefix key to enter prefix mode, then press a second key to trigger an action. For example, with the default prefix `a`, pressing ++ctrl+a++ then ++d++ deletes the selected entry.

See the [key binding page](key-binding.md#prefix-mode) for the full list of default prefix shortcuts, or the [advanced key binding page](advanced-key-binding.md#custom-prefix-bindings) to customize them.

```toml
prefix = "a"
```

### `exit_past_line_start`

Default: `true`

Exits the TUI when scrolling left while the cursor is at the start of the line.

```toml
exit_past_line_start = true
```

### `accept_past_line_end`

Default: `true`

The right arrow key performs the same functionality as Tab and copies the selected line to the command line to be
modified.

```toml
accept_past_line_end = true
```

### `accept_past_line_start`

Default: `false`

The left arrow key performs the same functionality as Tab and copies the selected line to the command line to be
modified.

```toml
accept_past_line_start = false
```

### `accept_with_backspace`

Default: `false`

The backspace key performs the same functionality as Tab and copies the selected line to the command line to be
modified.

```toml
accept_with_backspace = false
```

## preview

This section of the client config is specifically for configuring preview-related settings.
(In the future the other 2 preview settings will be moved here.)

```toml
[preview]
strategy = [...]
```

### `strategy`

Default: `auto`

Which preview strategy is used to calculate the preview height. It respects `max_preview_height`.

| Value          | Preview height is calculated from the length of the |
| -------------- | --------------------------------------------------- |
| auto (default) | selected command                                    |
| static         | longest command in the current result set           |
| fixed          | use `max_preview_height` as fixed value             |

By using `auto` a preview is shown, if the command is longer than the width of the terminal.

```toml
strategy = "auto"
```

## tmux

When you're inside tmux, open the search UI in a
[popup](https://github.com/tmux/tmux/wiki/Getting-Started#popups) floating above
your current pane, instead of drawing over the pane itself. The popup opens in
your current working directory, and closes when you accept a command or exit.

```toml
[tmux]
enabled = true
width = "80%"
height = "60%"
```

Atuin falls back to its normal rendering, with no error, whenever the popup
can't be used — outside tmux, on tmux older than 3.2, or in a shell that doesn't
support it.

!!! note "Requirements"

    - tmux >= 3.2, which is where `display-popup` gained the behavior Atuin needs
    - zsh, bash, or fish — nushell, xonsh, and PowerShell don't support the popup yet

!!! warning "iTerm2's native tmux integration"

    iTerm2's native tmux integration (control mode, `tmux -CC`) can't display
    `tmux display-popup` popups, and Atuin can't detect this to fall back
    automatically. If you rely on it, keep `[tmux] enabled = false` (the
    default) so the search UI renders inline.

These settings are read by `atuin init` and passed to the shell plugin through
environment variables, so **restart your shell after changing them**. To disable
the popup for a single session without touching your config, set
`ATUIN_TMUX_POPUP=false` before Atuin's key bindings run.

### `enabled`

Default: `false`

Whether to show the search UI in a tmux popup.

```toml
enabled = true
```

### `width`

Default: `"80%"`

Width of the popup, passed to `tmux display-popup -w`. Accepts a percentage of
the terminal width, or an absolute number of columns.

```toml
width = "80%"
```

### `height`

Default: `"60%"`

Height of the popup, passed to `tmux display-popup -h`. Accepts a percentage of
the terminal height, or an absolute number of rows.

```toml
height = "60%"
```

## Daemon

### enabled

Default: `false`

Enable the background daemon

Add the new section to the bottom of your config file

```toml
[daemon]
enabled = true
```

### autostart

Default: `false`

Automatically start and manage the daemon when needed.
This isn't compatible with `systemd_socket = true`.
If a legacy experimental daemon is already running, restart it manually once before using autostart.

```toml
autostart = false
```

### `sync_frequency`

Default: `300`

How often the daemon should sync, in seconds

```toml
sync_frequency = 300
```

### `socket_path`

Default:

```toml
socket_path = "~/.local/share/atuin/atuin.sock"
```

Where to bind a Unix socket for client -> daemon communication

If XDG_RUNTIME_DIR is available, Atuin uses this directory instead.

### `pidfile_path`

Default:

```toml
pidfile_path = "~/.local/share/atuin/atuin-daemon.pid"
```

Path to the daemon `pidfile` used for process coordination.

### `systemd_socket`

Default `false`

Use a socket passed via systemd socket activation protocol instead of the path

```toml
systemd_socket = false
```

### `tcp_port`

Default: `8889`

The port to use for client -> daemon communication. Only used on non-Unix systems.

```toml
tcp_port = 8889
```

## logs

Behavior of log files.

```toml
[logs]
enabled = true
dir = "~/.atuin/logs"
level = "info"
retention = 4
```

### enabled

Default: `true`

Whether to enable file-based logging.

```toml
enabled = true
```

### dir

Default: `"~/.atuin/logs"`

The directory in which to store log files.

```toml
dir = "~/.atuin/logs"
```

### level

Default: `"info"`

The logging level to use. Valid values are `"trace"`, `"debug"`, `"info"`, `"warn"`, and `"error"`, in order of highest-to-lowest verbosity.

```toml
level = "info"
```

### retention

Default: `4`

How many days of log files to keep (per file type). Files older than this will be removed.

```toml
retention = 4
```

### ai

A sub-object with specific options for AI logging:

* `enabled` - whether to output AI logs; defaults to `logs.enabled`
* `file` - the filename to use for the AI logs; defaults to `"ai.log"`. Always relative to `logs.dir`.
* `level` - override the log level for the AI logs; defaults to `logs.level`
* `retention` - how many days to store AI logs; defaults to `logs.retention`

```toml
[logs.ai]
enabled = true
file = "ai.log"
level = "info"
retention = 4
```

### daemon

A sub-object with specific options for daemon logging:

* `enabled` - whether to output daemon logs; defaults to `logs.enabled`
* `file` - the filename to use for the daemon logs; defaults to `"daemon.log"`. Always relative to `logs.dir`.
* `level` - override the log level for the daemon logs; defaults to `logs.level`
* `retention` - how many days to store daemon logs; defaults to `logs.retention`

```toml
[logs.daemon]
enabled = true
file = "daemon.log"
level = "info"
retention = 4
```

### search

A sub-object with specific options for search logging:

* `enabled` - whether to output search logs; defaults to `logs.enabled`
* `file` - the filename to use for the search logs; defaults to `"search.log"`. Always relative to `logs.dir`.
* `level` - override the log level for the search logs; defaults to `logs.level`
* `retention` - how many days to store search logs; defaults to `logs.retention`

```toml
[logs.search]
enabled = true
file = "search.log"
level = "info"
retention = 4
```

## theme

The theme to use for showing the terminal interface.

```toml
[theme]
name = "default"
debug = false
max_depth = 10
```

### `name`

Default: `"default"`

A theme name that must be present as a built-in (unset or `default` for the default,
else `autumn` or `marine`), or found in the themes directory, with the suffix `.toml`.
By default this is `~/.config/atuin/themes/` but can be overridden with the
`ATUIN_THEME_DIR` environment variable.

```toml
name = "my-theme"
```

### `debug`

Default: `false`

Output information about why a theme won't load. Independent from other log
levels as it can cause data from the theme file to be printed unfiltered to the
terminal.

```toml
debug = false
```

### `max_depth`

Default: 10

Number of levels of "parenthood" that will be traversed for a theme. This shouldn't
need to be added in or changed in normal usage.

```toml
max_depth = 10
```

## `ui`

Configure the interactive search UI appearance.

```toml
[ui]
columns = ["duration", "time", "command"]
```

### `columns`

Default: `["duration", "time", "command"]`

Columns to display in the interactive search, from left to right. The selection
indicator (`" > "`) is always shown first implicitly.

Each column can be specified as:
- A plain string (uses default width): `"duration"`
- An object with type and optional width/expand: `{ type = "directory", width = 30 }`

#### Available column types

| Column      | Default Width | Description                                     |
| ----------- | -------------- | ----------------------------------------------- |
| `duration`  | 5              | Command execution duration (for example, "123ms")      |
| `time`      | 8              | Relative time since execution (for example, "59m ago") |
| `datetime`  | 16             | Absolute timestamp (for example, "2025-01-22 14:35")   |
| `directory` | 20             | Working directory (truncated if too long)       |
| `host`      | 15             | Hostname where command was run                  |
| `user`      | 10             | Username                                        |
| `exit`      | 3              | Exit code (colored by success/failure)          |
| `command`   | *              | The command itself (expands by default)         |

#### Column options

- **type**: The column type (required when using object format)
- **width**: Custom width in characters (optional, uses default if not specified)
- **expand**: If `true`, the column fills remaining space. Default is `true` for `command`, `false` for others. Only one column should have `expand = true`.

#### Examples

```toml
# Minimal - more space for commands
columns = ["duration", "command"]

# With custom directory width
columns = ["duration", { type = "directory", width = 30 }, "command"]

# Show host for multi-machine sync users
columns = ["duration", "time", "host", "command"]

# Show exit codes prominently
columns = ["exit", "duration", "command"]

# Make directory expand instead of command
columns = ["duration", "time", { type = "directory", expand = true }, { type = "command", expand = false }]
```

### `syntax_highlight`

Default: `true`

Syntax highlight commands in the search results, parsed with the grammar for
the shell that ran them: bash/zsh/sh use the bash grammar, fish uses the fish
grammar, and shells without a grammar (nu, xonsh, PowerShell) are shown
unhighlighted. The selected row keeps its usual single highlight color.

The default colors are ANSI palette colors, so they automatically match your
terminal's color scheme. They can also be customized via the `Syntax*` keys in
a [theme](../guide/theming.md).

Not available on platforms where tree-sitter doesn't build (for example, Windows),
so commands are shown unhighlighted there.

```toml
syntax_highlight = false
```

## ai

The settings for Atuin AI are listed in [a separate section](../ai/settings.md).
