Back to Details

nushell

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Nushell

使用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)
Nushell是一款结构化数据Shell。命令通过管道传递表格、记录和列表——而非文本。
两种执行路径：
  • MCP服务器：
    mcp__nushell__evaluate
    - 持久化REPL（变量在多次调用间保留）
  • Bash工具：
    nu -c '<code>'
    - 单次执行（外层使用单引号包裹）

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:
nu
undefined
在MCP标准输入输出模式下，绝对不要使用裸
print
命令。 输出会丢失（返回空
[]
）。如需输出到标准错误流，请使用
print -e "msg"
，或直接返回值（隐式返回）。
字符串插值使用括号，而非大括号：
nu
undefined

WRONG: $"hello {$name}"

错误写法: $"hello {$name}"

CORRECT: $"hello ($name)"

正确写法: $"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)`.
$"($env.HOME)/docs" $"2 + 2 = (2 + 2)" $"files: (ls | length)"
注意：`$"(some text)"`会报错——括号内内容会被当作代码执行。若要使用字面括号，需转义：`\(text\)`。

**不支持Bash语法：** 应使用`cmd1; cmd2`而非`&&`，使用`o+e>|`而非`2>&1`，使用`$env.VAR`而非`$VAR`，使用`(cmd)`而非`$(cmd)`。

Common Mistakes

常见错误

MistakeFix
$"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 closureUse 
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)
错误写法修正方案
$"hello {$name}"
$"hello ($name)"
MCP模式下使用
print "msg"
使用
print -e "msg"
或直接返回值
command 2>&1
command o+e>| ...
$HOME/path
$env.HOME
或
$"($env.HOME)/path"
export FOO=bar
$env.FOO = "bar"
在闭包中修改数据使用
reduce
、
generate
或
each
使用
\u001b
表示ANSI转义		使用
ansi strip
移除颜色，使用
char --unicode '1b'
表示ESC字符
where ($in.a > 1) and ($in.b > 2)
第二个
$in
会绑定为布尔值。直接使用列名：
where a > 1 and b > 2
where not ($in.col | cmd)
not
会破坏
$in
上下文。使用
where ($in.col | cmd) == false
where col | cmd
（无括号）		会被解析为两个管道阶段。使用
where ($in.col | cmd)

When to Use Nushell

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.
以下场景优先使用Nushell：
  • 处理任何结构化数据（JSON、YAML、TOML、CSV、Parquet、SQLite）——统一所有数据格式
  • 支持
    --json
    参数的CLI工具——可将JSON输出直接传入Nushell进行查询（例如：
    ^gh pr list --json title,state | from json
    ）
  • 临时数据分析与探索——比Python环境搭建更快捷
  • 初始数据科学/分析——直方图、表格输出、基础聚合操作
  • 处理大型数据集的Polars插件——无需Python开销的DataFrames
仅在以下场景使用Bash： 需要Bash专属工具、MCP不可用，或需集成Bash语法时。

Reference Files

参考文档

Read the relevant file(s) based on what you need:
FileRead when you need...
commands.mdCommand reference tables (filters, strings, conversions, filesystem, math, dates)
types-and-syntax.mdType system, string types, operators, variables, control flow, cell-paths
data-analysis.mdFormat conversion, HTTP, Polars, SQLite, aggregation patterns
advanced.mdCustom commands, modules, error handling, jobs, external commands, env config
bash-equivalents.mdComplete Bash-to-Nushell translation table
http-transport.mdDifferences when using HTTP transport instead of stdio
根据需求阅读对应文档：
文档适用场景
commands.md命令参考表（过滤器、字符串、转换、文件系统、数学、日期）
types-and-syntax.md类型系统、字符串类型、运算符、变量、控制流、单元格路径
data-analysis.md格式转换、HTTP、Polars、SQLite、聚合模式
advanced.md自定义命令、模块、错误处理、任务、外部命令、环境配置
bash-equivalents.md完整的Bash到Nushell转换对照表
http-transport.md使用HTTP传输替代标准输入输出的差异说明

MCP Server Quick Notes

MCP服务器快速说明

  • 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.
  • mcp__nushell__evaluate
    - 运行代码；
    mcp__nushell__list_commands
    - 发现命令；
    mcp__nushell__command_help
    - 查看帮助
  • 调用间状态会保留。
    $history
    存储之前的执行结果（可通过
    $history.0
    等访问）
  • 处理大输出时使用
    | to text
    或
    | to json
    。使用
    ansi strip
    移除颜色标记。