Nushell Pro

Nushell Pro

Write secure, idiomatic, portable, and testable Nushell. Keep the main workflow in this file; load detailed references only when the task needs them.

Operating Workflow

1. Identify the task: new script, debugging, review, refactor, module design, migration, performance work, security audit, or Bash conversion.
2. Read the target .nu files, nearby tests, AGENTS.md, and existing project conventions before changing code.
3. Establish both the project's supported Nu range (from CI, documentation, or project configuration) and the active local version. Do not assume the local binary defines the compatibility target. Prefer the official English docs; translations can lag. When local docs/source checkouts are available, inspect them and record their revision separately from the installed Nu version. From any shell, prefer:

   nu --version

When already inside Nushell or when structured version data is needed, use:

   version | get version

1. Load the smallest relevant reference set:

1. Apply the cross-cutting guardrails below before style or performance cleanup.
2. Before a generated script's first real run, use nu-check --debug in the intended scope. Assert exact output for tricky strings/serialized payloads, then run the relevant tests; parsing alone cannot detect unintended but valid interpolation. Use --ide-check when structured diagnostics are needed.
3. Report security/correctness findings before style and performance notes.

If a referenced file is unavailable, say so and continue with this file rather than inventing its contents.

Cross-Cutting Guardrails

These rules apply across task types. Load the routed reference before relying on syntax or behavior that changed between Nushell releases.

Types and pipeline contracts

• Declare pipeline input in the I/O signature rather than as a positional parameter. Capture $in once when it must be reused because streams can be single-pass.
• Type exported command parameters and input/output signatures.
• Treat external/config records as untrusted; use optional access such as $record.field? and validate the resulting type/value.
• Remember that default evaluates its fallback argument eagerly. Make the fallback null-safe or branch explicitly when it can fail or is expensive.
• Keep return types consistent. Avoid any unless the function is genuinely polymorphic.
• Use external_arg on main parameters only when the CLI must preserve the caller's token spelling instead of applying Nushell literal coercion. It produces glob/list<glob> values in Nu 0.115, so validate or convert them before treating them as structured application data.
• Prefer match for several branches on one value; use if for one-off boolean predicates.

External commands and errors

• Pass external arguments as separate values, never as an interpolated command string. Use complete and check exit_code when status matters.
• Prefer try/catch and $err.details for structured in-process errors.
• On Nu 0.115, a spanned error make label has the shape {text: ..., span: {start: ..., end: ...}}. Do not use the obsolete flat {text, start, end} form.
• On Nu 0.115.0, a try/finally nested directly inside an outer try whose handler is catch silently skips the inner finally. Give the outer block a finally, or put the inner one behind a do/command boundary, and assert that the owned state is gone.
• Treat rendered nested-Nu diagnostics as presentation text, not a stable protocol. For CLI tests, normalize ANSI styling, gutters, and PTY wrapping before matching a long, domain-specific phrase.

Security stop checkpoint

Before approving code that executes commands, deletes files, reads credentials, or accepts paths/patterns, confirm these boundaries:

• Never pass untrusted strings to nu -c, source, run, ^sh -c, ^bash -c, or ^cmd.exe /C.
• Pass external command arguments as separate values, not an interpolated shell command string.
• For existing paths restricted to a base directory, expand both paths and use path relative-to to prove containment. A string starts-with check is unsafe because /safe/base2 starts with /safe/base.
• Prefer Nu's built-in mktemp/mktemp --directory; it is portable and returns a path directly. Do not use predictable temp names.
• Scope secrets with with-env; do not log them or pass them in argv when a stdin/config-file mechanism exists.
• Guard destructive paths against root, $nu.home-dir, unexpected types, and untrusted globs. Consider TOCTOU and partial-success behavior.

For output paths that do not exist yet, validate the existing parent directory with the same containment rule, then join only a validated leaf name.

Strings and formatting

• Prefer simple literals and raw regex strings; use double quotes only when actual escapes are required.
• Remember that $'...' interpolates but does not process escape sequences.
• A literal `(` directly inside interpolation requires `$"..."`. Since $'...' does no escape processing, every ( inside it opens an interpolation expression and \( cannot prevent that. Write $"\(abc)($var)", never $'\(abc)($var)'. The failure is often silent rather than an error: $'(1 + 1) items' evaluates to 2 items. See String Formats. For generated code with many delimiters, join plain literal fragments and serialized data instead.
• Keep code and data separate across interpreters: pass argv/stdin/JSON to a fixed program. If an API only accepts source, use a fixed, trusted template with target-language serialization; a single argv string is still code when