nushell/nushell

A new type of shell

Nushell

A new type of shell.

Table of Contents

• Status
• Learning About Nu
• Installation
• Configuration
• Philosophy
  • Pipelines
  • Opening files
  • Plugins
• Goals
• Officially Supported By
• Contributing
• License

Status

This project has reached a minimum-viable-product level of quality. Many people use it as their daily driver, but it may be unstable for some commands. Nu's design is subject to change as it matures.

Learning About Nu

The Nushell book is the primary source of Nushell documentation. You can find a full list of Nu commands in the book, and we have many examples of using Nu in our cookbook.

We're also active on Discord and Twitter; come and chat with us!

Installation

To quickly install Nu:

# Linux and macOS
brew install nushell
# Windows
winget install nushell

To use Nu in GitHub Action, check setup-nu for more detail.

Detailed installation instructions can be found in the installation chapter of the book. Nu is available via many package managers:

For details about which platforms the Nushell team actively supports, see our platform support policy.

Configuration

The default configurations can be found at sample_config which are the configuration files one gets when they startup Nushell for the first time.

It sets all of the default configuration to run Nushell. From here one can then customize this file for their specific needs.

To see where config.nu is located on your system simply type this command.

$nu.config-path

Please see our book for all of the Nushell documentation.

Philosophy

Nu draws inspiration from projects like PowerShell, functional programming languages, and modern CLI tools. Rather than thinking of files and data as raw streams of text, Nu looks at each input as something with structure. For example, when you list the contents of a directory what you get back is a table of rows, where each row represents an item in that directory. These values can be piped through a series of steps, in a series of commands called a 'pipeline'.

Pipelines

In Unix, it's common to pipe between commands to split up a sophisticated command over multiple steps. Nu takes this a step further and builds heavily on the idea of pipelines. As in the Unix philosophy, Nu allows commands to output to stdout and read from stdin. Additionally, commands can output structured data (you can think of this as a third kind of stream). Commands that work in the pipeline fit into one of three categories:

• Commands that produce a stream (e.g., ls)
• Commands that filter a stream (e.g., where type == "dir")
• Commands that consume the output of the pipeline (e.g., table)

Commands are separated by the pipe symbol (|) to denote a pipeline flowing left to right.

> ls | where type == "dir" | table
╭────┬──────────┬──────┬─────────┬───────────────╮
│ #  │   name   │ type │  size   │   modified    │
├────┼──────────┼──────┼─────────┼───────────────┤
│  0 │ .cargo   │ dir  │     0 B │ 9 minutes ago │
│  1 │ assets   │ dir  │     0 B │ 2 weeks ago   │
│  2 │ crates   │ dir  │ 4.0 KiB │ 2 weeks ago   │
│  3 │ docker   │ dir  │     0 B │ 2 weeks ago   │
│  4 │ docs     │ dir  │     0 B │ 2 weeks ago   │
│  5 │ images   │ dir  │     0 B │ 2 weeks ago   │
│  6 │ pkg_mgrs │ dir  │     0 B │ 2 weeks ago   │
│  7 │ samples  │ dir  │     0 B │ 2 weeks ago   │
│  8 │ src      │ dir  │ 4.0 KiB │ 2 weeks ago   │
│  9 │ target   │ dir  │     0 B │ a day ago     │
│ 10 │ tests    │ dir  │ 4.0 KiB │ 2 weeks ago   │
│ 11 │ wix      │ dir  │     0 B │ 2 weeks ago   │
╰────┴──────────┴──────┴─────────┴───────────────╯

Because most of the time you'll want to see the output of a pipeline, table is assumed. We could have also written the above:

> ls | where type == "dir"

Being able to use the same commands and compose them differently is an important philosophy in Nu. For example, we could use the built-in ps command to get a list of the running processes, using the same where as above.

