nushell-pro

name: nushell-pro description: | Comprehensive Nushell scripting best practices, idioms, security, and code review. Use when writing, reviewing, auditing, or refactoring Nushell (.nu) scripts to ensure they follow idiomatic patterns, naming conventions, proper type annotations, functional style, security best practices, and Nushell's unique design principles. Triggers on tasks involving Nushell scripts, modules, custom commands, pipelines, or any .nu file editing. Also helps convert Bash/POSIX scripts to idiomatic Nushell. Covers the type system, data manipulation, performance optimization, security hardening, script review, and common gotchas.

Nushell Pro — Best Practices & Security Skill

Write idiomatic, performant, secure, and maintainable Nushell scripts. This skill enforces Nushell conventions, catches security issues, and helps avoid common pitfalls.

Operating Workflow

Use this sequence whenever writing, reviewing, refactoring, or converting Nushell code:

1. Identify the task type: new script, code review, refactor, Bash conversion, module design, security audit, or debugging.
2. Read the existing .nu files and nearby project conventions before changing code.
3. Load only the reference files needed for the task:
   • String quoting, interpolation, escaping, regex, or globs -> String Formats
   • Security, untrusted input, external commands, paths, credentials, or destructive operations -> Security
   • Review-only requests -> Script Review
   • Bash/POSIX conversion -> Bash to Nushell
   • Modules, exports, scripts, or tests -> Modules & Scripts
   • Types, records, tables, lists, or conversions -> Data & Type System
   • Streaming, peek, parse, par-each, performance, closures, or version-sensitive command behavior -> Advanced Patterns
   • Large datasets, Polars dataframes, columnar analytics, heavy group-by/join -> Dataframes
   • Common mistakes and fixes -> Anti-Patterns
4. Apply the critical checks in this file first, then use references for details.
5. Validate parseability with nu -c 'source path/to/file.nu' for modules or nu path/to/script.nu for scripts when the command is safe to run.
6. Summarize security findings first, then correctness/style/performance changes.

If validation fails -> read the Nushell diagnostic, fix the syntax or type signature, and rerun the smallest safe validation command. If a command has side effects -> validate only parseability or use a fixture/temp directory. If a reference conflicts with local project style -> keep project style unless it violates safety, parseability, or Nushell semantics.

STOP CHECKPOINT: Before approving code that runs external commands, deletes files, reads credentials, mutates $env, or executes user-provided paths/patterns, explicitly confirm the safe argument boundaries and failure behavior.

Core Principles

1. Think in pipelines — Data flows through pipelines; prefer functional transformations over imperative loops
2. Immutability first — Use let by default; only use mut when functional alternatives don't apply
3. Structured data — Nushell works with tables, records, and lists natively; leverage structured data over string parsing
4. Static parsing — All code is parsed before execution; source/use require parse-time constants
5. Implicit return — The last expression's value is the return value; no need for echo or return
6. Scoped environment — Environment changes are local to their block; use def --env when caller-side changes are needed
7. Type safety — Annotate parameter types and input/output signatures for better error detection and documentation
8. Prefer match for branching — Use match instead of long if/else if chains when dispatching on one value or handling many branches
9. Parallel ready — Immutable code enables easy par-each parallelization

Critical: Pipeline Input vs Parameters

Pipeline input ($in) is NOT interchangeable with function parameters!

# WRONG — treats pipeline data as first parameter
def my-func [items: list, value: any] {
    $items | append $value
}

# CORRECT — declares pipeline signature
def my-func [value: any]: list -> list {
    $in | append $value
}

# Usage
[1 2 3] | my-func 4  # Works correctly

Why this matters:

• Pipeline input can be lazily evaluated (streaming)
• Parameters are eagerly evaluated (loaded into memory)
• Different calling conventions entirely — $list | func arg vs func $list arg

Type signature forms

def func [x: int] { ... }                    # params only
def func []: string -> int { ... }           # pipeline only
def func [x: int]: string -> int { ... }     # both pipeline and params
def func []: [list -> list, string -> list] { ... }  # multiple I/O types

Naming Conventions

• Prefer full words over abbreviations unless widely known (url ok, usr not ok)
• Flag variable access replaces dashes with underscores: --all-caps -> $all_caps

