Atuin

🏗︎

This article or section is a work in progress. The work on this article started on 11 March 2025 The information on this page may not be reliable, and the formatting may not follow the Manual of Style yet. Please remove this notice as soon as the work is in a presentable shape.

Atuin replaces your existing shell history with a SQLite database, and records additional context for your commands. Additionally, Atuin (optionally) syncs your shell history between all of your machines.

Enable in your terminal

Atuin can be enabled using home-manager. Documentation for all settings can be found at https://docs.atuin.sh/configuration/config/ .

❄︎ ~/.config/home-manager/home.nix

{ pkgs, ... }: {
  programs.atuin = {
    enable = true;
    settings = {
      auto_sync = true;
      sync_frequency = "5m";
      sync_address = "https://api.atuin.sh";
      search_mode = "fuzzy";
    };
  };
};

Disable up-arrow / Ctrl+R keybindings

Key bindings are not part of Atuin settings and need to be passed as flags instead.

❄︎ ~/.config/home-manager/home.nix

{ pkgs, ... }: {
  programs.atuin = {
    enable = true;
    # ...
    flags = [ "--disable-up-arrow" ]; # or --disable-ctrl-r
  };
};

Enable synchronization with atuin.sh

Imperatively

To synchronize your history with atuin.sh you first need to register an account or login with the cli utility. Doing that will create a key and a session token in ~/.local/share/atuin

atuin register -u <YOUR_USERNAME> -e <YOUR EMAIL>

To backfill your existing shell history run

atuin import auto
atuin sync # Optionally sync your history to the server

Declaratively

You can manage your atuin session declaratively by setting the session_path and key_path options to files containing a session token and a key. You can obtain these two files by registering as described above and copying them from ~/.local/share/key and ~/.local/share/session. The example below uses agenix

Note: Both the session and key file must not have a trailing newline or you get Error: failed to parse header value. Several common editors (e.g. Vim) will automatically add a newline on save.

❄︎ ~/.config/home-manager/home.nix

{ pkgs, ... }: {
  programs.atuin = {
    enable = true;
    settings = {
      # ... other settings
      
      session_path = config.age.secrets."atuin_session".path;
      key_path = config.age.secrets."atuin_key".path;
    };
  };
};

zsh autosuggestions

If zsh autosuggestions is enabled, atuin automatically adds itself as the first autosuggestion strategy; see atuin docs

❄︎ ~/.config/home-manager/home.nix

{ pkgs, ... }: {
  programs.zsh = {
    enable = true;
    autosuggestion.enable = true; # Enable autosuggestions
  };
  programs.atuin = {
    enable = true;
  };
};