> ps | where cpu > 0
╭───┬───────┬───────────┬───────┬───────────┬───────────╮
│ # │  pid  │   name    │  cpu  │    mem    │  virtual  │
├───┼───────┼───────────┼───────┼───────────┼───────────┤
│ 0 │  2240 │ Slack.exe │ 16.40 │ 178.3 MiB │ 232.6 MiB │
│ 1 │ 16948 │ Slack.exe │ 16.32 │ 205.0 MiB │ 197.9 MiB │
│ 2 │ 17700 │ nu.exe    │  3.77 │  26.1 MiB │   8.8 MiB │
╰───┴───────┴───────────┴───────┴───────────┴───────────╯

Opening files

Nu can load file and URL contents as raw text or structured data (if it recognizes the format). For example, you can load a .toml file as structured data and explore it:

> open Cargo.toml
╭──────────────────┬────────────────────╮
│ bin              │ [table 1 row]      │
│ dependencies     │ {record 25 fields} │
│ dev-dependencies │ {record 8 fields}  │
│ features         │ {record 10 fields} │
│ package          │ {record 13 fields} │
│ patch            │ {record 1 field}   │
│ profile          │ {record 3 fields}  │
│ target           │ {record 3 fields}  │
│ workspace        │ {record 1 field}   │
╰──────────────────┴────────────────────╯

We can pipe this into a command that gets the contents of one of the columns:

> open Cargo.toml | get package
╭───────────────┬────────────────────────────────────╮
│ authors       │ [list 1 item]                      │
│ default-run   │ nu                                 │
│ description   │ A new type of shell                │
│ documentation │ https://www.nushell.sh/book/       │
│ edition       │ 2018                               │
│ exclude       │ [list 1 item]                      │
│ homepage      │ https://www.nushell.sh             │
│ license       │ MIT                                │
│ metadata      │ {record 1 field}                   │
│ name          │ nu                                 │
│ repository    │ https://github.com/nushell/nushell │
│ rust-version  │ 1.60                               │
│ version       │ 0.72.0                             │
╰───────────────┴────────────────────────────────────╯

And if needed we can drill down further:

> open Cargo.toml | get package.version
0.72.0

Plugins

Nu supports plugins that offer additional functionality to the shell and follow the same structured data model that built-in commands use. There are a few examples in the crates/nu_plugins_* directories.

Plugins are binaries that are available in your path and follow a nu_plugin_* naming convention. These binaries interact with nu via a simple JSON-RPC protocol where the command identifies itself and passes along its configuration, making it available for use. If the plugin is a filter, data streams to it one element at a time, and it can stream data back in return via stdin/stdout. If the plugin is a sink, it is given the full vector of final data and is given free reign over stdin/stdout to use as it pleases.

The awesome-nu repo lists a variety of nu-plugins while the showcase repo shows off informative blog posts that have been written about Nushell along with videos that highlight technical topics that have been presented.

Goals

Nu adheres closely to a set of goals that make up its design philosophy. As features are added, they are checked against these goals.

• First and foremost, Nu is cross-platform. Commands and techniques should work across platforms and Nu has first-class support for Windows, macOS, and Linux.

• Nu ensures compatibility with existing platform-specific executables.

• Nu's workflow and tools should have the usability expected of modern software in 2022 (and beyond).

• Nu views data as either structured or unstructured. It is a structured shell like PowerShell.

• Finally, Nu views data functionally. Rather than using mutation, pipelines act as a means to load, change, and save data without mutable state.

Officially Supported By

Please submit an issue or PR to be added to this list.

• zoxide
• starship
• oh-my-posh
• Couchbase Shell
• virtualenv
• atuin
• clap
• Dorothy
• Direnv

Contributing

See Contributing for details. Thanks to all the people who already contributed!

License

The project is made available under the MIT license. See the LICENSE file for more information.

nushell's Issues

Add back size numbers

With the new parser refactor, we lost the ability to say things like where size > 10KB. We should try to add this back

10K parses weirdly

Get rid of unwraps in commands

We've got better error handling now, but there are still plenty of unwraps in our commands. We can convert these to use the error reporting system instead.

MVP #1 - "Hey it works"

"Hey, it works"

