### Install Atuin and Setup Sync

Source: https://github.com/atuinsh/atuin/blob/main/crates/atuin/README.md

This script downloads and installs Atuin, then registers you with the Atuin Cloud sync server. It also imports your existing history and initiates synchronization. Ensure you restart your shell after completion.

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh

atuin register -u <USERNAME> -e <EMAIL>
atuin import auto
atuin sync
```

--------------------------------

### Install Atuin using Nix environment

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation option for Nix users, installing from nixpkgs.

```shell
nix-env -f '<nixpkgs>' -iA atuin
```

--------------------------------

### Install Atuin on Windows using WinGet

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

The recommended installation method for Windows. After installation, add the initialization command to your PowerShell profile and restart your shell.

```powershell
winget install -e Atuinsh.Atuin
if (-not (Test-Path -Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force | Out-Null }
Write-Output 'atuin init powershell | Out-String | Invoke-Expression' >> $PROFILE
```

--------------------------------

### Install Atuin using XBPS

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation option for Void Linux users, installing from the void-packages repository.

```shell
sudo xbps-install atuin
```

--------------------------------

### Display Atuin Configuration and Version Info

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/info.md

Use the `atuin info` command to view the paths to your client and server configuration files, the client database location, key and session paths, environment variable overrides, and the installed version of Atuin. This is useful for troubleshooting or understanding your Atuin setup.

```bash
atuin info
```

--------------------------------

### Fish Shell Key Binding Setup

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/key-binding.md

Configure key bindings in the Fish shell by adding commands to `~/.config/fish/config.fish`. This example binds Ctrl+R in normal and insert modes to `_atuin_search`.

```fish
set -gx ATUIN_NOBIND "true"
atuin init fish | source

# bind to ctrl-r in normal and insert mode, add any other bindings you want here too
bind \cr _atuin_search
bind -M insert \cr _atuin_search
```

--------------------------------

### Install Atuin using Nix profile

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation option for Nix users, installing from the repository's flake.

```shell
nix profile install "github:atuinsh/atuin"
```

--------------------------------

### Install Atuin using the official script

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Recommended for Unix-like systems. This script handles Atuin installation and its requirements automatically. It installs the binary to `~/.atuin/bin` and sets up shell history import and sync.

```shell
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh
```

--------------------------------

### Install Atuin using zinit

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation using zinit, fetching the binary from GitHub releases and setting up shell integration.

```shell
# line 1: `atuin` binary as command, from github release, only look at .tar.gz files, use the `atuin` file from the extracted archive
# line 2: setup at clone(create init.zsh, completion)
# line 3: pull behavior same as clone, source init.zsh
zinit ice as"command" from"gh-r" bpick"atuin-*.tar.gz" mv"atuin*/atuin -> atuin" \
    atclone"./atuin init zsh > init.zsh; ./atuin gen-completions --shell zsh > _atuin" \
    atpull"%atclone" src"init.zsh"
zinit light atuinsh/atuin
```

--------------------------------

### Install and Register Atuin

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/index.md

Run this script to install Atuin, then register your account and import your existing history. Restart your shell after completion.

```bash
bash <(curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh)

atuin register -u <USERNAME> -e <EMAIL>
atuin import auto
atuin sync
```

--------------------------------

### Start Atuin Server

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/server-setup.md

Starts the atuin-server process. This command assumes the server binary is in your PATH.

```shell
atuin-server start
```

--------------------------------

### Enable and Start Atuin Server Service

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/systemd.md

Commands to enable the Atuin server service to start on boot and start it immediately.

```sh
systemctl enable --now atuin-server
```

--------------------------------

### Install Atuin using mise

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation option using the mise version manager.

```shell
mise use -g atuin@latest
```

--------------------------------

### Build and install Atuin from source

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation by cloning the repository and building from source using Cargo. Requires the latest stable Rust toolchain.

```shell
git clone https://github.com/atuinsh/atuin.git
cd atuin/crates/atuin
cargo install --path .
```

--------------------------------

### Install Atuin using Cargo

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation option using Cargo, Rust's package manager. Ensure you have rustup installed for a proper Rust toolchain setup.

```shell
cargo install atuin
```

--------------------------------

### Install Atuin using Pacman

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation option for Arch Linux users, installing from the extra repository.

```shell
pacman -S atuin
```

--------------------------------

### Install Atuin using WinGet (alternative)

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Alternative command for installing Atuin via WinGet.

```shell
winget install -e Atuinsh.Atuin
```

--------------------------------

### Nu Shell Key Binding Setup

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/key-binding.md

Set up key bindings in the Nu shell by configuring the `$env.config.keybindings`. This example binds Ctrl+R in emacs, vi_normal, and vi_insert modes to execute `_atuin_search_cmd`.

```nu
$env.ATUIN_NOBIND = true
atuin init nu | save -f ~/.local/share/atuin/init.nu #make sure you created the directory beforehand with `mkdir ~/.local/share/atuin/init.nu`
source ~/.local/share/atuin/init.nu

#bind to ctrl-r in emacs, vi_normal and vi_insert modes, add any other bindings you want here too
$env.config = (
    $env.config | upsert keybindings (
        $env.config.keybindings
        | append {
            name: atuin
            modifier: control
            keycode: char_r
            mode: [emacs, vi_normal, vi_insert]
            event: { send: executehostcommand cmd: (_atuin_search_cmd) }
        }
    )
)
```

--------------------------------

### Example: Alias 'k' to 'kubectl'

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/dotfiles.md

This example demonstrates setting a common alias 'k' to 'kubectl' using the `atuin dotfiles alias set` command.

```bash
atuin dotfiles alias set k 'kubectl'
```

--------------------------------

### Install Atuin using Termux

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation option for Termux users.

```shell
pkg install atuin
```

--------------------------------

### Install and Configure Atuin with Cloud Sync

Source: https://github.com/atuinsh/atuin/blob/main/README.md

This script automates the installation of Atuin and sets up the Atuin Cloud sync server. It requires curl and a shell environment. After running, register your account and import your existing history.

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh
```

```bash
atuin register -u <USERNAME> -e <EMAIL>
```

```bash
atuin import auto
```

```bash
atuin sync
```

--------------------------------

### Example: Set Environment Variable 'FOO' to 'bar'

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/dotfiles.md

This example shows how to set the environment variable 'FOO' to the value 'bar'.

```bash
atuin dotfiles var set FOO 'bar'
```

--------------------------------

### Manually Start Atuin Daemon

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/daemon.md

If autostart is disabled or you prefer manual management, run this command to start the Atuin daemon.

```bash
atuin daemon
```

--------------------------------

### Install Atuin using Homebrew

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation option for macOS and Linux users who prefer Homebrew.

```shell
brew install atuin
```

--------------------------------

### Install AI Agent Hooks

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/agent-hooks.md

Install hooks for AI agents to enable Atuin to capture their commands. Restart or reload the agent after installation.

```shell
# Claude Code
atuin hook install claude-code
```

```shell
# Codex
atuin hook install codex
```

```shell
# pi
atuin hook install pi
```

--------------------------------

### Bash Key Binding Setup

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/key-binding.md

Use `atuin-bind` to set up custom key bindings in Bash. This example binds Ctrl+R to `atuin-search` and the Up arrow key to `atuin-up-search`.

```bash
export ATUIN_NOBIND="true"
eval "$(atuin init bash)"

# bind to ctrl-r, add any other bindings you want here too
atuin-bind '\C-r' atuin-search
# example of CTRL-upkey
# atuin-bind '\e[1;5A' atuin-search

# bind to the up key, which depends on terminal mode
atuin-bind '\e[A' atuin-up-search
atuin-bind '\eOA' atuin-up-search
```

--------------------------------

### Install Latest Atuin Server

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/server-setup.md

Installs the latest release of the atuin-server binary using a shell script. Ensure you have curl installed.

```shell
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/atuinsh/atuin/releases/latest/download/atuin-server-installer.sh | sh
```

--------------------------------

### Example TOML for Project Permissions

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/ai/tools-permissions.md

Example TOML configuration for managing project-specific AI tool permissions. Allows writing markdown files and denies access to .env files.

```toml
[permissions]

allow = [
    "Write(**/*.md)"
]

deny = [
    "Read(.env)"
]
```

--------------------------------

### Configure Daemon Autostart

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md

Configure whether the daemon automatically starts when needed. Not compatible with systemd_socket = true.

```toml
autostart = false
```

--------------------------------

### Define a Code Review Skill

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/ai/skills.md

Example of a `SKILL.md` file for a code review skill. It includes YAML frontmatter for metadata and a description of the review process. Shell substitution is used to dynamically get the current branch.

```markdown
---
name: code-review
description: Conducts a structured code review. Use when the user asks to review code, a PR, or a diff.
---

When reviewing code:

1. **Correctness** — Does the code do what it claims?
2. **Edge cases** — What inputs could break it?
3. **Style** — Does it match the project's conventions?

Current branch: !`git branch --show-current`

```

--------------------------------

### Re-installing Atuin Hooks

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/agent-hooks.md

Running `atuin hook install` again is safe and will skip installation if hooks are already present, printing a message indicating they are installed.

```shell
hooks.PreToolUse: already installed, skipping
hooks.PostToolUse: already installed, skipping
hooks.PostToolUseFailure: already installed, skipping
```

--------------------------------

### Example: Alias 'll' to 'ls -lah'

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/dotfiles.md

This example shows how to alias 'll' to 'ls -lah' for convenience when listing directory contents.

```bash
atuin dotfiles alias set ll 'ls -lah'
```

--------------------------------

### Install Atuin using MacPorts

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Manual installation option for users who manage packages with MacPorts.

```shell
sudo port install atuin
```

--------------------------------

### Start Docker Compose Services

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/docker.md

Commands to create the configuration directory and start the services defined in your docker-compose.yml file in detached mode.

```sh
mkdir config
chown 1000:1000 config
docker compose up -d
```

--------------------------------

### Non-interactive Atuin installation via script

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Use this option to skip interactive prompts during installation, suitable for CI or Docker environments. The script automatically detects non-interactive environments.

```shell
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh -s -- --non-interactive
```

--------------------------------

### Verify pi Extension Installation

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/agent-hooks.md

Check for the presence of Atuin's extension file in the pi agent's extension directory.

```shell
ls ~/.pi/agent/extensions/atuin.ts
```

--------------------------------

### PostgreSQL Server Configuration (TOML)

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/server-setup.md

Example configuration for the Atuin server using a TOML file, specifying connection details for a PostgreSQL database.

```toml
host = "0.0.0.0"
port = 8888
open_registration = true
db_uri="postgres://user:password@hostname/database"
```

--------------------------------

### SQLite Server Configuration (TOML)

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/server-setup.md

Example configuration for the Atuin server using a TOML file, specifying a SQLite database URI. Ensure the `/config` directory is mapped to a persistent volume.

```toml
db_uri="sqlite:///config/atuin.db"
```

--------------------------------

### Reset Sync Account and Start Fresh

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/delete-history.md

To start completely fresh with sync enabled, delete your sync account and register a new one. This removes all server-side data and sync records.

```bash
# Delete your sync account and all server-side data
atuin account delete
```

```bash
# Register a new account
atuin register
```

```bash
# Import your shell history fresh (optional)
atuin import auto
```

--------------------------------

### Media Key Bindings

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/advanced-key-binding.md

Examples of media key bindings. These require a terminal that implements the kitty keyboard protocol with DISAMBIGUATE_ESCAPE_CODES enabled.

```toml
"play", "pause", "playpause", "stop"
"fastforward", "rewind", "tracknext", "trackprevious"
"record", "lowervolume", "raisevolume", "mutevolume", "mute"
```

--------------------------------

### Load Atuin Shell Plugin with Zinit

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

If you only want to install the shell plugin using Zinit, use this command. Ensure Atuin is already installed.

```shell
zinit load atuinsh/atuin
```

--------------------------------

### Install Atuin for Offline Use

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/getting-started.md

Install Atuin using this command for local history management without synchronization. This option keeps your history private and not backed up or shared across devices.

```bash
bash <(curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh)

atuin import auto
```

--------------------------------

### Initialize Atuin for Bash with ble.sh

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

For Bash users with ble.sh (>= 0.4) installed, add this line to your ~/.bashrc to initialize Atuin. Ensure ble.sh is loaded first.

```shell
echo 'eval "$(atuin init bash)"' >> ~/.bashrc
```

--------------------------------

### Initialize pty-proxy with custom PATH for bash

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/pty-proxy.md

This example shows how to initialize pty-proxy for bash when the `atuin` binary is not in the default PATH. Ensure the PATH is exported before calling the init command.

```bash
export PATH=$HOME/.atuin/bin:$PATH
eval "$(atuin pty-proxy init bash)"

# ... other shell configuration ...

eval "$(atuin init bash)"
```

--------------------------------

### Install Atuin Shell Plugin with Antidote

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

This command installs the Atuin shell plugin using Antidote. It's a straightforward way to add Atuin integration to your shell.

```shell
antidote install atuinsh/atuin
```

--------------------------------

### Manage Systemd Service

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/docker.md

Commands to enable and start the Atuin systemd service, and to check its status.

```sh
systemctl enable --now atuin
systemctl status atuin
```

--------------------------------

### Example: Delete Alias 'k'

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/dotfiles.md

This command demonstrates how to delete the previously set 'k' alias.

```bash
atuin dotfiles alias delete k
```

--------------------------------

### Example: Delete Environment Variable 'FOO'

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/dotfiles.md

This command demonstrates how to delete the previously set environment variable 'FOO'.

```bash
atuin dotfiles var delete FOO
```

--------------------------------

### Basic Key Formats

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/advanced-key-binding.md

Examples of basic key formats including lowercase letters, digits, and common named keys. Also includes function keys.

```toml
"a", "z", "1", "9"
"enter", "esc", "tab", "space", "backspace", "delete"
"up", "down", "left", "right"
"home", "end", "pageup", "pagedown"
"f1", "f2", ... "f12", ... "f24"
```

--------------------------------

### Configure Nushell to Source Atuin Init Script

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Add this line to your Nushell 'config.nu' file to source the generated Atuin initialization script. This ensures Atuin is active when you start Nushell.

```shell
source ~/.local/share/atuin/init.nu
```

--------------------------------

### Verify Atuin Preexec Hook in IDE

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/shell-integration.md

After configuring an IDE, run this command in a new terminal to confirm that Atuin's preexec hook is correctly installed.

```shell
atuin doctor | grep preexec
```

--------------------------------

### Use Case: Frecency Ranking with Filter and Scorer

Source: https://github.com/atuinsh/atuin/blob/main/crates/atuin-nucleo/README.md

Example demonstrating frecency-based ranking by filtering items by directory and combining fuzzy score with frecency using callbacks.

```rust
// External data store
let metadata: Arc<DashMap<String, ItemMetadata>> = /* ... */;

// Filter: only show items used in current directory
let dir = current_dir.clone();
let meta = metadata.clone();
nucleo.set_filter(Some(Arc::new(move |cmd: &String| {
    meta.get(cmd).map(|m| m.used_in_dir(&dir)).unwrap_or(false)
})));

// Scorer: combine fuzzy score with frecency
let meta = metadata.clone();
nucleo.set_scorer(Some(Arc::new(move |cmd: &String, fuzzy_score| {
    let frecency = meta.get(cmd).map(|m| m.frecency()).unwrap_or(0);
    fuzzy_score + (frecency * 10)
})));
```

--------------------------------

### List History with Custom Format

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/list.md

Use the `--format` argument to customize the output of the history list. This example shows how to display the time, duration, and command text.

```bash
atuin history list --format "{time} - {duration} - {command}"
```

--------------------------------

### Search Atuin History

Source: https://github.com/atuinsh/atuin/blob/main/crates/atuin/README.md

Search your Atuin history for specific commands based on criteria like exit code and time. This example finds successful 'make' commands from yesterday afternoon.

```bash
atuin search --exit 0 --after "yesterday 3pm" make
```

--------------------------------

### Initialize Atuin for Nushell (Standard)

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Run these commands in Nushell to set up Atuin. The first creates a directory for Atuin's init script, and the second generates and saves the script.

```shell
mkdir ~/.local/share/atuin/
atuin init nu | save ~/.local/share/atuin/init.nu
```

--------------------------------

### Skill with Arguments and Dynamic Content

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/ai/skills.md

Demonstrates how a skill can use the `$ARGUMENTS` placeholder and shell substitution to dynamically fetch deployment status.

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

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

```

--------------------------------

### Enable Sync V2 Records in Atuin Config

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/dotfiles.md

If sync v2 is not yet set up, include this configuration in `~/.config/atuin/config.toml` alongside the dotfiles configuration.

```toml
[sync]
records = true
```

--------------------------------

### Configure Preview Settings

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md

Configure preview-related settings for the Atuin TUI, specifically the strategy for calculating preview height.

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

--------------------------------

### Enable Atuin Daemon Configuration

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/daemon.md

Add this TOML configuration to your Atuin config file to enable the daemon and set it to autostart.

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

--------------------------------

### Register for Atuin Sync

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/sync.md

Use this command to register a new account with the Atuin sync server. You will need to provide a username and email address.

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

--------------------------------

### Download and Initialize bash-preexec

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

To use Atuin with bash-preexec, first download the script and then source it in your ~/.bashrc. Note potential issues with ignorespace and subshell commands.

```shell
curl https://raw.githubusercontent.com/rcaloras/bash-preexec/master/bash-preexec.sh -o ~/.bash-preexec.sh
echo '[[ -f ~/.bash-preexec.sh ]] && source ~/.bash-preexec.sh' >> ~/.bashrc
```

--------------------------------

### Emacs Keymap: Accept Past Line Start Behavior (Off by Default)

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/advanced-key-binding.md

Configures the 'left' key in the Emacs keymap to accept when the cursor is at the start of the line. This is off by default.

```toml
[keymap.emacs]
"left" = [
  { when = "cursor-at-start", action = "accept" },
  { action = "cursor-left" },
]
```

--------------------------------

### Enable Sync v2 Configuration

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/sync-v2.md

Opt into sync v2 by adding this configuration to your settings. This enables record synchronization.

```toml
[sync]
records = true

```

--------------------------------

### Initialize pty-proxy for Nushell

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/pty-proxy.md

Nushell requires pre-generating an initialization file. Run these commands to create the file and then source it in your `config.nu` before the regular `atuin init`.

```shell
mkdir ~/.local/share/atuin/
atuin pty-proxy init nu | save -f ~/.local/share/atuin/pty-proxy-init.nu
```

```shell
source ~/.local/share/atuin/pty-proxy-init.nu
```

--------------------------------

### Enable Dotfiles Sync in Atuin Config

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/dotfiles.md

Add this configuration to `~/.config/atuin/config.toml` to enable dotfiles management. This setting will be enabled by default in a future release.

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

--------------------------------

### Build and Check Commands

Source: https://github.com/atuinsh/atuin/blob/main/AGENTS.md

Standard commands for building, testing, linting, and formatting the Atuin project. Ensure these are run in your development environment.

```sh
cargo build
```

```sh
cargo test
```

```sh
cargo clippy -- -D warnings
```

```sh
cargo fmt --check
```

--------------------------------

### Example Atuin Doctor Output

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/doctor.md

This is an example of the output generated by the `atuin doctor` command, detailing Atuin version, sync status, shell configuration, and system information. This output should be provided when submitting bug reports.

```yaml
Atuin Doctor
Checking for diagnostics


Please include the output below with any bug reports or issues
atuin:
  version: 18.1.0
  sync:
    cloud: true
    records: true
    auto_sync: true
    last_sync: 2024-03-05 14:54:48.447677 +00:00:00
shell:
  name: zsh
  plugins:
  - atuin
system:
  os: Darwin
  arch: arm64
  version: 14.4
  disks:
  - name: Macintosh HD
    filesystem: apfs
  - name: Macintosh HD
    filesystem: apfs

```

--------------------------------

### Search with Limit

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/search.md

Retrieves exactly one result for commands starting with 'cargo'.

```bash
atuin search --limit 1 cargo
```

--------------------------------

### Login to Atuin Sync on a New Machine

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/sync.md

Log in to Atuin sync on a new machine using your username, password, and encryption key. Omit flags to be prompted securely via stdin.

```bash
atuin login -u <USERNAME> -p <PASSWORD> -k <KEY>
```

--------------------------------

### Verify Codex Hook Installation

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/agent-hooks.md

Check the Codex hooks file to confirm that Atuin hooks have been registered.

```shell
cat ~/.codex/hooks.json | grep atuin
```

--------------------------------

### Search with Limit and Offset

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/search.md

Retrieves a single result for commands starting with 'cargo', skipping the first result.

```bash
atuin search --offset 1 --limit 1 cargo
```

--------------------------------

### List All Environment Variables Managed by Atuin

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/dotfiles.md

Run this command to view all environment variables currently managed by Atuin.

```bash
atuin dotfiles var list
```

--------------------------------

### Search for Successful Commands

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/search.md

Finds all commands starting with 'cargo' that exited successfully (exit code 0).

```bash
atuin search --exit 0 cargo
```

--------------------------------

### Find Oldest Command

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/search.md

Searches for commands starting with 'cargo' and returns the oldest one by reversing the search results.

```bash
atuin search --limit 1 --reverse cargo
```

--------------------------------

### Print Atuin Configuration

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/config.md

Print configuration values from your config file in TOML format. Without a key, it prints the entire file. With a key, it prints only that specific section.

```bash
$ atuin config print daemon
[daemon]
enabled = true
socket_path = "/tmp/atuin_daemon.sock"
pidfile_path = "/tmp/atuin_daemon.pid"
autostart = false
```

--------------------------------

### Verify Claude Code Hook Installation

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/agent-hooks.md

Check the Claude Code settings file to confirm that Atuin hooks have been registered.

```shell
cat ~/.claude/settings.json | grep atuin
```

--------------------------------

### Search Successful Commands After a Specific Time

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/search.md

Finds commands starting with 'cargo' that exited successfully and ran after 'yesterday 3pm'.

```bash
atuin search --exit 0 --after "yesterday 3pm" cargo
```

--------------------------------

### Initialize Atuin for PowerShell

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Add this command to the end of your $PROFILE file to initialize Atuin for PowerShell. This integrates Atuin with your PowerShell session.

```powershell
atuin init powershell | Out-String | Invoke-Expression
```

--------------------------------

### Register for Atuin Sync Account

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/sync.md

Use this command to create a new Atuin sync account. You can omit the password flag to be prompted securely via stdin. Usernames must be alphanumeric or hyphens.

```bash
atuin register -u <USERNAME> -e <EMAIL> -p <PASSWORD>
```

--------------------------------

### Configure Theme Settings

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md

Set the theme name, debug mode, and max depth for theme traversal.

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

--------------------------------

### Invoke Skill with Arguments

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/ai/skills.md

Example of invoking a skill directly from the TUI with an argument. The argument is used within the skill's content.

```bash
/deploy patch
```

--------------------------------

### Configure Common Subcommands for Stats

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md

Specify commands where subcommands should be considered part of the statistics, like 'kubectl get' instead of just 'kubectl'.

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

--------------------------------

### Initialize pty-proxy for bash

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/pty-proxy.md

Place this command in your bash init script, ensuring it runs before your regular `atuin init` command.

```shell
eval "$(atuin pty-proxy init bash)"
```

--------------------------------

### Update Atuin

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Run this command to update Atuin to the latest version. If the command is unavailable, re-run the install script or use your package manager.

```shell
atuin update
```

--------------------------------

### Minimal UI Columns Configuration

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md

A minimal configuration for UI columns, prioritizing space for commands.

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

--------------------------------

### Delete Successful Commands After a Specific Time

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/search.md

Deletes commands starting with 'cargo' that exited successfully and ran after 'yesterday 3pm'. Use with caution.

```bash
atuin search --delete --exit 0 --after "yesterday 3pm" cargo
```

--------------------------------

### Initialize Atuin for Fish Shell

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Add this command to the 'is-interactive' block in your ~/.config/fish/config.fish file to initialize Atuin for Fish. This enables Atuin's history features.

```shell
atuin init fish | source
```

--------------------------------

### Calculate 1-day Stats

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/stats.md

Generate statistics for a 24-hour period starting from a specified date or relative time. Date formats are parsed by the 'interim' crate.

```bash
$ atuin stats last friday
```

```bash
$ atuin stats 2018-04-01
```

```bash
$ atuin stats April 1
```

```bash
$ atuin stats 01/04/22
```

```bash
$ atuin stats last thursday 3pm  # between last thursday 3:00pm and the following friday 3:00pm
```

--------------------------------

### Allow Atuin History Tool Access

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/ai/tools-permissions.md

Example TOML snippet to explicitly allow the AtuinHistory tool. This tool is used for searching command history.

```toml
[permissions]

allow = ["AtuinHistory"]
```

--------------------------------

### Create a Wrapper Script for Interactive Shells

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/shell-integration.md

Use this wrapper script for tools that don't easily support shell arguments, ensuring an interactive shell is launched.

```shell
#!/bin/bash
# Save as ~/bin/interactive-bash.sh and chmod +x
exec /bin/bash -i "$@"
```

--------------------------------

### Conditional Key Bindings with Boolean Expressions

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/advanced-key-binding.md

Demonstrates how to use conditions with boolean operators (AND, OR, NOT) and parentheses to create complex key binding logic.

```toml
# Negation
{ when = "!no-results", action = "select-next" }
```

```toml
# Conjunction (AND)
{ when = "cursor-at-start && input-empty", action = "exit" }
```

```toml
# Disjunction (OR)
{ when = "list-at-start || no-results", action = "exit" }
```

```toml
# Grouping with parentheses
{ when = "(cursor-at-start && !input-empty) || no-results", action = "return-original" }
```

--------------------------------

### Kubernetes Persistent Volume Claim Example

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/kubernetes.md

Defines a Persistent Volume Claim for Atuin's database storage. Ensure the storage size meets your needs.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: atuin-claim0
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Mi
```

--------------------------------

### Configure Keys

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md

Configure key-related settings for the Atuin TUI, including scroll behavior and prefix key for shortcuts.

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

--------------------------------

### Configure Compact UI Mode

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/basic-usage.md

Set `style = "compact"` in your configuration file to enable the compact UI mode for Atuin.

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

--------------------------------

### Initialize pty-proxy for fish

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/pty-proxy.md

For fish shell users, add this command to the `is-interactive` block within your `~/.config/fish/config.fish` file.

```shell
atuin pty-proxy init fish | source
```

--------------------------------

### Search History with Atuin

Source: https://github.com/atuinsh/atuin/blob/main/README.md

Use this command to search your shell history for specific commands based on exit code, time, and keywords. Ensure Atuin is installed and configured.

```bash
# search for all successful `make` commands, recorded after 3pm yesterday
atuin search --exit 0 --after "yesterday 3pm" make
```

--------------------------------

### Systemd Unit File for Docker Compose

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/docker.md

A systemd service unit file to manage the Atuin Docker Compose stack, ensuring it starts on boot and restarts on failure.

```ini
[Unit]
Description=Docker Compose Atuin Service
Requires=docker.service
After=docker.service

[Service]
# Where the docker-compose file is located
WorkingDirectory=/srv/atuin-server
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0
Restart=on-failure
StartLimitBurst=3

[Install]
WantedBy=multi-user.target
```

--------------------------------

### UI Columns with Expandable Directory

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md

Configure UI columns where the directory column expands to fill available space, while the command column does not.

```toml
columns = ["duration", "time", { type = "directory", expand = true }, { type = "command", expand = false }]
```

--------------------------------

### Configure VS Code for Interactive Shell

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/shell-integration.md

Modify VS Code's `settings.json` to ensure its integrated terminal starts an interactive shell, enabling Atuin integration.

```json
{
  "terminal.integrated.profiles.linux": {
    "bash": {
      "path": "/bin/bash",
      "args": ["-i"]
    }
  },
  "terminal.integrated.profiles.osx": {
    "zsh": {
      "path": "/bin/zsh",
      "args": ["-i"]
    }
  }
}
```

--------------------------------

### Configure Nushell to Source pty-proxy and Atuin Init Scripts

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/installation.md

Source both the pty-proxy init script and the regular Atuin init script in your 'config.nu' file. Ensure the pty-proxy script is sourced first.

```shell
source ~/.local/share/atuin/pty-proxy-init.nu
source ~/.local/share/atuin/init.nu
```

--------------------------------

### Enable Daemon

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md

Enable the background daemon for Atuin. Add this section to your configuration file.

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

--------------------------------

### Login to Atuin Sync on a New Machine

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/sync.md

Logs into the Atuin sync service on a new machine using your registered username. You will be prompted for your password and encryption key.

```bash
atuin login -u <USERNAME>
```

--------------------------------

### Get Atuin Configuration Value

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/config.md

Retrieve the value of a specific configuration key as it appears in the config file. If the key is not found, it indicates that it's not set in the config file.

```bash
$ atuin config get search_mode
fuzzy

$ atuin config get daemon
[daemon]
enabled = true
socket_path = "/tmp/atuin_daemon.sock"

$ atuin config get enter_accept
(not set in config file)
```

--------------------------------

### Clone and Build Atuin

Source: https://github.com/atuinsh/atuin/blob/main/CONTRIBUTING.md

Standard procedure to clone the Atuin repository and build the project using Cargo. This is the first step for any development.

```shell
git clone https://github.com/atuinsh/atuin
cd atuin
cargo build
```

--------------------------------

### Kubernetes Persistent Volume for Database

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/kubernetes.md

Configure a Kubernetes Persistent Volume (PV) for the PostgreSQL database data. This example uses a hostPath, suitable for local testing or development environments.

```yaml
---
kind: PersistentVolume
apiVersion: v1
metadata:
  name: database-pv
  labels:
    app: database
    type: local
spec:
  storageClassName: manual
  capacity:
    storage: 300Mi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: "/Users/firstname.lastname/.kube/database"
```

--------------------------------

### PostgreSQL Server Configuration (Environment Variables)

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/self-hosting/server-setup.md

Configures the Atuin server using environment variables for PostgreSQL connection details. These override TOML settings.

```shell
ATUIN_HOST="0.0.0.0"
ATUIN_PORT=8888
ATUIN_OPEN_REGISTRATION=true
ATUIN_DB_URI="postgres://user:password@hostname/database"
```

--------------------------------

### Sync Dotfiles and History with Atuin

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/guide/dotfiles.md

If Atuin sync is configured, this command backs up your configuration and history to the server, syncing it across all your machines.

```bash
atuin sync
```

--------------------------------

### Initialize pty-proxy for zsh

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/reference/pty-proxy.md

Add this line to your zsh init script before the normal `atuin init` call to enable pty-proxy functionality.

```shell
eval "$(atuin pty-proxy init zsh)"
```

--------------------------------

### Analyze Span Timing Data (Filter)

Source: https://github.com/atuinsh/atuin/blob/main/CONTRIBUTING.md

Use the `span-table.ts` script to filter and analyze specific spans from a captured JSON file. This example filters for spans containing 'search' or 'hydrate'.

```shell
bun scripts/span-table.ts spans.json --filter "search|hydrate"
```

--------------------------------

### Configure Log Directory

Source: https://github.com/atuinsh/atuin/blob/main/docs/docs/configuration/config.md

Specify the directory where Atuin log files will be stored. Defaults to "~/.atuin/logs".

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