---
name: nushell
which: nu
description: "Use when writing, debugging, or modernizing Nu code/config, or translating shell commands to Nushell."
license: MIT
---

# Nushell

Target installed Nu, not memory. Keep Nu guidance here; follow project instructions for Mise and OS boundaries.

## Source of truth

- Probe isolated: `nu --no-config-file -c '<probe>'`.
- Ask installed Nu: `help <command>`, `help --find <term>`, `scope commands`.
- For migrations, follow [Modernize](references/modernize.md): local help → release notes → isolated probes.
- Use the [Nu book](https://www.nushell.sh/book/), especially [Coming from Bash](https://www.nushell.sh/book/coming_from_bash.html), and [release notes](https://www.nushell.sh/blog/).

Never dump `$env`, source secrets, or run real login startup merely to check syntax.

## Code

- Pipelines carry typed values; external programs exchange byte streams.
- Guard optional values before filesystem commands.
- `which` may return nothing: check before `get 0.path`.
- Use `^cmd ...$args` for external commands.
- Use [Bash → Nu](https://www.nushell.sh/book/coming_from_bash.html), not Bash intuition:

  | Bash | Nu |
  | --- | --- |
  | `cmd1 && cmd2` | `cmd1; cmd2` |
  | `> file` | `o> file` or `| save file` |
  | `> /dev/null` | `| ignore` |
  | `> /dev/null 2>&1` | `o+e>| ignore` |
  | `$(cmd)` | `(cmd)`; inside strings `$"(cmd)"` |

  `$"some text(s)"` runs `s`; escape literal parentheses (`\(`, `\)`) or use a plain string.
- Use `save` for pipeline values; `o+e> file` for external output to a file; `o+e>| filter` for combined output.

Optional CLI:

- Detect the feature first; resolve the executable at invocation time.
- Check lookup before extracting its path; reuse that resolution for the operation.
- Prompt/status with no executable → explicit degraded output, no spawn.
- Explicit user action with no executable → actionable error, never fake success.
- Test present/absent states with identical triggering metadata; hide only the target executable where possible.

## Details

- [External process handling](references/external-processes.md)
- [Configuration and scripts](references/configuration.md)

## Verify

Read the target and imports first. For reviewed, non-secret code:

```sh
node scripts/check.mjs /absolute/path/to/file.nu
npm test
```

The helper checks Nu version and IDE diagnostics; it does not run the script and a pass does not prove runtime correctness or absence of deprecations. Exercise positive/negative behavior in isolated temporary fixtures: present/absent tools, exit codes, data shape, empty/missing input, and startup mode. Never execute a mutating script merely to validate it.