From 916b9cc647ecc7290e05c73d40202d361c0046d6 Mon Sep 17 00:00:00 2001
From: Xavier Ruiz <github@xav.ie>
Date: Mon, 23 Mar 2026 00:06:28 -0400
Subject: feat: hex init nu (#3330)

- **feat(hex): add nushell support for `atuin hex init`**
- **docs(hex): add nushell hex setup instructions**

This adds setup for nushell. It breaks the pattern of calling `eval
$(atuin init)` on behalf of the user because nushell simply cannot do
this. I tried to source the atuin.nu file and add the preamble to it,
but it is part of the atuin package, so it made things too difficult.

I think settling for separate init is ok.

Partially addresses #3329.

Please see #3323 as well.

I was able to get it working and I am using these changes in my
dotfiles:

https://github.com/xav-ie/dots/compare/b1a8cf96b58f802396ac5103f0925e1434fc473c...696dbf31008395587353e3071f5296c459685a17

Basically, I just do as the new docs say and make sure to add hex init
before regular init and source it.

<!-- Thank you for making a PR! Bug fixes are always welcome, but if
you're adding a new feature or changing an existing one, we'd really
appreciate if you open an issue, post on the forum, or drop in on
Discord -->

## Checks

- [x] I am happy for maintainers to push small adjustments to this PR,
to speed up the review cycle
- [x] I have checked that there are no existing pull requests for the
same thing
---
 docs/docs/guide/installation.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'docs')

diff --git a/docs/docs/guide/installation.md b/docs/docs/guide/installation.md
index 193b9ffa..d17a508b 100644
--- a/docs/docs/guide/installation.md
+++ b/docs/docs/guide/installation.md
@@ -260,6 +260,27 @@ After installing, remember to restart your shell.
     source ~/.local/share/atuin/init.nu
     ```
 
+    ??? tip "Optional: Atuin Hex"
+        Hex is a lightweight pty proxy that renders the Atuin popup over
+        your previous output, restoring it when closed — no clearing, no
+        fullscreen. To use Hex with Nushell, generate the init script:
+
+        ```shell
+        mkdir ~/.local/share/atuin/
+        atuin hex init nu | save -f ~/.local/share/atuin/hex-init.nu
+        ```
+
+        Then source it as early as possible in your `config.nu`, *before*
+        the regular atuin init:
+
+        ```shell
+        source ~/.local/share/atuin/hex-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
-- 
cgit v1.3.1