Formatting Rules

One-line format (default for short expressions)

[1 2 3] | each {|x| $x * 2 }
{name: 'Alice', age: 30}

Multi-line format (scripts, >80 chars, nested structures)

[1 2 3 4] | each {|x|
    $x * 2
}

[
    {name: 'Alice', age: 30}
    {name: 'Bob', age: 25}
]

Spacing rules

• One space before and after |
• No space before |params| in closures: {|x| ...} not { |x| ...}
• One space after : in records: {x: 1} not {x:1}
• Omit commas in lists: [1 2 3] not [1, 2, 3]
• No trailing spaces
• One space after , when used (closure params, etc.)

Custom Commands Best Practices

Type annotations and I/O signatures

# Fully typed with I/O signature
def add-prefix [text: string, --prefix (-p): string = 'INFO']: nothing -> string {
    $'($prefix): ($text)'
}

# Multiple I/O signatures
def to-list []: [
    list -> list
    string -> list
] {
    # implementation
}

Documentation with comments and attributes

# Fetch user data from the API
#
# Retrieves user information by ID and returns
# a structured record with all available fields.
@example 'Fetch user by ID' { fetch-user 42 }
@category 'network'
def fetch-user [
    id: int           # The user's unique identifier
    --verbose (-v)    # Show detailed request info
]: nothing -> record {
    # implementation
}

Parameter guidelines

• Maximum 2 positional parameters; use flags for the rest
• Provide both long and short flag names: --output (-o): string
• Use default values: def greet [name: string = 'World']
• Use ? for optional positional params: def greet [name?: string]
• Use rest params for variadic input: def multi-greet [...names: string]
• Use def --wrapped to wrap external commands and forward unknown flags

Calling commands with named flags

Keep short custom command calls with named flags on one line. If the invocation must span lines, wrap the whole command in parentheses so the continuation is explicit. A bare newline can terminate the command, leaving following --flags as separate statements that produce plain output or parse errors.

# Prefer for short calls
build-report $target --format json --strict

# Good — explicit multiline invocation
let report = (
    build-report $target
        --format json
        --strict
)

# Bad — flags start new statements
build-report $target
--format json
--strict

Environment-modifying commands

def --env setup-project [] {
    cd project-dir
    $env.PROJECT_ROOT = (pwd)
}

Data Manipulation Patterns

Working with records

{name: 'Alice', age: 30}          # Create record
$rec1 | merge $rec2                # Merge (right-biased)
[$r1 $r2 $r3] | into record       # Merge many records
$rec | update name {|r| $'Dr. ($r.name)' }  # Update field
$rec | insert active true          # Insert field
$rec | upsert count {|r| ($r.count? | default 0) + 1 }  # Update or insert
$rec | reject password secret_key  # Remove fields
$rec | select name age email       # Keep only these fields
$rec | items {|k, v| $'($k): ($v)' }  # Iterate key-value pairs
$rec | transpose key val           # Convert to table

Working with tables

$table | where age > 25                          # Filter rows
$table | insert retired {|row| $row.age > 65 }   # Add column
$table | rename -c {age: years}                   # Rename column
$table | group-by status --to-table               # Group by field
$table | transpose name data                      # Transpose rows/columns
$table | join $other_table user_id                 # Inner join
$table | join --left $other user_id                # Left join

Working with lists

$list | enumerate | where {|e| $e.index > 5 }     # Filter with index
$list | reduce --fold 0 {|it, acc| $acc + $it }   # Accumulate
$list | window 3                                   # Sliding window
$list | chunks 100                                 # Process in batches
$list | flatten                                    # Flatten nested lists

Null safety

$record.field?                    # Returns null if missing (no error)
$record.field? | default 'N/A'   # Provide fallback
if ($record.field? != null) { }   # Check existence
$list | default -e $fallback      # Default for empty collections

default's argument is eager: $x | default $rec.maybe_missing evaluates (and can error on) the fallback even when $x is non-null. Make the fallback null-safe (default ($rec.maybe? | default 0)) or branch with if. See Anti-Patterns.

Large data: Polars dataframes

Native list/table ops are row-oriented — ideal for small, interactive data. For large datasets and heavy analytics (multi-million row group-by, joins, aggregations, big CSV/Parquet), push the work into the polars plugin's columnar dataframes instead of each/reduce. They are lazy by default.

