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
---
 crates/atuin-hex/src/lib.rs     | 32 +++++++++++++++++++++++++++++++-
 docs/docs/guide/installation.md | 21 +++++++++++++++++++++
 2 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/crates/atuin-hex/src/lib.rs b/crates/atuin-hex/src/lib.rs
index ff37cfe3..b08da631 100644
--- a/crates/atuin-hex/src/lib.rs
+++ b/crates/atuin-hex/src/lib.rs
@@ -25,6 +25,8 @@ enum Shell {
     Bash,
     /// Fish setup
     Fish,
+    /// Nu setup
+    Nu,
 }
 
 impl Shell {
@@ -33,6 +35,7 @@ impl Shell {
             Self::Bash => "bash",
             Self::Zsh => "zsh",
             Self::Fish => "fish",
+            Self::Nu => "nu",
         }
     }
 }
@@ -76,7 +79,7 @@ fn detect_shell(cli_shell: Option<Shell>) -> Result<Shell, String> {
     }
 
     Err(
-        "could not detect a supported shell. Please specify one explicitly: bash, zsh, or fish"
+        "could not detect a supported shell. Please specify one explicitly: bash, zsh, fish, or nu"
             .to_string(),
     )
 }
@@ -94,6 +97,7 @@ fn shell_from_name(name: &str) -> Option<Shell> {
         "bash" => Some(Shell::Bash),
         "zsh" => Some(Shell::Zsh),
         "fish" => Some(Shell::Fish),
+        "nu" => Some(Shell::Nu),
         _ => None,
     }
 }
@@ -149,6 +153,21 @@ end
 {init_command} | source
 "#
         ),
+        // Nushell cannot dynamically source the output of `atuin init nu`,
+        // so we only output the hex preamble here. Users must also set up
+        // `atuin init nu` separately.
+        Shell::Nu => r#"if (is-terminal --stdin) and (is-terminal --stdout) {
+    let tmux_current = ($env.TMUX? | default "")
+    let tmux_previous = ($env.ATUIN_HEX_TMUX? | default "")
+
+    if ($env.ATUIN_HEX_ACTIVE? | default "" | is-empty) or ($tmux_current != $tmux_previous) {
+        $env.ATUIN_HEX_ACTIVE = "1"
+        $env.ATUIN_HEX_TMUX = $tmux_current
+        exec atuin hex
+    }
+}
+"#
+        .to_string(),
     }
 }
 
@@ -440,6 +459,7 @@ mod tests {
         assert_eq!(shell_from_name("/bin/zsh"), Some(Shell::Zsh));
         assert_eq!(shell_from_name("/usr/local/bin/bash"), Some(Shell::Bash));
         assert_eq!(shell_from_name("fish"), Some(Shell::Fish));
+        assert_eq!(shell_from_name("nu"), Some(Shell::Nu));
     }
 
     #[test]
@@ -462,4 +482,14 @@ mod tests {
         assert!(script.contains("exec atuin hex"));
         assert!(script.contains("atuin init fish | source"));
     }
+
+    #[test]
+    fn nu_init_uses_exec_and_tty_guard() {
+        let script = render_init(Shell::Nu);
+        assert!(script.contains("exec atuin hex"));
+        assert!(script.contains("ATUIN_HEX_TMUX"));
+        assert!(script.contains("is-terminal --stdin"));
+        assert!(script.contains("is-terminal --stdout"));
+        assert!(script.contains("ATUIN_HEX_ACTIVE"));
+    }
 }
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