diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/docs/guide/advanced-usage.md | 49 | ||||
| -rw-r--r-- | docs/docs/guide/agent-hooks.md | 138 | ||||
| -rw-r--r-- | docs/docs/guide/basic-usage.md | 65 | ||||
| -rw-r--r-- | docs/docs/guide/delete-history.md | 146 | ||||
| -rw-r--r-- | docs/docs/guide/dotfiles.md | 141 | ||||
| -rw-r--r-- | docs/docs/guide/getting-started.md | 54 | ||||
| -rw-r--r-- | docs/docs/guide/import.md | 18 | ||||
| -rw-r--r-- | docs/docs/guide/installation.md | 308 | ||||
| -rw-r--r-- | docs/docs/guide/shell-integration.md | 263 | ||||
| -rw-r--r-- | docs/docs/guide/sync.md | 78 | ||||
| -rw-r--r-- | docs/docs/guide/theming.md | 138 |
11 files changed, 0 insertions, 1398 deletions
diff --git a/docs/docs/guide/advanced-usage.md b/docs/docs/guide/advanced-usage.md deleted file mode 100644 index 0d5a1359..00000000 --- a/docs/docs/guide/advanced-usage.md +++ /dev/null @@ -1,49 +0,0 @@ -# Advanced Usage - -Atuin offers you several options to help navigate through the results. - -## Filter mode - -The command history can be filtered in different ways, letting you narrow the search scope. - -You can cycle through the different modes by pressing **ctrl-r**. - -The available modes are: - -| Mode | Description | -|------------------|--------------------------------------------------------------------------------------| -| global (default) | Search from the full history | -| host | Search history from this host | -| session | Search history from the current session | -| directory | Search history from the current directory | -| workspace | Search history from the current git repository | -| session-preload | Search from the current session and the global history from before the session start | - -See the [`filter_mode` config reference](../configuration/config.md#filter_mode) for more details. - -## Search mode - -Atuin offers different modes to interpret your search query. - -You can cycle through the different modes by pressing **ctrl-s**. - -The available modes are: - -| Mode | Description | -|-----------------|----------------------------------------------------------------------------------------------------------------| -| fuzzy (default) | Search for commands in a fuzzy way, similar to the [fzf syntax](https://github.com/junegunn/fzf#search-syntax) | -| prefix | Commands that start with your query | -| fulltext | Commands that contain your query as a substring | -| skim | Search for commands using the [skim syntax](https://github.com/lotabout/skim#search-syntax) | - -See the [`search_mode` config reference](../configuration/config.md#search_mode) for more details. - -## Context switch - -Atuin uses the current context (host, session, directory) to filter the history when you use a filter mode other than *global*. - -You can switch this context to the one of the currently selected command by pressing **ctrl-a** then **c**. - -This will set the filter mode to *session* and clear the search query, which will show you all the commands executed in the same shell session. - -Pressing this key combination again will return to the initial context. You can customize this behavior by setting [custom key bindings](../configuration/advanced-key-binding.md) to the `switch-context` and `clear-context` commands. `switch-context` can be called several times to navigate through multiple command contexts, while `clear-context` will always return to the initial context. diff --git a/docs/docs/guide/agent-hooks.md b/docs/docs/guide/agent-hooks.md deleted file mode 100644 index 0801e819..00000000 --- a/docs/docs/guide/agent-hooks.md +++ /dev/null @@ -1,138 +0,0 @@ -# AI Agent Hooks - -Atuin can capture commands run by AI coding agents (like Claude Code, Codex, and pi) alongside your regular shell history. Each command is tagged with the agent that ran it, so you can filter your history by author. - -## Quick Start - -Install hooks for your agent, then restart or reload the agent: - -```shell -# Claude Code -atuin hook install claude-code - -# Codex -atuin hook install codex - -# pi -atuin hook install pi -``` - -That's it. Commands the agent runs will now appear in your Atuin history, tagged with the agent's name. - -## How It Works - -AI coding agents support hook systems that notify external tools when they're about to run a shell command and when the command finishes. Atuin uses these hooks to record each command as a history entry, just like commands you type yourself. - -When `atuin hook install` runs, it writes the agent's config file or extension to register Atuin as a hook handler: - -| Agent | Config file / extension | -|-------|-------------------------| -| Claude Code | `~/.claude/settings.json` | -| Codex | `~/.codex/hooks.json` | -| pi | `~/.pi/agent/extensions/atuin.ts` | - -The hook lifecycle: - -1. **PreToolUse** -- the agent is about to run a Bash command. Atuin records the command, working directory, and timestamp (same as `history start`). -2. **PostToolUse / PostToolUseFailure** -- the command finished. Atuin records the exit code and duration (same as `history end`). - -Only `Bash` tool invocations are captured. Other tool types (file writes, web fetches, etc.) are ignored. - -## Filtering by Author - -By default, Atuin's interactive search shows only your own commands. Agent-run commands are hidden so they don't clutter your history. - -Today this default is built into the search UI rather than configurable via `config.toml`. Interactive search uses the equivalent of: - -- `$all-user` — any author that is **not** a known AI agent - -For explicit author filtering, use the CLI `atuin search --author ...` flag. Special values: - -| Value | Meaning | -|-------|---------| -| `$all-user` | Any author that is **not** a known AI agent | -| `$all-agent` | Any known AI agent author | - -You can also use literal author names: - -```shell -# Show only your own commands and Claude Code commands -atuin search --author '$all-user' --author 'claude-code' -- '' -``` - -```shell -# Show everything (no filtering) -atuin search -- '' -``` - -```shell -# Show only agent commands -atuin search --author '$all-agent' -- '' -``` - -Currently recognized agent names are: `claude-code`, `codex`, `copilot`, and `pi`. - -## Supported Agents - -### Claude Code - -```shell -atuin hook install claude-code -``` - -This adds hook entries to `~/.claude/settings.json`. Claude Code calls `atuin hook claude-code` on each `Bash` tool use, passing the event as JSON on stdin. - -### Codex - -```shell -atuin hook install codex -``` - -This adds hook entries to `~/.codex/hooks.json`. Codex calls `atuin hook codex` on each Bash tool use matching `^Bash$`. - -### pi - -```shell -atuin hook install pi -``` - -This writes Atuin's extension to `~/.pi/agent/extensions/atuin.ts`. - -Then restart pi or run `/reload`. The extension wraps pi's built-in `bash` tool and records every bash command with author `pi` by calling `atuin history start` before execution and `atuin history end` afterwards. - -## Verifying Installation - -After installing hooks and restarting your agent, run a command through the agent and then check your history: - -```shell -# Show all history including agent commands -atuin search --authors '' -- '' - -# Show only agent commands -atuin search --authors '$all-agent' -- '' -``` - -You can also check the agent's config file directly to confirm the hooks are registered: - -```shell -# Claude Code -cat ~/.claude/settings.json | grep atuin - -# Codex -cat ~/.codex/hooks.json | grep atuin - -# pi -ls ~/.pi/agent/extensions/atuin.ts -``` - -## Re-installing - -Running `atuin hook install` again is safe. If hooks are already installed, the command will skip them and print a message: - -``` -hooks.PreToolUse: already installed, skipping -hooks.PostToolUse: already installed, skipping -hooks.PostToolUseFailure: already installed, skipping -``` - -For pi, reinstalling will also skip if the managed extension already matches the bundled version. diff --git a/docs/docs/guide/basic-usage.md b/docs/docs/guide/basic-usage.md deleted file mode 100644 index 09cf67e0..00000000 --- a/docs/docs/guide/basic-usage.md +++ /dev/null @@ -1,65 +0,0 @@ -# Basic Usage - -Now that you're all set up and running, here's a quick walkthrough of how you can use Atuin best. - -## What does Atuin record? - -While you work, Atuin records: - -1. The command you run -2. The directory you ran it in -3. The time you ran it, and how long it took to run -4. The exit code of the command -5. The hostname + user of the machine -6. The shell session you ran it in - -## Opening and using the TUI - -At any time, you can open the TUI with the default keybindings of the up arrow, or `ctrl-r`. - -Once in the TUI, press enter to immediately execute a command, or press tab to insert it into your shell for editing. - -While searching in the TUI, you can adjust the "filter mode" by repeatedly pressing `ctrl-r`. Atuin can filter by: - -1. All hosts -2. Just your local machine -3. The current directory only -4. The current shell session only - -See the [advanced usage](advanced-usage.md) page for more options. - -## Common config adjustment - -For a full set of config values, please see the [config reference page](../configuration/config.md). - -The default configuration file is located at `~/.config/atuin/config.toml`. - -### Keybindings - -We have a [full page dedicated to keybinding adjustments](../configuration/key-binding.md). -There are a whole bunch of options there, including disabling the up arrow behavior if you don't like it. - -### Enter to run - -You may prefer that Atuin always inserts the selected command for editing. To configure this, set - -``` -enter_accept = false -``` - -in your config file. - -### Inline window - -If you find the full screen TUI overwhelming or too large, you can adjust it like so: - -``` -# height of the search window -inline_height = 40 -``` - -You may also prefer the compact UI mode: - -``` -style = "compact" -``` diff --git a/docs/docs/guide/delete-history.md b/docs/docs/guide/delete-history.md deleted file mode 100644 index 6d0022e1..00000000 --- a/docs/docs/guide/delete-history.md +++ /dev/null @@ -1,146 +0,0 @@ -# Deleting History - -Atuin provides several ways to delete history, whether you want to remove a single entry, bulk delete by query, clean up duplicates, or wipe everything. - -All deletion methods are local-first. If you have sync enabled, deletions are propagated to other machines automatically. - -## Deleting a single entry - -The quickest way to delete a single entry is via the interactive TUI. - -### Using the inspector - -1. Open the TUI with ++ctrl+r++ or the up arrow -2. Search for the entry you want to delete -3. Press ++ctrl+o++ to open the inspector on the selected entry -4. Verify this is the correct entry -5. Press ++ctrl+d++ to delete it - -### Using the prefix shortcut - -1. Open the TUI with ++ctrl+r++ or the up arrow -2. Navigate to the entry you want to delete -3. Press ++ctrl+a++ then ++d++ to delete the selected entry - -Both methods remove the entry immediately with no further confirmation. - -## Deleting entries matching a query - -Use `atuin search --delete` to delete all entries matching a search query. This uses the same query syntax as regular search, so you can preview what will be deleted before committing. - -### Preview first, then delete - -Always run your query without `--delete` first to verify the results: - -``` -# Step 1: preview - see what matches -atuin search "^curl https://internal" - -# Step 2: delete - once you're satisfied the results are correct -atuin search --delete "^curl https://internal" -``` - -### Combining filters - -You can combine `--delete` with any search filter: - -``` -# Delete all failed commands run from a specific directory -atuin search --delete --exit 1 --cwd /home/user/experiments - -# Delete commands matching a pattern that ran before a certain date -atuin search --delete --before "2024-01-01" "^tmp-script" - -# Delete successful cargo commands run after yesterday at 3pm -atuin search --delete --exit 0 --after "yesterday 3pm" cargo -``` - -!!! warning - `--delete` requires a query or filter. It will not run without one. This is intentional to prevent accidental bulk deletion. - -## Deleting all history - -If you want to wipe your entire local history: - -``` -atuin search --delete-it-all -``` - -!!! danger - This deletes every entry in your local history database. It cannot be combined with a query or filters. This action is irreversible. - -### Starting fresh with sync - -If you use sync and want to start completely fresh, `--delete-it-all` alone is not enough. Atuin sync works by recording every action (including deletions) as encrypted records. Deleting 100,000 entries locally creates 100,000 delete records that still need to sync. When your other machines pull those records, they process every single one, and your database still contains the overhead of all that history. - -The cleaner approach is to delete your sync account and start over: - -``` -# Delete your sync account and all server-side data -atuin account delete - -# Register a new account -atuin register - -# Import your shell history fresh (optional) -atuin import auto -``` - -This gives you a clean slate on the server with no leftover records. Your other machines can then register with the new account and start fresh too. - -!!! tip - If you only want to delete specific entries and keep the rest, `atuin search --delete` is the right tool. The account reset approach is only better when you want to wipe everything and start over. - -## Pruning filtered commands - -If you've updated your [`history_filter`](../configuration/config.md#history_filter) config and want to retroactively remove entries that match the new filters: - -``` -# Preview what will be removed -atuin history prune --dry-run - -# Perform the deletion -atuin history prune -``` - -This is useful when you add a new pattern to `history_filter` - future commands matching the filter are never recorded, but old entries that were recorded before the filter was set up remain. `prune` cleans those up. - -## Deduplicating history - -Remove duplicate entries (same command, working directory, and hostname): - -``` -# Preview duplicates that would be removed -atuin history dedup --dry-run --before "2025-01-01" --dupkeep 1 - -# Delete them -atuin history dedup --before "2025-01-01" --dupkeep 1 -``` - -| Flag | Description | -|------|-------------| -| `--dry-run`/`-n` | List duplicates without deleting | -| `--before`/`-b` | Only consider entries added before this date (required) | -| `--dupkeep` | Number of recent duplicates to keep | - -## Deleting your sync account - -To delete your remote sync account and all server-side history: - -``` -atuin account delete -``` - -This removes your account and all synchronized history from the server. **Local history is not affected.** See the [sync reference](../reference/sync.md) for more details. - -## Summary - -| Goal | Command | -|------|---------| -| Delete one entry (TUI) | ++ctrl+o++ then ++ctrl+d++, or ++ctrl+a++ then ++d++ | -| Delete entries by query | `atuin search --delete <query>` | -| Delete all history | `atuin search --delete-it-all` | -| Start fresh (with sync) | `atuin account delete` then re-register | -| Remove filtered entries | `atuin history prune` | -| Remove duplicates | `atuin history dedup --before <date> --dupkeep <n>` | -| Delete sync account | `atuin account delete` | diff --git a/docs/docs/guide/dotfiles.md b/docs/docs/guide/dotfiles.md deleted file mode 100644 index d4157cb7..00000000 --- a/docs/docs/guide/dotfiles.md +++ /dev/null @@ -1,141 +0,0 @@ -# Syncing dotfiles - -While Atuin started as a tool for syncing and searching shell history, we are -building tooling for syncing dotfiles across machines, and making them easier -to work with. - -At the moment, we support managing and syncing of shell aliases and environment variables - with more -coming soon. - -The following shells are supported: - -- zsh -- bash -- fish -- xonsh -- powershell - -Note: Atuin handles your configuration internally, so once it is installed you -no longer need to edit your config files manually. - -## Required config - -Once Atuin is set up and installed, the following is required in your config file (`~/.config/atuin/config.toml`) - -``` -[dotfiles] -enabled = true -``` - -In a later release, this will be enabled by default. - -Note: If you have not yet set up sync v2, please also add - -``` -[sync] -records = true -``` - -to the same config file. - -## Usage - -### Aliases - -After creating or deleting an alias, remember to restart your shell! - -#### Creating an alias - -``` -atuin dotfiles alias set NAME 'COMMAND' -``` - -For example, to alias `k` to be `kubectl` - - -``` -atuin dotfiles alias set k 'kubectl' -``` - -or to alias `ll` to be `ls -lah` - -``` -atuin dotfiles alias set ll 'ls -lah' -``` - -#### Deleting an alias - -Deleting an alias is as simple as: - -``` -atuin dotfiles alias delete NAME -``` - -For example, to delete the above alias `k`: - -``` -atuin dotfiles alias delete k -``` - -#### Listing aliases - -You can list all aliases with: - -``` -atuin dotfiles alias list -``` - -### Env vars - -After creating or deleting an env var, remember to restart your shell! - -#### Creating a var - -``` -atuin dotfiles var set NAME 'value' -``` - -For example, to set `FOO` to be `bar` - - -``` -atuin dotfiles var set FOO 'bar' -``` - -Vars are exported by default, but you can create a shell var like so - -``` -atuin dotfiles var set -n foo 'bar' -``` - - -#### Deleting a var - -Deleting a var is as simple as: - -``` -atuin dotfiles var delete NAME -``` - -For example, to delete the above var `FOO`: - -``` -atuin dotfiles var delete FOO -``` - -#### Listing vars - -You can list all vars with: - -``` -atuin dotfiles var list -``` - -### Syncing and backing up dotfiles -If you have [set up sync](sync.md), then running - -``` -atuin sync -``` - -will back up your config to the server and sync it across machines. diff --git a/docs/docs/guide/getting-started.md b/docs/docs/guide/getting-started.md deleted file mode 100644 index 85140b25..00000000 --- a/docs/docs/guide/getting-started.md +++ /dev/null @@ -1,54 +0,0 @@ -# Getting Started - -Atuin replaces your existing shell history with a SQLite database, and records -additional context for your commands. With this context, Atuin gives you faster -and better search of your shell history. - -Additionally, Atuin (optionally) syncs your shell history between all of your -machines. Fully end-to-end encrypted, of course. - -You may use either the server I host, or host your own! Or just don't use sync -at all. As all history sync is encrypted, I couldn't access your data even if I -wanted to. And I **really** don't want to. - -If you have any problems, please open an [issue](https://github.com/ellie/atuin/issues) or get in touch on our [Discord](https://discord.gg/Fq8bJSKPHh)! - -## Supported Shells - -- zsh -- bash -- fish -- nushell -- xonsh -- powershell (tier 2 support) - -## Quickstart - -Please do try and read this guide, but if you're in a hurry and want to get -started quickly: - -``` -bash <(curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh) - -atuin register -u <USERNAME> -e <EMAIL> -atuin import auto -atuin sync -``` - -Now restart your shell! - -Anytime you press ctrl-r or up, you will see the Atuin search UI. Type your -query, enter to execute. If you'd like to select a command without executing -it, press tab. - -You might like to configure an [inline window](../configuration/config.md#inline_height), or [disable up arrow bindings](../configuration/key-binding.md#disable-up-arrow) - -Note: The above sync and registration is fully optional. If you'd like to use Atuin offline, you can run - -``` -bash <(curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh) - -atuin import auto -``` - -Your shell history will be local only, not backed up, and not synchronized across devices. diff --git a/docs/docs/guide/import.md b/docs/docs/guide/import.md deleted file mode 100644 index 3e19b26c..00000000 --- a/docs/docs/guide/import.md +++ /dev/null @@ -1,18 +0,0 @@ -# Import existing history - -Atuin uses a shell plugin to ensure that we capture new shell history. But for -older history, you will need to import it - -This will import the history for your current shell: -``` -atuin import auto -``` - -Alternatively, you can specify the shell like so: - -``` -atuin import bash -atuin import zsh # etc -``` - -Your old shell history file will continue to be updated, regardless of Atuin usage. diff --git a/docs/docs/guide/installation.md b/docs/docs/guide/installation.md deleted file mode 100644 index 7fe69130..00000000 --- a/docs/docs/guide/installation.md +++ /dev/null @@ -1,308 +0,0 @@ -# Installation - -## Recommended installation approach - -### On Unix - -Let's get started! First up, you will want to install Atuin. The recommended -approach is to use the installation script, which automatically handles the -installation of Atuin including the requirements for your environment. - - -It will install a binary to `~/.atuin/bin`, and if you'd rather do something else -then the manual steps below offer much more flexibility. - -```shell -curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh -``` - -The install script will walk you through importing your shell history and setting -up a sync account. To skip these interactive prompts (e.g. in CI or -Dockerfiles), pass `--non-interactive`: - -```shell -curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh -s -- --non-interactive -``` - -The script also automatically detects non-interactive environments (piped input, -no TTY) and skips the prompts in those cases. - -[**Set up sync** - Move on to the next step, or read on to manually install Atuin instead.](sync.md) - -### On Windows - -The recommended approach on Windows is to use WinGet to install Atuin. Then, if you use PowerShell, -add the initialization command to your PowerShell profile, and restart your shell. - -```shell -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 -``` - -Note that the `$PROFILE` path may depend on your PowerShell version. - -[**Set up sync** - Move on to the next step.](sync.md) - -## Manual installation - -### Installing the binary - -If you don't wish to use the installer, the manual installation steps are as follows. - -=== "Cargo" - - It's best to use [rustup](https://rustup.rs/) to set up a Rust - toolchain, then you can run: - - ```shell - cargo install atuin - ``` - -=== "Homebrew" - - ```shell - brew install atuin - ``` - -=== "MacPorts" - - Atuin is also available in [MacPorts](https://ports.macports.org/port/atuin/) - - ```shell - sudo port install atuin - ``` - -=== "mise" - - Atuin is also installable using [mise](https://github.com/jdx/mise) - - ```shell - mise use -g atuin@latest - ``` - -=== "Nix" - - This repository is a flake, and can be installed using `nix profile`: - - ```shell - nix profile install "github:atuinsh/atuin" - ``` - - Atuin is also available in [nixpkgs](https://github.com/NixOS/nixpkgs): - - ```shell - nix-env -f '<nixpkgs>' -iA atuin - ``` - -=== "Pacman" - - Atuin is available in the Arch Linux [extra repository](https://archlinux.org/packages/extra/x86_64/atuin/): - - ```shell - pacman -S atuin - ``` - -=== "XBPS" - - Atuin is available in the Void Linux [repository](https://github.com/void-linux/void-packages/tree/master/srcpkgs/atuin): - - ```shell - sudo xbps-install atuin - ``` - -=== "Termux" - - Atuin is available in the Termux package repository: - - ```shell - pkg install atuin - ``` - -=== "zinit" - - Atuin is installable from github-releases directly: - - ```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 - ``` - -=== "WinGet" - - Atuin is available on WinGet: - - ```shell - winget install -e Atuinsh.Atuin - ``` - -=== "Source" - - Atuin builds on the latest stable version of Rust, and we make no - promises regarding older versions. We recommend using [rustup](https://rustup.rs/). - - ```shell - git clone https://github.com/atuinsh/atuin.git - cd atuin/crates/atuin - cargo install --path . - ``` - -!!! warning "Please be advised" - - If you choose to manually install Atuin rather than using the recommended installation script, - merely installing the binary is not sufficient, you should also set up the shell plugin. - ---- - -### Installing the shell plugin - -Once the binary is installed, the shell plugin requires installing. -If you use the install script, this should all be done for you! -After installing, remember to restart your shell. - -=== "zsh" - - ```shell - echo 'eval "$(atuin init zsh)"' >> ~/.zshrc - ``` - - === "zinit" - - ```shell - # if you _only_ want to install the shell-plugin, do this; otherwise look above for a "everything via zinit" solution - zinit load atuinsh/atuin - ``` - - === "Antigen" - - ```shell - antigen bundle atuinsh/atuin@main - ``` - - === "Antidote" - - ```shell - antidote install atuinsh/atuin - ``` - -=== "bash" - - === "ble.sh" - - Atuin works best in bash when using [ble.sh](https://github.com/akinomyoga/ble.sh) >= 0.4. - - With ble.sh (>= 0.4) installed and loaded in `~/.bashrc`, just add atuin to your `~/.bashrc` - - ```shell - echo 'eval "$(atuin init bash)"' >> ~/.bashrc - ``` - - === "bash-preexec" - - [Bash-preexec](https://github.com/rcaloras/bash-preexec) can also be used, but you may experience - some minor problems with the recorded duration and exit status of some commands. - - !!! warning "Please note" - - bash-preexec currently has an issue where it will stop honoring `ignorespace`. - While Atuin will ignore commands prefixed with whitespace, they may still end up in your bash history. - Please check your configuration! All other shells do not have this issue. - - To use `atuin < 18.10.0` in `bash < 4` with bash-preexec, the option - `enter_accept` needs to be turned on (which is so by default). There is no - restriction in the latest version of Atuin (>= 18.10.0). - - bash-preexec cannot properly invoke the `preexec` hook for subshell commands - `(...)`, function definitions `func() { ...; }`, empty for-in-statements `for - i in; do ...; done`, etc., so those commands and duration may not be recorded - in the Atuin's history correctly. - - To use bash-preexec, download and initialize it - - ```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 - ``` - - Then set up Atuin - - ```shell - echo 'eval "$(atuin init bash)"' >> ~/.bashrc - ``` - -=== "fish" - - Add - - ```shell - atuin init fish | source - ``` - - to your `is-interactive` block in your `~/.config/fish/config.fish` file - -=== "Nushell" - - Run in *Nushell*: - - ```shell - mkdir ~/.local/share/atuin/ - atuin init nu | save ~/.local/share/atuin/init.nu - ``` - - Add to `config.nu`: - - ```shell - source ~/.local/share/atuin/init.nu - ``` - - ??? tip "Optional: Atuin pty-proxy" - pty-proxy is a lightweight pty proxy that renders the Atuin popup over - your previous output, restoring it when closed — no clearing, no - fullscreen. To use pty-proxy with Nushell, generate the init script: - - ```shell - mkdir ~/.local/share/atuin/ - atuin pty-proxy init nu | save -f ~/.local/share/atuin/pty-proxy-init.nu - ``` - - Then source it as early as possible in your `config.nu`, *before* - the regular atuin init: - - ```shell - source ~/.local/share/atuin/pty-proxy-init.nu - source ~/.local/share/atuin/init.nu - ``` - - Nushell's `source` command requires a static file path, so you must - pre-generate both files. - -=== "xonsh" - - Add - ```shell - execx($(atuin init xonsh)) - ``` - to the end of your `~/.xonshrc` - -=== "PowerShell" - - Add the following to the end of your `$PROFILE` file: - - ```shell - atuin init powershell | Out-String | Invoke-Expression - ``` - -## Upgrade - -Run `atuin update`, and if that command is not available, run the install script again. - -If you used a package manager to install Atuin, then you should also use your package manager to update Atuin. - -## Uninstall - -If you'd like to uninstall Atuin, please check out [the uninstall page](../uninstall.md). diff --git a/docs/docs/guide/shell-integration.md b/docs/docs/guide/shell-integration.md deleted file mode 100644 index cc0d2530..00000000 --- a/docs/docs/guide/shell-integration.md +++ /dev/null @@ -1,263 +0,0 @@ -# Shell Integration and Interoperability - -Atuin uses shell hooks to capture your command history. This page explains how the integration works, why Atuin might not record commands in certain environments, and how to control what gets recorded. - -## How Atuin's Shell Integration Works - -When you add `eval "$(atuin init <shell>)"` to your shell configuration, Atuin installs hooks that run at specific points in your shell's command lifecycle: - -1. **Preexec hook**: Runs *before* each command executes. Atuin records the command text, timestamp, and working directory. -2. **Precmd hook**: Runs *after* each command completes. Atuin records the exit code and duration. - -These hooks only activate under specific conditions: - -- The shell must be **interactive** (started with `-i` or inherently interactive) -- Your shell configuration file must be **sourced** (`.bashrc`, `.zshrc`, etc.) -- The `atuin init` command must run during shell startup - -If any of these conditions aren't met, Atuin's hooks won't be installed, and commands won't be recorded. - -### Environment Variables - -When Atuin initializes, it sets several environment variables: - -| Variable | Purpose | -|----------|---------| -| `ATUIN_SESSION` | Unique identifier for this shell session | -| `ATUIN_SHLVL` | Tracks shell nesting level | -| `ATUIN_HISTORY_ID` | Temporary ID for the currently executing command | -| `ATUIN_HISTORY_AUTHOR` | Optional command author identity (for example `ellie`, `claude`, `copilot`) | -| `ATUIN_HISTORY_INTENT` | Optional command intent/rationale text | - -These variables are used internally to track command execution and associate commands with sessions. -If `ATUIN_HISTORY_AUTHOR` is not set, Atuin defaults to the local shell username. - -## Embedded Terminals and IDE Integrations - -Many development tools include embedded terminals: - -- **IDEs**: PyCharm, IntelliJ, VS Code, Cursor, Zed -- **AI coding assistants**: Claude Code, GitHub Copilot CLI, Aider -- **Container environments**: Docker, Podman, devcontainers - -These tools often spawn shells differently than your regular terminal, which can prevent Atuin from working. - -### Why Atuin Might Not Work - -Embedded terminals commonly: - -1. **Start non-interactive shells**: Many tools run commands via `bash -c "command"` or similar, which doesn't trigger shell configuration -2. **Skip shell configuration**: Some tools explicitly avoid sourcing `.bashrc`/`.zshrc` for performance or isolation -3. **Use different shell paths**: The embedded terminal might use a different shell than your default - -You can verify whether Atuin is active by running: - -```shell -atuin doctor -``` - -Look for the `shell.preexec` field in the output. If it shows `none`, Atuin's hooks aren't installed in that shell session. - -### Enabling Atuin in Embedded Terminals - -If you want Atuin to record commands from an embedded terminal, you'll need to ensure it starts an interactive shell that sources your configuration. - -#### IDE Terminal Settings - -Most IDEs let you customize the shell command used for their integrated terminal: - -**PyCharm / IntelliJ:** - -1. Go to Settings → Tools → Terminal -2. Change "Shell path" to include the `-i` flag: - - Linux/macOS: `/bin/bash -i` or `/bin/zsh -i` - - Or create a wrapper script (see below) - -**VS Code:** - -Add to your `settings.json` (substitute the shells for whatever you use): - -```json -{ - "terminal.integrated.profiles.linux": { - "bash": { - "path": "/bin/bash", - "args": ["-i"] - } - }, - "terminal.integrated.profiles.osx": { - "zsh": { - "path": "/bin/zsh", - "args": ["-i"] - } - } -} -``` - -#### Wrapper Script Approach - -For tools that don't easily support shell arguments, create a wrapper script: - -```shell -#!/bin/bash -# Save as ~/bin/interactive-bash.sh and chmod +x -exec /bin/bash -i "$@" -``` - -Then configure your IDE to use `~/bin/interactive-bash.sh` as the shell path. - -#### Verifying the Fix - -After configuring, open a new terminal in your IDE and run: - -```shell -atuin doctor | grep preexec -``` - -You should see `built-in`, `bash-preexec`, `blesh`, or similar—not `none`. - -## Excluding Commands from History - -Sometimes you *don't* want certain commands in your history. This is common when: - -- AI coding tools run many automated commands (git status, file listings, etc.) -- You're running sensitive commands you don't want synced -- Build tools or scripts generate repetitive command noise - -### Using history_filter - -The `history_filter` option in `~/.config/atuin/config.toml` lets you exclude commands matching specific patterns: - -```toml -history_filter = [ - "^ls$", # Exclude bare 'ls' commands - "^cd ", # Exclude cd commands - "^cat ", # Exclude cat commands -] -``` - -Patterns are regular expressions. They're unanchored by default, so `secret` matches anywhere in a command. Use `^` and `$` for exact matching. - -### Using cwd_filter - -To exclude all commands run from specific directories: - -```toml -cwd_filter = [ - "^/tmp", # Exclude commands run from /tmp - "/node_modules/", # Exclude commands from any node_modules - "^/home/user/scratch", # Exclude a scratch directory -] -``` - -### Prefix with Space (ignorespace) - -Most shells support "ignorespace"—commands prefixed with a space aren't saved to history. Atuin honors this convention: - -```shell - echo "this won't be saved" # Note the leading space -``` - -!!! warning "Bash with bash-preexec" - When using bash-preexec (not ble.sh), there's a known issue where ignorespace isn't fully honored. The command won't appear in Atuin, but may still appear in your bash history. See [installation](installation.md) for details. - -### Disabling Atuin for Specific Tools - -If a tool spawns interactive shells but you don't want its commands recorded, you have several options: - -#### Option 1: Environment Variable Check - -Modify your shell configuration to skip Atuin initialization based on an environment variable: - -```shell -# In .bashrc or .zshrc -if [[ -z "${MY_TOOL_SESSION}" ]]; then - eval "$(atuin init bash)" -fi -``` - -Then configure your tool to set `MY_TOOL_SESSION=1` when spawning shells. - -#### Option 2: Use history_filter for Tool-Specific Patterns - -If the tool runs predictable commands, filter them: - -```toml -history_filter = [ - "^git status$", - "^git diff", - "^ls -la$", -] -``` - -#### Option 3: Filter by Directory - -If the tool operates in specific directories: - -```toml -cwd_filter = [ - "^/path/to/tool/workspace", -] -``` - -### Cleaning Up Existing History - -After adding filters, you can remove matching entries from your existing history: - -```shell -atuin history prune -``` - -This removes entries that match your current `history_filter` or `cwd_filter` patterns. - -## Shell-Specific Notes - -### Bash - -Atuin supports two preexec backends for Bash: - -- **ble.sh** (recommended): Full-featured line editor with accurate timing and proper ignorespace support -- **bash-preexec**: Simpler but has some limitations with subshells and ignorespace - -The shell integration explicitly checks for interactive mode: - -```bash -if [[ $- != *i* ]]; then - # Not interactive, skip initialization - return -fi -``` - -### Zsh - -Zsh has native hook support via `add-zsh-hook`. The integration is straightforward and works reliably in interactive sessions. - -### Fish - -Fish uses its event system (`fish_preexec` and `fish_postexec` events). It also respects Fish's private mode—commands run with `fish --private` aren't recorded. - -## Troubleshooting - -### Commands aren't being recorded - -1. Run `atuin doctor` and check the output -2. Verify `shell.preexec` is not `none` -3. Ensure your shell is interactive (`echo $-` should contain `i`) -4. Check that `atuin init` is in your shell config and being sourced - -### Commands from a specific tool aren't recorded - -1. Check if the tool starts an interactive shell -2. Try configuring the tool to use `bash -i` or `zsh -i` -3. Use a wrapper script if the tool doesn't support shell arguments - -### Too many commands are being recorded - -1. Add patterns to `history_filter` in your config -2. Use `cwd_filter` for directory-based exclusion -3. Prefix sensitive commands with a space -4. Run `atuin history prune` to clean existing entries - -### Atuin works in terminal but not in IDE - -This is the most common issue. The IDE's embedded terminal likely isn't starting an interactive shell. See [Enabling Atuin in Embedded Terminals](#enabling-atuin-in-embedded-terminals) above. diff --git a/docs/docs/guide/sync.md b/docs/docs/guide/sync.md deleted file mode 100644 index 070d8178..00000000 --- a/docs/docs/guide/sync.md +++ /dev/null @@ -1,78 +0,0 @@ -# Setting up Sync - -At this point, you have Atuin storing and searching your shell history! But it -isn't syncing it just yet. To do so, you'll need to register with the sync -server. All of your history is fully end-to-end encrypted, so there are no -risks of the server snooping on you. - -If you don't have an account, please [register](#register). If you have already registered, -proceed to [login](#login). - -**Note:** You first have to set up your `sync_address` if you want to use a [self hosted server](../self-hosting/server-setup.md). - -## Register - -``` -atuin register -u <YOUR_USERNAME> -e <YOUR EMAIL> -``` - -After registration, Atuin will generate an encryption key for you and store it -locally. This is needed for logging in to other machines, and can be seen with - -``` -atuin key -``` - -Please **never** share this key with anyone! The Atuin developers will never -ask you for your key, your password, or the contents of your Atuin directory. - -If you lose your key, we can do nothing to help you. We recommend you store -this somewhere safe, such as in a password manager. - -## First sync -By default, Atuin will sync your history once per hour. This can be -[configured](../configuration/config.md#sync_frequency). - -To run a sync manually, please run - -``` -atuin sync -``` - -Atuin tries to be smart with a sync, and not waste data transfer. However, if -you are seeing some missing data, please try running - -``` -atuin sync -f -``` - -This triggers a full sync, which may take longer as it works through historical data. - -## Login - -When only signed in on one machine, Atuin sync operates as a backup. This is -pretty useful by itself, but syncing multiple machines is where the magic -happens. - -First, ensure you are [registered with the sync server](#register) and make a -note of your key. You can see this with `atuin key`. - -Then, install Atuin on a new machine. Once installed, login with - -``` -atuin login -u <USERNAME> -``` - -You will be prompted for your password, and for your key. - -Syncing will happen automatically in the background, but you may wish to run it manually with - -``` -atuin sync -``` - -Or, if you see missing data, force a full sync with: - -``` -atuin sync -f -``` diff --git a/docs/docs/guide/theming.md b/docs/docs/guide/theming.md deleted file mode 100644 index 2d71d41d..00000000 --- a/docs/docs/guide/theming.md +++ /dev/null @@ -1,138 +0,0 @@ -# Theming - -Available in Atuin >= 18.4 - -For terminal interface customization, Atuin supports user and built-in color themes. - -Atuin ships with only a couple of built-in alternative themes, but more can be added via TOML files. - -## Required config - -The following is required in your config file (`~/.config/atuin/config.toml`) - -``` -[theme] -name = "THEMENAME" -``` - -Where `THEMENAME` is a known theme. The following themes are available out-of-the-box: - -* `default` theme -* `autumn` theme -* `marine` theme -* `(none)` theme (removes all styling) - -These are present to ensure users and developers can try out theming, but in general, you -will need to download themes or make your own. - -If you are writing your own themes, you can add the following line to get additional output: - -``` -debug = true -``` - -to the same config block. This will print out any color names that cannot be parsed from -the requested theme. - -A final optional setting is available: - -``` -max_depth: 10 -``` - -which sets the maximum levels of theme parents to traverse. This should not need to be -explicitly added in normal use. - -## Usage - -### Theme structure - -Themes are maps from *Meanings*, describing the developer's intentions, -to (at present) colors. In future, this may be expanded to allow richer style support. - -*Meanings* are from an enum with the following values: - -* `AlertInfo`: alerting the user at an INFO level -* `AlertWarn`: alerting the user at a WARN level -* `AlertError`: alerting the user at an ERROR level -* `Annotation`: less-critical, supporting text -* `Base`: default foreground color -* `Guidance`: instructing the user as help or context -* `Important`: drawing the user's attention to information -* `Title`: titling a section or view -* `Muted`: anodyne, usually grey, foreground for contrast with other colors. Normally equivalent to the base color, but allows themes to change the base color, with less risk of breaking intentional color contrasts (e.g. stacked bar charts) - -These may expand over time as they are added to Atuin's codebase, but Atuin -should have fallbacks added for any new *Meanings* so that, whether themes limit to -the present list or take advantage of new *Meanings* in future, they should -keep working sensibly. - -**Note for Atuin contributors**: please do identify and, where appropriate during your own -PRs, extend the Meanings enum if needed (along with a fallback Meaning!). - -### Theme creation - -When a theme name is read but not yet loaded, Atuin will look for it in the folder -`~/.config/atuin/themes/` unless overridden by the `ATUIN_THEME_DIR` environment -variable. It will attempt to open a file of name `THEMENAME.toml` and read it as a -map from *Meanings* to foreground colors. - -Note that, at present, it is not possible to specify the default terminal color explicitly -in a theme file. However, the default theme Base color will always be unset and therefore -will be the user's default terminal color. Hence, you should only override the Base color -in your theme, or derive from a theme that does so, if your theme would not make sense -otherwise (e.g. the `marine` theme is intended to make everything green/blue, so it does, -but the `autumn` theme only seeks to make the custom colors warmer, so it does not). - -Colors may be specified either as names from the [palette](https://ogeon.github.io/docs/palette/master/palette/named/index.html) -crate in lowercase, or as six-character hex codes, prefixed with `#`. To explicitly select ANSI colors by integer, or for greater flexibility in general, you can prefix with `@` and the rest of the string will be handled by crossterm's color parsing. For examples, see [crossterm's color deserialization tests](https://github.com/crossterm-rs/crossterm/blob/5d50d8da62c5e034ef8b2787a771a2c0f9b3b2f9/src/style/types/color.rs#L389), remembering the need to add a `@` prefix for atuin. - -For example, the following are valid color names: - -* `#ff0088` -* `teal` -* `powderblue` -* `@ansi_(255)` -* `@rgb_(255, 128, 0)` - -You can also express colors through Crossterm-supported strings, prefixed by `@`. -For example, - -* `@ansi_(123)` -* `@dark_yellow` - -While there is not currently an official reference, you can see examples in the -[crossterm tests](https://docs.rs/crossterm/latest/src/crossterm/style/types/color.rs.html#376). -As this is passed straight to Crossterm, using [ANSI codes](https://www.ditig.com/256-colors-cheat-sheet) -can be helpful for ensuring your theme is compatible with 256-color terminals. - -A theme file, say `my-theme.toml` can then be built up, such as: - -```toml -[theme] -name = "my-theme" -parent = "autumn" - -[colors] -AlertInfo = "green" -Guidance = "#888844" - -``` - -where not all of the *Meanings* need to be explicitly defined. If they are absent, -then the color will be chosen from the parent theme, if one is defined, or if that -key is missing in the `theme` block, from the `default` theme. - -If the entire named theme is missing, which is inherently an error, then the theme -will drop to `(none)` and leave Atuin unstyled, rather than trying to fallback to -the any default, or other, theme. - -This theme file should be moved to `~/.config/atuin/themes/my-theme.toml` and the -following added to `~/.config/atuin/config.toml`: - -``` -[theme] -name = "my-theme" -``` - -When you next run Atuin, your theme should be applied. |