DOCSEARCHbyAlgolia
Submit Docs

Atuin Shell History

repository·main·Indexed 12 days ago

https://github.com/atuinsh/atuin

A shell history replacement that uses a SQLite database to store commands with rich metadata, including exit codes, duration, and directory. It features end-to-end encrypted synchronization across machines, a full-screen search UI, and AI-powered natural language command generation via an inline TUI. Supports zsh, bash, fish, nushell, xonsh, and PowerShell.

Tokens
132.4K
Snippets
494
Records
660
Agent score
97%

What's inside Atuin

  1. Overview of Atuin features

    main

    Atuin replaces your standard shell history with a SQLite database, capturing rich context for every command.

    Core Capabilities:

    • Contextual Logging: Records exit code, current working directory (cwd), hostname, session, and command duration.
    • Enhanced UI: Rebinds ctrl-r and up to a full-screen search UI. Supports quick-jumping to previous items with Alt-<num>.
    • Search Modes: Switch filter modes via ctrl-r to search history from the current session, current directory, or globally.
    • Encrypted Sync: Provides optional, fully end-to-end encrypted synchronization of history across multiple machines via an Atuin server.
    • Statistics: Calculates usage metrics like "most used command."
    • Non-destructive: Your old history file is not replaced during setup.

  2. Manage Atuin configuration with `atuin config`

    main

    The atuin config command allows you to read, write, and inspect configuration values in your config.toml. Atuin resolves configuration by merging multiple sources: defaults, the configuration file, and environment variables.

    Use this command to inspect your current settings or modify them via the CLI without manually opening a text editor.

    atuin config

  3. Atuin terminology and abbreviations

    main

    This document provides a glossary of terms and abbreviations used throughout the Atuin documentation to ensure clarity regarding the project's architecture, security model, and features.

    Core Concepts

    • E2E encryption (End-to-end encryption): Data is scrambled on your local device before transmission, ensuring no intermediary (including the server) can read it.
    • Hub (Atuin Hub): Atuin's hosted service for account management and history synchronization.
    • frecency: A ranking algorithm that combines command frequency and recency to prioritize your most relevant commands.
    • dotfiles: Your shell's personal configuration (aliases, functions, environment variables) that Atuin can sync across machines.
    • daemon: A background program; the Atuin daemon enables instant history writes and scheduled synchronization.

    Technical Infrastructure

    • PostgreSQL / Postgres: The recommended open-source database for self-hosting an Atuin server.
    • SQLite: A lightweight, file-based database used for local shell history storage.
    • MCP (Model Context Protocol): A standard allowing AI assistants to interface with tools like Atuin (e.g., for history searching).
    • LLM (Large Language Model): AI models (like Claude or GPT) used for Atuin's command generation.
    • PTY (Pseudo-terminal): The communication channel used by programs to interact with your terminal.
    • UUID: A unique identifier used to prevent ID clashes across different machines.

    Deployment and Connectivity

    • CLI (Command-line interface): The primary program used via terminal commands.
    • Docker: A tool for bundling programs into containers for consistent execution.
    • Kubernetes: A system for scaling containers, used for large-scale Atuin self-hosting.
    • SSH (Secure Shell): A secure method for remote command execution and login.
    • TLS (Transport Layer Security): The standard encryption for data in transit.
    • systemd: The Linux service manager used to start and supervise the Atuin daemon or server.

  4. What `atuin init` configures

    main

    Running atuin init sets up the following components in your shell session:

    • Hooks: Automatically records every command, its exit code, and its execution duration.
    • Key bindings: Enables Ctrl+r and the Up arrow for history searching, and the ? (question) key for Atuin AI.
    • Dotfiles: If enabled, it loads your synced aliases and environment variables.

  5. How Permission Scopes and Glob Patterns Work

    main

    Most permission rules can be scoped to specific contexts using glob patterns.

    • File Operations (Read, Write): The scope is a glob pattern matching file paths. A missing pattern (e.g., Read) matches all files.
    • Shell Commands (Shell): The scope is a command pattern matched against the words in the command.

    Important Rules for File Tools

    • Write Implies Read: To prevent data loss, Atuin AI must read a file before writing to it. Any rule allowing Write for a specific path automatically allows Read for that same path.
    • Backups: When Write is used for the first time in a session, Atuin AI creates a backup in the Atuin data directory under ai/sessions/<session_id>.

  6. Use Dynamic Content and Arguments in Skills

    main

    Skills support shell substitution and argument passing to make instructions context-aware.

    Dynamic Content (Shell Substitution)

    Commands run at the moment the skill is loaded. Use the following syntax:

    • Inline: !command`` — replaces the placeholder with the command's stdout.
    • Block: ```! code block — replaces the entire block with the script's stdout.

    Arguments

    When you invoke a skill with arguments (e.g., /deploy patch), you can use the $ARGUMENTS placeholder within the SKILL.md body. The placeholder is replaced with the argument string before shell substitution occurs.

    If the skill body does not contain the $ARGUMENTS placeholder but you provided arguments, Atuin appends them to the context as ARGUMENTS: <value>.

    Example with Arguments and Shell Substitution

    ---
name: deploy
description: Deploy the application
disable-model-invocation: true
---

Deploy $ARGUMENTS to production.
Current status: !`kubectl get deployment $ARGUMENTS`

  7. Benefits of pty-proxy TUI rendering

    main

    Standard Atuin search TUI modes typically involve either a fullscreen alt-screen mode or an inline mode that clears previous output.

    With pty-proxy, the Atuin popup renders over the top of your existing terminal output. When the search UI is closed, pty-proxy successfully restores your previous output, providing a smoother user experience.

    Alternative for tmux users: If you are using tmux, you can achieve a similar effect without pty-proxy by setting [tmux] enabled = true in your Atuin configuration. This opens the search UI in a tmux popup above your pane, leaving the pane content untouched.

  8. How pty-proxy captures command output

    main

    The pty-proxy sits between your terminal and your shell, allowing it to record command output by reading OSC 133 prompt markers emitted by your shell.

    Captured output blocks are handed to the Atuin daemon, which holds them in memory keyed by the command's Atuin history ID. This enables AI tools to understand the context of a command (e.g., reading actual error messages rather than guessing).

    Requirements for output capture:

    • Both pty-proxy and the Atuin daemon must be running.
    • Output capture is not enabled by default.

  9. How Atuin themes work

    main

    Atuin themes are maps that associate Meanings (semantic descriptions of UI elements) with specific colors.

    Theme Inheritance

    Themes can inherit from other themes using the parent key. If a specific Meaning is not defined in your custom theme, Atuin will:

    1. Look for the color in the specified parent theme.
    2. If not found in the parent, fall back to the default theme.

    Theme Loading Logic

    When a theme name is requested, Atuin looks for a file named THEMENAME.toml in:

    1. The directory specified by the ATUIN_THEME_DIR environment variable (if set).
    2. The default directory: ~/.config/atuin/themes/.

    If the requested theme file is not found, Atuin will fall back to the (none) theme, leaving the interface unstyled. It does not automatically fall back to the default theme.

  10. Configure search modes and syntax

    main

    Atuin supports several search modes via the search_mode key:

    • prefix: Searches for query*.
    • fulltext: Searches for *query*.
    • fuzzy: Uses fzf-style fuzzy syntax.
    • daemon-fuzzy: Uses an in-memory index via the Atuin daemon for faster searches (requires daemon enabled).

    Fuzzy Search Syntax

    Fuzzy and daemon-fuzzy modes use fzf syntax:

    TokenMatch typeDescription
    sbtrktfuzzy-matchItems that match sbtrkt
    'wildexact-match (quoted)Items that include wild
    ^musicprefix-exact-matchItems that start with music
    .mp3$suffix-exact-matchItems that end with .mp3
    !fireinverse-exact-matchItems that don't include fire
    !^musicinverse-prefix-exact-matchItems that don't start with music
    !.mp3$inverse-suffix-exact-matchItems that don't end with .mp3

    Note: The bar character | (OR operator) is not supported in daemon-fuzzy mode.

    search_mode = "fuzzy"

  11. Configure terminal key bindings

    main

    Atuin's advanced key bindings depend on your terminal's capabilities.

    Terminals that implement the kitty keyboard protocol can report:

    • Modifier keys
    • Function keys (e.g., Fn1 through Fn24)
    • Media keys
    • The super (Command) modifier

    Terminals without this protocol (such as the default macOS Terminal) are limited to basic key combinations. For more advanced configuration, refer to the Advanced key binding guide.

  12. Invoke user-defined skills as slash commands

    main

    Any user-defined skill (defined in your skills configuration) that has a name is automatically registered as a slash command.

    • Invocation: Type / followed by the skill name (e.g., /my-skill).
    • Parameters: If the skill requires parameters, provide them after the skill name, separated by spaces.
    • Discovery: Skill names and their descriptions appear in the /help menu and the slash command fuzzy picker.
    /my-skill parameter1 parameter2