Quick Tour
The easiest way to see what Nu can do is to start with some examples, so let's dive in.
The first thing you'll notice when you run a command like ls is that instead of a block of text coming back, you get a structured table.
> ls
╭────┬───────────────────────┬──────┬───────────┬─────────────╮
│ # │ name │ type │ size │ modified │
├────┼───────────────────────┼──────┼───────────┼─────────────┤
│ 0 │ 404.html │ file │ 429 B │ 3 days ago │
│ 1 │ CONTRIBUTING.md │ file │ 955 B │ 8 mins ago │
│ 2 │ Gemfile │ file │ 1.1 KiB │ 3 days ago │
│ 3 │ Gemfile.lock │ file │ 6.9 KiB │ 3 days ago │
│ 4 │ LICENSE │ file │ 1.1 KiB │ 3 days ago │
│ 5 │ README.md │ file │ 213 B │ 3 days ago │
...
The table does more than show the directory in a different way. Just like tables in a spreadsheet, this table allows us to work with the data more interactively.
The first thing we'll do is to sort our table by size. To do this, we'll take the output from ls and feed it into a command that can sort tables based on the contents of a column.
> ls | sort-by size | reverse
╭────┬───────────────────────┬──────┬───────────┬─────────────╮
│ # │ name │ type │ size │ modified │
├────┼───────────────────────┼──────┼───────────┼─────────────┤
│ 0 │ Gemfile.lock │ file │ 6.9 KiB │ 3 days ago │
│ 1 │ SUMMARY.md │ file │ 3.7 KiB │ 3 days ago │
│ 2 │ Gemfile │ file │ 1.1 KiB │ 3 days ago │
│ 3 │ LICENSE │ file │ 1.1 KiB │ 3 days ago │
│ 4 │ CONTRIBUTING.md │ file │ 955 B │ 9 mins ago │
│ 5 │ books.md │ file │ 687 B │ 3 days ago │
...
You can see that to make this work we didn't pass commandline arguments to ls. Instead, we used the sort-by command that Nu provides to do the sorting of the output of the ls command. To see the biggest files on top, we also used reverse.
Nu provides many commands that can work on tables. For example, we could use where to filter the contents of the ls table so that it only shows files over 1 kilobyte:
> ls | where size > 1kb
╭───┬───────────────────┬──────┬─────────┬────────────╮
│ # │ name │ type │ size │ modified │
├───┼───────────────────┼──────┼─────────┼────────────┤
│ 0 │ Gemfile │ file │ 1.1 KiB │ 3 days ago │
│ 1 │ Gemfile.lock │ file │ 6.9 KiB │ 3 days ago │
│ 2 │ LICENSE │ file │ 1.1 KiB │ 3 days ago │
│ 3 │ SUMMARY.md │ file │ 3.7 KiB │ 3 days ago │
╰───┴───────────────────┴──────┴─────────┴────────────╯
Just as in the Unix philosophy, being able to have commands talk to each other gives us ways to mix-and-match in many different combinations. Let's look at a different command:
> ps
╭─────┬───────┬───────┬──────────────────────────────────────────────┬─────────┬───────┬──────────┬──────────╮
│ # │ pid │ ppid │ name │ status │ cpu │ mem │ virtual │
├─────┼───────┼───────┼──────────────────────────────────────────────┼─────────┼───────┼──────────┼──────────┤
│ 0 │ 87194 │ 1 │ mdworker_shared │ Sleep │ 0.00 │ 25.9 MB │ 418.0 GB │
│ 1 │ 87183 │ 2314 │ Arc Helper (Renderer) │ Sleep │ 0.00 │ 59.9 MB │ 1.6 TB │
│ 2 │ 87182 │ 2314 │ Arc Helper (Renderer) │ Sleep │ 0.23 │ 224.3 MB │ 1.6 TB │
│ 3 │ 87156 │ 87105 │ Code Helper (Plugin) │ Sleep │ 0.00 │ 56.0 MB │ 457.4 GB │
...
You may be familiar with the ps command if you've used Linux. With it, we can get a list of all the current processes that the system is running, what their status is, and what their name is. We can also see the CPU load for the processes.
What if we wanted to show the processes that were actively using the CPU? Just like we did with the ls command earlier, we can also work with the table that the ps command gives back to us:
> ps | where cpu > 5
╭───┬───────┬───────┬─────────────────────────────────────────┬─────────┬───────┬──────────┬──────────╮
│ # │ pid │ ppid │ name │ status │ cpu │ mem │ virtual │
├───┼───────┼───────┼─────────────────────────────────────────┼─────────┼───────┼──────────┼──────────┤
│ 0 │ 86759 │ 86275 │ nu │ Running │ 6.27 │ 38.7 MB │ 419.7 GB │
│ 1 │ 89134 │ 1 │ com.apple.Virtualization.VirtualMachine │ Running │ 23.92 │ 1.5 GB │ 427.3 GB │
│ 2 │ 70414 │ 1 │ VTDecoderXPCService │ Sleep │ 19.04 │ 17.5 MB │ 419.7 GB │
│ 3 │ 2334 │ 1 │ TrackpadExtension │ Sleep │ 7.47 │ 25.3 MB │ 418.8 GB │
│ 4 │ 1205 │ 1 │ iTerm2 │ Sleep │ 11.92 │ 657.2 MB │ 421.7 GB │
╰───┴───────┴───────┴─────────────────────────────────────────┴─────────┴───────┴──────────┴──────────╯
So far, we've been using ls and ps to list files and processes in the form of a simple table. But data in Nu is structured and can be arbitrarily nested. As an example, let's now explore the help commands command.
Running help commands gives us information for all Nushell commands as a table. However, the output will be quite large, so let's get the row for the each command only.
> help commands | where name == each | first
╭──────────────┬────────────────────────────────────────────────────────────────────────────────────────────────╮
│ name │ each │
│ category │ filters │
│ command_type │ built-in │
│ usage │ Run a closure on each row of the input list, creating a new list with the results. │
│ │ ╭───┬──────────────────┬──────────────┬──────────┬───────────────────────────────────────────╮ │
│ params │ │ # │ name │ type │ required │ description │ │
│ │ ├───┼──────────────────┼──────────────┼──────────┼───────────────────────────────────────────┤ │
│ │ │ 0 │ closure │ closure(any) │ true │ The closure to run. │ │
│ │ │ 1 │ --help(-h) │ switch │ false │ Display the help message for this command │ │
│ │ │ 2 │ --keep-empty(-k) │ switch │ false │ keep empty result cells │ │
│ │ ╰───┴──────────────────┴──────────────┴──────────┴───────────────────────────────────────────╯ │
│ │ ╭───┬───────────┬───────────╮ │
│ input_output │ │ # │ input │ output │ │
│ │ ├───┼───────────┼───────────┤ │
│ │ │ 0 │ list<any> │ list<any> │ │
│ │ │ 1 │ table │ list<any> │ │
│ │ │ 2 │ any │ any │ │
│ │ ╰───┴───────────┴───────────╯ │
│ search_terms │ for, loop, iterate, map │
╰──────────────┴────────────────────────────────────────────────────────────────────────────────────────────────╯
This is a bit different than the tables we saw before. Retrieving a single row from a table gives us a record, which is set of key-value pairs. Note that the "params" and "input_output" columns happen to contain tables instead of a simple values. To view only one of those columns, we can use the get command to retrieve it:
> help commands | where name == each | first | get params
╭───┬──────────────────┬──────────────┬──────────┬───────────────────────────────────────────╮
│ # │ name │ type │ required │ description │
├───┼──────────────────┼──────────────┼──────────┼───────────────────────────────────────────┤
│ 0 │ closure │ closure(any) │ true │ The closure to run. │
│ 1 │ --help(-h) │ switch │ false │ Display the help message for this command │
│ 2 │ --keep-empty(-k) │ switch │ false │ keep empty result cells │
╰───┴──────────────────┴──────────────┴──────────┴───────────────────────────────────────────╯
The get command lets us jump into the contents of structured data (a table, record, or list). We can even pass it nested columns to access data at any depth.
> help commands | where name == each | first | get params.name
╭───┬──────────────────╮
│ 0 │ closure │
│ 1 │ --help(-h) │
│ 2 │ --keep-empty(-k) │
╰───┴──────────────────╯
These nested columns are called cell paths. Nu will take the cell path and go to the corresponding bit of data in a table, record, or list. Cell paths also support row numbers, so we could have rewritten the above pipeline as:
> help commands | where name == each | get 0.params.name
╭───┬──────────────────╮
│ 0 │ closure │
│ 1 │ --help(-h) │
│ 2 │ --keep-empty(-k) │
╰───┴──────────────────╯
Getting Help
You can see the help text for any of Nu's built-in commands by using the help command or by passing the --help flag to a command. You can also search for a topic by doing help -f <topic>.
> help path
Explore and manipulate paths.
There are three ways to represent a path:
* As a path literal, e.g., '/home/viking/spam.txt'
* As a structured path: a table with 'parent', 'stem', and 'extension' (and
* 'prefix' on Windows) columns. This format is produced by the 'path parse'
subcommand.
* As an inner list of path parts, e.g., '[[ / home viking spam.txt ]]'.
Splitting into parts is done by the `path split` command.
All subcommands accept all three variants as an input. Furthermore, the 'path
join' subcommand can be used to join the structured path or path parts back into
the path literal.
Usage:
> path
Subcommands:
path basename - Get the final component of a path
path dirname - Get the parent directory of a path
path exists - Check whether a path exists
path expand - Try to expand a path to its absolute form
path join - Join a structured path or a list of path parts.
path parse - Convert a path into structured data.
path relative-to - Get a path as relative to another path.
path split - Split a path into parts by a separator.
path type - Get the type of the object a path refers to (e.g., file, dir, symlink)
Flags:
-h, --help
Display this help message