Use when writing or running Nushell commands, scripts, or pipelines - via the Nushell MCP server (mcp__nushell__evaluate), via Bash (nu -c), or in .nu script files. Also use when working with structured data (JSON, YAML, TOML, CSV, Parquet, SQLite), doing ad-hoc data analysis or exploration, or when the user's shell is Nushell.
Nushell is a structured-data shell. Commands pass tables, records, and lists through pipelines - not text.
Two execution paths:
mcp__nushell__evaluate - persistent REPL (variables survive across calls)nu -c '<code>' - one-shot (use single quotes for outer wrapper)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: errors - parens are evaluated as code. Escape literal parens: .
$"(some text)"\(text\)No bash syntax: cmd1; cmd2 not &&, o+e>| not 2>&1, $env.VAR not $VAR, (cmd) not $(cmd).
| 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) |
Always prefer Nushell for:
--json flags - pipe JSON output directly into Nushell for querying (e.g. ^gh pr list --json title,state | from json)Use Bash only when: bash-specific tooling, MCP unavailable, or bash-syntax integrations.
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__nushell__evaluate - run code; mcp__nushell__list_commands - discover; mcp__nushell__command_help - help$history stores prior results (access $history.0, etc.)| to text or | to json for large outputs. Use ansi strip for color removal.