nushell-plugins/updates/108/NUSHELL_0.108.0_CHANGES.md

Nushell 0.108.0 Complete Breaking Changes and Features Documentation

Release Date: 2025-10-15 Version: 0.108.0 Previous Version: 0.107.x

Table of Contents

1. Breaking Changes
2. New Features
3. Experimental Features
4. Plugin API Changes
5. Command Changes
6. Behavior Changes
7. Build System Changes
8. Bug Fixes
9. Migration Guide
10. Recommendations for Best Practices

---

Breaking Changes

1. Command Rename: into value → detect type

Category: command_rename Impact: HIGH Old: into value New: detect type (for type detection) and into value (for custom value conversion)

Description: Until version 0.107, into value tried to detect the types of table cells by converting strings into typed values. This command is now called detect type, but it doesn't operate on cells anymore.

Migration Guide:

# OLD (0.107)
$data | into value

# NEW (0.108.0) - for type detection on cells
$data | update cells {detect type}

# NEW (0.108.0) - for type detection on non-table types
$value | detect type

# NEW (0.108.0) - for converting custom plugin values to native values
$custom_value | into value

Additional Notes:

• detect type can now be used on non-table types to try to infer the types
• The into value name is now used for converting custom values from plugins into native Nushell values

---

2. Stream Error Collection Behavior

Category: behavior_change Impact: HIGH Old: Collecting a stream with errors would silently include or hide errors New: Collecting a stream that contains errors now raises an error itself

Description: Implemented by @Bahex to fix an issue where some errors hiding inside other commands weren't showing up quite right. This makes error handling more explicit and prevents silent failures.

Migration Guide:

# If you were relying on error suppression in stream collection, you now need to:

# Option 1: Use try-catch to handle errors explicitly
try {
    $stream | collect
} catch {
    # Handle error
}

# Option 2: Use error handling flags where available
$stream | collect --ignore-errors  # If supported by command

Impact:

• Code that was silently ignoring errors in streams will now fail explicitly
• Better error visibility but may break existing scripts that relied on silent error handling

---

3. format bits Endian Behavior

Category: behavior_change Impact: MEDIUM Old: format bits used native endian (before 0.107), then changed to big endian in 0.107 New: Explicit --endian flag to choose behavior

Description: format bits used to output in native endian until Nu 0.107.0 changed it to big endian. Now, you can choose the behavior with --endian.

Migration Guide:

# To get original behavior (before Nu 0.107.0):
format bits --endian native

# To use big endian (0.107.0 default):
format bits --endian big

# Or explicitly:
format bits --endian little

---

4. Polars Plugin Changes

Category: api_change Impact: MEDIUM Old: polars fetch command available, polars pivot stable by default New: polars fetch removed, polars pivot requires --stable flag

Description:

• polars fetch has been removed due to no longer being supported on LazyFrame
• polars pivot will no longer perform a stable pivot by default

Migration Guide:

# polars fetch - REMOVED
# OLD (0.107):
$data | polars fetch

# NEW (0.108.0):
# No direct replacement - functionality removed due to upstream Polars changes
# Alternative approaches depend on your use case

# polars pivot - requires --stable flag
# OLD (0.107):
$data | polars pivot  # Was stable by default

# NEW (0.108.0):
$data | polars pivot --stable  # Must explicitly request stable pivot

---

5. Windows Path Handling

Category: behavior_change Impact: LOW (Windows-only) Platform: Windows Old: UNC and device paths got trailing \ appended, device paths didn't work with open, save, source New: No trailing backslashes, full device path support

Description: On Windows, UNC and device paths no longer get a trailing \ appended when being cast to path, and open, save, and source now work with device paths like \\.\NUL or \\.\CON, as well as reserved device names like NUL and CON.

Migration Guide:

# Windows device paths now work correctly:
open \\.\NUL    # Now works
source \\.\CON  # Now works
save \\.\NUL    # Now works

# Reserved device names work:
open NUL        # Now works
open CON        # Now works

# UNC paths no longer get trailing backslash:
# OLD: \\server\share\
# NEW: \\server\share

Note: Using full device paths is recommended for clarity.

---

6. Network Commands Feature Flag

