Experimental Options for the Nu codebase.

This crate defines all experimental options used in Nushell.

An [ExperimentalOption] is basically a fancy global boolean. It should be set very early during initialization and lets us switch between old and new behavior for parts of the system.

The goal is to have a consistent way to handle experimental flags across the codebase, and to make it easy to find all available options.

Usage

Using an option is simple:

if nu_experimental::EXAMPLE.get() {
    // new behavior
} else {
    // old behavior
}

Adding New Options

1. Create a new module in options.rs.
2. Define a marker struct and implement ExperimentalOptionMarker for it.
3. Add a new static using ExperimentalOption::new.
4. Add the static to [ALL].

That's it. See [EXAMPLE] in options/example.rs for a complete example.

For Users

Users can view enabled options using either version or debug experimental-options.

To enable or disable options, use either the NU_EXPERIMENTAL_OPTIONS environment variable, or pass them via CLI using --experimental-options.

Environment variable

Set [ENV] before launching nu (comma-separated list of options):

NU_EXPERIMENTAL_OPTIONS=example=true,pipefail=false nu

Command line (--experimental-options)

Each --experimental-options flag takes one shell argument. That argument can be a single option, a comma-separated list, or a bracketed list (with optional spaces). You can repeat the flag to add more options.

nu --experimental-options example=true
nu --experimental-options '[example=true, pipefail=false]'
nu --experimental-options example=true --experimental-options pipefail=false

To run a script with experimental options, pass the script path after the option value (the script is not part of the option list):

nu --experimental-options '[example=true]' script.nu

For Embedders

If you're embedding Nushell, prefer using [parse_env] or [parse_iter] to load options.

parse_iter is useful if you want to feed in values from other sources. Since options are expected to stay stable during runtime, make sure to do this early.

You can also call [ExperimentalOption::set] manually, but be careful with that.