From 640beb344dd469651f918a0a2ea04fbcb5690c56 Mon Sep 17 00:00:00 2001
From: Michelle Tilley <michelle@michelletilley.net>
Date: Mon, 23 Mar 2026 15:12:02 -0700
Subject: fix: Don't run 'atuin init' in 'atuin hex init' — each must be
 initialized separately (#3334)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/docs/reference/hex.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/mkdocs.yml            |  1 +
 2 files changed, 66 insertions(+)
 create mode 100644 docs/docs/reference/hex.md

(limited to 'docs')

diff --git a/docs/docs/reference/hex.md b/docs/docs/reference/hex.md
new file mode 100644
index 00000000..1bbf9336
--- /dev/null
+++ b/docs/docs/reference/hex.md
@@ -0,0 +1,65 @@
+# hex
+
+Atuin Hex is an experimental lightweight PTY proxy, providing new features without needing to replace your existing terminal or shell. Atuin Hex currently supports bash, zsh, fish, and nu.
+
+## TUI Rendering
+
+The search TUI exposes a tradeoff: the UI is either in fullscreen alt-screen mode that takes over your terminal, or inline mode that clears your previous output. Neither is great.
+
+With Hex, we can have our cake AND eat it too. The Atuin popup renders over the top of your previous output, but when it's closed we can restore the output successfully.
+
+## Initialization
+
+Atuin Hex needs to be initialized separately from your existing Atuin config. Place the init line shown below in your shell's init script, as high in the document as possible, *before* your normal `atuin init` call.
+
+=== "zsh"
+
+    ```shell
+    eval "$(atuin hex init zsh)"
+    ```
+
+=== "bash"
+
+    ```shell
+    eval "$(atuin hex init bash)"
+    ```
+
+=== "fish"
+
+    Add
+
+    ```shell
+    atuin hex 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 hex init nu | save -f ~/.local/share/atuin/hex-init.nu
+    ```
+
+    Add to `config.nu`, **before** the regular `atuin init`:
+
+    ```shell
+    source ~/.local/share/atuin/hex-init.nu
+    ```
+    Nushell's `source` command requires a static file path, so you must
+    pre-generate the file.
+
+---
+
+If the `atuin` binary is not in your `PATH` by default, you should initialize Hex as soon as it is set. For example, for a bash user with Atuin installed in `~/.atuin/bin/atuin`, a config file might look like this:
+
+```bash
+export PATH=$HOME/.atuin/bin:$PATH
+eval "$(atuin hex init bash)"
+
+# ... other shell configuration ...
+
+eval "$(atuin init bash)"
+```
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 0c2445be..3a06643d 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -81,6 +81,7 @@ nav:
       - doctor: reference/doctor.md
       - daemon: reference/daemon.md
       - gen-completions: reference/gen-completions.md
+      - hex: reference/hex.md
       - import: reference/import.md
       - info: reference/info.md
       - history list: reference/list.md
-- 
cgit v1.3.1