Category: build_change Impact: LOW (affects custom builds only) Old: Network commands included by default New: Must explicitly enable with --features network when building without defaults

Description: Nushell can now be compiled without network-related commands. If building manually without default features, you must pass --features network to get access to network commands.

Migration Guide:

# OLD (0.107):
cargo build --no-default-features

# NEW (0.108.0):
cargo build --no-default-features --features network

Affected Commands:

• http get, http post, http delete, etc.
• Other network-related commands

---

7. Power Operator Associativity Fix

Category: behavior_change Impact: LOW Old: ** operator parsed left-to-right (incorrect) New: ** operator parses right-to-left (mathematically correct)

Description: The ** (power) operator now parses as right-associative instead of left-associative, matching standard mathematical behavior.

Migration Guide:

# Expression: 2.0 ** 3.0 ** 4.0

# OLD (0.107) - left-associative (WRONG):
# (2.0 ** 3.0) ** 4.0 = 8.0 ** 4.0 = 4096

# NEW (0.108.0) - right-associative (CORRECT):
# 2.0 ** (3.0 ** 4.0) = 2.0 ** 81.0 = 2.4178516392292583e+24

# If you were relying on the old (incorrect) behavior, use explicit parentheses:
(2.0 ** 3.0) ** 4.0

---

New Features

1. MCP Server for AI Agents

Category: Optional Feature (Compilation Flag) Added by: @ayax79 Status: Experimental

Description: Adds an MCP (Model Context Protocol) server for Nushell, allowing AI agents to run Nushell commands.

How to Enable:

# Compile Nushell with MCP feature (not included by default):
cargo build --features mcp

Usage: When compiled with the "mcp" feature, the nushell binary can be used as a local (stdio) MCP server, allowing a local AI agent to use MCP to execute native nushell commands and external commands.

Capabilities:

• Execute native Nushell commands via MCP
• Execute external commands via MCP
• Secure command execution for AI agents

Community: Join the discussion on Discord in #ai-with-nu channel.

---

2. Smarter Completions with Per-Command Completers

Category: Enhancement Impact: User Experience Improvement

Description: New, simpler way to define completions for command parameters with inline completion lists.

Features:

Inline Completion Lists

# Define completions inline:
def go [direction: string@[left up right down]] {
    $direction
}

# Use const variables for reusable completions:
const directions = [left up right down]
def go [direction: string@$directions] {
    $direction
}

Built-in Command Suggestions

Built-in commands that expect a specific set of values now suggest these values automatically.

File Completions for Redirections

File completions have been added for command redirections (o>>, e>, etc.)

Directory-Only Completions

For commands expecting directory arguments, regular files will no longer be suggested as completions when no directory can be suggested.

---

3. Enhanced CustomValue Support

Category: Plugin API Enhancement Added by: @cptpiepmatz Impact: Plugin Developers

Description: CustomValues let plugin authors introduce their own data types without being limited to Nushell's built-in Values. They now behave much closer to regular Values.

New Capabilities:

Error Propagation Syntax Support

# Both syntaxes now work with CustomValues:
$custom_value?  # Old syntax (try operator)
$custom_value!  # New syntax (unwrap operator, added in 0.105.0)

Plugin authors can now decide exactly how these should behave for their custom types.

Save Command Integration

# CustomValues now work with save:
$custom_value | save output.dat

Plugin authors can define how their custom data should be saved, which is often more complex than for built-in types.

New into value Command

# Convert custom plugin values to native Nushell values:
$custom_value | into value

---

4. which Command Enhancement

Category: Command Enhancement

Description: The which command now lists all commands (internal and external) when no argument is passed to it.

Usage:

# OLD (0.107):
which  # Would show help or error

# NEW (0.108.0):
which  # Lists ALL available commands (internal and external)

# Still works with specific command:
which ls
which cargo

---

5. Enhanced HTTP Commands

Category: Command Enhancement

Description: All http commands now attach response data (previously only accessible with http * --full) as metadata to their output streams.

Usage:

# Access response metadata without --full flag:
let response = http get https://api.example.com/data

# Metadata now automatically attached
$response | metadata

---

6. New Date/Time Format Specifiers

Category: Command Enhancement

