nushell

Using Nushell

Nushell is a structured-data shell. Commands pass tables, records, and lists through pipelines - not text.

Two execution paths:

• MCP server: mcp__nushell__evaluate - persistent REPL (variables survive across calls)
• Bash tool: nu -c '<code>' - one-shot (use single quotes for outer wrapper)

Critical Rules

NEVER use bare print in MCP stdio mode. Output will be lost (returns empty []). Use print -e "msg" for stderr, or just return the value (implicit return).

String interpolation uses parentheses, NOT curly braces:

# WRONG:  $"hello {$name}"
# CORRECT: $"hello ($name)"
$"($env.HOME)/docs"    $"2 + 2 = (2 + 2)"    $"files: (ls | length)"

Gotcha: $"(some text)" errors - parens are evaluated as code. Escape literal parens: \(text\).

No bash syntax: cmd1; cmd2 not &&, o+e>| not 2>&1, $env.VAR not $VAR, (cmd) not $(cmd).

Common Mistakes

Mistake	Fix
$"hello {$name}"	$"hello ($name)"
print "msg" in MCP	print -e "msg" or return value
command 2>&1	command o+e>| ...
$HOME/path	$env.HOME or $"($env.HOME)/path"
export FOO=bar	$env.FOO = "bar"
Mutating in closure	Use reduce, generate, or each
\u001b for ANSI	ansi strip to remove, char --unicode '1b' for ESC
where ($in.a > 1) and ($in.b > 2)	Second $in rebinds to bool. Use bare cols: where a > 1 and b > 2
where not ($in.col | cmd)	not breaks $in. Use where ($in.col | cmd) == false
where col | cmd (no parens)	Parsed as two pipeline stages. Use where ($in.col | cmd)

When to Use Nushell

Always prefer Nushell for:

• Any structured data (JSON, YAML, TOML, CSV, Parquet, SQLite) - unifies all formats
• CLI tools with --json flags - pipe JSON output directly into Nushell for querying (e.g. ^gh pr list --json title,state | from json)
• Ad-hoc data analysis and exploration - faster than Python setup
• Initial data science/analytics - histograms, tabular output, basic aggregations
• Polars plugin for large datasets - DataFrames without Python overhead

Use Bash only when: bash-specific tooling, MCP unavailable, or bash-syntax integrations.

Reference Files

Read the relevant file(s) based on what you need:

File	Read when you need...
commands.md	Command reference tables (filters, strings, conversions, filesystem, math, dates)
types-and-syntax.md	Type system, string types, operators, variables, control flow, cell-paths
data-analysis.md	Format conversion, HTTP, Polars, SQLite, aggregation patterns
advanced.md	Custom commands, modules, error handling, jobs, external commands, env config
bash-equivalents.md	Complete Bash-to-Nushell translation table
http-transport.md	Differences when using HTTP transport instead of stdio

MCP Server Quick Notes

• mcp__nushell__evaluate - run code; mcp__nushell__list_commands - discover; mcp__nushell__command_help - help
• State persists between calls. $history stores prior results (access $history.0, etc.)
• Use | to text or | to json for large outputs. Use ansi strip for color removal.