# For large data, let Polars plan and execute the whole pipeline:
polars open big.csv                       # lazy by default (a plan, not yet run)
| polars group-by category
| polars agg (polars col amount | polars sum | polars as total)
| polars sort-by total -r [true]
| polars collect                          # execute the optimized plan once

Choose native vs Polars (and eager vs lazy), and see the full command set, in Dataframes.

Pipeline & Functional Patterns

Prefer functional over imperative

# Bad — imperative with mutable variable
mut total = 0
for item in $items { $total += $item.price }

# Good — functional pipeline
$items | get price | math sum

# Bad — mutable counter
mut i = 0
for file in (ls) { print $'($i): ($file.name)'; $i += 1 }

# Good — enumerate
ls | enumerate | each {|it| $'($it.index): ($it.item.name)' }

Iteration patterns

# each: transform each element
$list | each {|item| $item * 2 }

# each --flatten: stream outputs (turns list<list<T>> into list<T>)
ls *.txt | each --flatten {|f| open $f.name | lines } | find 'TODO'

# each --keep-empty: preserve null results
[1 2 3] | each --keep-empty {|e| if $e == 2 { 'found' } }

# par-each: parallel processing (I/O or CPU-bound)
$urls | par-each {|url| http get $url }
$urls | par-each --threads 4 {|url| http get $url }

# reduce: accumulate (first element is initial acc if no --fold)
[1 2 3 4] | reduce {|it, acc| $acc + $it }

# generate: create values from arbitrary sources without mut
generate {|state| { out: ($state * 2), next: ($state + 1) } } 1 | first 5

Row conditions vs closures

# Row conditions — short-hand syntax, auto-expands $it
ls | where type == file              # Simple and readable
$table | where size > 100            # Expands to: $it.size > 100

# Closures — full flexibility, can be stored and reused
let big_files = {|row| $row.size > 1mb }
ls | where $big_files
$list | where {$in > 10}             # Use $in or parameter

Use row conditions for simple field comparisons; use closures for complex logic or reusable conditions.

Branching with match

Nushell's match is a parser keyword: match <value> <match_block>. Prefer it over if/else if chains when multiple branches depend on the same value, such as status dispatch, command routing, type guards, or enum-like options. Use if for a single boolean condition or when each branch has a different predicate.

# Less clear — repeated checks against the same value
if $status == 'ok' {
    handle-ok
} else if $status == 'error' {
    handle-error
} else if $status == 'pending' {
    handle-pending
} else {
    handle-unknown
}

# Preferred — one dispatch expression with an explicit fallback
match $status {
    ok => { handle-ok }
    error => { handle-error }
    pending => { handle-pending }
    _ => { handle-unknown }
}

Pipeline input with $in

def double-all []: list<int> -> list<int> {
    $in | each {|x| $x * 2 }
}