Description: The format date and into datetime commands now support two new format specifiers for creating compact, sortable date and time components.

New Specifiers:

• %J - Produces compact dates in YYYYMMDD format (e.g., 20250918)
• %Q - Produces compact times in HHMMSS format (e.g., 131144)

Usage:

# Compact date format:
date now | format date "%J"  # Output: 20251015

# Compact time format:
date now | format date "%Q"  # Output: 143022

# Combined for sortable timestamp:
date now | format date "%J%Q"  # Output: 20251015143022

---

7. Metadata Set Merge

Category: Command Enhancement

Description: New --merge flag for metadata set command to attach arbitrary metadata fields.

Usage:

# Merge custom metadata:
$value | metadata set --merge { custom_field: "value", priority: 1 }

---

8. Each Flatten

Category: Command Enhancement

Description: New --flatten flag for each command for better streaming behavior.

Usage:

# Flatten nested results while streaming:
$data | each --flatten { |item|
    # Process and return potentially nested data
}

---

Experimental Features

1. Pipefail

Status: Opt-in Experimental Added by: @WindSoilder Tracking Issue: #16760

Description: When enabled, $env.LAST_EXIT_CODE will be set to the exit code of the rightmost command in a pipeline that exited with a non-zero status, or zero if all commands succeeded.

How to Enable:

# Command line:
nu --experimental-options='pipefail'

# Or in config:
$env.config.experimental = { pipefail: true }

Behavior:

Before enabling pipefail:

^false | echo ''
$env.LAST_EXIT_CODE  # Returns 0 (incorrect)

After enabling pipefail:

^false | echo ''
$env.LAST_EXIT_CODE  # Returns 1 (correct)

Enhanced Error Reporting: When used together with $env.config.display_errors.exit_code = true, Nushell will also report which command failed.

Use Cases:

• Shell scripting requiring strict error checking
• CI/CD pipelines where any failure should be caught
• Bash-like pipeline error handling

---

2. Enforce Runtime Annotations

Status: Opt-in Experimental Added by: @mkatychev

Description: When enabled, Nushell catches errors at runtime when assigning values to type-annotated variables, providing stronger runtime type safety.

How to Enable:

# Command line:
nu --experimental-options='enforce-runtime-annotations'

# Or in config:
$env.config.experimental = { enforce-runtime-annotations: true }

Behavior:

Without feature:

let x: int = "not a number"  # May pass parse time, fail silently at runtime

With feature enabled:

let x: int = "not a number"  # Throws cant_convert error at runtime

Why Experimental: This would be a breaking change for scripts where any coercion/conversions previously ignored field constraints for records and tables.

Use Cases:

• Stricter type safety in production scripts
• Catching type conversion errors early
• More predictable behavior for typed variables

---

3. Reorder Cell Paths (Now Enabled by Default)

Status: Opt-out (Previously opt-in, now default) Tracking Issue: #16766

Description: Promoted from opt-in to opt-out, so it's now enabled by default. Improves cell-path accesses by reordering how the cell-path should be evaluated without modifying the output.

Performance: Improves performance by reordering how cell-paths are evaluated, making lookups faster.

How to Disable (if needed):

# Command line:
nu --experimental-options='reorder-cell-paths=false'

# Or in config:
$env.config.experimental = { reorder-cell-paths: false }

Note: Originally introduced in Nushell 0.106.0, now default in 0.108.0.

---

Plugin API Changes

1. CustomValue API Enhancements

Impact: Plugin Developers Added by: @cptpiepmatz

Changes:

Error Propagation Support

// Plugin authors can now implement both:
// - try operator (?)
// - unwrap operator (!)

impl CustomValue for MyCustomValue {
    fn follow_path_int(&self, ...) -> Result<Value, ShellError> {
        // Supports both $value? and $value! syntax
    }
}

Save Command Integration

impl CustomValue for MyCustomValue {
    fn to_base_value(&self, span: Span) -> Result<Value, ShellError> {
        // Define how custom value should be saved
        // This is called when using `save` command
    }
}

Into Value Support

// Custom values can now be converted to native values
// via the new `into value` command
impl CustomValue for MyCustomValue {
    fn to_base_value(&self, span: Span) -> Result<Value, ShellError> {
        // Return native Nushell value representation
    }
}