While there are a lot of areas nu can grow, this is the list to get to the point we can demonstrate all the core philosophy and functionality:

Requirements for loadable plugins

• full-fidelity Value serialization
• plugin metadata

Requirements for for-each/$it

• evaluating 'static' and 'per-value' commands

Requirements for basic shell functionality

• Basic file operations (#207)
  • cp
  • rm
  • mv
  • mkdir
  • (others?)
• Escape valve to system binaries (#25)

Reliability (#294)

"Make the shell not crash"

• Fix list viewing (currently it seems like values just disappear)

Essentials and nice-to-haves

• a means to edit objects
• working with globs (eg ls *.jpg)
• space in file names (eg open my\ file.dat)
• a better 'view'
• a rotated table view that makes it easier to view tables with many columns
• optional row numbers

Polish

• Complete docs

Note: there is also a follow-up MVP planned. Info available at #261

Pipeline from external | nu

Strawperson:

The external command produces a nu string for each line of stdout.

Handling compressed/disk image files

Can we cd into .zip and .dmg files? Or is there a way to enter them and step inside the mount?

Pipeline between external processes

TL;DR we already use subprocess, and https://docs.rs/subprocess/0.1.18/subprocess/struct.Pipeline.html

Interactive Table View

Use Cursive to pipe tables into a more interactive view

ls should use 'name' and 'type'

To align with the other columns, and to generally be easier to type, we might want to go with 'name' and 'size' instead of "file name" and "file size"

Name of command to edit cell

Our view of table data is read-only, but as we think about round-tripping with load/save, it would be helpful to be able to edit cells easily

cd ..\otherdir is broken

If you cd ..\otherdir, we currently crash

Escape valve into system executables

Maybe ^ls to run the system's ls instead of the builtin

Linux doesn't work for external commands with args

Some commands are working fine in Windows, but I'm seeing a few in Linux (or WSL) that aren't working correctly. Might be related to recent changes, I'm not sure.

Add email (*.eml) support

Would be pretty cool to magic open .eml files and get into their contents

Add a general facility for subtotaling numeric columns

This avoids needing to hardcode this sort of infrastructure in #33.

Non-primitive cast error

While building:

error[E0605]: non-primitive cast: `sysinfo::linux::process::ProcessStatus` as `i64`
  --> src/object/process.rs:20:35
   |
20 |     dict.add("status", Value::int(proc.status() as i64));
   |                                   ^^^^^^^^^^^^^^^^^^^^
   |
   = note: an `as` expression can only be used to convert between primitive types. Consider using the `From` trait

error: aborting due to previous error

For more information about this error, try `rustc --explain E0605`.
error: Could not compile `nu`.

I'm running rustc 1.36.0-nightly (7158ed9cb 2019-05-15)

CI for PRs

Once we have #63, we need to enable CI support for at least Windows and Linux (and macOS if it differs noticeably from Linux)

Type check commands

We have enough information about the commands and the piped chain of commands that we could do some simple typechecking on it before we run it.

Some examples:

• Commands that expect objects need objects to flow in
• Commands that expect strings can't have objects flow in
• External commands that use $it expect strings

Ctrl-C should break running app

Right now, ctrl-C will close nu altogether, rather than breaking the running app. Would be nice to just break the app and get back to the nu shell

Per directory $env

Might be interesting to explore what it would be like to be able to craft your environment specific to a given directory, effectively letting directories have their own env

Add iCal/vCard support

It'd be fun to be able to magic open up iCal and/or vCard files and get into the details

Autocomplete needs smarter 'cd'

Currently, history appears to pop up when typing 'cd', but this will show the directory you just cd'ed into rather than helping you pick the next directory to 'cd' to.

Pipeline should be streaming

Right now, each nu->nu pipeline collects all the results before moving to the next step. Ideally, all pipelines would be streaming so we could seamlessly integrate with external commands and also handle commands with large amounts of data.

License

Just noticed we're currently ISC. Not sure exactly what that is. We might want to switch to something more Rust-y at some point.

rm

Basic spec:

function rm($file)
OR
function rm($it)

$file may be an absolute or relative path or a file object. $it may only be a file object.

If $file is a relative path, it's interpreted relative to the current cwd.

If the file to delete is a directory, it behaves like rm -rf in Linux or rm -Recurse -Force in PowerShell. The user must have permissions to delete the relevant files.

If the file to delete is a file, it behaves like rm. The user must have permissions to delete the relevant file.

Open Question: Should rm on a directory confirm? If so, how does it relate to #16.

Need a 'less'/'more' command to pipe into

Partial evaluation like xargs

Straw man:

ps | where name =~ chrome | kill $it.pid

TL;DR, when a statement refers to $it, it effectively desugars into a closure taking one parameter whose value is the current pipeline input.

Add some sort of data persistence infrastructure

I'm thinking https://github.com/jgallagher/rusqlite

Can't run `cargo run -- --arg`

Can't pass additional args, eg cargo run -- --arg

Field groups

To make it possible to quickly select a bunch of common fields without having to enumerate them every time.

This can also be used to describe the default group of fields used in a table.

open <url> doesn't support binary

open may be opening a url pointing to a binary file. We should extend the MIME support to detect this as best we can, so that we get a Value::Binary instead of String.

Save functionality

We have open, but no way to save out the result to a file easily

Track down possible rustyline issue

Not sure if this is rustyline, so I don't want to point fingers, but I am seeing nu fail on rare occasion on start with:

Error: Io(Kind(InvalidData))

Use '?' to switch into help mode

From the Julia CLI:

If you type ? first, the prompt switches to help?> to let you know you can now ask about questions rather than run them. Great idea

General cleanup of error reporting

Along with #65, we should have a more general cleanup of how we're handling errors and uniformally use the error value.

As part of this, also get rid of unwraps, and flow errors out without crashing.

`which`

Should be able to handle builtins. I think something like the where.exe approach is nice here -- a list of all of the results and if you want the top you do | first 1

Improvements to 'open'

Open/from/to for each file type should be registered in a central place so that in the future plugins have access to the registry.

open and view can't take $it

It would be great if $it (and $it with path) was universal, and we could use it on any commands. Currently, it seems to be a mixed bag whether or not the command supports it.

Scanf equivalent command

Rather than only having split-column, it'd be nice to have a scan-column that can do a split but based on a pattern.

Eg) rg -n None | split-row "\n" | scan "<Filename>: <Line>: <Extra>"

Magic open binary formats?

Are there any binary formats we want to magic-open?

Split

Now that we have external->nu, it'd be great to take in a stream and split the lines as they come in to create columns

Refactor enter/open functionality

There's a lot of duplication between enter and open, we should refactor

Fixed #134

Store history.txt in central location

Right now, it's possible for history.txt to appear in different parts of the file system depending on when and where you use nu. Would be nice if this history was part of config, or generally lived in a central location.

Tests

We need a way of standing up nu, running a command, and diffing the output against the expected output.

size

Like wc. Takes a list of strings as $it or a file as $it.

Produces an object with these fields:

• bytes
• lines
• words (maybe)
• max-length

And any other useful facilities from wc

Pipes should detect errors and bail

Pipes allow us to stream, but we should also detect errors being streamed and bail early so the user can do something about it.

Confirmation infrastructure

Like -WhatIf and -Force in PowerShell.

We should do better than PS at getting arbitrary commands to support confirmation.

Idea from @jonathandturner: what if dangerous behavior like removing files could only be accomplished by returning actions from commands, which would then be handled by the host?

@wycats likes it.

Support $PATH

On Windows, you can lean on the Windows system for invoking applications, but you need some path support in Linux if you want to use this as your shell.

Note: this may be from us using the default shelling, which runs sh, and may not have access to the additional directories that bash makes visible to the path.

Parse boolean values

Would be nice to be able to do pass commands like where yanked != true though it currently seems that true is being parsed as a string.

Piping between externals is currently broken

Eg)

ps ax | grep telegram