# Capture $in early when needed later (it's consumed on first use)
def process []: table -> table {
    let input = $in
    let count = $input | length
    $input | first ($count // 2)
}

Variable Best Practices

Prefer immutability

let config = (open config.toml)
let names = $config.users | get name

# Acceptable — mut when no functional alternative
mut retries = 0
loop {
    if (try-connect) { break }
    $retries += 1
    if $retries >= 3 { error make {msg: 'Connection failed'} }
    sleep 1sec
}

Constants for parse-time values

const lib_path = 'src/lib.nu'
source $lib_path                  # Works: const is resolved at parse time

let lib_path = 'src/lib.nu'
source $lib_path                  # Error: let is runtime only

Closures cannot capture mut

mut count = 0
ls | each {|f| $count += 1 }     # Error! Closures can't capture mut

# Solutions:
ls | length                       # Use built-in commands
[1 2 3] | reduce {|x, acc| $acc + $x }  # Use reduce
for f in (ls) { $count += 1 }    # Use a loop if mutation truly needed

String Conventions

Refer to String Formats Reference for the full priority and rules.

String form mistakes are common and high impact. Decide with this table before writing or reviewing any string:

Decision order:

1. Bare words in arrays: [foo bar baz]
2. Raw strings for regex: r#'(?:pattern)'#
3. Single quotes: 'simple string'
4. Single-quoted interpolation: $'Hello, ($name)!'
5. Backticks for path/glob arguments containing spaces: `./My Dir/*.nu`
6. Double quotes only for real escapes: "line1\nline2"
7. Double-quoted interpolation only when both interpolation and escapes are required: $"tab:\t($value)\n"

Non-negotiable string rules:

• $'...' and '...' do not process escapes. \n, \t, and \' remain literal characters.
• A string containing (...) only evaluates it when prefixed with $: $'(ansi g)OK(ansi rst)', not '(ansi g)OK(ansi rst)'.
• Use char nl inside $'...' when interpolation is needed but the only escape-like value is a newline: $'(char nl)Done'.
• Use $"..." only when the final string truly needs escape processing and interpolation in the same literal.
• Do not build shell command strings for execution. Pass arguments separately: ^git commit -m $msg, not ^sh -c $'git commit -m "($msg)"'.
• For external command format strings, prefer double-quoted strings with a single escape backslash for simple escapes (^git log --format="%H\t%an"). Do not double the backslash ("%H\\t%an"), because that produces a literal \t. Use (char tab) / (char nl) when interpolation is needed or explicit separators are clearer.
• For regex literals, prefer raw strings and add # delimiters when the pattern contains quotes: r#'name="[^"]+"'#.

Common corrections:

# Wrong: interpolation is missing because there is no $ prefix
print 'User: ($name)'
# Right
print $'User: ($name)'

# Wrong: $'...' does not turn \n into a newline
print $'Done\n'
# Right: command interpolation, no escape processing needed
print $'Done(char nl)'
# Right: escape processing is required
print $"Done\n"

# Wrong: double-quoted interpolation without escapes
let label = $"($pkg.name)@($pkg.version)"
# Right
let label = $'($pkg.name)@($pkg.version)'

# Wrong: regex backslashes are hard to audit
let pattern = "(?:src|lib)/.*\\.nu"
# Right
let pattern = r#'(?:src|lib)/.*\.nu'#

# Wrong: single quotes pass literal \t to the external formatter
^git log --format='%H\t%an'
# Wrong: double backslash preserves literal \t
^git log --format="%H\\t%an"
# Preferred: Nushell turns \t into an actual tab before calling git
^git log --format="%H\t%an"
# Also right: explicit separator, useful with interpolation
let tab = (char tab)
^git log --format=$'%H($tab)%an'

Modules & Scripts

Module structure

my-module/
├── mod.nu              # Module entry point
├── utils.nu            # Submodule
└── tests/
    └── mod.nu          # Test module

Export rules

• Only export definitions are public; non-exported are private
• Use export def main when command name matches module name
• Use export use submodule.nu * to re-export submodule commands
• Use export-env for environment setup blocks

Script with main command and subcommands

#!/usr/bin/env nu

# Build the project
def "main build" [--release (-r)] {
    print 'Building...'
}

# Run tests
def "main test" [--verbose (-v)] {
    print 'Testing...'
}

def main [] {
    print 'Usage: script.nu <build|test>'
}

For stdin access in shebang scripts: #!/usr/bin/env -S nu --stdin

Error Handling

Custom errors with span info

def validate-age [age: int] {
    if $age < 0 or $age > 150 {
        error make {
            msg: 'Invalid age value'
            label: {
                text: $'Age must be between 0 and 150, got ($age)'
                span: (metadata $age).span
            }
        }
    }
    $age
}

try/catch and graceful degradation

let result = try {
    http get $url
} catch {|err|
    print -e $'Request failed: ($err.msg)'
    null
}

# Use complete for detailed external command error info
let result = (^some-external-cmd | complete)
if $result.exit_code != 0 {
    print -e $'Error: ($result.stderr)'
}

Suppress errors with do -i

do -i (ignore errors) runs a closure and suppresses any errors, returning null on failure. do -c (capture errors) catches errors and returns them as values.

# Ignore errors — returns null if the closure fails
do -i { rm non_existent_file }

# Use as a concise fallback
let val = (do -i { open config.toml | get setting } | default 'fallback')

# Capture errors as values (instead of aborting the pipeline)
let result = (do -c { ^some-cmd })

When to use each approach:

• do -i — Fire-and-forget, or when you only need a default on failure
• do -c — Catch errors as values to abort downstream pipeline on failure
• try/catch — When you need to inspect or log the error
• complete — When you need exit code + stdout + stderr from external commands

Testing

Using std assert

use std/assert

for t in [[input expected]; [0 0] [1 1] [2 1] [5 5]] {
    assert equal (fib $t.input) $t.expected
}

Custom assertions

def "assert even" [number: int] {
    assert ($number mod 2 == 0) --error-label {
        text: $'($number) is not an even number'
        span: (metadata $number).span
    }
}

Debugging Techniques

$value | describe                 # Inspect type
$data | each {|x| print $x; $x } # Print intermediate values (pass-through)
timeit { expensive-command }      # Measure execution time
metadata $value                   # Inspect span and other metadata

Security Best Practices

Refer to Security Reference for the full guide.

Nushell is safer than Bash by design (no eval, arguments passed as arrays not through shell), but security risks remain.

Never execute untrusted input as code

# DANGEROUS — arbitrary code execution
^nu -c $user_input
source $user_provided_file

# DANGEROUS — shell interprets the string
^sh -c $'echo ($user_input)'
^bash -c $user_input

Validating a command string (e.g. an allowlist regex) before nu -c is not sufficient: \s matches newlines, regex shortcuts like \b/\w are not command-token rules, and the string is still re-interpreted. Prefer validated argv/list data and run the binary with separated args instead. See Security.

Separate commands from arguments (prevent injection)

# Bad — constructing command strings
let cmd = $'ls ($user_path)'
^sh -c $cmd

# Good — pass arguments directly (no shell interpretation)
^ls $user_path
run-external 'ls' $user_path

Validate and sanitize paths

# Bad — path traversal possible
def read-file [name: string] { open $name }

# Good — validate against traversal
def read-file [name: string, --base-dir: string = '.'] {
    let full = ($base_dir | path join $name | path expand)
    let base = ($base_dir | path expand)
    if not ($full | str starts-with $base) {
        error make {msg: $'Path traversal detected: ($name)'}
    }
    open $full
}

Protect credentials

# Bad — credential visible to all child processes and in env
$env.API_KEY = 'secret-key-123'
^curl -H $'Authorization: Bearer ($env.API_KEY)' $url

# Good — scope credentials, use with-env
with-env {API_KEY: (open ~/.secrets/api_key | str trim)} {
    ^curl -H $'Authorization: Bearer ($env.API_KEY)' $url
}

Safe file operations

# Bad — predictable temp file, race condition
let tmp = '/tmp/my-script-tmp'
'data' | save $tmp

# Good — use mktemp for unique temp files
let tmp = (^mktemp | str trim)
'data' | save $tmp
# ... use $tmp ...
rm $tmp

Handle external command errors

let result = (^cargo build o+e>| complete)
if $result.exit_code != 0 {
    error make {msg: $'Build failed: ($result.stderr)'}
}

Safe rm operations

# Bad — glob from variable, could match unintended files
^rm $'($user_dir)/*'

# Good — validate then use trash or explicit paths
if ($user_dir | path type) == 'dir' {
    rm -r $user_dir
}

Script Review Checklist

Refer to Script Review Reference for the full checklist.

When reviewing a Nushell script, check these categories in order:

1. Security review (highest priority)

• No nu -c / source / ^sh -c with untrusted input
• No credential hardcoding or env leaking
• Paths from user input are validated (no traversal)
• External commands use argument separation (not string concatenation)
• Temp files use mktemp, not predictable paths
• rm operations are guarded and intentional

2. Correctness review

• Type annotations on all exported commands
• I/O pipeline signatures match actual behavior
• Error handling with try/catch for fallible operations
• External commands checked with complete when error handling matters
• Optional fields accessed with ? operator
• No for as final expression (use each instead)
• Long if/else if chains on one value prefer match unless if is clearer
• mut not captured in closures
• parse gets lines first when line-by-line parsing of stream input is intended
• Multiline custom command calls with named flags are one-line or wrapped in parentheses

3. Style review

• Naming: kebab-case commands, snake_case variables
• String format priority followed: simple literal -> '...'; interpolation without escapes -> $'...'; escapes -> "..."; interpolation plus escapes -> $"..."; regex -> r#'...'#
• Strings containing (...) that should run Nushell expressions have $ prefix
• $'...' is not used for \n, \t, \', or other escape processing
• External command format strings use double quotes for simple escapes, or char tab / char nl when interpolation is needed
• Formatting: spacing, line length, multi-line rules
• Documentation comments on exported commands
• ^ prefix on external commands
• Functional style preferred over imperative

4. Performance review

• par-each for I/O or CPU-bound parallel work
• each --flatten for streaming when appropriate
• peek used when inspecting stream metadata/sample values without collecting
• Expensive computations cached in let bindings
• Large files streamed (lazy), not loaded entirely
• Large/columnar datasets and heavy group-by/join use Polars dataframes (lazy), not native loops

Common Pitfalls

Refer to Anti-Patterns Reference for detailed explanations.

Best Practices Summary

1. Use type signatures — Catch errors early, improve documentation
2. Prefer pipelines — More idiomatic, composable, and streamable
3. Document with comments — # above def for help integration
4. Export selectively — Don't pollute namespace
5. Use default — Handle null/missing gracefully
6. Validate inputs — Check types/ranges at function start
7. Return consistent types — Don't mix null and values unexpectedly
8. Use modules — Organize related functions
9. Prefix external commands with ^ — ^grep not grep; Nushell builtins take precedence (e.g., find is Nushell's, not Unix find)
10. Use external tools when faster — ^rg for large file search, ^jq for giant JSON
11. Group multiline command calls — Keep named-flag invocations one-line or wrap them in (...)
12. Use clear separators in external formats — Prefer double-quoted escapes when no interpolation is needed; use (char tab) / (char nl) when interpolation or explicit separators are needed

Do Not Do These Things

• Do not replace every quoted value with double quotes. Double quotes are for escape processing.
• Do not use $"..." just because a string contains interpolation; use $'...' unless escapes are required.
• Do not assume \', \n, or \t work inside single-quoted or single-interpolated strings.
• Do not expect single-quoted or double-escaped external format strings to process \t or \n; use one backslash in double quotes, (char tab), or (char nl).
• Do not remove $ from strings containing command interpolation such as (ansi g), (char nl), or ($value).
• Do not use echo to print user-facing messages — echo has no print side effect; its returned value is shown only when it becomes final output. Use print for side-effect output (echo 'msg'; exit 1 prints nothing).
• Do not split named flags for a custom command onto new statement lines; keep one line or wrap the invocation in parentheses.
• Do not convert user input into nu -c, source, ^sh -c, ^bash -c, or ^cmd.exe /C strings.
• Do not parse structured Nushell output as plain strings when a record/table/list operation exists.
• Do not run destructive examples during validation; parse-check them or use a temp fixture.

Workflow

When writing or reviewing Nushell code:

1. Read existing code to understand the context
2. Security audit — Check for injection, path traversal, credential leaks (see Security)
3. Check naming — kebab-case commands, snake_case variables
4. Check types — Add/verify type annotations and I/O signatures
5. Check strings — Follow the string format priority
6. Check branching — Prefer match over long if/else if chains on one value
7. Check patterns — Prefer functional pipelines over imperative loops
8. Check formatting — Spacing, line length, multi-line rules
9. Check documentation — Comments for exported commands, parameter descriptions
10. Check error handling — try/catch, complete for externals, validate inputs
11. Run validation if possible — nu -c 'source file.nu' or nu file.nu
12. Summarize changes made with security findings highlighted

References

• Security — Security hardening, threat model, safe patterns
• Script Review — Comprehensive review checklist
• String Formats — String type priority and conversion rules
• Anti-Patterns — Common mistakes with detailed fixes
• Data & Type System — Type hierarchy, collections, conversions, type guards
• Dataframes — Polars dataframes: lazy/eager, group-by, joins, expressions, large-data processing
• Advanced Patterns — Performance, streaming, closures, memory efficiency
• Modules & Scripts — Module system, testing, attributes
• Bash to Nushell — Conversion guide from Bash/POSIX

Getting Help

• Use nu -c 'help <command>' to check command signatures and examples
• Use Nushell MCP tools for evaluating and testing Nushell code
• Consult the Nushell Book for in-depth documentation