Plugin Developer Notes:

• CustomValues now support all major value operations
• Better integration with Nushell's type system
• More predictable behavior matching built-in types

---

2. Plugin Protocol Stability

Status: Stable Version: 0.108.0

Notes: No breaking changes to the plugin protocol in this release. Plugins compiled for 0.107.x should work with 0.108.0.

Recommendation: While the protocol is stable, rebuilding plugins against 0.108.0 is recommended to take advantage of new CustomValue features.

---

Command Changes

Commands Renamed

Old Name	New Name	Purpose
into value	detect type	Type detection from strings
N/A	into value	Convert custom plugin values to native values

Commands Removed

Command	Reason	Alternative
polars fetch	No longer supported on LazyFrame	Depends on use case - functionality removed upstream

Commands Added

Command	Description	Category
detect type	Detect and convert string types to typed values	Type Conversion
into value (new purpose)	Convert custom plugin values to native Nushell values	Plugin Integration

Commands Modified

Command	Change	Description
format bits	Added --endian flag	Choose endian behavior (native, big, little)
polars pivot	Added --stable flag	Must explicitly request stable pivot
which	No args lists all	Lists all commands when called without arguments
http *	Metadata attachment	Response data attached as metadata without --full
format date	New format specifiers	Added %J (compact date) and %Q (compact time)
into datetime	New format specifiers	Added %J (compact date) and %Q (compact time)
metadata set	Added --merge	Merge arbitrary metadata fields
each	Added --flatten	Better streaming behavior for nested data
compact	Improved --empty	Now recognizes 0 byte binary values as empty
open	Windows improvement	Now works with device paths (Windows only)
save	Windows improvement	Now works with device paths (Windows only)
save	CustomValue support	Now works with custom plugin values
source	Windows improvement	Now works with device paths (Windows only)

---

Behavior Changes

1. Error Handling in Try Blocks

Description: Clean up error handlers when jumping outside of try blocks with break/continue.

Impact:

• Error handlers now properly clean up when using break/continue to exit try blocks
• Previously, error handlers would remain active after breaking out
• More predictable error handling behavior

Example:

# Previously could cause issues:
for $item in $items {
    try {
        if $condition {
            break  # Now properly cleans up error handler
        }
    } catch {
        # This won't catch errors from outside the try block anymore
    }
}

---

2. Break/Continue Outside Loops

Description: Using break/continue outside loops now raises a compile error.

Impact:

• Catches logical errors at compile time
• Previously may have caused runtime errors or unexpected behavior

Example:

# This now produces a compile error:
break  # Error: break used outside of loop

# Must be inside a loop:
for $i in 1..10 {
    if $i == 5 { break }  # OK
}

---

3. Error Context Preservation

Description: Errors inside each calls now keep their full context, making it easier to track down what went wrong.

Impact:

• Better error messages
• Easier debugging of pipeline errors
• Full stack traces preserved

Example:

# Better error reporting:
[1 2 "three"] | each { |x| $x + 1 }
# Error now includes full context of which element failed

---

4. Improved Error Messages

Description: Improved error message is thrown for invalid binary, hexadecimal, and octal strings.

Impact:

• Clearer error messages when parsing number literals fails
• Better guidance on correct syntax

Example:

# Invalid binary:
0b102  # Better error message explaining invalid binary digit

# Invalid hex:
0xGGG  # Clearer error about invalid hex characters

# Invalid octal:
0o999  # Better error for invalid octal digit

---

Build System Changes

1. Optional Network Commands

Change: Network commands now optional via feature flag Impact: Custom builds can exclude network functionality Feature Flag: network

Usage:

# Include network commands (default):
cargo build

# Exclude network commands:
cargo build --no-default-features

# Explicitly include network commands:
cargo build --no-default-features --features network

---

2. Optional MCP Server

Change: MCP server support via feature flag Impact: Can build Nushell with MCP server for AI integration Feature Flag: mcp

Usage:

# Include MCP server:
cargo build --features mcp

# Default build (no MCP):
cargo build

---

Bug Fixes

Critical Fixes

1. Try block error handler cleanup

   • Fixed: Error handlers not cleaning up when jumping out of try blocks with break/continue
   • Impact: More predictable error handling behavior

2. Power operator associativity

   • Fixed: ** operator was left-associative (incorrect)
   • Impact: Mathematical expressions now compute correctly

3. Stream error collection

   • Fixed: Errors in streams weren't being properly reported
   • Impact: Errors are now explicitly raised when collecting streams with errors

Platform-Specific Fixes

1. Windows UNC and device paths
   • Fixed: Trailing backslash on UNC paths
   • Fixed: Device paths (\.\NUL, \.\CON) now work with open, save, source
   • Impact: Better Windows compatibility

Command-Specific Fixes

1. compact --empty recognition

   • Fixed: Now recognizes 0 byte binary values as empty
   • Impact: More consistent empty value handling

2. Error context in each

   • Fixed: Errors inside each calls now preserve full context
   • Impact: Easier debugging of pipeline errors

3. Break/Continue compile-time checks

   • Fixed: Using break/continue outside loops now caught at compile time
   • Impact: Better error detection during parsing

---

Migration Guide

High Priority Changes (Must Update)

1. Replace into value with detect type

Search for:

| into value

Replace with:

| update cells {detect type}  # For table cell type detection
# OR
| detect type                  # For non-table type detection

Automated migration:

# Find all uses of `into value`:
rg "into value" --type nu

# Review each case and update based on context

---

2. Update stream error handling

Before:

# Silently collected streams with errors
let results = $stream | collect

After:

# Option 1: Handle errors explicitly
let results = try {
    $stream | collect
} catch {
    # Handle collection errors
    []
}

# Option 2: Filter out errors first (if appropriate)
let results = $stream
    | where ($it | describe) != "error"
    | collect

---

3. Update format bits calls

Before:

# Relied on default endian behavior
$value | format bits

After:

# Explicitly specify endian if you need specific behavior:
$value | format bits --endian native  # Pre-0.107 behavior
$value | format bits --endian big     # 0.107 default
$value | format bits --endian little  # Little endian

---

Medium Priority Changes (Should Update)

1. Update polars commands

Remove polars fetch:

# OLD:
$data | polars fetch

# NEW:
# No direct replacement - review your use case
# Alternative approaches depend on what you're trying to achieve

Add --stable to polars pivot:

# OLD:
$data | polars pivot  # Was stable by default

# NEW:
$data | polars pivot --stable  # Must be explicit

---

2. Update custom builds without defaults

Before:

cargo build --no-default-features

After:

# Include network commands:
cargo build --no-default-features --features network

---

3. Review power operator usage

Check chained power operations:

# This now evaluates differently:
2 ** 3 ** 4

# If you need the old behavior, use parentheses:
(2 ** 3) ** 4  # Explicit left-to-right evaluation

---

Low Priority Changes (Nice to Have)

1. Adopt inline completion syntax

Old style:

def my-command [direction: string] {
    # Custom completer function elsewhere
}

New style:

# Inline completions:
def my-command [direction: string@[left up right down]] {
    $direction
}

# Or with const:
const directions = [left up right down]
def my-command [direction: string@$directions] {
    $direction
}

---

2. Use new date/time format specifiers

New compact formats:

# Sortable date stamps:
date now | format date "%J"      # 20251015
date now | format date "%Q"      # 143022
date now | format date "%J%Q"    # 20251015143022

---

3. Simplify HTTP metadata access

Before:

# Had to use --full flag:
let response = http get $url --full
$response.headers

After:

# Metadata automatically attached:
let response = http get $url
$response | metadata  # Includes headers and other response data

---

Testing Your Migration

1. Run your test suite

nu your_test_suite.nu

2. Check for deprecated patterns

# Search for problematic patterns:
rg "into value" . --type nu
rg "polars fetch" . --type nu
rg "format bits" . --type nu | where ($it !~ "--endian")

3. Test with experimental features

# Test with stricter settings:
nu --experimental-options='pipefail,enforce-runtime-annotations' your_script.nu

---

Recommendations for Best Practices

1. Error Handling

Always handle stream errors explicitly:

# GOOD:
try {
    $stream | collect
} catch { |err|
    log error $"Failed to collect stream: ($err.msg)"
    []
}

# AVOID:
$stream | collect  # May fail silently in older code

---

2. Type Safety

Use explicit type annotations with runtime checks:

# Enable runtime type checking for production:
$env.config.experimental = {
    enforce-runtime-annotations: true
}

# Use type annotations:
def process-data [count: int, name: string] -> list<string> {
    # Implementation
}

---

3. Completions

Prefer inline completions for simple cases:

# GOOD for static values:
def deploy [env: string@[dev staging prod]] {
    # Implementation
}

# Use custom completers for dynamic values:
def deploy [env: string@get-environments] {
    # Implementation
}

def get-environments [] {
    # Dynamic completion logic
}

---

4. Platform Compatibility

Windows path handling:

# Use full device paths on Windows:
if $nu.os-info.name == "windows" {
    open \\.\NUL  # Better than "NUL"
}

# Handle UNC paths correctly:
# Don't assume trailing backslashes

---

5. Custom Values in Plugins

Implement full CustomValue support:

impl CustomValue for MyValue {
    // Support error propagation:
    fn follow_path_int(&self, ...) -> Result<Value, ShellError> { ... }

    // Support save command:
    fn to_base_value(&self, span: Span) -> Result<Value, ShellError> { ... }

    // Support into value:
    // (same as to_base_value)
}

---

6. Endian Handling

Be explicit about endian when it matters:

# For binary data interchange, always specify:
$data | format bits --endian big    # Network byte order
$data | format bits --endian little # Intel/AMD architecture
$data | format bits --endian native # Platform-specific

---

7. Pipeline Error Handling

Use pipefail for critical scripts:

# In critical scripts:
$env.config.experimental = { pipefail: true }
$env.config.display_errors = { exit_code: true }

# Then check exit codes:
some-command | another-command
if $env.LAST_EXIT_CODE != 0 {
    error make { msg: "Pipeline failed" }
}

---

8. Migration Testing

Test incrementally:

# 1. Update syntax without logic changes
# 2. Test with old behavior flags
# 3. Enable new features one at a time
# 4. Run comprehensive test suite
# 5. Deploy to staging environment first

---

9. Documentation

Update your code documentation:

# Document required Nushell version:
# @requires nushell >= 0.108.0
# @experimental pipefail, enforce-runtime-annotations

def my-command [] {
    # Implementation
}

---

10. Future-Proofing

Prepare for experimental features to become default:

# Write code that works with experimental features enabled:
# - Explicit error handling (pipefail-ready)
# - Type annotations (runtime-check-ready)
# - Explicit endian specifications
# - No reliance on removed commands

---

Summary of Impact Levels

HIGH Impact (Must Address)

• into value → detect type rename
• Stream error collection behavior
• Polars fetch removal (if using polars)

MEDIUM Impact (Should Address)

• format bits endian behavior
• Network feature flag (custom builds only)
• Power operator associativity (if using chained powers)
• Polars pivot --stable flag (if using polars)

LOW Impact (Nice to Have)

• Windows UNC/device path improvements (Windows users)
• Inline completion syntax adoption
• HTTP metadata access simplification
• New date/time format specifiers
• Enhanced CustomValue support (plugin developers)

---

Additional Resources

• Official Release Notes: https://www.nushell.sh/blog/2025-10-15-nushell_v0_108_0.html
• GitHub Release: https://github.com/nushell/nushell/releases/tag/0.108.0
• Discord Community: #ai-with-nu (for MCP server discussions)
• Experimental Options Tracking:
  • Pipefail: Issue #16760
  • Reorder Cell Paths: Issue #16766

---

Contributors

This release was made possible by PR contributions from:

@132ikl, @andoalon, @app/dependabot, @ayax79, @Bahex, @blindFS, @cablehead, @cptpiepmatz, @fdncred, @fixerer, @Jan9103, @maxim-uvarov, @mkatychev, @nome, @sgvictorino, @Sheape, @sholderbach, @simonborje, @Tyarel8, @weirdan, @WindSoilder, @xolra0d, @Xylobyte, @ysthakur

---

Document Version: 1.0 Last Updated: 2025-10-18 Maintained By: Nushell Plugins Repository Team