# Command Reference

How do I get started?

# How do I get started?

Pick any command from the checklist and write a comment acknowledging you started work.

# Instructions for documenting a Nu command of your choosing

Name the file after the command, like so:

command.md

Example: If you want to add documentation for the Nu command enter, create a file named enter.md, write documentation, save it at /docs/commands/[your_command_picked].md as and create your pull request.

# What kind of documentation should I write?

Anything you want that you believe it best documents the command and the way you would like to see it. Here are some of our ideas of documentation we would love to see (feel free to add yours):

  • Examples of using the command (max creativity welcomed!)
  • Description of the command.
  • Command usage.

# Anything else?

Of course! (These are drafts) so feel free to leave feedback and suggestions in the same file.

Happy Documenting.

alias

This command allows you to define shortcuts for other common commands. By default, they only apply to the current session. To persist them, add them to your config.

Syntax: alias <name> = <body>

The command expects two parameters:

  • The name of the alias
  • The body of the alias

# Examples

Define a custom myecho command as an alias:

> alias myecho = echo
> myecho "hello world"
hello world

The suggested help command works!

> myecho -h

Usage:
  > myecho {flags}

flags:
  -h, --help: Display this help message

all

Find if the table rows matches the condition.

# Usage

> all? <condition> {flags} 

# Parameters

  • <condition> the condition that must match

# Flags

  • -h, --help: Display this help message

# Examples

Find if services are running

> echo [[status]; [UP] [UP]] | all? status == UP

Check that all values are even

> echo [2 4 6 8] | all? ($it mod 2) == 0

ansi strip

strip ansi escape sequences from string

# Usage

> ansi strip ...args {flags} 

# Parameters

  • ...args: optionally, remove ansi sequences by column paths

# Flags

  • -h, --help: Display this help message

# Examples

strip ansi escape sequences from string

> echo [(ansi gb) 'hello' (ansi reset)] | str collect | ansi strip

ansi

Output ANSI codes to change color.

For escape sequences: Escape: \x1b[ is not required for --escape parameter

Format: #(;#)m

Example: 1;31m for bold red or 2;37;41m for dimmed white fg with red bg There can be multiple text formatting sequence numbers separated by a ; and ending with an m where the # is of the following values:

attributes

  • 0 reset / normal display
  • 1 bold or increased intensity
  • 2 faint or decreased intensity
  • 3 italic on (non-mono font)
  • 4 underline on
  • 5 slow blink on
  • 6 fast blink on
  • 7 reverse video on
  • 8 nondisplayed (invisible) on
  • 9 strike-through on
    foreground/bright colors    background/bright colors
    30/90    black              40/100    black
    31/91    red                41/101    red
    32/92    green              42/102    green
    33/93    yellow             43/103    yellow
    34/94    blue               44/104    blue
    35/95    magenta            45/105    magenta
    36/96    cyan               46/106    cyan
    37/97    white              47/107    white
    https://en.wikipedia.org/wiki/ANSI_escape_code

OSC: \x1b] is not required for --osc parameter

Example: echo [(ansi -o '0') 'some title' (char bel)] | str collect

Format:

  • 0 Set window title and icon name
  • 1 Set icon name
  • 2 Set window title
  • 4 Set/read color palette
  • 9 iTerm2 Grown notifications
  • 10 Set foreground color (x11 color spec)
  • 11 Set background color (x11 color spec)
  • ... others

# Usage

> ansi (code) <subcommand> {flags} 

# Subcommands

  • ansi strip - strip ansi escape sequences from string

# Parameters

  • (code) the name of the code to use like 'green' or 'reset' to reset the color

# Flags

  • -h, --help: Display this help message
  • -e, --escape : escape sequence without the escape character(s)
  • -o, --osc : operating system command (ocs) escape sequence without the escape character(s)

# Examples

Change color to green

> ansi green

Reset the color

> ansi reset

Use ansi to color text (rb = red bold, gb = green bold, pb = purple bold)

> echo [(ansi rb) Hello " " (ansi gb) Nu " " (ansi pb) World] | str collect

Use ansi to color text (rb = red bold, gb = green bold, pb = purple bold)

> echo [(ansi -e '3;93;41m') Hello (ansi reset) " " (ansi gb) Nu " " (ansi pb) World] | str collect

any

Find if the table rows matches the condition.

# Usage

> any? <condition> {flags} 

# Parameters

  • <condition> the condition that must match

# Flags

  • -h, --help: Display this help message

# Examples

Find if a service is not running

> echo [[status]; [UP] [DOWN] [UP]] | any? status == DOWN

Check if any of the values is odd

> echo [2 4 1 6 8] | any? ($it mod 2) == 1

append

Append a row to the table.

# Examples

Given the following text file cities.txt containing cities:

Canberra
London
Nairobi
Washington

And getting back a Nu table:

> open cities.txt | lines
───┬────────────
 0 │ Canberra
 1 │ London
 2 │ Nairobi
 3 │ Washington
───┴────────────

Add the city named Beijing like so:

> open cities.txt | lines | append Beijing
───┬────────────
 0 │ Canberra
 1 │ London
 2 │ Nairobi
 3 │ Washington
 4 │ Beijing
───┴────────────

It's not possible to add multiple rows at once, so you'll need to use append multiple times:

> open cities.txt | lines | append Beijing | append "Buenos Aires"
───┬──────────────
 0 │ Canberra
 1 │ London
 2 │ Nairobi
 3 │ Washington
 4 │ Beijing
 5 │ Buenos Aires
───┴──────────────

So far we have been working with a table without a column, which leaves us with plain rows. Let's wrap the plain rows into a column called city and save it as a json file called cities.json:

Before we save, let's check how it looks after wrapping:

open cities.txt | lines | wrap city
───┬────────────
 # │ city
───┼────────────
 0 │ Canberra
 1 │ London
 2 │ Nairobi
 3 │ Washington
───┴────────────

And save:

> open cities.txt | lines | wrap city | save cities.json

Since we will be working with rows that have a column, appending like before won't quite give us back what we want:

> open cities.json | append Guayaquil
───┬────────────
 # │ city
───┼────────────
 0 │ Canberra
 1 │ London
 2 │ Nairobi
 3 │ Washington
───┴────────────
───┬───────────
 4 │ Guayaquil
───┴───────────

We append a row literal directly:

> open cities.json | append [[city]; [Guayaquil]]
───┬────────────
 # │ city
───┼────────────
 0 │ Canberra
 1 │ London
 2 │ Nairobi
 3 │ Washington
 4 │ Guayaquil
───┴────────────

autoenv untrust

Untrust a .nu-env file in the current or given directory

# Usage

> autoenv untrust (dir) {flags} 

# Parameters

  • (dir) Directory to disallow

# Flags

  • -h, --help: Display this help message

# Examples

Disallow .nu-env file in current directory

> autoenv untrust

Disallow .nu-env file in directory foo

> autoenv untrust foo

autoenv trust

Trust a .nu-env file in the current or given directory

# Usage

> autoenv trust (dir) {flags} 

# Parameters

  • (dir) Directory to allow

# Flags

  • -h, --help: Display this help message

# Examples

Allow .nu-env file in current directory

> autoenv trust

Allow .nu-env file in directory foo

> autoenv trust foo

autoenv

Manage directory specific environment variables and scripts.

Create a file called .nu-env in any directory and run 'autoenv trust' to let nushell load it when entering the directory. The .nu-env file has the same format as your $HOME/nu/config.toml file. By loading a .nu-env file the following applies:

    • environment variables (section "[env]") are loaded from the .nu-env file. Those env variables only exist in this directory (and children directories)
    • the "startup" commands are run when entering the directory
    • the "on_exit" commands are run when leaving the directory

# Usage

> autoenv <subcommand> {flags} 

# Subcommands

  • autoenv trust - Trust a .nu-env file in the current or given directory
  • autoenv untrust - Untrust a .nu-env file in the current or given directory

# Flags

  • -h, --help: Display this help message

# Examples

Example .nu-env file

> cat .nu-env
    startup = ["echo ...entering the directory", "echo 1 2 3"]
    on_exit = ["echo ...leaving the directory"]

    [env]
    mykey = "myvalue"

autoview

Print the content of the pipeline as a table or list. It is the implied or default viewer when none is provided.

When reading a single value, a table or a list, autoview will attempt to view it. When reading a string that originally comes from a source file it will attempt to use textview. When reading a binary file it will attempt to display its content as hexadecimal numbers and the corresponding characters.

-h, --help Display help message.

# Examples

In all following examples autoview can be removed with no change in the output. The use of autoview at the end of the pipeline is implied when no viewer is explicitly used.

> which nu | get path | autoview
/home/me/.cargo/bin/nu
> ls | autoview
────┬────────────────────┬──────┬─────────┬──────────────
 #  │ name               │ type │ size    │ modified
────┼────────────────────┼──────┼─────────┼──────────────
  0 │ README.md          │ File │   932 B │ 19 hours ago
  1 │ alias.md           │ File │  2.0 KB │ 19 hours ago
  2 │ append.md          │ File │  1.4 KB │ 19 hours ago
   ...
 82 │ wrap.md            │ File │  1.8 KB │ 19 hours ago
────┴────────────────────┴──────┴─────────┴──────────────
> echo "# Hi" "## Section" "Some text" | save file.md
> open file.md | autoview
# Hi
## Section
Some text

autoview will use textview to colorize the text based on the file format. The style used by textview can be configured in config.toml.

> open --raw (which nu | get path) | autoview
...
126d1c0:   64 31 66 37  62 30 31 63  36 2e 31 31  38 2e 6c 6c   d1f7b01c6.118.ll
126d1d0:   76 6d 2e 34  34 38 37 35  37 31 32 34  39 35 33 39   vm.4487571249539
126d1e0:   34 34 30 34  30 39 00 61  6e 6f 6e 2e  30 30 61 63   440409.anon.00ac
126d1f0:   37 32 65 36  37 66 32 31  39 34 62 32  32 61 61 63   72e67f2194b22aac
126d200:   62 35 39 37  33 36 30 62  64 31 39 38  2e 31 36 2e   b597360bd198.16.
...

benchmark

Runs a block and returns the time it took to execute it.

# Usage

> benchmark <block> {flags} 

# Parameters

  • <block> the block to run and benchmark

# Flags

  • -h, --help: Display this help message
  • -p, --passthrough : Display the benchmark results and pass through the block's output

# Examples

Benchmarks a command within a block

> benchmark { sleep 500ms }

Benchmarks a command within a block and passes its output through

> echo 45 | benchmark { sleep 500ms } --passthrough {}

binaryview

Autoview of binary data.

# Usage

> binaryview {flags} 

# Flags

  • -h, --help: Display this help message
  • -l, --lores: use low resolution output mode
  • -s, --skip : skip x number of bytes
  • -b, --bytes : show y number of bytes

build-string

# build-string

Builds a string from the arguments.

# Usage

> build-string ...args {flags} 

# Parameters

  • ...args: all values to form into the string

# Flags

  • -h, --help: Display this help message

# Examples

Builds a string from a string and a number, without spaces between them

> build-string 'foo' 3

cal

Use cal to display a calendar.

# Flags

  • -y, --year: Display the year column
  • -q, --quarter: Display the quarter column
  • -m, --month: Display the month column
  • --full-year <integer>: Display a year-long calendar for the specified year
  • --week-start <string>: Display the calendar with the specified day as the first day of the week
  • --month-names: Display the month names instead of integers

# Examples

> cal
───┬────────┬────────┬─────────┬───────────┬──────────┬────────┬──────────
 # │ sunday │ monday │ tuesday │ wednesday │ thursday │ friday │ saturday
───┼────────┼────────┼─────────┼───────────┼──────────┼────────┼──────────
 0 │        │        │         │           │          │      12
 13456789
 210111213141516
 317181920212223
 424252627282930
 531 │        │         │           │          │        │
───┴────────┴────────┴─────────┴───────────┴──────────┴────────┴──────────
> cal -yqm --full-year 2020
────┬──────┬─────────┬───────┬────────┬────────┬─────────┬───────────┬──────────┬────────┬──────────
 #  │ year │ quarter │ month │ sunday │ monday │ tuesday │ wednesday │ thursday │ friday │ saturday
────┼──────┼─────────┼───────┼────────┼────────┼─────────┼───────────┼──────────┼────────┼──────────
  0202011 │        │        │         │         1234
  1202011567891011
  220201112131415161718
  320201119202122232425
  42020112627282930315202012 │        │        │         │           │          │        │        1
  62020122345678
  72020129101112131415
  820201216171819202122
  920201223242526272829
 102020131234567
 11202013891011121314
 1220201315161718192021
 1320201322232425262728
 14202013293031 │           │          │        │
 15202024 │        │        │         │         1234
 16202024567891011
 1720202412131415161718
 1820202419202122232425
 192020242627282930 │        │
 20202025 │        │        │         │           │          │      12
 212020253456789
 2220202510111213141516
 2320202517181920212223
 2420202524252627282930
 2520202531 │        │         │           │          │        │
 26202026 │        │      123456
 2720202678910111213
 2820202614151617181920
 2920202621222324252627
 30202026282930 │           │          │        │
 31202037 │        │        │         │         1234
 32202037567891011
 3320203712131415161718
 3420203719202122232425
 3520203726272829303136202038 │        │        │         │           │          │        │        1
 372020382345678
 382020389101112131415
 3920203816171819202122
 4020203823242526272829
 412020383031 │         │           │          │        │
 42202039 │        │        │       12345
 432020396789101112
 4420203913141516171819
 4520203920212223242526
 4620203927282930 │          │        │
 472020410 │        │        │         │           │        123
 48202041045678910
 49202041011121314151617
 50202041018192021222324
 51202041025262728293031
 5220204111234567
 532020411891011121314
 54202041115161718192021
 55202041122232425262728
 5620204112930 │         │           │          │        │
 572020412 │        │        │       12345
 5820204126789101112
 59202041213141516171819
 60202041220212223242526
 6120204122728293031 │        │
────┴──────┴─────────┴───────┴────────┴────────┴─────────┴───────────┴──────────┴────────┴──────────
> cal -yqm --full-year 2020 --month-names
────┬──────┬─────────┬───────────┬────────┬────────┬─────────┬───────────┬──────────┬────────┬──────────
 #  │ year │ quarter │ month     │ sunday │ monday │ tuesday │ wednesday │ thursday │ friday │ saturday
────┼──────┼─────────┼───────────┼────────┼────────┼─────────┼───────────┼──────────┼────────┼──────────
  020201 │ january   │        │        │         │         1234
  120201 │ january   │      567891011
  220201 │ january   │     12131415161718
  320201 │ january   │     19202122232425
  420201 │ january   │     262728293031520201 │ february  │        │        │         │           │          │        │        1
  620201 │ february  │      2345678
  720201 │ february  │      9101112131415
  820201 │ february  │     16171819202122
  920201 │ february  │     23242526272829
 1020201 │ march     │      1234567
 1120201 │ march     │      891011121314
 1220201 │ march     │     15161718192021
 1320201 │ march     │     22232425262728
 1420201 │ march     │     293031 │           │          │        │
 1520202 │ april     │        │        │         │         1234
 1620202 │ april     │      567891011
 1720202 │ april     │     12131415161718
 1820202 │ april     │     19202122232425
 1920202 │ april     │     2627282930 │        │
 2020202 │ may       │        │        │         │           │          │      12
 2120202 │ may       │      3456789
 2220202 │ may       │     10111213141516
 2320202 │ may       │     17181920212223
 2420202 │ may       │     24252627282930
 2520202 │ may       │     31 │        │         │           │          │        │
 2620202 │ june      │        │      123456
 2720202 │ june      │      78910111213
 2820202 │ june      │     14151617181920
 2920202 │ june      │     21222324252627
 3020202 │ june      │     282930 │           │          │        │
 3120203 │ july      │        │        │         │         1234
 3220203 │ july      │      567891011
 3320203 │ july      │     12131415161718
 3420203 │ july      │     19202122232425
 3520203 │ july      │     2627282930313620203 │ august    │        │        │         │           │          │        │        1
 3720203 │ august    │      2345678
 3820203 │ august    │      9101112131415
 3920203 │ august    │     16171819202122
 4020203 │ august    │     23242526272829
 4120203 │ august    │     3031 │         │           │          │        │
 4220203 │ september │        │        │       12345
 4320203 │ september │      6789101112
 4420203 │ september │     13141516171819
 4520203 │ september │     20212223242526
 4620203 │ september │     27282930 │          │        │
 4720204 │ october   │        │        │         │           │        123
 4820204 │ october   │      45678910
 4920204 │ october   │     11121314151617
 5020204 │ october   │     18192021222324
 5120204 │ october   │     25262728293031
 5220204 │ november  │      1234567
 5320204 │ november  │      891011121314
 5420204 │ november  │     15161718192021
 5520204 │ november  │     22232425262728
 5620204 │ november  │     2930 │         │           │          │        │
 5720204 │ december  │        │        │       12345
 5820204 │ december  │      6789101112
 5920204 │ december  │     13141516171819
 6020204 │ december  │     20212223242526
 6120204 │ december  │     2728293031 │        │
────┴──────┴─────────┴───────────┴────────┴────────┴─────────┴───────────┴──────────┴────────┴──────────
> cal -ym --full-year 2303 --month-names | where month == "june"
───┬──────┬───────┬────────┬────────┬─────────┬───────────┬──────────┬────────┬──────────
 # │ year │ month │ sunday │ monday │ tuesday │ wednesday │ thursday │ friday │ saturday
───┼──────┼───────┼────────┼────────┼─────────┼───────────┼──────────┼────────┼──────────
 02303 │ june  │        │      123456
 12303 │ june  │      78910111213
 22303 │ june  │     14151617181920
 32303 │ june  │     21222324252627
 42303 │ june  │     282930 │           │          │        │
───┴──────┴───────┴────────┴────────┴─────────┴───────────┴──────────┴────────┴──────────
> cal -my --full-year 2020 --month-names | default friday 0 | where friday == 13
───┬──────┬──────────┬────────┬────────┬─────────┬───────────┬──────────┬────────┬──────────
 # │ year │ month    │ sunday │ monday │ tuesday │ wednesday │ thursday │ friday │ saturday
───┼──────┼──────────┼────────┼────────┼─────────┼───────────┼──────────┼────────┼──────────
 02020 │ march    │      891011121314
 12020 │ november │      891011121314
───┴──────┴──────────┴────────┴────────┴─────────┴───────────┴──────────┴────────┴──────────
> cal -ymq --month-names --week-start monday
───┬──────┬─────────┬───────┬────────┬─────────┬───────────┬──────────┬────────┬──────────┬────────
 # │ year │ quarter │ month │ monday │ tuesday │ wednesday │ thursday │ friday │ saturday │ sunday
───┼──────┼─────────┼───────┼────────┼─────────┼───────────┼──────────┼────────┼──────────┼────────
 020202 │ june  │      1234567
 120202 │ june  │      891011121314
 220202 │ june  │     15161718192021
 320202 │ june  │     22232425262728
 420202 │ june  │     2930 │           │          │        │          │
───┴──────┴─────────┴───────┴────────┴─────────┴───────────┴──────────┴────────┴──────────┴────────

cd

If you didn't already know, the cd command is very simple. It stands for 'change directory' and it does exactly that. It changes the current directory to the one specified. If no directory is specified, it takes you to the home directory. Additionally, using cd .. takes you to the parent directory.

# Examples

/home/username> cd Desktop
/home/username/Desktop> now your current directory has been changed
/home/username/Desktop/nested/folders> cd ..
/home/username/Desktop/nested> cd ..
/home/username/Desktop> cd ../Documents/school_related
/home/username/Documents/school_related> cd ../../..
/home/>
/home/username/Desktop/super/duper/crazy/nested/folders> cd
/home/username> cd ../../usr
/usr> cd
/home/username>

Using cd - will take you to the previous directory:

/home/username/Desktop/super/duper/crazy/nested/folders> cd
/home/username> cd -
/home/username/Desktop/super/duper/crazy/nested/folders> cd

char

Output special characters (e.g., 'newline').

# Usage

> char (character) ...args {flags} 

# Parameters

  • (character) the name of the character to output
  • ...args: multiple Unicode bytes

# Flags

  • -h, --help: Display this help message
  • -l, --list: List all supported character names
  • -u, --unicode: Unicode string i.e. 1f378

# Examples

Output newline

> char newline

Output prompt character, newline and a hamburger character

> echo (char prompt) (char newline) (char hamburger)

Output Unicode character

> char -u 1f378

Output multi-byte Unicode character

> char -u 1F468 200D 1F466 200D 1F466

chart bar

Bar charts

# Usage

> chart bar (columns) {flags} 

# Parameters

  • (columns) the columns to chart [x-axis y-axis]

# Flags

  • -h, --help: Display this help message
  • -a, --acc: accumulate values
  • -u, --use : column to use for evaluation
  • -f, --format : Specify date and time formatting

chart line

Line charts

# Usage

> chart line (columns) {flags} 

# Parameters

  • (columns) the columns to chart [x-axis y-axis]

# Flags

  • -h, --help: Display this help message
  • -a, --acc: accumulate values
  • -u, --use : column to use for evaluation
  • -f, --format : Specify date and time formatting

chart

Displays charts.

# Usage

> chart <subcommand> {flags} 

# Subcommands

  • chart bar - Bar charts
  • chart line - Line charts

# Flags

  • -h, --help: Display this help message

clear

Clears the terminal.

# Usage

> clear {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Clear the screen

> clear

clip

Copy the contents of the pipeline to the copy/paste buffer.

# Usage

> clip {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Save text to the clipboard

> echo 'secret value' | clip

Save numbers to the clipboard

> random integer 10000000..99999999 | clip

compact

This command allows us to filters out rows with empty columns. Other commands are capable of feeding compact with their output through pipelines.

# Usage

> [input-command] | compact [column-name]

# Examples

Let's say we have a table like this:

> open contacts.json
━━━┯━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━
 # │ name     │ email
───┼──────────┼──────────────────
 0 │ paul     │ paul@example.com
 1 │ andres   │
 2 │ jonathan │
━━━┷━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━

compact allows us to filter out rows with empty email column:

> open contacts.json | compact email
━━━━━━┯━━━━━━━━━━━━━━━━━━
 name │ email
──────┼──────────────────
 paul │ paul@example.com
━━━━━━┷━━━━━━━━━━━━━━━━━━

config clear

clear the config

# Usage

> config clear {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Clear the config (be careful!)

> config clear

config get

Gets a value from the config

# Usage

> config get <get> {flags} 

# Parameters

  • <get> value to get from the config

# Flags

  • -h, --help: Display this help message

# Examples

Get the current startup commands

> config get startup

config path

return the path to the config file

# Usage

> config path {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Get the path to the current config file

> config path

config remove

Removes a value from the config

# Usage

> config remove <remove> {flags} 

# Parameters

  • <remove> remove a value from the config

# Flags

  • -h, --help: Display this help message

# Examples

Remove the startup commands

> config remove startup

config set

Sets a value in the config

# Usage

> config set <key> <value> {flags} 

# Parameters

  • <key> variable name to set
  • <value> value to use

# Flags

  • -h, --help: Display this help message

# Examples

Set auto pivoting

> config set pivot_mode always

Set line editor options

> config set line_editor [[edit_mode, completion_type]; [emacs circular]]

Set coloring options

> config set color_config [[header_align header_bold]; [left $true]]

Set nested options

> config set color_config.header_color white

config set_into

Sets a value in the config

# Usage

> config set_into <set_into> {flags} 

# Parameters

  • <set_into> sets a variable from values in the pipeline

# Flags

  • -h, --help: Display this help message

# Examples

Store the contents of the pipeline as a path

> echo ['/usr/bin' '/bin'] | config set_into path

config

Configuration management.

Syntax: config {flags}

# Flags

load <file path shape>
  load the config from the path give

set <any shape>
  set a value in the config, eg) set variable value

set_into <member shape>
  sets a variable from values in the pipeline

get <any shape>
  get a value from the config

remove <any shape>
  remove a value from the config

clear
  clear the config

path
  return the path to the config file

# Variables

Variable Type Description
path table of strings PATH to use to find binaries
env row the environment variables to pass to external commands
ctrlc_exit boolean whether or not to exit Nu after multiple ctrl-c presses
table_mode "light" or other enable lightweight or normal tables
edit_mode "vi" or "emacs" changes line editing to "vi" or "emacs" mode
key_timeout integer (milliseconds) vi: the delay to wait for a longer key sequence after ESC
history_size integer maximum entries that will be stored in history (100,000 default)
completion_mode "circular" or "list" changes completion type to "circular" (default) or "list" mode
complete_from_path boolean whether or not to complete names of binaries on PATH (default true)
rm_always_trash boolean whether or not to always use system trash when no flags are given to rm
pivot_mode "auto" or "always" or "never" "auto" will only pivot single row tables if the output is greater than the terminal width. "always" will always pivot single row tables. "never" will never pivot single row tables.
plugin_dirs table of strings additional directories to search for plugins during startup

# Examples

> config set table_mode "light"

A more detailed description on how to use this command to configure Nu shell can be found in the configuration chapter of Nu Book (opens new window).

count

Rename count to length (opens new window) since 0.29 version!

Obtain the row or column count of a table.

# Flags

  • -c, --column: Calculate number of columns in table

# Examples

> ls
────┬────────────────────┬──────┬──────────┬──────────────
 #  │ name               │ type │ size     │ modified
────┼────────────────────┼──────┼──────────┼──────────────
 0  │ CODE_OF_CONDUCT.md │ File │   3.4 KB │ 42 mins ago
 1  │ CONTRIBUTING.md    │ File │   1.3 KB │ 42 mins ago
 2  │ Cargo.lock         │ File │ 113.3 KB │ 42 mins ago
 3  │ Cargo.toml         │ File │   4.6 KB │ 42 mins ago
 4  │ LICENSE            │ File │   1.1 KB │ 3 months ago
 5  │ Makefile.toml      │ File │    449 B │ 5 months ago
 6  │ README.md          │ File │  15.9 KB │ 31 mins ago
 7  │ TODO.md            │ File │      0 B │ 42 mins ago
 8  │ assets             │ Dir  │    128 B │ 5 months ago
 9  │ build.rs           │ File │     78 B │ 4 months ago
 10 │ crates             │ Dir  │    704 B │ 42 mins ago
 11 │ debian             │ Dir  │    352 B │ 5 months ago
 12 │ docker             │ Dir  │    288 B │ 3 months ago
 13 │ docs               │ Dir  │    192 B │ 42 mins ago
 14 │ features.toml      │ File │    632 B │ 4 months ago
 15 │ images             │ Dir  │    160 B │ 5 months ago
 16 │ rustfmt.toml       │ File │     16 B │ 5 months ago
 17 │ src                │ Dir  │    128 B │ 1 day ago
 18 │ target             │ Dir  │    160 B │ 5 days ago
 19 │ tests              │ Dir  │    192 B │ 3 months ago
────┴────────────────────┴──────┴──────────┴──────────────

By default, count will return the number of rows in a table

> ls | count
20

The -c flag will produce a count of the columns in the table

> ls | count -c
4
> ls | where type == File | count
11
> ls | where type == Dir | count
9
> ls | where size > 2KB | count
4

cp

Copy files.

# Usage

> cp <src> <dst> {flags} 

# Parameters

  • <src> the place to copy from
  • <dst> the place to copy to

# Flags

  • -h, --help: Display this help message
  • -r, --recursive: copy recursively through subdirectories

# Examples

Copy myfile to dir_b

> cp myfile dir_b

Recursively copy dir_a to dir_b

> cp -r dir_a dir_b

date list-timezone

# date list-timezone

List supported time zones.

# Usage

> date list-timezone {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

List all supported time zones

> date list-timezone

List all supported European time zones

> date list-timezone | where timezone =~ Europe

date now

Get the current date.

# Usage

> date now {flags} 

# Flags

  • -h, --help: Display this help message

date to-table

# date to-table

Print the date in a structured table.

# Usage

> date to-table {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Print the current date in a table

> date now | date to-table

date to-timezone

# date to-timezone

Convert a date to a given time zone.

Use 'date list-timezone' to list all supported time zones.

# Usage

> date to-timezone <time zone> {flags} 

# Parameters

# Flags

  • -h, --help: Display this help message

# Examples

Get the current date in UTC+05:00

> date now | date to-timezone +0500

Get the current local date

> date now | date to-timezone local

Get the current date in Hawaii

> date now | date to-timezone US/Hawaii

date format

Format a given date using the given format string.

# Usage

> date format <format> {flags} 

# Parameters

  • <format> strftime format

# Flags

  • -h, --help: Display this help message
  • -t, --table: print date in a table

# Examples

Format the current date

> date now | date format '%Y.%m.%d_%H %M %S,%z'

Format the current date and print in a table

> date now | date format -t '%Y-%m-%d_%H:%M:%S %z'

date

Use date to get the current date and time. Defaults to local timezone but you can get it in UTC too.

# Flags

--utc
  Returns the current date and time in UTC

--local
  Returns the current date and time in your local timezone

# Examples

> date
──────────┬────────
 year     │ 2020
 month    │ 6
 day      │ 21
 hour     │ 18
 minute   │ 3
 second   │ 43
 timezone │ -04:00
──────────┴────────
> date --utc
──────────┬──────
 year     │ 2020
 month    │ 6
 day      │ 21
 hour     │ 22
 minute   │ 3
 second   │ 53
 timezone │ UTC
──────────┴──────
> date --local
──────────┬────────
 year     │ 2020
 month    │ 6
 day      │ 21
 hour     │ 18
 minute   │ 4
 second   │ 3
 timezone │ -04:00
──────────┴────────

debug

debug prints a debugging view of the table data. It is useful when you want to get the specific types of the data and while investigating errors.

# Examples

> ls | first 2 | debug
───┬──────────────────────────────────────────
 # │
───┼──────────────────────────────────────────
 0(name=".azure"type="Dir"size=nothing
   │ modified=2020-02-09T05:31:39.950305440Z((B
   │ mdate))
 1(name=".cargo"type="Dir"size=nothing
   │ modified=2020-01-06T05:45:30.933303081Z((B
   │ mdate))
───┴──────────────────────────────────────────
> ls | last 8 | get type | debug
───┬───────────────────────
 # │
───┼───────────────────────
 0"Dir"
 1"Dir"
 2"File"
 3"Dir"
 4"File"
 5"Dir"
 6"Dir"
 7"Dir"
───┴───────────────────────
> open --raw Cargo.toml | size | debug
(lines=139 words=560 chars=4607 bytes=4607)
> du src/ | debug
(path="src"(path)
 apparent=705300(bytesize)
 physical=1118208(bytesize)
 directories=[(path="src/utils"(path) apparent=21203(bytesize) physical=24576(bytesize))
  (path="src/data"(path)
   apparent=52860(bytesize)
   physical=86016(bytesize)
   directories=[(path="src/data/config"(path) apparent=2609(bytesize) physical=12288(bytesize))
    (path="src/data/base"(path) apparent=12627(bytesize) physical=16384(bytesize))])
  (path="src/env"(path) apparent=30257(bytesize) physical=36864(bytesize))
  (path="src/plugins"(path) apparent=1358(bytesize) physical=49152(bytesize))
  (path="src/commands"(path)
   apparent=412617(bytesize)
   physical=651264(bytesize)
   directories=[(path="src/commands/classified"(path) apparent=37125(bytesize) physical=49152(bytesize))])
  (path="src/evaluate"(path) apparent=11475(bytesize) physical=24576(bytesize))
  (path="src/format"(path) apparent=15426(bytesize) physical=24576(bytesize))
  (path="src/shell"(path) apparent=81093(bytesize) physical=94208(bytesize))])

default

This command sets a default row's column if missing. Other commands are capable of feeding default with their output through pipelines.

# Usage

> [input-command] | default [column-name] [column-value]

# Examples

Let's say we have a table like this:

> open contacts.json
━━━┯━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━
 # │ name     │ email
───┼──────────┼──────────────────
 0 │ paul     │ paul@example.com
 1 │ andres   │
 2 │ jonathan │
━━━┷━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━

default allows us to fill email column with a default value:

> open contacts.json | default email "no-reply@example.com"
━━━┯━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━
 # │ name     │ email
───┼──────────┼──────────────────────
 0 │ paul     │ paul@example.com
 1 │ andres   │ no-reply@example.com
 2 │ jonathan │ no-reply@example.com
━━━┷━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━

def

Use def to create a custom command.

# Examples

> def my_command [] { echo hi nu }
> my_command
hi nu
> def my_command [adjective: string, num: int] { echo $adjective $num meet nu }
> my_command nice 2
nice 2 meet nu
def my_cookie_daemon [
    in: path             # Specify where the cookie daemon shall look for cookies :p
    ...rest: path        # Other places to consider for cookie supplies
    --output (-o): path  # Where to store leftovers
    --verbose
] {
    echo $in $rest | each { eat $it }
    ...
}
my_cookie_daemon /home/bob /home/alice --output /home/mallory

Further (and non trivial) examples can be found in our nushell scripts repo (opens new window)

# Syntax

The syntax of the def command is as follows. def <name> <signature> <block>

The signature is a list of parameters flags and at maximum one rest argument. You can specify the type of each of them by appending : <type>. Example:

def cmd [
parameter: string
--flag: int
...rest: path
] { ... }

It is possible to comment them by appending # Comment text! Example

def cmd [
parameter # Parameter comment
--flag: int # Flag comment
...rest: path # Rest comment
] { ... }

Flags can have a single character shorthand form. For example --output is often abbreviated by -o. You can declare a shorthand by writing (-<shorthand>) after the flag name. Example

def cmd [
--flag(-f): int # Flag comment
] { ... }

You can make a parameter optional by adding ? to its name. Optional parameters do not need to be passed. (TODO Handling optional parameters in scripts is WIP. Please don't expect it to work seamlessly)

def cmd [
parameter?: path # Optional parameter
] { ... }

describe

Describes the objects in the stream.

# Usage

> describe {flags} 

# Flags

  • -h, --help: Display this help message

drop column

Remove the last number of columns. If you want to remove columns by name, try 'reject'.

# Usage

> drop column (columns) {flags} 

# Parameters

  • (columns) starting from the end, the number of columns to remove

# Flags

  • -h, --help: Display this help message

# Examples

Remove the last column of a table

> echo [[lib, extension]; [nu-lib, rs] [nu-core, rb]] | drop column

do

Runs a block, optionally ignoring errors.

# Usage

> do <block> ...args {flags} 

# Parameters

  • <block> the block to run
  • ...args: the parameter(s) for the block

# Flags

  • -h, --help: Display this help message
  • -i, --ignore-errors: ignore errors as the block runs

# Examples

Run the block

> do { echo hello }

Run the block and ignore errors

> do -i { thisisnotarealcommand }

Run the block with a parameter

> do { |x| $x + 100 } 55

drop

Remove the last number of rows or columns.

# Usage

> drop (rows) <subcommand> {flags} 

# Subcommands

  • drop column - Remove the last number of columns. If you want to remove columns by name, try 'reject'.

# Parameters

  • (rows) starting from the back, the number of rows to remove

# Flags

  • -h, --help: Display this help message

# Examples

Remove the last item of a list/table

> echo [1 2 3] | drop

Remove the last 2 items of a list/table

> echo [1 2 3] | drop 2

du

du stands for disk usage. It will give you the physical and apparent size of files and folders

# Examples

> du src/commands
─────────────┬────────────────────────────
 path        │ crates/nu-cli/src/commands
 apparent    │ 655.9 KB
 physical    │ 950.3 KB
 directories │ [table 5 rows]
 files       │
─────────────┴────────────────────────────
> du -a src/commands
─────────────┬────────────────────────────
 path        │ crates/nu-cli/src/commands
 apparent    │ 655.9 KB
 physical    │ 950.3 KB
 directories │ [table 5 rows]
 files       │ [table 118 rows]
─────────────┴────────────────────────────
> du *.rs
───┬──────────┬──────────┬──────────
 # │ path     │ apparent │ physical
───┼──────────┼──────────┼──────────
 0 │ build.rs │     78 B │   4.1 KB
───┴──────────┴──────────┴──────────

each group

Runs a block on groups of group_size rows of a table at a time.

# Usage

> each group <group_size> <block> {flags} 

# Parameters

  • <group_size> the size of each group
  • <block> the block to run on each group

# Flags

  • -h, --help: Display this help message

# Examples

Echo the sum of each pair

> echo [1 2 3 4] | each group 2 { echo $it | math sum }

each window

Runs a block on sliding windows of window_size rows of a table at a time.

# Usage

> each window <window_size> <block> {flags} 

# Parameters

  • <window_size> the size of each window
  • <block> the block to run on each group

# Flags

  • -h, --help: Display this help message
  • -s, --stride : the number of rows to slide over between windows

# Examples

Echo the sum of each window

> echo [1 2 3 4] | each window 2 { echo $it | math sum }

each

Run a block on each row of the table.

# Usage

> each <block> <subcommand> {flags} 

# Subcommands

  • each group - Runs a block on groups of group_size rows of a table at a time.
  • each window - Runs a block on sliding windows of window_size rows of a table at a time.

# Parameters

  • <block> the block to run on each row

# Flags

  • -h, --help: Display this help message
  • -n, --numbered: returned a numbered item ($it.index and $it.item)

# Examples

Echo the sum of each row

> echo [[1 2] [3 4]] | each { echo $it | math sum }

Echo the square of each integer

> echo [1 2 3] | each { echo ($it * $it) }

Number each item and echo a message

> echo ['bob' 'fred'] | each --numbered { echo $"($it.index) is ($it.item)" }

Name the block variable that each uses

> [1, 2, 3] | each {|x| $x + 100}

echo

Use echo to repeat arguments back to the user

# Examples

> echo Hello world
───┬───────
 # │
───┼───────
 0 │ Hello
 1 │ world
───┴───────
> echo "Hello, world!"
Hello, world!

enter

This command creates a new shell and begin at this path.

# Examples

/home/foobar> cat user.json
{
    "Name": "Peter",
    "Age": 30,
    "Telephone": 88204828,
    "Country": "Singapore"
}
/home/foobar> enter user.json
/> ls
━━━━━━━┯━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━
 Name  │ Age │ Telephone │ Country
───────┼─────┼───────────┼───────────
 Peter │  3088204828 │ Singapore
━━━━━━━┷━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━
/> exit
/home/foobar>

It also provides the ability to work with multiple directories at the same time. This command will allow you to create a new "shell" and enter it at the specified path. You can toggle between this new shell and the original shell with the p (for previous) and n (for next), allowing you to navigate around a ring buffer of shells. Once you're done with a shell, you can exit it and remove it from the ring buffer.

/> enter /tmp
/tmp> enter /usr
/usr> enter /bin
/bin> enter /opt
/opt> p
/bin> p
/usr> p
/tmp> p
/> n
/tmp>

# Note

If you enter a JSON file with multiple a top-level list, this will open one new shell for each list element.

/private/tmp> printf "1\\n2\\n3\\n" | lines | save foo.json
/private/tmp> enter foo.json
/> shells
───┬────────┬─────────────────────────┬──────────────
 # │ active │ name                    │ path
───┼────────┼─────────────────────────┼──────────────
 0 │        │ filesystem              │ /private/tmp
 1 │        │ {/private/tmp/foo.json} │ /
 2 │        │ {/private/tmp/foo.json} │ /
 3 │ X      │ {/private/tmp/foo.json} │ /
───┴────────┴─────────────────────────┴──────────────
/>

empty

Check for empty values. Pass the column names to check emptiness. Optionally pass a block as the last parameter if setting contents to empty columns is wanted.

# Examples

Check if a value is empty

> echo '' | empty?
true

Given the following meals

> echo [[meal size]; [arepa small] [taco '']]
═══╦═══════╦═══════
 # ║ meal  ║ size
═══╬═══════╬═══════
 0 ║ arepa ║ small
 1 ║ taco  ║
═══╩═══════╩═══════

Show the empty contents

> echo [[meal size]; [arepa small] [taco '']] | empty? meal size
═══╦═══════╦═══════
 # ║ meal  ║ size
═══╬═══════╬═══════
 0falsefalse
 1falsetrue
═══╩═══════╩═══════

Let's assume we have a report of totals per day. For simplicity we show just for three days 2020/04/16, 2020/07/10, and 2020/11/16. Like so

> echo [[2020/04/16 2020/07/10 2020/11/16]; ['' 27 37]]
═══╦════════════╦════════════╦════════════
 # ║ 2020/04/16 ║ 2020/07/10 ║ 2020/11/16
═══╬════════════╬════════════╬════════════
 0 ║            ║         2737
═══╩════════════╩════════════╩════════════

In the future, the report now has many totals logged per day. In this example, we have 1 total for the day 2020/07/10 and 2020/11/16 like so

> echo [[2020/04/16 2020/07/10 2020/11/16]; ['' [27] [37]]]
═══╦════════════╦════════════════╦════════════════
 # ║ 2020/04/16 ║ 2020/07/10     ║ 2020/11/16
═══╬════════════╬════════════════╬════════════════
 0 ║            ║ [table 1 rows][table 1 rows]
═══╩════════════╩════════════════╩════════════════

We want to add two totals (numbers 33 and 37) for the day 2020/04/16

Set a table with two numbers for the empty column

> echo [[2020/04/16 2020/07/10 2020/11/16]; ['' [27] [37]]] | empty? 2020/04/16 { [33 37] }
═══╦════════════════╦════════════════╦════════════════
 # ║ 2020/04/16     ║ 2020/07/10     ║ 2020/11/16
═══╬════════════════╬════════════════╬════════════════
 0[table 2 rows][table 1 rows][table 1 rows]
═══╩════════════════╩════════════════╩════════════════

Checking all the numbers

> echo [[2020/04/16 2020/07/10 2020/11/16]; ['' [27] [37]]] | empty? 2020/04/16 { [33 37] } | pivot _ totals | get totals
═══╦════
 033
 137
 227
 337
═══╩════

exec

Execute command.

# Usage

> exec <command> ...args {flags} 

# Parameters

  • <command> the command to execute
  • ...args: any additional arguments for command

# Flags

  • -h, --help: Display this help message

# Examples

Execute 'ps aux'

> exec ps aux

Execute 'nautilus'

> exec nautilus

every

Selects every n-th row of a table, starting from the first one. With the --skip flag, every n-th row will be skipped, inverting the original functionality.

Syntax: > [input-command] | every <stride> {flags}

# Flags

  • --skip, -s: Skip the rows that would be returned, instead of selecting them

# Examples

> open contacts.csv
───┬─────────┬──────┬─────────────────
 # │ first   │ last │ email
───┼─────────┼──────┼─────────────────
 0 │ John    │ Doe  │ doe.1@email.com
 1 │ Jane    │ Doe  │ doe.2@email.com
 2 │ Chris   │ Doe  │ doe.3@email.com
 3 │ Francis │ Doe  │ doe.4@email.com
 4 │ Stella  │ Doe  │ doe.5@email.com
───┴─────────┴──────┴─────────────────
> open contacts.csv | every 2
───┬─────────┬──────┬─────────────────
 # │ first   │ last │ email
───┼─────────┼──────┼─────────────────
 0 │ John    │ Doe  │ doe.1@email.com
 2 │ Chris   │ Doe  │ doe.3@email.com
 4 │ Stella  │ Doe  │ doe.5@email.com
───┴─────────┴──────┴─────────────────
> open contacts.csv | every 2 --skip
───┬─────────┬──────┬─────────────────
 # │ first   │ last │ email
───┼─────────┼──────┼─────────────────
 1 │ Jane    │ Doe  │ doe.2@email.com
 3 │ Francis │ Doe  │ doe.4@email.com
───┴─────────┴──────┴─────────────────

flatten

Flatten the table.

# Usage

> flatten ...args {flags} 

# Parameters

  • ...args: optionally flatten data by column

# Flags

  • -h, --help: Display this help message

# Examples

  • flatten a table
> echo [[N, u, s, h, e, l, l]] | flatten | first
  • flatten a column having a nested table
> echo [[origin, people]; [Ecuador, (echo [[name, meal]; ['Andres', 'arepa']])]] | flatten | get meal

restrict the flattening by passing column names

> echo [[origin, crate, versions]; [World, (echo [[name]; ['nu-cli']]), ['0.21', '0.22']]] | flatten versions | last | get versions

for

Run a block on each row of the table.

# Usage

> for <var> <in> <value> <block> {flags} 

# Parameters

  • <var> the name of the variable
  • <in> the word 'in'
  • <value> the value we want to iterate
  • <block> the block to run on each item

# Flags

  • -h, --help: Display this help message
  • -n, --numbered: returned a numbered item ($it.index and $it.item)

# Examples

Echo the square of each integer

> for x in [1 2 3] { $x * $x }

Work with elements of a range

> for $x in 1..3 { $x }

Number each item and echo a message

> for $it in ['bob' 'fred'] --numbered { $"($it.index) is ($it.item)" }

format filesize

Converts a column of filesizes to some specified format

# Usage

> format filesize <field> <format value> {flags} 

# Parameters

  • <field> the name of the column to update the format into which convert the filesizes

# Flags

  • -h, --help: Display this help message

# Examples

Convert the size row to KB

> ls | format filesize size KB

Convert the apparent row to B

> du | format filesize apparent B

from bson

Convert from .bson binary into table

# Usage

> from bson {flags} 

# Flags

  • -h, --help: Display this help message

format

Format columns into a string using a simple pattern

Syntax: format <pattern>

# Parameters

  • <pattern>: the pattern to match

# Example

Let's say we have a table like this:

> open pets.csv
━━━┯━━━━━━━━━━━┯━━━━━━━━┯━━━━━
 # │ animal    │ name   │ age
───┼───────────┼────────┼─────
 0cat       │ Tom    │ 7
 1 │ dog       │ Alfred │ 10
 2 │ chameleon │ Linda  │ 1
━━━┷━━━━━━━━━━━┷━━━━━━━━┷━━━━━

format allows us to convert table data into a string by following a formatting pattern. To print the value of a column we have to put the column name in curly brackets:

> open pets.csv | format "{name} is a {age} year old {animal}"
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │
───┼─────────────────────────────────
 0 │ Tom is a 7 year old cat
 1 │ Alfred is a 10 year old dog
 2 │ Linda is a 1 year old chameleon
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

from eml

Parse text as .eml and create table.

# Usage

> from eml {flags} 

# Flags

  • -h, --help: Display this help message
  • -b, --preview-body : How many bytes of the body to preview

from ini

Converts ini data into table. Use this when nushell cannot determine the input file extension.

# Example

Let's say we have the following .txt file:

> open sample.txt
[SectionOne]

key = value
integer = 1234
string1 = 'Case 1'

This file is actually a ini file, but the file extension isn't .ini. That's okay, we can use the from ini command:

> open sample.txt | from ini | get SectionOne
━━━━━━━┯━━━━━━━━━┯━━━━━━━━━━
 key   │ integer │ string1
───────┼─────────┼──────────
 value │ 1234'Case 1'
━━━━━━━┷━━━━━━━━━┷━━━━━━━━━━

from csv

Converts csv data into table. Use this when nushell cannot determine the input file extension.

# Example

Let's say we have the following file:

> cat pets.txt
animal, name, age
cat, Tom, 7
dog, Alfred, 10
chameleon, Linda, 1

pets.txt is actually a .csv file but it has the .txt extension, open is not able to convert it into a table:

> open pets.txt
animal, name, age
cat, Tom, 7
dog, Alfred, 10
chameleon, Linda, 1

To get a table from pets.txt we need to use the from csv command:

> open pets.txt | from csv
━━━┯━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━
 # │ animal    │  name   │  age
───┼───────────┼─────────┼──────
 0cat       │  Tom    │  7
 1 │ dog       │  Alfred │  10
 2 │ chameleon │  Linda  │  1
━━━┷━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━

To ignore the csv headers use --headerless:

━━━┯━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━━━━
 # │ Column1   │ Column2 │ Column3
───┼───────────┼─────────┼─────────
 0 │ dog       │  Alfred │  10
 1 │ chameleon │  Linda  │  1
━━━┷━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━━━━

To split on a character other than ',' use --separator:

> open pets.txt
animal; name; age
cat; Tom; 7
dog; Alfred; 10
chameleon; Linda; 1
> open pets.txt | from csv --separator ';'
━━━┯━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━
 # │ animal    │  name   │  age
───┼───────────┼─────────┼──────
 0cat       │  Tom    │  7
 1 │ dog       │  Alfred │  10
 2 │ chameleon │  Linda  │  1
━━━┷━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━

To use this command to open a csv with separators other than a comma, use the --raw switch of open to open the csv, otherwise the csv will enter from csv as a table split on commas rather than raw text.

> mv pets.txt pets.csv
> open pets.csv | from csv --separator ';'
error: Expected a string from pipeline
- shell:1:16
1 | open pets.csv | from csv --separator ';'
  |                 ^^^^^^^^ requires string input
- shell:1:0
1 | open pets.csv | from csv --separator ';'
  |  value originates from here

> open pets.csv --raw | from csv --separator ';'
━━━┯━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━
 # │ animal    │  name   │  age
───┼───────────┼─────────┼──────
 0cat       │  Tom    │  7
 1 │ dog       │  Alfred │  10
 2 │ chameleon │  Linda  │  1
━━━┷━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━

The string '\t' can be used to separate on tabs. Note that this is the same as using the from tsv command.

Newlines '\n' are not acceptable separators.

Note that separators are currently provided as strings and need to be wrapped in quotes.

> open pets.csv --raw | from csv --separator ;
- shell:1:43
1 | open pets.csv --raw | from csv --separator ;
  |                                            ^

It is also considered an error to use a separator greater than one char:

> open pets.txt | from csv --separator '123'
error: Expected a single separator char from --separator
- shell:1:37
1 | open pets.txt | from csv --separator '123'
  |                                      ^^^^^ requires a single character string input

from json

Parse text as .json and create table. Use this when nushell cannot determine the input file extension.

Syntax: from json {flags}

# Flags

--objects
  treat each line as a separate value

# Examples

> open command_from-json
[
    {
        title: "from json",
        type: "command",
        flags: true
    }
]
> open command_from-json | from json
━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━━
 title     │ type    │ flags
───────────┼─────────┼───────
 from json │ commandtrue
━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━━

from ics

Parse text as .ics and create table.

Syntax: from ics

# Examples

Suppose calendar.txt is a text file that is formatted like a .ics (iCal) file:

> open calendar.txt
BEGIN:VCALENDAR
BEGIN:VEVENT
DTSTART:20171007T200000Z
DTEND:20171007T233000Z
DTSTAMP:20200319T182138Z
SUMMARY:Basketball Game
UID:4l80f6dcovnriq38g57g07btid@google.com
...

Pass the output of the open command to from ics to get a correctly formatted table:

> open calendar.txt | from ics
───┬────────────────┬──────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────
 # │ properties     │ events           │ alarms         │ to-Dos         │ journals       │ free-busys     │ timezones
───┼────────────────┼──────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────
 0[table 0 rows][table 1 row][table 0 rows][table 0 rows][table 0 rows][table 0 rows][table 0 rows]
───┴────────────────┴──────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────
> open calendar.txt | from ics | get events | get properties | where name == "SUMMARY"
─────┬─────────┬───────────────────────────────────────┬────────
 #   │ name    │ value                                 │ params
─────┼─────────┼───────────────────────────────────────┼────────
   0 │ SUMMARY │ Basketball Game                       │

from ods

Parses OpenDocument Spreadsheet binary data into a table. open calls from ods automatically when the file extension is ods. Use this command when open is unable to guess the file type from the extension.

# Examples

> open abc.ods
─────────────────
 Sheet1
─────────────────
 [table 26 rows]
─────────────────
> open abc.ods --raw
Length: 4816 (0x12d0) bytes
0000:   50 4b 03 04  14 00 00 00  00 00 00 00  00 00 85 6c   PK.............l
0010:   39 8a 2e 00  00 00 2e 00  00 00 08 00  00 00 6d 69   9.............mi
0020:   6d 65 74 79  70 65 61 70  70 6c 69 63  61 74 69 6f   metypeapplicatio
...
12a0:   00 61 10 00  00 4d 45 54  41 2d 49 4e  46 2f 6d 61   .a...META-INF/ma
12b0:   6e 69 66 65  73 74 2e 78  6d 6c 50 4b  05 06 00 00   nifest.xmlPK....
12c0:   00 00 06 00  06 00 5a 01  00 00 60 11  00 00 00 00   ......Z...`.....
> open abc.ods --raw | from ods
─────────────────
 Sheet1
─────────────────
 [table 26 rows]
─────────────────

from ssv

Parse text as space-separated values and create a table. The default minimum number of spaces counted as a separator is 2.

# Usage

> from ssv {flags} 

# Flags

  • -h, --help: Display this help message
  • -n, --noheaders: don't treat the first row as column names
  • -a, --aligned-columns: assume columns are aligned
  • -m, --minimum-spaces : the minimum spaces to separate columns

from sqlite

Convert from sqlite binary into table

# Usage

> from sqlite {flags} 

# Flags

  • -h, --help: Display this help message

from toml

Converts toml data into table. Use this when nushell cannot determine the input file extension.

# Example

Let's say we have the following Rust .lock file:

> open Cargo.lock
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.                                   [[package]]                                                                name = "adler32"                                                           version = "1.0.3"                                                          source = "registry+https://github.com/rust-lang/crates.io-index"
...

The "Cargo.lock" file is actually a .toml file, but the file extension isn't .toml. That's okay, we can use the from toml command:

> open Cargo.lock | from toml
─────────┬──────────────────
 package │ [table 459 rows]
─────────┴──────────────────

from url

Parse url-encoded string (opens new window) as a table.

# Example

> echo 'bread=baguette&cheese=comt%C3%A9&meat=ham&fat=butter' | from url
────────┬──────────
 bread  │ baguette
 cheese │ comté
 meat   │ ham
 fat    │ butter
────────┴──────────

from tsv

Parse text as .tsv and create table.

Syntax: from tsv {flags}

# Flags

--headerless
  don't treat the first row as column names

# Examples

Let's say we have the following file which is formatted like a tsv file:

> open elements.txt
Symbol        Element
H        Hydrogen
He        Helium
Li        Lithium
Be        Beryllium

If we pass the output of the open command to from tsv we get a correct formatted table:

> open elements.txt | from tsv
━━━┯━━━━━━━━┯━━━━━━━━━━━
 # │ Symbol │ Element
───┼────────┼───────────
 0 │ H      │ Hydrogen
 1 │ He     │ Helium
 2 │ Li     │ Lithium
 3 │ Be     │ Beryllium
━━━┷━━━━━━━━┷━━━━━━━━━━━

Using the --headerless flag has the following output:

> open elements.txt | from tsv --headerless
━━━━┯━━━━━━━━━┯━━━━━━━━━━━
 #  │ Column1 │ Column2
────┼─────────┼───────────
  0 │ Symbol  │ Element
  1 │ H       │ Hydrogen
  2 │ He      │ Helium
  3 │ Li      │ Lithium
  4 │ Be      │ Beryllium
━━━━┷━━━━━━━━━┷━━━━━━━━━━━

from vcf

Parse text as .vcf and create table.

Syntax: from vcf

# Examples

Suppose contacts.txt is a text file that is formatted like a .vcf (vCard) file:

> open contacts.txt
BEGIN:VCARD
VERSION:3.0
FN:John Doe
N:Doe;John;;;
EMAIL;TYPE=INTERNET:john.doe99@gmail.com
...

Pass the output of the open command to from vcf to get a correctly formatted table:

> open contacts.txt | from vcf
─────┬─────────────────
 #   │ properties
─────┼─────────────────
   0[table 8 rows]
> open contacts.txt | from vcf | get properties | where $it.name == "FN" | select value
─────┬──────────────────────
 #   │
─────┼──────────────────────
   0 │ John Doe

from xml

Parse text as .xml and create table. Use this when nushell cannot determine the input file extension.

Syntax: from xml

# Examples

Let's say we've got a file in xml format but the file extension is different so Nu can't auto-format it:

> open world.txt
<?xml version="1.0" encoding="utf-8"?>
<world>
    <continent>Africa</continent>
    <continent>Antarctica</continent>
    <continent>Asia</continent>
    <continent>Australia</continent>
    <continent>Europe</continent>
    <continent>North America</continent>
    <continent>South America</continent>
</world>

We can use from xml to read the input like a xml file:

> open world.txt | from xml
━━━━━━━━━━━━━━━━
 world
────────────────
 [table 7 rows]
━━━━━━━━━━━━━━━━

from xlsx

Parses MS Excel binary data into a table. open calls from xlsx automatically when the file extension is xlsx. Use this command when open is unable to guess the file type from the extension.

# Examples

> open abc.xlsx
─────────────────
 Sheet1
─────────────────
 [table 26 rows]
─────────────────
> open abc.xlsx --raw
Length: 6344 (0x18c8) bytes
0000:   50 4b 03 04  14 00 00 00  08 00 00 00  00 00 d5 5f   PK............._
0010:   a7 48 68 01  00 00 23 05  00 00 13 00  00 00 5b 43   .Hh...#.......[C
0020:   6f 6e 74 65  6e 74 5f 54  79 70 65 73  5d 2e 78 6d   ontent_Types].xm
...
18a0:   6b 73 68 65  65 74 73 2f  73 68 65 65  74 31 2e 78   ksheets/sheet1.x
18b0:   6d 6c 50 4b  05 06 00 00  00 00 0a 00  0a 00 7f 02   mlPK............
18c0:   00 00 33 16  00 00 00 00                             ..3.....
> open abc.xlsx --raw | from xlsx
─────────────────
 Sheet1
─────────────────
 [table 26 rows]
─────────────────

from yaml

Parse text as .yaml/.yml and create table. Use this when nushell cannot determine the input file extension.

Syntax: from yaml

# Examples

> open command_from-yaml
title: from-yaml
type: command
flags: false
> open command_from-yaml | from yaml
━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━━
 title     │ type    │ flags
───────────┼─────────┼───────
 from-yaml │ command │ No
━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━━

from yml

Parse text as .yaml/.yml and create table.

# Usage

> from yml {flags} 

# Flags

  • -h, --help: Display this help message

from

Converts content (string or binary) into a table. The source format is specified as a subcommand, like from csv or from json.

Use this when nushell cannot determine the input file extension.

# Available Subcommands

Subcommands without links are currently missing their documentation.

# Example for from csv

Let's say we have the following file:

> cat pets.txt
animal, name, age
cat, Tom, 7
dog, Alfred, 10
chameleon, Linda, 1

pets.txt is actually a .csv file but it has the .txt extension, open is not able to convert it into a table:

> open pets.txt
animal, name, age
cat, Tom, 7
dog, Alfred, 10
chameleon, Linda, 1

To get a table from pets.txt we need to use the from csv command:

> open pets.txt | from csv
━━━┯━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━
 # │ animal    │  name   │  age
───┼───────────┼─────────┼──────
 0cat       │  Tom    │  7
 1 │ dog       │  Alfred │  10
 2 │ chameleon │  Linda  │  1
━━━┷━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━

group-by date

# group-by date

creates a table grouped by date.

# Usage

> group-by date (column_name) {flags} 

# Parameters

  • (column_name) the name of the column to group by

# Flags

  • -h, --help: Display this help message
  • -f, --format : Specify date and time formatting

# Examples

Group files by type

> ls | group-by date --format '%d/%m/%Y'

get

Open given cells as text.

Syntax: get ...args

# Parameters

  • args: optionally return additional data by path

# Examples

If we run sys we receive a table which contains tables itself:

> sys
─────────┬─────────────────────────────────────────
 host[row 7 columns]
 cpu     │ [row cores current ghz max ghz min ghz]
 disks   │ [table 4 rows]
 mem     │ [row free swap free swap total total]
 net     │ [table 19 rows]
 battery │ [table 1 rows]
─────────┴─────────────────────────────────────────

To access one of the embedded tables we can use the get command

> sys | get cpu
─────────────┬────────
 cores       │ 16
 current ghz │ 2.4000
 min ghz     │ 2.4000
 max ghz     │ 2.4000
─────────────┴────────
> sys | get battery
───────────────┬──────────
 vendor        │ DSY
 model         │ bq40z651
 cycles        │ 43
 mins to empty │ 70.0000
───────────────┴──────────

There's also the ability to pass multiple parameters to get which results in an output like this

sys | get cpu battery
───┬───────┬─────────────┬─────────┬─────────
 # │ cores │ current ghz │ min ghz │ max ghz
───┼───────┼─────────────┼─────────┼─────────
 0162.40002.40002.4000
───┴───────┴─────────────┴─────────┴─────────
───┬────────┬──────────┬────────┬───────────────
 # │ vendor │ model    │ cycles │ mins to empty
───┼────────┼──────────┼────────┼───────────────
 1 │ DSY    │ bq40z651 │     4370.0000
───┴────────┴──────────┴────────┴───────────────

hash base64

base64 encode or decode a value

# Usage

> hash base64 ...args {flags} 

# Parameters

  • ...args: optionally base64 encode / decode data by column paths

# Flags

  • -h, --help: Display this help message
  • -c, --character_set : specify the character rules for encoding the input. Valid values are 'standard', 'standard-no-padding', 'url-safe', 'url-safe-no-padding','binhex', 'bcrypt', 'crypt'
  • -e, --encode: encode the input as base64. This is the default behavior if not specified.
  • -d, --decode: decode the input from base64

# Examples

Base64 encode a string with default settings

> echo 'username:password' | hash base64

Base64 encode a string with the binhex character set

> echo 'username:password' | hash base64 --character_set binhex --encode

Base64 decode a value

> echo 'dXNlcm5hbWU6cGFzc3dvcmQ=' | hash base64 --decode

group-by

# group-by

This command creates a new table with the data from the table rows grouped by the column given.

# Examples

Let's say we have this table of all countries in the world sorted by their population:

> open countries_by_population.json | from json | first 10
━━━┯━━━━━━┯━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━┯━━━━━━━━
 # │ rank │ country or area │ UN continental region │ UN statistical region │ population 2018 │ population 2019 │ change
───┼──────┼─────────────────┼───────────────────────┼───────────────────────┼─────────────────┼─────────────────┼────────
 01    │ China           │ Asia                  │ Eastern Asia          │ 1,427,647,786   │ 1,433,783,686   │ +0.4%
 12    │ India           │ Asia                  │ Southern Asia         │ 1,352,642,280   │ 1,366,417,754   │ +1.0%
 23    │ United States   │ Americas              │ Northern America      │ 327,096,265     │ 329,064,917     │ +0.6%
 34    │ Indonesia       │ Asia                  │ South-eastern Asia    │ 267,670,543     │ 270,625,568     │ +1.1%
 45    │ Pakistan        │ Asia                  │ Southern Asia         │ 212,228,286     │ 216,565,318     │ +2.0%
 56    │ Brazil          │ Americas              │ South America         │ 209,469,323     │ 211,049,527     │ +0.8%
 67    │ Nigeria         │ Africa                │ Western Africa        │ 195,874,683     │ 200,963,599     │ +2.6%
 78    │ Bangladesh      │ Asia                  │ Southern Asia         │ 161,376,708     │ 163,046,161     │ +1.0%
 89    │ Russia          │ Europe                │ Eastern Europe        │ 145,734,038     │ 145,872,256     │ +0.1%
 910   │ Mexico          │ Americas              │ Central America       │ 126,190,788     │ 127,575,529     │ +1.1%
━━━┷━━━━━━┷━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━┷━━━━━━━━

Here we have listed only the first 10 lines. In total this table has got 233 rows which is to big to get information easily out of it.

We can use the group-by command on 'UN statistical region' to create a table per continental region.

> open countries_by_population.json | from json | group-by "UN continental region"
━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━
 Asia             │ Americas         │ Africa           │ Europe           │ Oceania
──────────────────┼──────────────────┼──────────────────┼──────────────────┼──────────────────
 [table: 51 rows][table: 53 rows][table: 58 rows][table: 48 rows][table: 23 rows]
━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━

Now we can already get some information like "which continental regions are there" and "how many countries are in each region". If we want to see only the countries in the continental region of Oceania we can type:

> open countries_by_population.json | from json | group-by "UN continental region" | get Oceania
━━━━┯━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━┯━━━━━━━━
 #  │ rank │ country or area                │ UN continental region │ UN statistical region     │ population 2018 │ population 2019 │ change
────┼──────┼────────────────────────────────┼───────────────────────┼───────────────────────────┼─────────────────┼─────────────────┼────────
  055   │ Australia                      │ Oceania               │ Australia and New Zealand │ 24,898,152      │ 25,203,198      │ +1.2%
  198   │ Papua New Guinea               │ Oceania               │ Melanesia                 │ 8,606,323       │ 8,776,109       │ +2.0%
  2125  │ New Zealand                    │ Oceania               │ Australia and New Zealand │ 4,743,131       │ 4,783,063       │ +0.8%
  3161  │ Fiji                           │ Oceania               │ Melanesia                 │ 883,483889,953         │ +0.7%
  4166  │ Solomon Islands                │ Oceania               │ Melanesia                 │ 652,857669,823         │ +2.6%
  5181  │ Vanuatu                        │ Oceania               │ Melanesia                 │ 292,680299,882         │ +2.5%
  6183  │ New Caledonia                  │ Oceania               │ Melanesia                 │ 279,993282,750         │ +1.0%
  7185  │ French Polynesia               │ Oceania               │ Polynesia                 │ 277,679279,287         │ +0.6%
  8188  │ Samoa                          │ Oceania               │ Polynesia                 │ 196,129197,097         │ +0.5%
  9191  │ Guam                           │ Oceania               │ Micronesia                │ 165,768167,294         │ +0.9%
 10193  │ Kiribati                       │ Oceania               │ Micronesia                │ 115,847117,606         │ +1.5%
 11194  │ Federated States of Micronesia │ Oceania               │ Micronesia                │ 112,640113,815         │ +1.0%
 12196  │ Tonga                          │ Oceania               │ Polynesia                 │ 110,589110,940         │ +0.3%
 13207  │ Marshall Islands               │ Oceania               │ Micronesia                │ 58,41358,791          │ +0.6%
 14209  │ Northern Mariana Islands       │ Oceania               │ Micronesia                │ 56,88256,188          │ −1.2%
 15210  │ American Samoa                 │ Oceania               │ Polynesia                 │ 55,46555,312          │ −0.3%
 16221  │ Palau                          │ Oceania               │ Micronesia                │ 17,90718,008          │ +0.6%
 17222  │ Cook Islands                   │ Oceania               │ Polynesia                 │ 17,51817,548          │ +0.2%
 18224  │ Tuvalu                         │ Oceania               │ Polynesia                 │ 11,50811,646          │ +1.2%
 19225  │ Wallis and Futuna              │ Oceania               │ Polynesia                 │ 11,66111,432          │ −2.0%
 20226  │ Nauru                          │ Oceania               │ Micronesia                │ 10,67010,756          │ +0.8%
 21231  │ Niue                           │ Oceania               │ Polynesia                 │ 1,6201,615           │ −0.3%
 22232  │ Tokelau                        │ Oceania               │ Polynesia                 │ 1,3191,340           │ +1.6%
━━━━┷━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━┷━━━━━━━━

hash md5

md5 encode a value

# Usage

> hash md5 ...args {flags} 

# Parameters

  • ...args: optionally md5 encode data by column paths

# Flags

  • -h, --help: Display this help message

# Examples

md5 encode a string

> echo 'abcdefghijklmnopqrstuvwxyz' | hash md5

md5 encode a file

> open ./nu_0_24_1_windows.zip | hash md5

hash

Apply hash function.

# Usage

> hash ...args <subcommand> {flags} 

# Subcommands

  • hash base64 - base64 encode or decode a value
  • hash md5 - md5 encode a value

# Parameters

  • ...args: optionally convert by column paths

# Flags

  • -h, --help: Display this help message

headers

Use headers to turn the first row of a table into meaningful column names.

As demonstrated in the following example, it's particularly handy when working with spreadsheets.

# Examples

> open sample_data.ods | get SalesOrders
────┬────────────┬─────────┬──────────┬─────────┬─────────┬───────────┬───────────
 #  │  Column0   │ Column1 │ Column2  │ Column3 │ Column4 │  Column5  │  Column6
────┼────────────┼─────────┼──────────┼─────────┼─────────┼───────────┼───────────
  0 │ OrderDate  │ Region  │ Rep      │ Item    │ Units   │ Unit Cost │ Total
  12018-01-06 │ East    │ Jones    │ Pencil  │ 95.00001.9900189.0500
> open sample_data.ods | get SalesOrders | headers
────┬────────────┬─────────┬──────────┬─────────┬─────────┬───────────┬───────────
 #  │ OrderDate  │ Region  │   Rep    │  Item   │  Units  │ Unit Cost │   Total
────┼────────────┼─────────┼──────────┼─────────┼─────────┼───────────┼───────────
  02018-01-06 │ East    │ Jones    │ Pencil  │ 95.00001.9900189.0500
  12018-01-23 │ Central │ Kivell   │ Binder  │ 50.000019.9900999.4999

help

Use help for more information on a command. Use help commands to list all available commands. Use help <command name> to display help about a particular command.

# Examples

> help
Welcome to Nushell.

Here are some tips to help you get started.
  * help commands - list all available commands
  * help <command name> - display help about a particular command

Nushell works on the idea of a "pipeline". Pipelines are commands connected with the '|' character.
Each stage in the pipeline works together to load, parse, and display information to you.

[Examples]

List the files in the current directory, sorted by size:
    ls | sort-by size

Get information about the current system:
    sys | get host

Get the processes on your system actively using CPU:
    ps | where cpu > 0

You can also learn more at https://www.nushell.sh/book/
> help commands
────┬──────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 #  │ name         │ description
────┼──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 0alias        │ Define a shortcut for another command.
 1  │ append       │ Append the given row to the table
 2  │ autoview     │ View the contents of the pipeline as a table or list.
 3  │ build-string │ Builds a string from the arguments
 4cal          │ Display a calendar.
 5  │ calc         │ Parse a math expression into a number
...
 83 │ where        │ Filter table to match the condition.
 84which        │ Finds a program file.
 85 │ with-env     │ Runs a block with an environment set. Eg) with-env [NAME 'foo'] { echo $nu.env.NAME }
 86 │ wrap         │ Wraps the given data in a table.
────┴──────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
> help cd
Change to a new path.

Usage:
  > cd (directory) {flags}

Parameters:
  (directory) the directory to change to

Flags:
  -h, --help: Display this help message

Examples:
  Change to a new directory called 'dirname'
  > cd dirname

  Change to your home directory
  > cd

  Change to your home directory (alternate version)
  > cd ~

  Change to the previous directory
  > cd -

history

Displays the last 100 commands.

# Example

> history
─────┬────────────────────────────────────────────────────────────────────────
  #  │
─────┼────────────────────────────────────────────────────────────────────────
...
 97date
 98ls
 99ls -la
─────┴────────────────────────────────────────────────────────────────────────

if

Run blocks if a condition is true or false.

# Usage

> if <condition> <then_case> <else_case> {flags} 

# Parameters

  • <condition> the condition that must match
  • <then_case> block to run if condition is true
  • <else_case> block to run if condition is false

# Flags

  • -h, --help: Display this help message

# Examples

Run a block if a condition is true

> let x = 10; if $x > 5 { echo 'greater than 5' } { echo 'less than or equal to 5' }

Run a block if a condition is false

> let x = 1; if $x > 5 { echo 'greater than 5' } { echo 'less than or equal to 5' }

histogram

Creates a new table with a histogram based on the column name passed in.

Syntax: histogram <column_name> ...args

# Parameters

  • <column-name>: name of the column to graph by
  • args: column name to give the histogram's frequency column

# Examples

Let's say we have this file random_numers.csv which contains 50 random numbers.

Note: The input doesn't have to be numbers it works on strings too. Try it out.

> open random_numbers.csv
────┬────────────────
 #  │ random numbers
────┼────────────────
  05
  12
  20
...
 471
 481
 492
────┴────────────────

If we now want to see how often the different numbers were generated, we can use the histogram function:

> open random_numbers.csv | histogram "random numbers"
───┬────────────────┬─────────────┬────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────
 # │ random numbers │    count    │ percentage │ frequency
───┼────────────────┼─────────────┼────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
 00857.14%     │ *********************************************************
 1114100.00%    │ ****************************************************************************************************
 22964.29%     │ ****************************************************************
 33642.86%     │ ******************************************
 44321.43%     │ *********************
 551071.43%     │ ***********************************************************************
───┴────────────────┴─────────────┴────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────

We can also set the name of the second column or sort the table:

> open random_numbers.csv | histogram "random numbers" probability
───┬────────────────┬─────────────┬────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────
 # │ random numbers │    count    │ percentage │ probability
───┼────────────────┼─────────────┼────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
 00857.14%     │ *********************************************************
 1114100.00%    │ ****************************************************************************************************
 22964.29%     │ ****************************************************************
 33642.86%     │ ******************************************
 44321.43%     │ *********************
 551071.43%     │ ***********************************************************************
───┴────────────────┴─────────────┴────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────

> open random_numbers.csv | histogram "random numbers" probability | sort-by probability
───┬────────────────┬─────────────┬────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────
 # │ random numbers │    count    │ percentage │ probability
───┼────────────────┼─────────────┼────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
 04321.43%     │ *********************
 13642.86%     │ ******************************************
 20857.14%     │ *********************************************************
 32964.29%     │ ****************************************************************
 451071.43%     │ ***********************************************************************
 5114100.00%    │ ****************************************************************************************************
───┴────────────────┴─────────────┴────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────

Of course, histogram operations are not restricted to just analyzing numbers in files, you can also analyze your directories

> ls -la | histogram type | sort-by count
───┬─────────┬─────────────┬────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────
 # │ type    │    count    │ percentage │ frequency
───┼─────────┼─────────────┼────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
 0 │ Dir     │           54.76%      │ ****
 1 │ Symlink │          2826.67%     │ **************************
 2 │ File    │         105100.00%    │ ****************************************************************************************************
───┴─────────┴─────────────┴────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────

inc

This command increments the value of variable by one.

# Examples

> open rustfmt.toml
─────────┬──────
 edition │ 2018
─────────┴──────
> open rustfmt.toml | inc edition
─────────┬──────
 edition │ 2019
─────────┴──────
> open Cargo.toml | get package.version
0.15.1
> open Cargo.toml | inc package.version --major | get package.version
1.0.0
> open Cargo.toml | inc package.version --minor | get package.version
0.16.0
> open Cargo.toml | inc package.version --patch | get package.version
0.15.2

insert

This command adds a column to any table output. The first parameter takes the heading, the second parameter takes the value for all the rows.

# Examples

> ls | insert is_on_a_computer yes_obviously
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━
 # │ name                       │ type │ readonly │ size   │ accessed  │ modified  │ is_on_a_computer
───┼────────────────────────────┼──────┼──────────┼────────┼───────────┼───────────┼──────────────────
 0 │ zeusiscrazy.txt            │ File │          │ 556 B  │ a day ago │ a day ago │ yes_obviously
 1 │ coww.txt                   │ File │          │  24 B  │ a day ago │ a day ago │ yes_obviously
 2 │ randomweirdstuff.txt       │ File │          │ 197 B  │ a day ago │ a day ago │ yes_obviously
 3 │ abaracadabra.txt           │ File │          │ 401 B  │ a day ago │ a day ago │ yes_obviously
 4 │ youshouldeatmorecereal.txt │ File │          │ 768 B  │ a day ago │ a day ago │ yes_obviously
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━
> shells | insert os linux_on_this_machine
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path                           │ os
───┼───┼────────────┼────────────────────────────────┼───────────────────────
 0 │ X │ filesystem │ /home/shaurya/stuff/expr/stuff │ linux_on_this_machine
 1 │   │ filesystem │ /                              │ linux_on_this_machine
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━

into binary

Convert value to a binary primitive

# Usage

> into binary ...args {flags} 

# Parameters

  • ...args: column paths to convert to binary (for table input)

# Flags

  • -h, --help: Display this help message
  • -s, --skip : skip x number of bytes
  • -b, --bytes : show y number of bytes

# Examples

convert string to a nushell binary primitive

> echo 'This is a string that is exactly 52 characters long.' | into binary

convert string to a nushell binary primitive

> echo 'This is a string that is exactly 52 characters long.' | into binary --skip 10

convert string to a nushell binary primitive

> echo 'This is a string that is exactly 52 characters long.' | into binary --skip 10 --bytes 10

convert a number to a nushell binary primitive

> echo 1 | into binary

convert a boolean to a nushell binary primitive

> echo $true | into binary

convert a filesize to a nushell binary primitive

> ls | where name == LICENSE | get size | into binary

convert a filepath to a nushell binary primitive

> ls | where name == LICENSE | get name | path expand | into binary

convert a decimal to a nushell binary primitive

> echo 1.234 | into binary

into int

Convert value to integer

# Usage

> into int ...args {flags} 

# Parameters

  • ...args: column paths to convert to int (for table input)

# Flags

  • -h, --help: Display this help message

# Examples

Convert string to integer in table

> echo [[num]; ['-5'] [4] [1.5]] | into int num

Convert string to integer

> echo '2' | into int

Convert decimal to integer

> echo 5.9 | into int

Convert decimal string to integer

> echo '5.9' | into int

Convert file size to integer

> echo 4KB | into int

Convert bool to integer

> echo $false $true | into int

into string

Convert value to string

# Usage

> into string ...args {flags} 

# Parameters

  • ...args: column paths to convert to string (for table input)

# Flags

  • -h, --help: Display this help message
  • -d, --decimals : decimal digits to which to round

# Examples

convert decimal to string and round to nearest integer

> echo 1.7 | into string -d 0

convert decimal to string

> echo 4.3 | into string

convert string to string

> echo '1234' | into string

convert boolean to string

> echo $true | into string

convert date to string

> date now | into string

convert filepath to string

> ls Cargo.toml | get name | into string

convert filesize to string

> ls Cargo.toml | get size | into string

into

Apply into function.

# Usage

> into <subcommand> {flags} 

# Subcommands

  • into binary - Convert value to a binary primitive
  • into int - Convert value to integer
  • into string - Convert value to string

# Flags

  • -h, --help: Display this help message

keep until

Keeps rows until the condition matches.

# Usage

> keep until <condition> {flags} 

# Parameters

  • <condition> The condition that must be met to stop keeping rows

# Flags

  • -h, --help: Display this help message

keep while

Keeps rows while the condition matches.

# Usage

> keep while <condition> {flags} 

# Parameters

  • <condition> The condition that must be met to keep rows

# Flags

  • -h, --help: Display this help message

keep

Keep the number of rows only.

# Usage

> keep (rows) <subcommand> {flags} 

# Subcommands

  • keep until - Keeps rows until the condition matches.
  • keep while - Keeps rows while the condition matches.

# Parameters

  • (rows) Starting from the front, the number of rows to keep

# Flags

  • -h, --help: Display this help message

# Examples

Keep the first row

> echo [1 2 3] | keep

Keep the first four rows

> echo [1 2 3 4 5] | keep 4

kill

Kill a process using the process id.

# Usage

> kill <pid> ...args {flags} 

# Parameters

  • <pid> process id of process that is to be killed
  • ...args: rest of processes to kill

# Flags

  • -h, --help: Display this help message
  • -f, --force: forcefully kill the process
  • -q, --quiet: won't print anything to the console
  • -s, --signal : signal decimal number to be sent instead of the default 15 (unsupported on Windows)

# Examples

Kill the pid using the most memory

> ps | sort-by mem | last | kill $it.pid

Force kill a given pid

> kill --force 12345

Send INT signal

> kill -s 2 12345

last

Use last to retrieve the last "n" rows of a table. last has a required amount parameter that indicates how many rows you would like returned. If more than one row is returned, an index column will be included showing the row number. last does not alter the order of the rows of the table.

# Examples

> ps | last 1
─────────┬─────────────
 pid     │ 167
 name    │ loginwindow
 status  │ Running
 cpu     │ 0.0000
 mem     │ 461.2 MB
 virtual │ 7.2 GB
─────────┴─────────────
> ps | last 5
───┬─────┬─────────────────┬─────────┬────────┬──────────┬─────────
 # │ pid │ name            │ status  │ cpu    │ mem      │ virtual
───┼─────┼─────────────────┼─────────┼────────┼──────────┼─────────
 0334 │ knowledge-agent │ Running │ 0.000053.7 MB │  6.7 GB
 1332 │ UserEventAgent  │ Running │ 0.000022.1 MB │  6.6 GB
 2326 │ cfprefsd        │ Running │ 0.00008.1 MB │  5.6 GB
 3325 │ coreauthd       │ Running │ 0.00009.7 MB │  5.0 GB
 4167 │ loginwindow     │ Running │ 0.0000461.2 MB │  7.2 GB
───┴─────┴─────────────────┴─────────┴────────┴──────────┴─────────

length

Obtain the row or column count of a table.

# Flags

  • -c, --column: Calculate number of columns in table

# Examples

> ls
────┬────────────────────┬──────┬──────────┬──────────────
 #  │ name               │ type │ size     │ modified
────┼────────────────────┼──────┼──────────┼──────────────
 0  │ CODE_OF_CONDUCT.md │ File │   3.4 KB │ 42 mins ago
 1  │ CONTRIBUTING.md    │ File │   1.3 KB │ 42 mins ago
 2  │ Cargo.lock         │ File │ 113.3 KB │ 42 mins ago
 3  │ Cargo.toml         │ File │   4.6 KB │ 42 mins ago
 4  │ LICENSE            │ File │   1.1 KB │ 3 months ago
 5  │ Makefile.toml      │ File │    449 B │ 5 months ago
 6  │ README.md          │ File │  15.9 KB │ 31 mins ago
 7  │ TODO.md            │ File │      0 B │ 42 mins ago
 8  │ assets             │ Dir  │    128 B │ 5 months ago
 9  │ build.rs           │ File │     78 B │ 4 months ago
 10 │ crates             │ Dir  │    704 B │ 42 mins ago
 11 │ debian             │ Dir  │    352 B │ 5 months ago
 12 │ docker             │ Dir  │    288 B │ 3 months ago
 13 │ docs               │ Dir  │    192 B │ 42 mins ago
 14 │ features.toml      │ File │    632 B │ 4 months ago
 15 │ images             │ Dir  │    160 B │ 5 months ago
 16 │ rustfmt.toml       │ File │     16 B │ 5 months ago
 17 │ src                │ Dir  │    128 B │ 1 day ago
 18 │ target             │ Dir  │    160 B │ 5 days ago
 19 │ tests              │ Dir  │    192 B │ 3 months ago
────┴────────────────────┴──────┴──────────┴──────────────

By default, length will return the number of rows in a table

> ls | length
20

The -c flag will produce a count of the columns in the table

> ls | length -c
4
> ls | where type == File | length
11
> ls | where type == Dir | length
9
> ls | where size > 2KB | length
4

let-env

# let-env

Create an environment variable and give it a value.

# Usage

> let-env <name> <equals> <expr> {flags} 

# Parameters

  • <name> the name of the environment variable
  • <equals> the equals sign
  • <expr> the value for the environment variable

# Flags

  • -h, --help: Display this help message

let

Create a variable and give it a value.

# Usage

> let <name> <equals> <expr> {flags} 

# Parameters

  • <name> the name of the variable
  • <equals> the equals sign
  • <expr> the value for the variable

# Flags

  • -h, --help: Display this help message

# Examples

Assign a simple value to a variable

> let x = 3

Assign the result of an expression to a variable

> let result = (3 + 7); echo $result

Create a variable using the full name

> let $three = 3

lines

This command takes a string from a pipeline as input, and returns a table where each line of the input string is a row in the table. Empty lines are ignored. This command is capable of feeding other commands, such as nth, with its output.

# Usage

> [input-command] | lines

# Examples

Basic usage:

> printf "Hello\nWorld!\nLove, nushell." | lines
━━━┯━━━━━━━━━━━━━━━━
 # │ value
───┼────────────────
 0 │ Hello
 1 │ World!
 2 │ Love, nushell.
━━━┷━━━━━━━━━━━━━━━━

One useful application is piping the contents of file into lines. This example extracts a certain line from a given file.

> cat lines.md | lines | nth 6
## Examples

Similarly to this example, lines can be used to extract certain portions of or apply transformations to data returned by any program which returns a string.

load-env

# load-env

Set environment variables using a table stream

# Usage

> load-env (environ) {flags} 

# Parameters

  • (environ) Optional environment table to load in. If not provided, will use the table provided on the input stream

# Flags

  • -h, --help: Display this help message

# Examples

Load variables from an input stream

> echo [[name, value]; ["NAME", "JT"] ["AGE", "UNKNOWN"]] | load-env; echo $nu.env.NAME

Load variables from an argument

> load-env [[name, value]; ["NAME", "JT"] ["AGE", "UNKNOWN"]]; echo $nu.env.NAME

Load variables from an argument and an input stream

> echo [[name, value]; ["NAME", "JT"]] | load-env [[name, value]; ["VALUE", "FOO"]]; echo $nu.env.NAME $nu.env.VALUE

ls

View the contents of the current or given path.

# Usage

> ls (path) {flags} 

# Parameters

  • (path) a path to get the directory contents from

# Flags

  • -h, --help: Display this help message
  • -a, --all: Show hidden files
  • -l, --long: List all available columns for each entry
  • -s, --short-names: Only print the file names and not the path
  • -d, --du: Display the apparent directory size in place of the directory metadata size

# Examples

List all files in the current directory

> ls

List all files in a subdirectory

> ls subdir

List all rust files

> ls *.rs

match

Filter rows by Regex pattern.

# Usage

> match <member> <regex> {flags} 

# Parameters

  • <member> the column name to match
  • <regex> the regex to match with

# Flags

  • -h, --help: Display this help message
  • -i, --insensitive: case-insensitive search
  • -m, --multiline: multi-line mode: ^ and $ match begin/end of line
  • -s, --dotall: dotall mode: allow a dot . to match newline character \n
  • -v, --invert: invert the match

math abs

Returns absolute values of a list of numbers

# Usage

> math abs {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Get absolute of each value in a list of numbers

> echo [-50 -100.0 25] | math abs

math avg

Finds the average of a list of numbers or tables

# Usage

> math avg {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Get the average of a list of numbers

> echo [-50 100.0 25] | math avg

math eval

math eval is a command that takes a math expression from the pipeline and evaluates that into a number. It also optionally takes the math expression as an argument.

This command supports the following operations -

operations:

  • Binary operators: +, -, *, /, % (remainder), ^ (power)
  • Unary operators: +, -, ! (factorial)

functions:

  • sqrt, abs
  • exp, ln, log10
  • sin, cos, tan, asin, acos, atan, atan2
  • sinh, cosh, tanh, asinh, acosh, atanh
  • floor, ceil, round
  • signum
  • max(x, ...), min(x, ...): maximum and minimum of 1 or more numbers

constants:

  • pi
  • e

# Examples

> echo "1+2+3" | math eval
6.0u
> echo "1-2+3" | math eval
2.0
> echo "-(-23)" | math eval
23.0
> echo "5^2" | math eval
25.0
> echo "5^3" | math eval
125.0
> echo "min(5,4,3,2,1,0,-100,45)" | math eval
-100.0
> echo "max(5,4,3,2,1,0,-100,45)" | math eval
45.0
> echo sqrt(2) | math eval
1.414213562373095
> echo pi | math eval
3.141592653589793
> echo e | math eval
2.718281828459045
> echo "sin(pi / 2)" | math eval
1.0
> echo "floor(5999/1000)" | math eval
5.0
> open abc.json
───┬──────
 # │ size
───┼──────
 0816
 11627
 21436
 31573
 4935
 552
 6999
 71639
───┴──────
> open abc.json | format "({size} + 500) * 4"
───┬──────────────────
 # │
───┼──────────────────
 0(816 + 500) * 4
 1(1627 + 500) * 4
 2(1436 + 500) * 4
 3(1573 + 500) * 4
 4(935 + 500) * 4
 5(52 + 500) * 4
 6(999 + 500) * 4
 7(1639 + 500) * 4
───┴──────────────────
> open abc.json | format "({size} + 500) * 4" | math eval
───┬───────────
 # │
───┼───────────
 05264.0000
 18508.0000
 27744.0000
 38292.0000
 45740.0000
 52208.0000
 65996.0000
 78556.0000
───┴───────────
> open abc.json | format "({size} - 1000) * 4" | math eval
───┬────────────
 # │
───┼────────────
 0 │  -736.0000
 12508.0000
 21744.0000
 32292.0000
 4 │  -260.0000
 5 │ -3792.0000
 6 │    -4.0000
 72556.0000
───┴────────────

Note that since math eval uses floating-point numbers, the result may not always be precise.

> echo "floor(5999999999999999999/1000000000000000000)" | math eval
6.0

math ceil

Applies the ceil function to a list of numbers

# Usage

> math ceil {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Apply the ceil function to a list of numbers

> echo [1.5 2.3 -3.1] | math ceil

math floor

Applies the floor function to a list of numbers

# Usage

> math floor {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Apply the floor function to a list of numbers

> echo [1.5 2.3 -3.1] | math floor

math max

Finds the maximum within a list of numbers or tables

# Usage

> math max {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Find the maximum of list of numbers

> echo [-50 100 25] | math max

math median

Gets the median of a list of numbers

# Usage

> math median {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Get the median of a list of numbers

> echo [3 8 9 12 12 15] | math median

math min

Finds the minimum within a list of numbers or tables

# Usage

> math min {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Get the minimum of a list of numbers

> echo [-50 100 25] | math min

math product

Finds the product of a list of numbers or tables

# Usage

> math product {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Get the product of a list of numbers

> echo [2 3 3 4] | math product

math mode

Gets the most frequent element(s) from a list of numbers or tables

# Usage

> math mode {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Get the mode(s) of a list of numbers

> echo [3 3 9 12 12 15] | math mode

math round

Applies the round function to a list of numbers

# Usage

> math round {flags} 

# Flags

  • -h, --help: Display this help message
  • -p, --precision : digits of precision

# Examples

Apply the round function to a list of numbers

> echo [1.5 2.3 -3.1] | math round

Apply the round function with precision specified

> echo [1.555 2.333 -3.111] | math round -p 2

math sqrt

Applies the square root function to a list of numbers

# Usage

> math sqrt {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Apply the square root function to a list of numbers

> echo [9 16] | math sqrt

math sum

Finds the sum of a list of numbers or tables

# Usage

> math sum {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Sum a list of numbers

> echo [1 2 3] | math sum

Get the disk usage for the current directory

> ls --all --du | get size | math sum

math stddev

Finds the stddev of a list of numbers or tables

# Usage

> math stddev {flags} 

# Flags

  • -h, --help: Display this help message
  • -s, --sample: calculate sample standard deviation

# Examples

Get the stddev of a list of numbers

> echo [1 2 3 4 5] | math stddev

Get the sample stddev of a list of numbers

> echo [1 2 3 4 5] | math stddev -s

math variance

Finds the variance of a list of numbers or tables

# Usage

> math variance {flags} 

# Flags

  • -h, --help: Display this help message
  • -s, --sample: calculate sample variance

# Examples

Get the variance of a list of numbers

> echo [1 2 3 4 5] | math variance

Get the sample variance of a list of numbers

> echo [1 2 3 4 5] | math variance -s

merge

Merge a table.

# Usage

> merge <block> {flags} 

# Parameters

  • <block> the block to run and merge into the table

# Flags

  • -h, --help: Display this help message

# Examples

Merge a 1-based index column with some ls output

> ls | select name | keep 3 | merge { echo [1 2 3] | wrap index }

math

Mathematical functions that generally only operate on a list of numbers (integers, decimals, bytes) and tables. Currently the following functions are implemented:

  • math abs: Returns absolute values of a list of numbers
  • math avg: Finds the average of a list of numbers or tables
  • math ceil: Applies the ceil function to a list of numbers
  • math eval: Evaluates a list of math expressions into numbers
  • math floor: Applies the floor function to a list of numbers
  • math max: Finds the maximum within a list of numbers or tables
  • math median: Finds the median of a list of numbers or tables
  • math min: Finds the minimum within a list of numbers or tables
  • math mode: Finds the most frequent element(s) within a list of numbers or tables
  • math round: Applies the round function to a list of numbers
  • math sqrt: Applies the square root function to a list of numbers
  • math stddev: Finds the standard deviation of a list of numbers or tables
  • math sum: Finds the sum of a list of numbers or tables
  • math product: Finds the product of a list of numbers or tables
  • math variance: Finds the variance of a list of numbers or tables

However, the mathematical functions like min and max are more permissive and also work on Dates.

# Examples

To get the average of the file sizes in a directory, simply pipe the size column from the ls command to the average command.

# List of Numbers (Integers, Decimals, Bytes)

> ls
 #  │ name               │ type │ size     │ modified
────┼────────────────────┼──────┼──────────┼─────────────
  0 │ CODE_OF_CONDUCT.md │ File │   3.4 KB │ 4 days ago
  1 │ CONTRIBUTING.md    │ File │   1.3 KB │ 4 days ago
  2 │ Cargo.lock         │ File │ 106.3 KB │ 6 mins ago
  3 │ Cargo.toml         │ File │   4.6 KB │ 3 days ago
  4 │ LICENSE            │ File │   1.1 KB │ 4 days ago
  5 │ Makefile.toml      │ File │    449 B │ 4 days ago
  6 │ README.md          │ File │  16.0 KB │ 6 mins ago
  7 │ TODO.md            │ File │      0 B │ 6 mins ago
  8 │ assets             │ Dir  │    128 B │ 4 days ago
  9 │ build.rs           │ File │     78 B │ 4 days ago
 10 │ crates             │ Dir  │    672 B │ 3 days ago
 11 │ debian             │ Dir  │    352 B │ 4 days ago
 12 │ docker             │ Dir  │    288 B │ 4 days ago
 13 │ docs               │ Dir  │    160 B │ 4 days ago
 14 │ features.toml      │ File │    632 B │ 4 days ago
 15 │ images             │ Dir  │    160 B │ 4 days ago
 16 │ justfile           │ File │    234 B │ 3 days ago
 17 │ rustfmt.toml       │ File │     16 B │ 4 days ago
 18 │ src                │ Dir  │    128 B │ 4 days ago
 19 │ target             │ Dir  │    192 B │ 8 hours ago
 20 │ tests              │ Dir  │    192 B │ 4 days ago
> ls | get size | math avg
───┬────────
 # │
───┼────────
 07.2 KB
───┴────────
> ls | get size | math min
───┬─────
 # │
───┼─────
 00 B
───┴─────
> ls | get size | math max
───┬──────────
 # │
───┼──────────
 0113.6 KB
───┴──────────
> ls | get size | math median
───┬───────
 # │
───┼───────
 0320 B
───┴───────
> ls | get size | math sum
───┬──────────
 # │
───┼──────────
 0143.6 KB
───┴──────────
> echo [3 3 9 12 12 15] | math mode
───┬────
 03
 112
───┴────
> echo [2 3 3 4] | math product
72
> echo [1 4 6 10 50] | math stddev
18.1372
> echo [1 4 6 10 50] | math variance
328.96
> echo [1.5 2.3 -3.1] | math ceil
───┬────
 02
 13
 2 │ -3
───┴────
> echo [1.5 2.3 -3.1] | math floor
───┬────
 01
 12
 2 │ -4
───┴────
> echo [1.5 2.3 -3.1] | math round
───┬────
 02
 12
 2 │ -3
───┴────
> echo [4 16 0.25] | math sqrt
───┬────
 02
 14
 20.5
───┴────
> echo [1 -2 -3.0] | math abs
───┬────────
 01
 12
 23.0000
───┴────────

# Dates

> ls | get modified | math min
2020-06-09 17:25:51.798743222 UTC
> ls | get modified | math max
2020-06-14 05:49:59.637449186 UT

# Operations on tables

>  pwd | split row / | size
───┬───────┬───────┬───────┬────────────
 # │ lines │ words │ chars │ bytes
───┼───────┼───────┼───────┼────────────
 00155
 1011111
 2011111
 30144
 4021212
 50177
───┴───────┴───────┴───────┴────────────
> pwd | split row / | size | math max
────────────┬────
 lines      │ 0
 words      │ 2
 chars      │ 12
 bytes │ 12
────────────┴────
> pwd | split row / | size | math avg
────────────┬────────
 lines      │ 0.0000
 words      │ 1.1666
 chars      │ 8.3333
 bytes │ 8.3333
────────────┴────────

To get the sum of the characters that make up your present working directory.

> pwd | split row / | size | get chars | math sum
50

# Errors

math functions are aggregation functions so empty lists are invalid

> echo [] | math avg
error: Error: Unexpected: Cannot perform aggregate math operation on empty data

mkdir

Make directories, creates intermediary directories as required.

# Usage

> mkdir ...args {flags} 

# Parameters

  • ...args: the name(s) of the path(s) to create

# Flags

  • -h, --help: Display this help message
  • -s, --show-created-paths: show the path(s) created.

# Examples

Make a directory named foo

> mkdir foo

move

Move columns.

# Usage

> move ...args {flags} 

# Parameters

  • ...args: the columns to move

# Flags

  • -h, --help: Display this help message
  • --after : the column that will precede the columns moved
  • --before : the column that will be next the columns moved

# Examples

Move the column "type" before the column "name"

> ls | move type --before name | first

or move the column "chickens" after "name"

> ls | move chickens --after name | first

you can selectively move many columns in either direction

> ls | move name chickens --after type | first

mv

Move files or directories.

# Usage

> mv <source> <destination> {flags} 

# Parameters

  • <source> the location to move files/directories from
  • <destination> the location to move files/directories to

# Flags

  • -h, --help: Display this help message

# Examples

Rename a file

> mv before.txt after.txt

Move a file into a directory

> mv test.txt my/subdirectory

Move many files into a directory

> mv *.txt my/subdirectory

n

Go to next shell.

# Usage

> n {flags} 

# Flags

  • -h, --help: Display this help message

nth

This command returns the nth row of a table, starting from 0. If the number given is less than 0 or more than the number of rows, nothing is returned.

# Usage

> [input-command] | nth <row number>  ...args

# Parameters

  • <row number> the number of the row to return
  • args: Optionally return more rows

# Examples

> ls
────┬────────────────────┬──────┬──────────┬──────────────
 #  │ name               │ type │ size     │ modified
────┼────────────────────┼──────┼──────────┼──────────────
 0  │ CODE_OF_CONDUCT.md │ File │   3.4 KB │ 53 mins ago
 1  │ CONTRIBUTING.md    │ File │   1.3 KB │ 6 mins ago
 2  │ Cargo.lock         │ File │ 113.3 KB │ 53 mins ago
 3  │ Cargo.toml         │ File │   4.6 KB │ 53 mins ago
 4  │ LICENSE            │ File │   1.1 KB │ 3 months ago
 5  │ Makefile.toml      │ File │    449 B │ 5 months ago
 6  │ README.md          │ File │  15.8 KB │ 2 mins ago
 7  │ TODO.md            │ File │      0 B │ 53 mins ago
 8  │ assets             │ Dir  │    128 B │ 5 months ago
 9  │ build.rs           │ File │     78 B │ 4 months ago
 10 │ crates             │ Dir  │    704 B │ 53 mins ago
 11 │ debian             │ Dir  │    352 B │ 5 months ago
 12 │ docker             │ Dir  │    288 B │ 3 months ago
 13 │ docs               │ Dir  │    192 B │ 53 mins ago
 14 │ features.toml      │ File │    632 B │ 4 months ago
 15 │ images             │ Dir  │    160 B │ 5 months ago
 16 │ rustfmt.toml       │ File │     16 B │ 5 months ago
 17 │ src                │ Dir  │    128 B │ 1 day ago
 18 │ target             │ Dir  │    160 B │ 5 days ago
 19 │ tests              │ Dir  │    192 B │ 3 months ago
────┴────────────────────┴──────┴──────────┴──────────────
> ls | nth 0
──────────┬────────────────────
 name     │ CODE_OF_CONDUCT.md
 type     │ File
 size     │ 3.4 KB
 modified │ 54 mins ago
──────────┴────────────────────
> ls | nth 0 2
───┬────────────────────┬──────┬──────────┬─────────────
 # │ name               │ type │ size     │ modified
───┼────────────────────┼──────┼──────────┼─────────────
 0 │ CODE_OF_CONDUCT.md │ File │   3.4 KB │ 54 mins ago
 1 │ Cargo.lock         │ File │ 113.3 KB │ 54 mins ago
───┴────────────────────┴──────┴──────────┴─────────────
> ls | nth 5
──────────┬───────────────
 name     │ Makefile.toml
 type     │ File
 size     │ 449 B
 modified │ 5 months ago
──────────┴───────────────

open

Loads a file into a cell, convert it to table if possible (avoid by appending --raw flag)

# Example

> cat user.yaml
- Name: Peter
  Age: 30
  Telephone: 88204828
  Country: Singapore
- Name: Michael
  Age: 42
  Telephone: 44002010
  Country: Spain
- Name: Will
  Age: 50
  Telephone: 99521080
  Country: Germany
> open user.yaml
━━━┯━━━━━━━━━┯━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━
 # │ Name    │ Age │ Telephone │ Country
───┼─────────┼─────┼───────────┼───────────
 0 │ Peter   │  3088204828 │ Singapore
 1 │ Michael │  4244002010 │ Spain
 2 │ Will    │  5099521080 │ Germany
━━━┷━━━━━━━━━┷━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━
> open user.yaml --raw
- Name: Peter
  Age: 30
  Telephone: 88204828
  Country: Singapore
- Name: Michael
  Age: 42
  Telephone: 44002010
  Country: Spain
- Name: Will
  Age: 50
  Telephone: 99521080
  Country: Germany
> cat user.json
[
    {
        "Name": "Peter",
        "Age": 30,
        "Telephone": 88204828,
        "Country": "Singapore"
    },
    {
        "Name": "Michael",
        "Age": 42,
        "Telephone": 44002010,
        "Country": "Spain"
    },
    {
        "Name": "Will",
        "Age": 50,
        "Telephone": 99521080,
        "Country": "Germany"
    }
]
> open user.json
━━━┯━━━━━━━━━┯━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━
 # │ Name    │ Age │ Telephone │ Country
───┼─────────┼─────┼───────────┼───────────
 0 │ Peter   │  3088204828 │ Singapore
 1 │ Michael │  4244002010 │ Spain
 2 │ Will    │  5099521080 │ Germany
━━━┷━━━━━━━━━┷━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━
> open user.json --raw
[
    {
        "Name": "Peter",
        "Age": 30,
        "Telephone": 88204828,
        "Country": "Singapore"
    },
    {
        "Name": "Michael",
        "Age": 42,
        "Telephone": 44002010,
        "Country": "Spain"
    },
    {
        "Name": "Will",
        "Age": 50,
        "Telephone": 99521080,
        "Country": "Germany"
    }
]

p

Go to previous shell.

# Usage

> p {flags} 

# Flags

  • -h, --help: Display this help message

parse

Parse columns from string data using a simple pattern.

# Usage

> parse <pattern> {flags} 

# Parameters

  • <pattern> the pattern to match. Eg) "{foo}: {bar}"

# Flags

  • -h, --help: Display this help message
  • -r, --regex: use full regex syntax for patterns

# Examples

Parse a string into two named columns

> echo "hi there" | parse "{foo} {bar}"

Parse a string using regex pattern

> echo "hi there" | parse -r "(?P<foo>\w+) (?P<bar>\w+)"

path basename

Get the final component of a path

# Usage

> path basename ...args {flags} 

# Parameters

  • ...args: Optionally operate by column path

# Flags

  • -h, --help: Display this help message
  • -r, --replace : Return original path with basename replaced by this string

# Examples

Get basename of a path

> echo '/home/joe/test.txt' | path basename

Replace basename of a path

> echo '/home/joe/test.txt' | path basename -r 'spam.png'

path dirname

Get the parent directory of a path

# Usage

> path dirname ...args {flags} 

# Parameters

  • ...args: Optionally operate by column path

# Flags

  • -h, --help: Display this help message
  • -r, --replace : Return original path with dirname replaced by this string
  • -n, --num-levels : Number of directories to walk up

# Examples

Get dirname of a path

> echo '/home/joe/code/test.txt' | path dirname

Walk up two levels

> echo '/home/joe/code/test.txt' | path dirname -n 2

Replace the part that would be returned with a custom path

> echo '/home/joe/code/test.txt' | path dirname -n 2 -r /home/viking

path exists

Check whether a path exists

# Usage

> path exists ...args {flags} 

# Parameters

  • ...args: Optionally operate by column path

# Flags

  • -h, --help: Display this help message

# Examples

Check if a file exists

> echo '/home/joe/todo.txt' | path exists

path expand

Expand a path to its absolute form

# Usage

> path expand ...args {flags} 

# Parameters

  • ...args: Optionally operate by column path

# Flags

  • -h, --help: Display this help message

# Examples

Expand relative directories

> echo '/home/joe/foo/../bar' | path expand

path join

Join a structured path or a list of path parts.

Optionally, append an additional path to the result. It is designed to accept the output of 'path parse' and 'path split' subcommands.

# Usage

> path join ...args {flags} 

# Parameters

  • ...args: Optionally operate by column path

# Flags

  • -h, --help: Display this help message
  • -a, --append : Path to append to the input

# Examples

Append a filename to a path

> echo '/home/viking' | path join -a spam.txt

Join a list of parts into a path

> echo [ '/' 'home' 'viking' 'spam.txt' ] | path join

Join a structured path into a path

> echo [[ parent stem extension ]; [ '/home/viking' 'spam' 'txt' ]] | path join

path parse

Convert a path into structured data.

Each path is split into a table with 'parent', 'stem' and 'extension' fields. On Windows, an extra 'prefix' column is added.

# Usage

> path parse ...args {flags} 

# Parameters

  • ...args: Optionally operate by column path

# Flags

  • -h, --help: Display this help message
  • -e, --extension : Manually supply the extension (without the dot)

# Examples

Parse a path

> echo '/home/viking/spam.txt' | path parse

Replace a complex extension

> echo '/home/viking/spam.tar.gz' | path parse -e tar.gz | update extension { 'txt' }

Ignore the extension

> echo '/etc/conf.d' | path parse -e ''

Parse all paths under the 'name' column

> ls | path parse name

path relative-to

# path relative-to

Get a path as relative to another path.

Can be used only when the input and the argument paths are either both absolute or both relative. The argument path needs to be a parent of the input path.

# Usage

> path relative-to <path> ...args {flags} 

# Parameters

  • <path> Parent shared with the input path
  • ...args: Optionally operate by column path

# Flags

  • -h, --help: Display this help message

# Examples

Find a relative path from two absolute paths

> '/home/viking' | path relative-to '/home'

Find a relative path from two relative paths

> 'eggs/bacon/sausage/spam' | path relative-to 'eggs/bacon/sausage'

path split

Split a path into parts by a separator.

# Usage

> path split ...args {flags} 

# Parameters

  • ...args: Optionally operate by column path

# Flags

  • -h, --help: Display this help message

# Examples

Split a path into parts

> echo '/home/viking/spam.txt' | path split

Split all paths under the 'name' column

> ls | path split name

path type

Get the type of the object a path refers to (e.g., file, dir, symlink)

# Usage

> path type ...args {flags} 

# Parameters

  • ...args: Optionally operate by column path

# Flags

  • -h, --help: Display this help message

# Examples

Show type of a filepath

> echo '.' | path type

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 <subcommand> {flags} 

# 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 - 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

post

Post content to a url and retrieve data as a table if possible.

# Usage

> post <path> <body> {flags} 

# Parameters

  • <path> the URL to post to
  • <body> the contents of the post body

# Flags

  • -h, --help: Display this help message
  • -u, --user : the username when authenticating
  • -p, --password : the password when authenticating
  • -t, --content-type : the MIME type of content to post
  • -l, --content-length : the length of the content being posted
  • -r, --raw: return values as a string instead of a table

pivot

Pivots the table contents so rows become columns and columns become rows.

# Examples

> ls docs
───┬────────────────────┬──────┬────────┬─────────────
 # │ name               │ type │ size   │ modified
───┼────────────────────┼──────┼────────┼─────────────
 0 │ docs/commands      │ Dir  │ 2.7 KB │ 53 mins ago
 1 │ docs/docker.md     │ File │ 7.0 KB │ 40 mins ago
 2 │ docs/philosophy.md │ File │  912 B │ 54 mins ago
───┴────────────────────┴──────┴────────┴─────────────
> ls docs | pivot
───┬──────────┬───────────────┬────────────────┬────────────────────
 # │ Column0  │ Column1       │ Column2        │ Column3
───┼──────────┼───────────────┼────────────────┼────────────────────
 0 │ name     │ docs/commands │ docs/docker.md │ docs/philosophy.md
 1type     │ Dir           │ File           │ File
 2 │ size     │        2.7 KB │         7.0 KB │              912 B
 3 │ modified │ 53 mins ago   │ 40 mins ago    │ 55 mins ago
───┴──────────┴───────────────┴────────────────┴────────────────────

Use --header-row to treat the first row as column names:

> ls docs | pivot --header-row
───┬───────────────┬────────────────┬────────────────────
 # │ docs/commands │ docs/docker.md │ docs/philosophy.md
───┼───────────────┼────────────────┼────────────────────
 0 │ Dir           │ File           │ File
 12.7 KB │         7.0 KB │              912 B
 253 mins ago   │ 40 mins ago    │ 55 mins ago
───┴───────────────┴────────────────┴────────────────────

Use --ignore-titles to prevent pivoting the column names into values:

> ls docs | pivot --ignore-titles
───┬───────────────┬────────────────┬────────────────────
 # │ Column0       │ Column1        │ Column2
───┼───────────────┼────────────────┼────────────────────
 0 │ docs/commands │ docs/docker.md │ docs/philosophy.md
 1 │ Dir           │ File           │ File
 22.7 KB │         7.0 KB │              912 B
 354 mins ago   │ 41 mins ago    │ 56 mins ago
───┴───────────────┴────────────────┴────────────────────

Additional arguments are used as column names:

> ls docs | pivot foo bar baz
───┬──────────┬───────────────┬────────────────┬────────────────────
 # │ foo      │ bar           │ baz            │ Column3
───┼──────────┼───────────────┼────────────────┼────────────────────
 0 │ name     │ docs/commands │ docs/docker.md │ docs/philosophy.md
 1type     │ Dir           │ File           │ File
 2 │ size     │        2.7 KB │         7.0 KB │              912 B
 3 │ modified │ 55 mins ago   │ 41 mins ago    │ 56 mins ago
───┴──────────┴───────────────┴────────────────┴────────────────────

prepend

This command prepends the given row to the front of the table

Note:

  • prepend does not change a file itself. If you want to save your changes, you need to run the save command
  • if you want to add something containing a whitespace character, you need to put it in quotation marks

# Examples

Let's complete this table with the missing continents:

> open continents.txt | lines
━━━┯━━━━━━━━━━━━━━━
 # │
───┼───────────────
 0 │ Africa
 1 │ South America
 2 │ Australia
 3 │ Europe
 4 │ Antarctica
━━━┷━━━━━━━━━━━━━━━

You can add a new row at the top by using prepend:

> open continents.txt | lines | prepend Asia
━━━┯━━━━━━━━━━━━━━━
 # │
───┼───────────────
 0 │ Asia
 1 │ Africa
 2 │ South America
 3 │ Australia
 4 │ Europe
 5 │ Antarctica
━━━┷━━━━━━━━━━━━━━━

It's not possible to add multiple rows at once, so you'll need to call prepend multiple times:

> open continents.txt | lines | prepend Asia | prepend "North America"
━━━┯━━━━━━━━━━━━━━━
 # │
───┼───────────────
 0 │ North America
 1 │ Asia
 2 │ Africa
 3 │ South America
 4 │ Australia
 5 │ Europe
 6 │ Antarctica
━━━┷━━━━━━━━━━━━━━━

pwd

Print the current working directory.

-h, --help Display help message.

# Examples

> pwd
/home/me/nushell/docs/commands
> pwd | split column "/" | reject Column1 | pivot | reject Column0
───┬──────────
 # │ Column1
───┼──────────
 0 │ home
 1 │ me
 2 │ projects
 3 │ nushell
 4 │ docs
 5 │ commands
───┴──────────

ps

This command shows information about system processes.

Syntax: ps

# Example

> ps
━━━━┯━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━
 #  │ pid   │ name                                                               │ status  │ cpu
────┼───────┼────────────────────────────────────────────────────────────────────┼─────────┼───────────────────
 5010184 │ firefox.exe                                                        │ Running │ 0.000000000000000
 5111584 │ WindowsTerminal.exe                                                │ Running │ 0.000000000000000
 5211052 │ conhost.exe                                                        │ Running │ 0.000000000000000
 537076 │ nu.exe                                                             │ Running │ 0.000000000000000
   ...
 663000 │ Code.exe                                                           │ Running │ 0.000000000000000
 675388 │ conhost.exe                                                        │ Running │ 0.000000000000000
 686268 │ firefox.exe                                                        │ Running │ 0.000000000000000
 698972 │ nu_plugin_ps.exe                                                   │ Running │ 58.00986000000000
━━━━┷━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━

Find processes with the highest cpu time

> ps -l | sort-by cpu_time | last 2
 # │ pid │       name       │ status  │  cpu   │   mem    │ virtual │     cpu_time      │ parent │         exe          │       command
───┼─────┼──────────────────┼─────────┼────────┼──────────┼─────────┼───────────────────┼────────┼──────────────────────┼──────────────────────
 0396 │ Google Chrome    │ Running │ 0.0000271.6 MB │  5.8 GB │ 6hr 20min 28sec   │      1 │ /Applications/Google │ /Applications/Google
   │     │                  │         │        │          │         │ 173ms 641us 315ns │        │ Chrome.app/Contents/ │ Chrome.app/Contents/
   │     │                  │         │        │          │         │                   │        │ MacOS/Google         │ MacOS/Google
   │     │                  │         │        │          │         │                   │        │ Chrome               │ Chrome
 1444 │ Google Chrome He │ Running │ 0.0000398.9 MB │  5.3 GB │ 10hr 36min 17sec  │    396 │ /Applications/Google │ /Applications/Google
   │     │                  │         │        │          │         │ 304ms 66us 889ns  │        │ Chrome.app/Contents/ │ Chrome.app/Contents/
   │     │                  │         │        │          │         │                   │        │ Frameworks/Google    │ Frameworks/Google
   │     │                  │         │        │          │         │                   │        │ Chrome               │ Chrome
   │     │                  │         │        │          │         │                   │        │ Framework.framework/ │ Framework.framework/
   │     │                  │         │        │          │         │                   │        │ Versions/84.0.4147.1 │ Versions/84.0.4147.1
   │     │                  │         │        │          │         │                   │        │ 25/Helpers/Google    │ 25/Helpers/Google
   │     │                  │         │        │          │         │                   │        │ Chrome Helper        │ Chrome Helper
   │     │                  │         │        │          │         │                   │        │ (GPU).app/Contents/M │ (GPU).app/Contents/M
   │     │                  │         │        │          │         │                   │        │ acOS/Google          │ acOS/Google
   │     │                  │         │        │          │         │                   │        │ Chrome Helper (GPU)  │ Chrome Helper (GPU)
───┴─────┴──────────────────┴─────────┴────────┴──────────┴─────────┴───────────────────┴────────┴──────────────────────┴──────────────────────

random bool

Generate a random boolean value

# Usage

> random bool {flags} 

# Flags

  • -h, --help: Display this help message
  • -b, --bias : Adjusts the probability of a "true" outcome

# Examples

Generate a random boolean value

> random bool

Generate a random boolean value with a 75% chance of "true"

> random bool --bias 0.75

random chars

Generate random chars

# Usage

> random chars {flags} 

# Flags

  • -h, --help: Display this help message
  • -l, --length : Number of chars

# Examples

Generate random chars

> random chars

Generate random chars with specified length

> random chars -l 20

random decimal

Generate a random decimal within a range [min..max]

# Usage

> random decimal (range) {flags} 

# Parameters

  • (range) Range of values

# Flags

  • -h, --help: Display this help message

# Examples

Generate a default decimal value between 0 and 1

> random decimal

Generate a random decimal less than or equal to 500

> random decimal ..500

Generate a random decimal greater than or equal to 100000

> random decimal 100000..

Generate a random decimal between 1.0 and 1.1

> random decimal 1.0..1.1

random dice

Generate a random dice roll

# Usage

> random dice {flags} 

# Flags

  • -h, --help: Display this help message
  • -d, --dice : The amount of dice being rolled
  • -s, --sides : The amount of sides a die has

# Examples

Roll 1 dice with 6 sides each

> random dice

Roll 10 dice with 12 sides each

> random dice -d 10 -s 12

random integer

Generate a random integer [min..max]

# Usage

> random integer (range) {flags} 

# Parameters

  • (range) Range of values

# Flags

  • -h, --help: Display this help message

# Examples

Generate an unconstrained random integer

> random integer

Generate a random integer less than or equal to 500

> random integer ..500

Generate a random integer greater than or equal to 100000

> random integer 100000..

Generate a random integer between 1 and 10

> random integer 1..10

random uuid

Generate a random uuid4 string

# Usage

> random uuid {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Generate a random uuid4 string

> random uuid

random

Use random to generate random values

# bool

  • random bool: Generate a random boolean value

# bool Flags

  • -b, --bias <number>: Adjusts the probability of a "true" outcome

# bool Examples

> random bool
false
> random bool --bias 0.75
true

# dice

  • random dice: Generate a random dice roll

# dice Flags

  • d, --dice <integer>: The amount of dice being rolled
  • s, --sides <integer>: The amount of sides a die has

# dice Examples

> random dice
4
> random dice -d 10 -s 12
───┬────
 011
 111
 211
 311
 45
 53
 610
 77
 83
 91
───┴────
> random dice --dice 1024 --sides 16 | histogram | sort-by occurrences
────┬───────┬─────────────┬────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────
 #  │ value │ occurrences │ percentage │ frequency
────┼───────┼─────────────┼────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
  065775.00%     │ ***************************************************************************
  1125977.63%     │ *****************************************************************************
  235977.63%     │ *****************************************************************************
  3166078.95%     │ ******************************************************************************
  4136180.26%     │ ********************************************************************************
  5116281.58%     │ *********************************************************************************
  656281.58%     │ *********************************************************************************
  796281.58%     │ *********************************************************************************
  846382.89%     │ **********************************************************************************
  986484.21%     │ ************************************************************************************
 10106585.53%     │ *************************************************************************************
 11156686.84%     │ **************************************************************************************
 12146788.16%     │ ****************************************************************************************
 1376990.79%     │ ******************************************************************************************
 1417294.74%     │ **********************************************************************************************
 15276100.00%    │ ****************************************************************************************************
────┴───────┴─────────────┴────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────

# uuid

  • random uuid: Generate a random uuid4 string

# uuid Examples

> random uuid
8af4de39-acbc-42f0-94d1-7cfad6c01f8b

# integer

  • random integer: Generate a random integer

# integer Flags

  • m, --min <integer>: The minimum value to generate
  • x, --max <integer>: The maximum value to generate

# integer Examples

> random integer
42
> random integer 5000..
8700890823
> random integer ..100
73
> random integer 100000..200000
173400

# chars Examples

Generate a random password of length 15

> random chars -l 15
fWBSbE7QtaoJGeo

range

Return only the selected rows.

# Usage

> range <rows> {flags} 

# Parameters

  • <rows> range of rows to return: Eg) 4..7 (=> from 4 to 7)

# Flags

  • -h, --help: Display this help message

# Examples

Return rows 1 through 3

> echo [1 2 3 4 5] | range 1..3

Return the third row from the end, through to the end

> echo [1 2 3 4 5] | range (-3..)

reduce

Aggregate a list table to a single value using an accumulator block.

Block must be (A, A) -> A unless --fold is selected, in which case it may be A, B -> A.

# Usage

> reduce <block> {flags} 

# Parameters

  • <block> reducing function

# Flags

  • -h, --help: Display this help message
  • -f, --fold : reduce with initial value
  • -n, --numbered: returned a numbered item ($it.index and $it.item)

# Examples

Simple summation (equivalent to math sum)

> echo 1 2 3 4 | reduce { $acc + $it }

Summation from starting value using fold

> echo 1 2 3 4 | reduce -f (-1) { $acc + $it }

Folding with rows

> <table> | reduce -f 1.6 { $acc * (echo $it.a | str to-int) + (echo $it.b | str to-int) }

Numbered reduce to find index of longest word

> echo one longest three bar | reduce -n { if ($it.item | str length) > ($acc.item | str length) {echo $it} {echo $acc}} | get index

reject

This command removes or rejects the columns passed to it.

# Examples

> ls
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━
 # │ name                       │ type │ readonly │ size   │ created     │ accessed    │ modified
───┼────────────────────────────┼──────┼──────────┼────────┼─────────────┼─────────────┼─────────────
 0 │ zeusiscrazy.txt            │ File │          │ 556 B  │ a month ago │ a month ago │ a month ago
 1 │ coww.txt                   │ File │          │  24 B  │ a month ago │ a month ago │ a month ago
 2 │ randomweirdstuff.txt       │ File │          │ 197 B  │ a month ago │ a month ago │ a month ago
 3 │ abaracadabra.txt           │ File │          │ 401 B  │ a month ago │ a month ago │ a month ago
 4 │ youshouldeatmorecereal.txt │ File │          │ 768 B  │ a month ago │ a month ago │ a month ago
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━┷━━━━━━━━━━━━━┷━━━━━━━━━━━━━
> ls | reject readonly
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━
 # │ name                       │ type │ size   │ created     │ accessed    │ modified
───┼────────────────────────────┼──────┼────────┼─────────────┼─────────────┼─────────────
 0 │ zeusiscrazy.txt            │ File │ 556 B  │ a month ago │ a month ago │ a month ago
 1 │ coww.txt                   │ File │  24 B  │ a month ago │ a month ago │ a month ago
 2 │ randomweirdstuff.txt       │ File │ 197 B  │ a month ago │ a month ago │ a month ago
 3 │ abaracadabra.txt           │ File │ 401 B  │ a month ago │ a month ago │ a month ago
 4 │ youshouldeatmorecereal.txt │ File │ 768 B  │ a month ago │ a month ago │ a month ago
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━┷━━━━━━━━━━━━━┷━━━━━━━━━━━━━
> ls | reject readonly accessed
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━
 # │ name                       │ type │ size   │ created     │ modified
───┼────────────────────────────┼──────┼────────┼─────────────┼─────────────
 0 │ zeusiscrazy.txt            │ File │ 556 B  │ a month ago │ a month ago
 1 │ coww.txt                   │ File │  24 B  │ a month ago │ a month ago
 2 │ randomweirdstuff.txt       │ File │ 197 B  │ a month ago │ a month ago
 3 │ abaracadabra.txt           │ File │ 401 B  │ a month ago │ a month ago
 4 │ youshouldeatmorecereal.txt │ File │ 768 B  │ a month ago │ a month ago
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━┷━━━━━━━━━━━━━

rename

Use rename to give columns more appropriate names.

# Examples

> open /etc/passwd | lines | split column ":" | rename user password uid gid gecos home shell
────┬────────┬──────────┬──────┬──────┬────────┬─────────────────┬──────────────────
 #  │ user   │ password │ uid  │ gid  │ gecos  │ home            │ shell
────┼────────┼──────────┼──────┼──────┼────────┼─────────────────┼──────────────────
  0 │ root   │ x        │ 00    │ root   │ /root           │ /bin/bash
  1 │ bin    │ x        │ 11    │ bin    │ /bin            │ /usr/bin/nologin
  2 │ daemon │ x        │ 22    │ daemon │ /               │ /usr/bin/nologin
  3 │ mail   │ x        │ 812   │ mail   │ /var/spool/mail │ /usr/bin/nologin
────┴────────┴──────────┴──────┴──────┴────────┴─────────────────┴──────────────────

rm

Remove file(s).

# Usage

> rm ...args {flags} 

# Parameters

  • ...args: the file path(s) to remove

# Flags

  • -h, --help: Display this help message
  • -t, --trash: use the platform's recycle bin instead of permanently deleting
  • -p, --permanent: don't use recycle bin, delete permanently
  • -r, --recursive: delete subdirectories recursively
  • -f, --force: suppress error when no file

# Examples

Delete or move a file to the system trash (depending on 'rm_always_trash' config option)

> rm file.txt

Move a file to the system trash

> rm --trash file.txt

Delete a file permanently

> rm --permanent file.txt

Delete a file, and suppress errors if no file is found

> rm --force file.txt

reverse

This command reverses the order of the elements in a sorted table.

# Examples

> ls | sort-by name
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━
 # │ name                       │ type │ readonly │ size   │ accessed       │ modified
───┼────────────────────────────┼──────┼──────────┼────────┼────────────────┼────────────────
 0 │ abaracadabra.txt           │ File │          │ 401 B  │ 23 minutes ago │ 16 minutes ago
 1 │ coww.txt                   │ File │          │  24 B  │ 22 minutes ago │ 17 minutes ago
 2 │ randomweirdstuff.txt       │ File │          │ 197 B  │ 21 minutes ago │ 18 minutes ago
 3 │ youshouldeatmorecereal.txt │ File │          │ 768 B  │ 30 seconds ago │ now
 4 │ zeusiscrazy.txt            │ File │          │ 556 B  │ 22 minutes ago │ 18 minutes ago
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━
> ls | sort-by name | reverse
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━
 # │ name                       │ type │ readonly │ size   │ accessed       │ modified
───┼────────────────────────────┼──────┼──────────┼────────┼────────────────┼────────────────
 0 │ zeusiscrazy.txt            │ File │          │ 556 B  │ 22 minutes ago │ 19 minutes ago
 1 │ youshouldeatmorecereal.txt │ File │          │ 768 B  │ 39 seconds ago │ 18 seconds ago
 2 │ randomweirdstuff.txt       │ File │          │ 197 B  │ 21 minutes ago │ 18 minutes ago
 3 │ coww.txt                   │ File │          │  24 B  │ 22 minutes ago │ 18 minutes ago
 4 │ abaracadabra.txt           │ File │          │ 401 B  │ 23 minutes ago │ 16 minutes ago
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━
> ls | sort-by size
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━
 # │ name                       │ type │ readonly │ size   │ accessed       │ modified
───┼────────────────────────────┼──────┼──────────┼────────┼────────────────┼────────────────
 0 │ coww.txt                   │ File │          │  24 B  │ 22 minutes ago │ 18 minutes ago
 1 │ randomweirdstuff.txt       │ File │          │ 197 B  │ 21 minutes ago │ 18 minutes ago
 2 │ abaracadabra.txt           │ File │          │ 401 B  │ 23 minutes ago │ 16 minutes ago
 3 │ zeusiscrazy.txt            │ File │          │ 556 B  │ 22 minutes ago │ 19 minutes ago
 4 │ youshouldeatmorecereal.txt │ File │          │ 768 B  │ a minute ago   │ 26 seconds ago
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━
> ls | sort-by size | reverse
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━
 # │ name                       │ type │ readonly │ size   │ accessed       │ modified
───┼────────────────────────────┼──────┼──────────┼────────┼────────────────┼────────────────
 0 │ youshouldeatmorecereal.txt │ File │          │ 768 B  │ a minute ago   │ 32 seconds ago
 1 │ zeusiscrazy.txt            │ File │          │ 556 B  │ 22 minutes ago │ 19 minutes ago
 2 │ abaracadabra.txt           │ File │          │ 401 B  │ 23 minutes ago │ 16 minutes ago
 3 │ randomweirdstuff.txt       │ File │          │ 197 B  │ 21 minutes ago │ 18 minutes ago
 4 │ coww.txt                   │ File │          │  24 B  │ 22 minutes ago │ 18 minutes ago
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━

roll column

Rolls the table columns

# Usage

> roll column (by) {flags} 

# Parameters

  • (by) the number of times to roll

# Flags

  • -h, --help: Display this help message
  • -o, --opposite: roll in the opposite direction
  • -c, --cells-only: only roll the cells

roll up

Rolls the table rows

# Usage

> roll up (by) {flags} 

# Parameters

  • (by) the number of times to roll

# Flags

  • -h, --help: Display this help message

roll

Rolls the table rows.

# Usage

> roll (by) <subcommand> {flags} 

# Subcommands

  • roll column - Rolls the table columns
  • roll up - Rolls the table rows

# Parameters

  • (by) the number of times to roll

# Flags

  • -h, --help: Display this help message

rotate counter-clockwise

# rotate counter-clockwise

Rotates the table by 90 degrees counter clockwise.

# Usage

> rotate counter-clockwise ...args {flags} 

# Parameters

  • ...args: the names to give columns once rotated

# Flags

  • -h, --help: Display this help message

rotate

Rotates the table by 90 degrees clockwise.

# Usage

> rotate ...args <subcommand> {flags} 

# Subcommands

  • rotate counter-clockwise - Rotates the table by 90 degrees counter clockwise.

# Parameters

  • ...args: the names to give columns once rotated

# Flags

  • -h, --help: Display this help message

s3

Load S3 resource into a cell, convert to table if possible (avoid by appending '--raw' or '-R')

# Usage

> s3 <RESOURCE> {flags} 

# Parameters

  • <RESOURCE> the RESOURCE to fetch the contents from

# Flags

  • -h, --help: Display this help message
  • -e, --endpoint : the endpoint info for the S3 resource, i.g., s3.ap-northeast-1.amazonaws.com or 10.1.1.1
  • -a, --access_key : the access key when authenticating
  • -s, --secret_key : the secret key when authenticating
  • -r, --region : the region of the resource, default will use us-east-1
  • -R, --raw: fetch contents as text rather than a table

save

This command saves the contents of the pipeline to a file. Use this in combination with the to json, to csv, ... commands to save the contents in the specified format.

Syntax: save (path) {flags}

# Parameters

  • (path) the path to save contents to

# Flags

--raw
  treat values as-is rather than auto-converting based on file extension

# Example

You can save the name of files in a directory like this:

> ls | where type == File | select name | save filenames.csv

Or you can format it in supported formats using one of the to commands:

> ls | where type == File | select name | to csv | save filenames

filename.csv and filenames are both csv formatted files. Nu auto-converts the format if a supported file extension is given.

select

This command displays only the column names passed on to it.

# Examples

> ls
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━
 # │ name                       │ type │ readonly │ size   │ created     │ accessed    │ modified
───┼────────────────────────────┼──────┼──────────┼────────┼─────────────┼─────────────┼─────────────
 0 │ zeusiscrazy.txt            │ File │          │ 556 B  │ a month ago │ a month ago │ a month ago
 1 │ coww.txt                   │ File │          │  24 B  │ a month ago │ a month ago │ a month ago
 2 │ randomweirdstuff.txt       │ File │          │ 197 B  │ a month ago │ a month ago │ a month ago
 3 │ abaracadabra.txt           │ File │          │ 401 B  │ a month ago │ a month ago │ a month ago
 4 │ youshouldeatmorecereal.txt │ File │          │ 768 B  │ a month ago │ a month ago │ a month ago
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━┷━━━━━━━━━━━━━┷━━━━━━━━━━━━━
> ls | select name
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │ name
───┼────────────────────────────
 0 │ zeusiscrazy.txt
 1 │ coww.txt
 2 │ randomweirdstuff.txt
 3 │ abaracadabra.txt
 4 │ youshouldeatmorecereal.txt
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The order in which you put the column names matters:

> ls | select type name size
━━━┯━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━
 # │ type │ name                       │ size
───┼──────┼────────────────────────────┼────────
 0 │ File │ zeusiscrazy.txt            │ 556 B
 1 │ File │ coww.txt                   │  24 B
 2 │ File │ randomweirdstuff.txt       │ 197 B
 3 │ File │ abaracadabra.txt           │ 401 B
 4 │ File │ youshouldeatmorecereal.txt │ 768 B
━━━┷━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━
> ls | select size type name
━━━┯━━━━━━━━┯━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │ size   │ type │ name
───┼────────┼──────┼────────────────────────────
 0556 B  │ File │ zeusiscrazy.txt
 124 B  │ File │ coww.txt
 2197 B  │ File │ randomweirdstuff.txt
 3401 B  │ File │ abaracadabra.txt
 4768 B  │ File │ youshouldeatmorecereal.txt
━━━┷━━━━━━━━┷━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━

selector

execute selector query on html/web

# Usage

> selector <query> {flags} 

# Parameters

  • <query> selector query

# Flags

  • -h, --help: Display this help message
  • -a, --as_html: return the query output as html

seq date

print sequences of dates

# Usage

> seq date {flags} 

# Flags

  • -h, --help: Display this help message
  • -s, --separator : separator character (defaults to \n)
  • -o, --output_format : prints dates in this format (defaults to %Y-%m-%d)
  • -i, --input_format : give argument dates in this format (defaults to %Y-%m-%d)
  • -b, --begin_date : beginning date range
  • -e, --end_date : ending date
  • -n, --increment : increment dates by this number
  • -d, --days : number of days to print
  • -r, --reverse: print dates in reverse

# Examples

print the next 10 days in YYYY-MM-DD format with newline separator

> seq date --days 10

print the previous 10 days in YYYY-MM-DD format with newline separator

> seq date --days 10 -r

print the previous 10 days starting today in MM/DD/YYYY format with newline separator

> seq date --days 10 -o '%m/%d/%Y' -r

print the first 10 days in January, 2020

> seq date -b '2020-01-01' -e '2020-01-10'

print every fifth day between January 1st 2020 and January 31st 2020

> seq date -b '2020-01-01' -e '2020-01-31' -n 5

starting on May 5th, 2020, print the next 10 days in your locale's date format, colon separated

> seq date -o %x -s ':' -d 10 -b '2020-05-01'

seq

Print sequences of numbers.

# Usage

> seq ...args <subcommand> {flags} 

# Subcommands

  • seq date - print sequences of dates

# Parameters

  • ...args: sequence values

# Flags

  • -h, --help: Display this help message
  • -s, --separator : separator character (defaults to \n)
  • -t, --terminator : terminator character (defaults to \n)
  • -w, --widths: equalize widths of all numbers by padding with zeros

# Examples

  • sequence 1 to 10 with newline separator
> seq 1 10
  • sequence 1.0 to 2.0 by 0.1s with newline separator
> seq 1.0 0.1 2.0
  • sequence 1 to 10 with pipe separator
> seq -s '|' 1 10
  • sequence 1 to 10 with pipe separator padded with 0
> seq -s '|' -w 1 10
  • sequence 1 to 10 with pipe separator padded by 2s
> seq -s ' | ' -w 1 2 10

shells

Lists all the active nu shells with a number/index, a name and the path. Also marks the current nu shell.

# Examples

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼─────────────────────────────────────
 0 │   │ filesystem │ /home/jonathanturner/Source/nushell
 1 │   │ filesystem │ /usr
 2 │ X │ filesystem │ /home
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/> shells
━━━┯━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name                                             │ path
───┼───┼──────────────────────────────────────────────────┼─────────────────────────────────────
 0 │   │ filesystem                                       │ /home/jonathanturner/Source/nushell
 1 │ X │ {/home/jonathanturner/Source/nushell/Cargo.toml} │ /
━━━┷━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

shuffle

Shuffles the rows in a random order.

# Examples

Passing the same input to shuffle multiple times gives different results -

> echo [ a b c d ] | shuffle
───┬───
 0 │ a
 1 │ c
 2 │ d
 3 │ b
───┴───
> echo [ a b c d ] | shuffle
───┬───
 0 │ c
 1 │ b
 2 │ d
 3 │ a
───┴───
> echo [ a b c d ] | shuffle
───┬───
 0 │ c
 1 │ b
 2 │ a
 3 │ d
───┴───

size

This commands gives word count statistics on any text.

# Examples

> open lalala.txt | size
━━━━━━━┯━━━━━━━┯━━━━━━━┯━━━━━━━━━━━━
 lines │ words │ chars │ bytes
───────┼───────┼───────┼────────────
     4107272
━━━━━━━┷━━━━━━━┷━━━━━━━┷━━━━━━━━━━━━
> open the_mysterious_affair_at_styles.txt | size
━━━━━━━┯━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━
 lines │ words │ chars  │ bytes
───────┼───────┼────────┼────────────
  893562352349459361771
━━━━━━━┷━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━

skip until

Skips rows until the condition matches.

# Usage

> skip until <condition> {flags} 

# Parameters

  • <condition> The condition that must be met to stop skipping

# Flags

  • -h, --help: Display this help message

skip

Skips the first 'n' rows of a table.

# Usage

> [input-command] | skip (n)

# Examples

If we open a file with a list of contacts, we get all of the contacts.

> open contacts.csv
───┬─────────┬──────┬─────────────────
 # │ first   │ last │ email
───┼─────────┼──────┼─────────────────
 0 │ John    │ Doe  │ doe.1@email.com
 1 │ Jane    │ Doe  │ doe.2@email.com
 2 │ Chris   │ Doe  │ doe.3@email.com
 3 │ Francis │ Doe  │ doe.4@email.com
───┴─────────┴──────┴─────────────────

To ignore the first 2 contacts, we can skip them.

> open contacts.csv | skip 2
───┬─────────┬──────┬─────────────────
 # │ first   │ last │ email
───┼─────────┼──────┼─────────────────
 0 │ Chris   │ Doe  │ doe.3@email.com
 1 │ Francis │ Doe  │ doe.4@email.com
───┴─────────┴──────┴─────────────────

skip-while

# skip-while

Skips rows while the condition matches.

# Usage

> [input-command] | skip-while <condition>

# Examples

If we open a file with a list of contacts, we get all of the contacts.

> open contacts.csv | sort-by "last name"
───┬────────────┬───────────┬──────────────────
 # │ first name │ last name │ email
───┼────────────┼───────────┼──────────────────
 0 │ John       │ Abbot     │ abbot@email.com
 1 │ Chris      │ Beasly    │ beasly@email.com
 2 │ Jane       │ Carver    │ carver@email.com
 3 │ Francis    │ Davis     │ davis@email.com
───┴────────────┴───────────┴──────────────────

To exclude skip contacts with last names starting with 'A' or 'B', use skip-while:

> open contacts.csv | sort-by "last name" |  skip-while "last name" < "C"
───┬────────────┬───────────┬──────────────────
 # │ first name │ last name │ email
───┼────────────┼───────────┼──────────────────
 0 │ Jane       │ Carver    │ carver@email.com
 1 │ Francis    │ Davis     │ davis@email.com
───┴────────────┴───────────┴──────────────────

Note that the order of input rows matters. Once a single row does not match the condition, all following rows are included in the output, whether or not they match the condition:

> open contacts.csv | skip-while "last name" < "C"
───┬────────────┬───────────┬──────────────────
 # │ first name │ last name │ email
───┼────────────┼───────────┼──────────────────
 0 │ Jane       │ Carver    │ carver@email.com
 1 │ Chris      │ Beasly    │ beasly@email.com
 2 │ Francis    │ Davis     │ davis@email.com
───┴────────────┴───────────┴──────────────────

See the where command to filter each individual row by a condition, regardless of order.

sleep

Delay for a specified amount of time

Syntax: sleep <time> [additional_time]...

# Flags

-h, --help Display help message.

# Examples

Sleep for 3 seconds

> sleep 3sec

Sleep for 1 minute and 2 seconds

> sleep 1sec 1min 1sec

sort-by

# sort-by

The sort-by command sorts the table being displayed in the terminal by a chosen column(s).

sort-by takes multiple arguments (being the names of columns) sorting by each argument in order.

# Flags

  • -i, --insensitive: Sort string-based columns case insensitively

# Examples

> ls | sort-by size
━━━┯━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━
 # │ name │ type │ readonly │ size   │ accessed       │ modified
───┼──────┼──────┼──────────┼────────┼────────────────┼────────────────
 0 │ az   │ File │          │  18 B  │ 4 minutes ago  │ 4 minutes ago
 1 │ a    │ File │          │  18 B  │ 4 minutes ago  │ 38 minutes ago
 2 │ ad   │ File │          │  18 B  │ 4 minutes ago  │ 4 minutes ago
 3 │ ac   │ File │          │  18 B  │ 4 minutes ago  │ 4 minutes ago
 4 │ ab   │ File │          │  18 B  │ 4 minutes ago  │ 4 minutes ago
 5 │ c    │ File │          │ 102 B  │ 35 minutes ago │ 35 minutes ago
 6 │ d    │ File │          │ 189 B  │ 35 minutes ago │ 34 minutes ago
 7 │ b    │ File │          │ 349 B  │ 35 minutes ago │ 35 minutes ago
━━━┷━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━
> ls | sort-by size name
━━━┯━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━
 # │ name │ type │ readonly │ size   │ accessed       │ modified
───┼──────┼──────┼──────────┼────────┼────────────────┼────────────────
 0 │ a    │ File │          │  18 B  │ 4 minutes ago  │ 39 minutes ago
 1 │ ab   │ File │          │  18 B  │ 4 minutes ago  │ 4 minutes ago
 2 │ ac   │ File │          │  18 B  │ 4 minutes ago  │ 4 minutes ago
 3 │ ad   │ File │          │  18 B  │ 4 minutes ago  │ 4 minutes ago
 4 │ az   │ File │          │  18 B  │ 4 minutes ago  │ 4 minutes ago
 5 │ c    │ File │          │ 102 B  │ 36 minutes ago │ 35 minutes ago
 6 │ d    │ File │          │ 189 B  │ 35 minutes ago │ 35 minutes ago
 7 │ b    │ File │          │ 349 B  │ 36 minutes ago │ 36 minutes ago
> ls | sort-by accessed
━━━┯━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━
 # │ name │ type │ readonly │ size   │ accessed       │ modified
───┼──────┼──────┼──────────┼────────┼────────────────┼────────────────
 0 │ b    │ File │          │ 349 B  │ 37 minutes ago │ 37 minutes ago
 1 │ c    │ File │          │ 102 B  │ 37 minutes ago │ 37 minutes ago
 2 │ d    │ File │          │ 189 B  │ 37 minutes ago │ 36 minutes ago
 3 │ a    │ File │          │  18 B  │ 6 minutes ago  │ 40 minutes ago
 4 │ ab   │ File │          │  18 B  │ 6 minutes ago  │ 6 minutes ago
 5 │ ac   │ File │          │  18 B  │ 6 minutes ago  │ 6 minutes ago
 6 │ ad   │ File │          │  18 B  │ 5 minutes ago  │ 5 minutes ago
 7 │ az   │ File │          │  18 B  │ 5 minutes ago  │ 5 minutes ago
━━━┷━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━

Within the Nushell repository...

> ls | sort-by --insensitive name
────┬────────────────────┬──────┬──────────┬──────────────
 #  │ name               │ type │ size     │ modified
────┼────────────────────┼──────┼──────────┼──────────────
  0 │ assets             │ Dir  │    128 B │ 6 months ago
  1 │ build.rs           │ File │     78 B │ 5 months ago
  2 │ Cargo.lock         │ File │ 118.3 KB │ 1 hour ago
  3 │ Cargo.toml         │ File │   5.5 KB │ 1 hour ago
  4 │ CODE_OF_CONDUCT.md │ File │   3.4 KB │ 1 hour ago
  5 │ CONTRIBUTING.md    │ File │   1.3 KB │ 1 hour ago
  6 │ crates             │ Dir  │    832 B │ 1 hour ago
  7 │ debian             │ Dir  │    352 B │ 6 months ago
  8 │ docker             │ Dir  │    288 B │ 4 months ago
  9 │ docs               │ Dir  │    192 B │ 1 hour ago
 10 │ features.toml      │ File │    632 B │ 5 months ago
 11 │ images             │ Dir  │    160 B │ 6 months ago
 12 │ LICENSE            │ File │   1.1 KB │ 4 months ago
 13 │ Makefile.toml      │ File │    449 B │ 6 months ago
 14 │ README.build.txt   │ File │    192 B │ 1 hour ago
 15 │ README.md          │ File │  16.0 KB │ 1 hour ago
 16 │ rustfmt.toml       │ File │     16 B │ 6 months ago
 17 │ src                │ Dir  │    128 B │ 1 week ago
 18 │ target             │ Dir  │    160 B │ 1 day ago
 19 │ tests              │ Dir  │    192 B │ 4 months ago
 20 │ TODO.md            │ File │      0 B │ 1 week ago
 21 │ wix                │ Dir  │    128 B │ 1 hour ago
────┴────────────────────┴──────┴──────────┴──────────────

Within the Nushell repository...

> ls | sort-by --insensitive type name
────┬────────────────────┬──────┬──────────┬──────────────
 #  │ name               │ type │ size     │ modified
────┼────────────────────┼──────┼──────────┼──────────────
  0 │ assets             │ Dir  │    128 B │ 6 months ago
  1 │ crates             │ Dir  │    832 B │ 1 hour ago
  2 │ debian             │ Dir  │    352 B │ 6 months ago
  3 │ docker             │ Dir  │    288 B │ 4 months ago
  4 │ docs               │ Dir  │    192 B │ 1 hour ago
  5 │ images             │ Dir  │    160 B │ 6 months ago
  6 │ src                │ Dir  │    128 B │ 1 week ago
  7 │ target             │ Dir  │    160 B │ 1 day ago
  8 │ tests              │ Dir  │    192 B │ 4 months ago
  9 │ wix                │ Dir  │    128 B │ 1 hour ago
 10 │ build.rs           │ File │     78 B │ 5 months ago
 11 │ Cargo.lock         │ File │ 118.3 KB │ 1 hour ago
 12 │ Cargo.toml         │ File │   5.5 KB │ 1 hour ago
 13 │ CODE_OF_CONDUCT.md │ File │   3.4 KB │ 1 hour ago
 14 │ CONTRIBUTING.md    │ File │   1.3 KB │ 1 hour ago
 15 │ features.toml      │ File │    632 B │ 5 months ago
 16 │ LICENSE            │ File │   1.1 KB │ 4 months ago
 17 │ Makefile.toml      │ File │    449 B │ 6 months ago
 18 │ README.build.txt   │ File │    192 B │ 1 hour ago
 19 │ README.md          │ File │  16.0 KB │ 1 hour ago
 20 │ rustfmt.toml       │ File │     16 B │ 6 months ago
 21 │ TODO.md            │ File │      0 B │ 1 week ago
────┴────────────────────┴──────┴──────────┴──────────────

source

Runs a script file in the current context.

# Usage

> source <filename> {flags} 

# Parameters

  • <filename> the filepath to the script file to source

# Flags

  • -h, --help: Display this help message

split-by

# split-by

Creates a new table with the data from the inner tables split by the column given.

# Usage

> split-by (column_name) {flags} 

# Parameters

  • (column_name) the name of the column within the nested table to split by

# Flags

  • -h, --help: Display this help message

split chars

splits a string's characters into separate rows

# Usage

> split chars {flags} 

# Flags

  • -h, --help: Display this help message

# Examples

Split the string's characters into separate rows

> echo 'hello' | split chars

split column

splits contents across multiple columns via the separator.

Syntax: split column <separator> ...args{flags}

# Parameters

  • <separator>: string that denotes what separates columns
  • args: column names to give the new columns. If not specified they will be set to Column1 Column2 ...

# Flags

--collapse-empty
  Removes empty columns

# Examples

If we have file structured like this:

0.12643678160919541 | 0.6851851851851852 | 0.273972602739726
0.28735632183908044 | 0.09259259259259259 | 0.6986301369863014
0.8045977011494253 | 0.8148148148148148 | 0.7397260273972602
0.28735632183908044 | 0.09259259259259259 | 0.547945205479452
0.6896551724137931 | 0.7037037037037037 | 1.2465753424657535
0.6896551724137931 | 0.8333333333333334 | 0.4657534246575342
0.9080459770114943 | 1.3333333333333333 | 0.4931506849315068
0.9310344827586207 | 1.1296296296296295 | 0.7123287671232876
0.3448275862068966 | 0.018518518518518517 | 0.6575342465753424
1.0459770114942528 | 1.0925925925925926 | 0.6164383561643836

We can build a table from it using the split column command

> open coordinates.txt | lines | split column " | "
───┬─────────────────────┬──────────────────────┬────────────────────
 # │ Column1             │ Column2              │ Column3
───┼─────────────────────┼──────────────────────┼────────────────────
 00.126436781609195410.68518518518518520.273972602739726
 10.287356321839080440.092592592592592590.6986301369863014
 20.80459770114942530.81481481481481480.7397260273972602
 30.287356321839080440.092592592592592590.547945205479452
 40.68965517241379310.70370370370370371.2465753424657535
 50.68965517241379310.83333333333333340.4657534246575342
 60.90804597701149431.33333333333333330.4931506849315068
 70.93103448275862071.12962962962962950.7123287671232876
 80.34482758620689660.0185185185185185170.6575342465753424
 91.04597701149425281.09259259259259260.6164383561643836
───┴─────────────────────┴──────────────────────┴────────────────────

And give names to the columns

> open coordinates.txt | lines | split column " | " x y z
───┬─────────────────────┬──────────────────────┬────────────────────
 # │ x                   │ y                    │ z
───┼─────────────────────┼──────────────────────┼────────────────────
 00.126436781609195410.68518518518518520.273972602739726
 10.287356321839080440.092592592592592590.6986301369863014
 20.80459770114942530.81481481481481480.7397260273972602
 30.287356321839080440.092592592592592590.547945205479452
 40.68965517241379310.70370370370370371.2465753424657535
 50.68965517241379310.83333333333333340.4657534246575342
 60.90804597701149431.33333333333333330.4931506849315068
 70.93103448275862071.12962962962962950.7123287671232876
 80.34482758620689660.0185185185185185170.6575342465753424
 91.04597701149425281.09259259259259260.6164383561643836
───┴─────────────────────┴──────────────────────┴────────────────────

split row

splits contents over multiple rows via the separator.

Syntax: split row <separator>

# Parameters

  • <separator> the character that denotes what separates rows

# Examples

We can build a table from a file that looks like this

> open table.txt
4, 0, 2, 0, 7, 8

using the split row command.

open table.txt | split row ", "
───┬───
 # │
───┼───
 04
 10
 22
 30
 47
 58
───┴───

split

Split contents across desired subcommand (like row, column) via the separator.

# Usage

> split <subcommand> {flags} 

# Subcommands

  • split chars - splits a string's characters into separate rows
  • split column - splits contents across multiple columns via the separator.
  • split row - splits contents over multiple rows via the separator.

# Flags

  • -h, --help: Display this help message

start

Opens each file/directory/URL using the default application.

Syntax: start ...args{flags}

# Parameters

  • args: a list of space-separated files to open

# Flags

-a --application <string>
  Specifies the application used for opening the files/directories/urls

# Example

Open index.html in the system's default browser (cross platform):

> start index.html

Open index.html in Firefox (specific path for OSX):

start index.html -a /Applications/Firefox.app

str camel-case

# str camel-case

converts a string to camelCase

# Usage

> str camel-case ...args {flags} 

# Parameters

  • ...args: optionally convert text to camelCase by column paths

# Flags

  • -h, --help: Display this help message

# Examples

convert a string to camelCase

> echo 'NuShell' | str camel-case

str capitalize

capitalizes text

# Usage

> str capitalize ...args {flags} 

# Parameters

  • ...args: optionally capitalize text by column paths

# Flags

  • -h, --help: Display this help message

# Examples

Capitalize contents

> echo 'good day' | str capitalize

str collect

collects a list of strings into a string

# Usage

> str collect (separator) {flags} 

# Parameters

  • (separator) the separator to put between the different values

# Flags

  • -h, --help: Display this help message

# Examples

Collect a list of string

> echo ['a' 'b' 'c'] | str collect

str contains

Checks if string contains pattern

# Usage

> str contains <pattern> ...args {flags} 

# Parameters

  • <pattern> the pattern to find
  • ...args: optionally check if string contains pattern by column paths

# Flags

  • -h, --help: Display this help message
  • -i, --insensitive: search is case insensitive

# Examples

Check if string contains pattern

> echo 'my_library.rb' | str contains '.rb'

Check if string contains pattern case insensitive

> echo 'my_library.rb' | str contains -i '.RB'

str downcase

downcases text

# Usage

> str downcase ...args {flags} 

# Parameters

  • ...args: optionally downcase text by column paths

# Flags

  • -h, --help: Display this help message

# Examples

Downcase contents

> echo 'NU' | str downcase

str ends-with

# str ends-with

checks if string ends with pattern

# Usage

> str ends-with <pattern> ...args {flags} 

# Parameters

  • <pattern> the pattern to match
  • ...args: optionally matches suffix of text by column paths

# Flags

  • -h, --help: Display this help message

# Examples

Checks if string ends with '.rb' pattern

> echo 'my_library.rb' | str ends-with '.rb'

str find-replace

# str find-replace

finds and replaces text

# Usage

> str find-replace <find> <replace> ...args {flags} 

# Parameters

  • <find> the pattern to find
  • <replace> the replacement pattern
  • ...args: optionally find and replace text by column paths

# Flags

  • -h, --help: Display this help message
  • -a, --all: replace all occurrences of find string

# Examples

Find and replace contents with capture group

> echo 'my_library.rb' | str find-replace '(.+).rb' '$1.nu'

Find and replace all occurrences of find string

> echo 'abc abc abc' | str find-replace -a 'b' 'z'

str index-of

# str index-of

Returns starting index of given pattern in string counting from 0. Returns -1 when there are no results.

# Usage

> str index-of <pattern> ...args {flags} 

# Parameters

  • <pattern> the pattern to find index of
  • ...args: optionally returns index of pattern in string by column paths

# Flags

  • -h, --help: Display this help message
  • -r, --range : optional start and/or end index
  • -e, --end: search from the end of the string

# Examples

Returns index of pattern in string

> echo 'my_library.rb' | str index-of '.rb'

Returns index of pattern in string with start index

> echo '.rb.rb' | str index-of '.rb' -r '1,'

Returns index of pattern in string with end index

> echo '123456' | str index-of '6' -r ',4'

Returns index of pattern in string with start and end index

> echo '123456' | str index-of '3' -r '1,4'

Alternatively you can use this form

> echo '123456' | str index-of '3' -r [1 4]

Returns index of pattern in string

> echo '/this/is/some/path/file.txt' | str index-of '/' -e

str kebab-case

# str kebab-case

converts a string to kebab-case

# Usage

> str kebab-case ...args {flags} 

# Parameters

  • ...args: optionally convert text to kebab-case by column paths

# Flags

  • -h, --help: Display this help message

# Examples

convert a string to kebab-case

> echo 'NuShell' | str kebab-case

str length

outputs the lengths of the strings in the pipeline

# Usage

> str length ...args {flags} 

# Parameters

  • ...args: optionally find length of text by column paths

# Flags

  • -h, --help: Display this help message

# Examples

Return the lengths of multiple strings

> echo 'hello' | str length

Return the lengths of multiple strings

> echo 'hi' 'there' | str length

str lpad

pad a string with a character a certain length

# Usage

> str lpad ...args {flags} 

# Parameters

  • ...args: optionally check if string contains pattern by column paths

# Flags

  • -h, --help: Display this help message
  • -l, --length (required parameter): length to pad to
  • -c, --character (required parameter): character to pad with

# Examples

Left pad a string with a character a number of places

> echo 'nushell' | str lpad -l 10 -c '*'

Left pad a string with a character a number of places

> echo '123' | str lpad -l 10 -c '0'

Use lpad to truncate a string

> echo '123456789' | str lpad -l 3 -c '0'

Use lpad to pad Unicode

> echo '▉' | str lpad -l 10 -c '▉'

str ltrim

trims whitespace or character from the beginning of text

# Usage

> str ltrim ...args {flags} 

# Parameters

  • ...args: optionally trim text starting from the beginning by column paths

# Flags

  • -h, --help: Display this help message
  • -c, --char : character to trim (default: whitespace)

# Examples

Trim whitespace from the beginning of string

> echo ' Nu shell ' | str ltrim

Trim a specific character

> echo '=== Nu shell ===' | str ltrim -c '='

str pascal-case

# str pascal-case

converts a string to PascalCase

# Usage

> str pascal-case ...args {flags} 

# Parameters

  • ...args: optionally convert text to PascalCase by column paths

# Flags

  • -h, --help: Display this help message

# Examples

convert a string to PascalCase

> echo 'nu-shell' | str pascal-case

str reverse

outputs the reversals of the strings in the pipeline

# Usage

> str reverse ...args {flags} 

# Parameters

  • ...args: optionally reverse text by column paths

# Flags

  • -h, --help: Display this help message

# Examples

Return the reversals of multiple strings

> echo 'Nushell' | str reverse

str rpad

pad a string with a character a certain length

# Usage

> str rpad ...args {flags} 

# Parameters

  • ...args: optionally check if string contains pattern by column paths

# Flags

  • -h, --help: Display this help message
  • -l, --length (required parameter): length to pad to
  • -c, --character (required parameter): character to pad with

# Examples

Right pad a string with a character a number of places

> echo 'nushell' | str rpad -l 10 -c '*'

Right pad a string with a character a number of places

> echo '123' | str rpad -l 10 -c '0'

Use rpad to truncate a string

> echo '123456789' | str rpad -l 3 -c '0'

Use rpad to pad Unicode

> echo '▉' | str rpad -l 10 -c '▉'

str rtrim

trims whitespace or character from the end of text

# Usage

> str rtrim ...args {flags} 

# Parameters

  • ...args: optionally trim text starting from the end by column paths

# Flags

  • -h, --help: Display this help message
  • -c, --char : character to trim (default: whitespace)

# Examples

Trim whitespace from the end of string

> echo ' Nu shell ' | str rtrim

Trim a specific character

> echo '=== Nu shell ===' | str rtrim -c '='

str screaming-snake-case

# str screaming-snake-case

converts a string to SCREAMING_SNAKE_CASE

# Usage

> str screaming-snake-case ...args {flags} 

# Parameters

  • ...args: optionally convert text to SCREAMING_SNAKE_CASE by column paths

# Flags

  • -h, --help: Display this help message

# Examples

convert a string to SCREAMING_SNAKE_CASE

> echo 'NuShell' | str screaming-snake-case

str snake-case

# str snake-case

converts a string to snake_case

# Usage

> str snake-case ...args {flags} 

# Parameters

  • ...args: optionally convert text to snake_case by column paths

# Flags

  • -h, --help: Display this help message

# Examples

convert a string to snake_case

> echo 'NuShell' | str snake-case

str starts-with

# str starts-with

checks if string starts with pattern

# Usage

> str starts-with <pattern> ...args {flags} 

# Parameters

  • <pattern> the pattern to match
  • ...args: optionally matches prefix of text by column paths

# Flags

  • -h, --help: Display this help message

# Examples

Checks if string starts with 'my' pattern

> echo 'my_library.rb' | str starts-with 'my'

str substring

substrings text

# Usage

> str substring <range> ...args {flags} 

# Parameters

  • <range> the indexes to substring [start end]
  • ...args: optionally substring text by column paths

# Flags

  • -h, --help: Display this help message

# Examples

Get a substring from the text

> echo 'good nushell' | str substring [5 12]

Alternatively, you can use the form

> echo 'good nushell' | str substring '5,12'

Drop the last n characters from the string

> echo 'good nushell' | str substring ',-5'

Get the remaining characters from a starting index

> echo 'good nushell' | str substring '5,'

Get the characters from the beginning until ending index

> echo 'good nushell' | str substring ',7'

str to-datetime

# str to-datetime

converts text into datetime

# Usage

> str to-datetime ...args {flags} 

# Parameters

  • ...args: optionally convert text into datetime by column paths

# Flags

  • -h, --help: Display this help message
  • -z, --timezone : Specify timezone if the input is timestamp, like 'UTC/u' or 'LOCAL/l'
  • -o, --offset : Specify timezone by offset if the input is timestamp, like '+8', '-4', prior than timezone
  • -f, --format : Specify date and time formatting

# Examples

Convert to datetime

> echo '16.11.1984 8:00 am +0000' | str to-datetime

Convert to datetime

> echo '2020-08-04T16:39:18+00:00' | str to-datetime

Convert to datetime using a custom format

> echo '20200904_163918+0000' | str to-datetime -f '%Y%m%d_%H%M%S%z'

Convert timestamp (no larger than 8e+12) to datetime using a specified timezone

> echo '1614434140' | str to-datetime -z 'UTC'

Convert timestamp (no larger than 8e+12) to datetime using a specified timezone offset (between -12 and 12)

> echo '1614434140' | str to-datetime -o '+9'

str to-decimal

# str to-decimal

converts text into decimal

# Usage

> str to-decimal ...args {flags} 

# Parameters

  • ...args: optionally convert text into decimal by column paths

# Flags

  • -h, --help: Display this help message

# Examples

Convert to decimal

> echo '3.1415' | str to-decimal

str to-int

# str to-int

converts text into integer

# Usage

> str to-int ...args {flags} 

# Parameters

  • ...args: optionally convert text into integer by column paths

# Flags

  • -h, --help: Display this help message
  • -r, --radix : radix of integer

# Examples

Convert to an integer

> echo '255' | str to-int

Convert str column to an integer

> echo [['count']; ['255']] | str to-int count | get count

Convert to integer from binary

> echo '1101' | str to-int -r 2

Convert to integer from hex

> echo 'FF' | str to-int -r 16

str trim

trims text

# Usage

> str trim ...args {flags} 

# Parameters

  • ...args: optionally trim text by column paths

# Flags

  • -h, --help: Display this help message
  • -c, --char : character to trim (default: whitespace)

# Examples

Trim whitespace

> echo 'Nu shell ' | str trim

Trim a specific character

> echo '=== Nu shell ===' | str trim -c '=' | str trim

str upcase

upcases text

# Usage

> str upcase ...args {flags} 

# Parameters

  • ...args: optionally upcase text by column paths

# Flags

  • -h, --help: Display this help message

# Examples

Upcase contents

> echo 'nu' | str upcase

str

Applies the subcommand to a value or a table.

# Examples

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────────────
 0 │ X │ filesystem │ /home/TUX/stuff/expr/stuff
 1 │   │ filesystem │ /
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> shells | str upcase path
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────────────
 0 │ X │ filesystem │ /HOME/TUX/STUFF/EXPR/STUFF
 1 │   │ filesystem │ /
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> shells | str downcase path
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────────────
 0 │ X │ filesystem │ /home/tux/stuff/expr/stuff
 1 │   │ filesystem │ /
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> shells | str substring "21, 99" path
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────────────
 0 │ X │ filesystem │ stuff
 1 │   │ filesystem │
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> shells | str substring "6," path
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────────────
 0 │ X │ filesystem │ TUX/stuff/expr/stuff
 1 │   │ filesystem │
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> echo "1, 2, 3" | split row "," | str to-int | math sum
6
> echo "nu" | str capitalize
Nu
> echo "Nu    " | str trim
Nu
> echo "Nushell" | str reverse
llehsuN
> shells | str find-replace "TUX" "skipper" path
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────────────
 0 │ X │ filesystem │ /home/skipper/stuff/expr/stuff
 1 │   │ filesystem │ /
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

sys

This command gives information about the system nu is running on.

# Examples

> sys
─────────┬─────────────────────────────────────────
 host[row 7 columns]
 cpu     │ [row cores current ghz max ghz min ghz]
 disks   │ [table 4 rows]
 mem     │ [row free swap free swap total total]
 net     │ [table 19 rows]
 battery │ [table 1 rows]
─────────┴─────────────────────────────────────────
> sys | get host
──────────┬──────────────────────────────────────────────────────────────────────────────────────────────────
 name     │ Darwin
 release  │ 19.5.0
 version  │ Darwin Kernel Version 19.5.0: Tue May 26 20:41:44 PDT 2020; root:xnu-6153.121.2~2/RELEASE_X86_64
 hostname │ Josephs-MacBook-Pro.local
 arch     │ x86_64
 uptime5:10:12:33
 sessions │ [table 2 rows]
──────────┴──────────────────────────────────────────────────────────────────────────────────────────────────
> sys | get cpu
─────────────┬────────
 cores       │ 16
 current ghz │ 2.4000
 min ghz     │ 2.4000
 max ghz     │ 2.4000
─────────────┴────────
> sys | get mem
────────────┬─────────
 total      │ 68.7 GB
 free11.1 GB
 swap total │ 0 B
 swap free0 B
────────────┴─────────

table

View the contents of the pipeline as a table.

# Usage

> table {flags} 

# Flags

  • -h, --help: Display this help message
  • -n, --start_number : row number to start viewing from

tags

The tags commands allows users to access the metadata of the previous value in the pipeline. This command may be run on multiple values of input as well.

As of writing this, the only metadata returned includes:

  • span: the start and end indices of the previous value's substring location
  • anchor: the source where data was loaded from; this may not appear if the previous pipeline value didn't actually have a source (like trying to open a dir, or running ls on a dir)

# Examples

> open README.md | tags
────────┬──────────────────────────────────────────────────
 span   │ [row end start]
 anchor │ /Users/danielh/Projects/github/nushell/README.md
────────┴──────────────────────────────────────────────────
> open README.md | tags | get span
───────┬────
 start │ 5
 end   │ 14
───────┴────
> ls | tags | first 3 | get span
───┬───────┬─────
 # │ start │ end
───┼───────┼─────
 002
 102
 202
───┴───────┴─────

# Reference

More useful information on the tags command can be found by referencing The Nu Book's entry on Metadata (opens new window)

textview

Autoview of text data.

# Usage

> textview {flags} 

# Flags

  • -h, --help: Display this help message

textview config

# textview config

The configuration for textview, which is used to autoview text files, uses bat (opens new window). The textview configuration will not use any existing bat configuration you may have.

# Configuration Points and Defaults

config point definition implemented
term_width The character width of the terminal (default: autodetect) yes
tab_width The width of tab characters (default: None - do not turn tabs to spaces) yes
colored_output Whether or not the output should be colorized (default: true) yes
true_color Whether or not to output 24bit colors (default: true) yes
header Whether to show a header with the file name yes
line_numbers Whether to show line numbers yes
grid Whether to paint a grid, separating line numbers, git changes and the code yes
vcs_modification_markers Whether to show modification markers for VCS changes. This has no effect if the git feature is not activated. yes
snip Whether to show "snip" markers between visible line ranges (default: no) yes
wrapping_mode Text wrapping mode (default: do not wrap), options (Character, NoWrapping) yes
use_italics Whether or not to use ANSI italics (default: off) yes
paging_mode If and how to use a pager (default: no paging), options (Always, QuitIfOneScreen, Never) yes
pager Specify the command to start the pager (default: use "less") yes
line_ranges Specify the lines that should be printed (default: all) no
highlight Specify a line that should be highlighted (default: none). This can be called multiple times to highlight more than one line. See also: highlight_range. no
highlight_range Specify a range of lines that should be highlighted (default: none). This can be called multiple times to highlight more than one range of lines. no
theme Specify the highlighting theme (default: OneHalfDark) yes

# Example textview configuration for config.toml

[textview]
term_width = "default"
tab_width = 4
colored_output = true
true_color = true
header = true
line_numbers = false
grid = false
vcs_modification_markers = true
snip = true
wrapping_mode = "NoWrapping"
use_italics = true
paging_mode = "QuitIfOneScreen"
pager = "less"
theme = "TwoDark"

# Example Usage

> open src/main.rs
> cat some_file.txt | textview
> fetch https://www.jonathanturner.org/feed.xml --raw

# Help

For a more detailed description of the configuration points that textview uses, please visit the bat repo at https://github.com/sharkdp/bat (opens new window).

to bson

Convert table into .bson binary

# Usage

> to bson {flags} 

# Flags

  • -h, --help: Display this help message

to csv

Converts table data into csv text.

# Example

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────
 0 │ X │ filesystem │ /home/shaurya
 1 │   │ filesystem │ /home/shaurya/Pictures
 2 │   │ filesystem │ /home/shaurya/Desktop
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━
> shells | to csv
 ,name,path
X,filesystem,/home/shaurya
 ,filesystem,/home/shaurya/Pictures
 ,filesystem,/home/shaurya/Desktop
> open caco3_plastics.csv
━━━┯━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━━┯━━━━━━━━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━━━━
 # │ importer     │ shipper      │ tariff_item │ name         │ origin   │ shipped_at │ arrived_at │ net_weight │ fob_price │ cif_price │ cif_per_net_
   │              │              │             │              │          │            │            │            │           │           │ weight
───┼──────────────┼──────────────┼─────────────┼──────────────┼──────────┼────────────┼────────────┼────────────┼───────────┼───────────┼──────────────
 0 │ PLASTICOS    │ S A REVERTE  │ 2509000000  │ CARBONATO DE │ SPAIN    │ 18/03/2016 │ 17/04/2016 │ 81,000.00  │ 14,417.58 │ 18,252.34 │ 0.23
   │ RIVAL CIA    │              │             │ CALCIO TIPO  │          │            │            │            │           │           │
   │ LTDA         │              │             │ CALCIPORE    │          │            │            │            │           │           │
   │              │              │             │ 160 T AL     │          │            │            │            │           │           │
 1 │ MEXICHEM     │ OMYA ANDINA  │ 2836500000  │ CARBONATO    │ COLOMBIA │ 07/07/2016 │ 10/07/2016 │ 26,000.00  │ 7,072.00  │ 8,127.18  │ 0.31
   │ ECUADOR S.A. │ S A          │             │              │          │            │            │            │           │           │
 2 │ PLASTIAZUAY  │ SA REVERTE   │ 2836500000  │ CARBONATO DE │ SPAIN    │ 27/07/2016 │ 09/08/2016 │ 81,000.00  │ 8,100.00  │ 11,474.55 │ 0.14
   │ SA           │              │             │ CALCIO       │          │            │            │            │           │           │
 3 │ PLASTICOS    │ AND          │ 2836500000  │ CALCIUM      │ TURKEY   │ 04/10/2016 │ 11/11/2016 │ 100,000.00 │ 17,500.00 │ 22,533.75 │ 0.23
   │ RIVAL CIA    │ ENDUSTRIYEL  │             │ CARBONATE    │          │            │            │            │           │           │
   │ LTDA         │ HAMMADDELER  │             │ ANADOLU      │          │            │            │            │           │           │
   │              │ DIS TCARET   │             │ ANDCARB CT-1 │          │            │            │            │           │           │
   │              │ LTD.STI.     │             │              │          │            │            │            │           │           │
 4 │ QUIMICA      │ SA REVERTE   │ 2836500000  │ CARBONATO DE │ SPAIN    │ 24/06/2016 │ 12/07/2016 │ 27,000.00  │ 3,258.90  │ 5,585.00  │ 0.21
   │ COMERCIAL    │              │             │ CALCIO       │          │            │            │            │           │           │
   │ QUIMICIAL    │              │             │              │          │            │            │            │           │           │
   │ CIA. LTDA.   │              │             │              │          │            │            │            │           │           │
 5 │ PICA         │ OMYA ANDINA  │ 3824909999  │ CARBONATO DE │ COLOMBIA │ 01/01/1900 │ 18/01/2016 │ 66,500.00  │ 12,635.00 │ 18,670.52 │ 0.28
   │ PLASTICOS    │ S.A          │             │ CALCIO       │          │            │            │            │           │           │
   │ INDUSTRIALES │              │             │              │          │            │            │            │           │           │
   │ C.A.         │              │             │              │          │            │            │            │           │           │
 6 │ PLASTIQUIM   │ OMYA ANDINA  │ 3824909999  │ CARBONATO DE │ COLOMBIA │ 01/01/1900 │ 25/10/2016 │ 33,000.00  │ 6,270.00  │ 9,999.00  │ 0.30
   │ S.A.         │ S.A NIT      │             │ CALCIO       │          │            │            │            │           │           │
   │              │ 830.027.386- │             │ RECUBIERTO   │          │            │            │            │           │           │
   │              │ 6            │             │ CON ACIDO    │          │            │            │            │           │           │
   │              │              │             │ ESTEARICO    │          │            │            │            │           │           │
   │              │              │             │ OMYA CARB 1T │          │            │            │            │           │           │
   │              │              │             │ CG BBS 1000  │          │            │            │            │           │           │
 7 │ QUIMICOS     │ SIBELCO      │ 3824909999  │ CARBONATO DE │ COLOMBIA │ 01/11/2016 │ 03/11/2016 │ 52,000.00  │ 8,944.00  │ 13,039.05 │ 0.25
   │ ANDINOS      │ COLOMBIA SAS │             │ CALCIO       │          │            │            │            │           │           │
   │ QUIMANDI     │              │             │ RECUBIERTO   │          │            │            │            │           │           │
   │ S.A.         │              │             │              │          │            │            │            │           │           │
 8 │ TIGRE        │ OMYA ANDINA  │ 3824909999  │ CARBONATO DE │ COLOMBIA │ 01/01/1900 │ 28/10/2016 │ 66,000.00  │ 11,748.00 │ 18,216.00 │ 0.28
   │ ECUADOR S.A. │ S.A NIT      │             │ CALCIO       │          │            │            │            │           │           │
   │ ECUATIGRE    │ 830.027.386- │             │ RECUBIERTO   │          │            │            │            │           │           │
   │              │ 6            │             │ CON ACIDO    │          │            │            │            │           │           │
   │              │              │             │ ESTEARICO    │          │            │            │            │           │           │
   │              │              │             │ OMYACARB 1T  │          │            │            │            │           │           │
   │              │              │             │ CG BPA 25 NO │          │            │            │            │           │           │
━━━┷━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━┷━━━━━━━━━━━━━┷━━━━━━━━━━━━━━┷━━━━━━━━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━━━━
> open caco3_plastics.csv | to csv
importer,shipper,tariff_item,name,origin,shipped_at,arrived_at,net_weight,fob_price,cif_price,cif_per_net_weight
PLASTICOS RIVAL CIA LTDA,S A REVERTE,2509000000,CARBONATO DE CALCIO TIPO CALCIPORE 160 T AL,SPAIN,18/03/2016,17/04/2016,"81,000.00","14,417.58","18,252.34",0.23
MEXICHEM ECUADOR S.A.,OMYA ANDINA S A,2836500000,CARBONATO,COLOMBIA,07/07/2016,10/07/2016,"26,000.00","7,072.00","8,127.18",0.31
PLASTIAZUAY SA,SA REVERTE,2836500000,CARBONATO DE CALCIO,SPAIN,27/07/2016,09/08/2016,"81,000.00","8,100.00","11,474.55",0.14
PLASTICOS RIVAL CIA LTDA,AND ENDUSTRIYEL HAMMADDELER DIS TCARET LTD.STI.,2836500000,CALCIUM CARBONATE ANADOLU ANDCARB CT-1,TURKEY,04/10/2016,11/11/2016,"100,000.00","17,500.00","22,533.75",0.23
QUIMICA COMERCIAL QUIMICIAL CIA. LTDA.,SA REVERTE,2836500000,CARBONATO DE CALCIO,SPAIN,24/06/2016,12/07/2016,"27,000.00","3,258.90","5,585.00",0.21
PICA PLASTICOS INDUSTRIALES C.A.,OMYA ANDINA S.A,3824909999,CARBONATO DE CALCIO,COLOMBIA,01/01/1900,18/01/2016,"66,500.00","12,635.00","18,670.52",0.28
PLASTIQUIM S.A.,OMYA ANDINA S.A NIT 830.027.386-6,3824909999,CARBONATO DE CALCIO RECUBIERTO CON ACIDO ESTEARICO OMYA CARB 1T CG BBS 1000,COLOMBIA,01/01/1900,25/10/2016,"33,000.00","6,270.00","9,999.00",0.30
QUIMICOS ANDINOS QUIMANDI S.A.,SIBELCO COLOMBIA SAS,3824909999,CARBONATO DE CALCIO RECUBIERTO,COLOMBIA,01/11/2016,03/11/2016,"52,000.00","8,944.00","13,039.05",0.25
TIGRE ECUADOR S.A. ECUATIGRE,OMYA ANDINA S.A NIT 830.027.386-6,3824909999,CARBONATO DE  CALCIO RECUBIERTO CON ACIDO ESTEARICO OMYACARB 1T CG BPA 25 NO,COLOMBIA,01/01/1900,28/10/2016,"66,000.00","11,748.00","18,216.00",0.28

To use a character other than ',' to separate records, use --separator:

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────
 0 │ X │ filesystem │ /home/shaurya
 1 │   │ filesystem │ /home/shaurya/Pictures
 2 │   │ filesystem │ /home/shaurya/Desktop
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━
> shells | to csv --separator ';'
 ;name,path
X;filesystem;/home/shaurya
 ;filesystem;/home/shaurya/Pictures
 ;filesystem;/home/shaurya/Desktop

The string '\t' can be used to separate on tabs. Note that this is the same as using the to tsv command.

Newlines '\n' are not acceptable separators.

Note that separators are currently provided as strings and need to be wrapped in quotes.

It is also considered an error to use a separator greater than one char:

> open pets.txt | from csv --separator '123'
error: Expected a single separator char from --separator
- shell:1:37
1 | open pets.txt | from csv --separator '123'
  |                                      ^^^^^ requires a single character string input

to html

Convert table into simple HTML

# Usage

> to html {flags} 

# Flags

  • -h, --help: Display this help message
  • -c, --html_color: change ansi colors to html colors
  • -n, --no_color: remove all ansi colors in output
  • -d, --dark: indicate your background color is a darker color
  • -p, --partial: only output the html for the content itself
  • -t, --theme : the name of the theme to use (github, blulocolight, ...)
  • -l, --list: list the names of all available themes

to json

Converts table data into JSON text.

# Flags

  • -p, --pretty <integer>: Formats the JSON text with the provided indentation setting

# Example

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────
 0 │ X │ filesystem │ /home/shaurya
 1 │   │ filesystem │ /home/shaurya/Pictures
 2 │   │ filesystem │ /home/shaurya/Desktop
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━
> shells | to json
[{" ":"X","name":"filesystem","path":"/home/shaurya"},{" ":" ","name":"filesystem","path":"/home/shaurya/Pictures"},{" ":" ","name":"filesystem","path":"/home/shaurya/Desktop"}]
> open sgml_description.json
━━━━━━━━━━━━━━━━
 glossary
────────────────
 [table: 1 row]
━━━━━━━━━━━━━━━━
> open sgml_description.json | to json
{"glossary":{"title":"example glossary","GlossDiv":{"title":"S","GlossList":{"GlossEntry":{"ID":"SGML","SortAs":"SGML","GlossTerm":"Standard Generalized Markup Language","Acronym":"SGML","Abbrev":"ISO 8879:1986","Height":10,"GlossDef":{"para":"A meta-markup language, used to create markup languages such as DocBook.","GlossSeeAlso":["GML","XML"]},"Sections":[101,102],"GlossSee":"markup"}}}}}

We can also convert formats!

> open jonathan.xml
━━━━━━━━━━━━━━━━
 rss
────────────────
 [table: 1 row]
━━━━━━━━━━━━━━━━
> open jonathan.xml | to json
{"rss":[{"channel":[{"title":["Jonathan Turner"]},{"link":["http://www.jonathanturner.org"]},{"link":[]},{"item":[{"title":["Creating crossplatform Rust terminal apps"]},{"description":["<p><img src=\"/images/pikachu.jpg\" alt=\"Pikachu animation in Windows\" /></p>\n\n<p><em>Look Mom, Pikachu running in Windows CMD!</em></p>\n\n<p>Part of the adventure is not seeing the way ahead and going anyway.</p>\n"]},{"pubDate":["Mon, 05 Oct 2015 00:00:00 +0000"]},{"link":["http://www.jonathanturner.org/2015/10/off-to-new-adventures.html"]},{"guid":["http://www.jonathanturner.org/2015/10/off-to-new-adventures.html"]}]}]}]}

to md

Convert table into simple Markdown.

# Flags

  • -p, --pretty: Formats the Markdown table to vertically align items

# Example

> ls | to md
|name|type|size|modified|
|-|-|-|-|
|CODE_OF_CONDUCT.md|File|3.4 KB|2 months ago|
|CONTRIBUTING.md|File|1.4 KB|1 month ago|
|Cargo.lock|File|144.4 KB|2 days ago|
|Cargo.toml|File|6.0 KB|2 days ago|
|LICENSE|File|1.1 KB|2 months ago|
|Makefile.toml|File|449 B|2 months ago|
|README.build.txt|File|192 B|2 months ago|
|README.md|File|15.9 KB|1 month ago|
|TODO.md|File|0 B|2 months ago|
|crates|Dir|896 B|2 days ago|
|debian|Dir|352 B|2 months ago|
|docker|Dir|288 B|1 month ago|
|docs|Dir|256 B|1 month ago|
|features.toml|File|632 B|2 months ago|
|images|Dir|160 B|2 months ago|
|pkg_mgrs|Dir|96 B|1 month ago|
|rustfmt.toml|File|16 B|9 months ago|
|samples|Dir|96 B|1 month ago|
|src|Dir|128 B|2 days ago|
|target|Dir|160 B|1 month ago|
|tests|Dir|192 B|2 months ago|
|wix|Dir|128 B|23 hours ago|

If we provide the -p flag, we can obtain a formatted version of the Markdown table

> ls | to md  -p
|name              |type|size    |modified    |
|------------------|----|--------|------------|
|CODE_OF_CONDUCT.md|File|3.4 KB  |2 months ago|
|CONTRIBUTING.md   |File|1.4 KB  |1 month ago |
|Cargo.lock        |File|144.4 KB|2 days ago  |
|Cargo.toml        |File|6.0 KB  |2 days ago  |
|LICENSE           |File|1.1 KB  |2 months ago|
|Makefile.toml     |File|449 B   |2 months ago|
|README.build.txt  |File|192 B   |2 months ago|
|README.md         |File|15.9 KB |1 month ago |
|TODO.md           |File|0 B     |2 months ago|
|crates            |Dir |896 B   |2 days ago  |
|debian            |Dir |352 B   |2 months ago|
|docker            |Dir |288 B   |1 month ago |
|docs              |Dir |256 B   |1 month ago |
|features.toml     |File|632 B   |2 months ago|
|images            |Dir |160 B   |2 months ago|
|pkg_mgrs          |Dir |96 B    |1 month ago |
|rustfmt.toml      |File|16 B    |9 months ago|
|samples           |Dir |96 B    |1 month ago |
|src               |Dir |128 B   |2 days ago  |
|target            |Dir |160 B   |1 month ago |
|tests             |Dir |192 B   |2 months ago|
|wix               |Dir |128 B   |23 hours ago|

to sqlite

Convert table into sqlite binary

# Usage

> to sqlite {flags} 

# Flags

  • -h, --help: Display this help message

to toml

Converts table data into toml text.

# Example

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────
 0 │ X │ filesystem │ /home/shaurya
 1 │   │ filesystem │ /home/shaurya/Pictures
 2 │   │ filesystem │ /home/shaurya/Desktop
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━
> shells | to toml
[[]]
" " = "X"
name = "filesystem"
path = "/home/shaurya"

[[]]
" " = " "
name = "filesystem"
path = "/home/shaurya/Pictures"

[[]]
" " = " "
name = "filesystem"
path = "/home/shaurya/Desktop"
> open cargo_sample.toml
━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━
 dependencies   │ dev-dependencies │ package
────────────────┼──────────────────┼────────────────
 [table: 1 row][table: 1 row][table: 1 row]
━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━
> open cargo_sample.toml | to toml
[dependencies]
ansi_term = "0.11.0"
directories = "2.0.2"
byte-unit = "2.1.0"
bytes = "0.4.12"
chrono-humanize = "0.0.11"
chrono-tz = "0.5.1"
clap = "2.33.0"
conch-parser = "0.1.1"
derive-new = "0.5.6"
dunce = "1.0.0"
futures-sink-preview = "0.3.0-alpha.16"
futures_codec = "0.2.2"
getset = "0.0.7"
itertools = "0.8.0"
lalrpop-util = "0.17.0"
language-reporting = "0.3.0"
log = "0.4.6"
logos = "0.10.0-rc2"
logos-derive = "0.10.0-rc2"
nom = "5.0.0-beta1"
ordered-float = "1.0.2"
pretty_env_logger = "0.3.0"
prettyprint = "0.6.0"
prettytable-rs = "0.8.0"
regex = "1.1.6"
rustyline = "4.1.0"
serde = "1.0.91"
serde_derive = "1.0.91"
serde_json = "1.0.39"
sysinfo = "0.8.4"
term = "0.5.2"
tokio-fs = "0.1.6"
toml = "0.5.1"
toml-query = "0.9.0"

[dependencies.chrono]
features = ["serde"]
version = "0.4.6"

[dependencies.cursive]
default-features = false
features = ["pancurses-backend"]
version = "0.31.1"

[dependencies.futures-preview]
features = ["compat", "io-compat"]
version = "0.3.0-alpha.16"

[dependencies.indexmap]
features = ["serde-1"]
version = "1.0.2"

[dependencies.pancurses]
features = ["win32a"]
version = "0.16"

[dev-dependencies]
pretty_assertions = "0.6.1"

[package]
authors = ["The Nu Project Contributors"]
description = "A shell for the GitHub era"
edition = "2018"
license = "ISC"
name = "nu"
version = "0.1.1"

to tsv

Converts table data into tsv text.

# Example

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────
 0 │ X │ filesystem │ /home/shaurya
 1 │   │ filesystem │ /home/shaurya/Pictures
 2 │   │ filesystem │ /home/shaurya/Desktop
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━
> shells | to tsv
  name  path
X filesystem  /home/shaurya
> open caco3_plastics.tsv
━━━┯━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━━┯━━━━━━━━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━━━━
 # │ importer     │ shipper      │ tariff_item │ name         │ origin   │ shipped_at │ arrived_at │ net_weight │ fob_price │ cif_price │ cif_per_net_
   │              │              │             │              │          │            │            │            │           │           │ weight
───┼──────────────┼──────────────┼─────────────┼──────────────┼──────────┼────────────┼────────────┼────────────┼───────────┼───────────┼──────────────
 0 │ PLASTICOS    │ S A REVERTE  │ 2509000000  │ CARBONATO DE │ SPAIN    │ 18/03/2016 │ 17/04/2016 │ 81,000.00  │ 14,417.58 │ 18,252.34 │ 0.23
   │ RIVAL CIA    │              │             │ CALCIO TIPO  │          │            │            │            │           │           │
   │ LTDA         │              │             │ CALCIPORE    │          │            │            │            │           │           │
   │              │              │             │ 160 T AL     │          │            │            │            │           │           │
 1 │ MEXICHEM     │ OMYA ANDINA  │ 2836500000  │ CARBONATO    │ COLOMBIA │ 07/07/2016 │ 10/07/2016 │ 26,000.00  │ 7,072.00  │ 8,127.18  │ 0.31
   │ ECUADOR S.A. │ S A          │             │              │          │            │            │            │           │           │
 2 │ PLASTIAZUAY  │ SA REVERTE   │ 2836500000  │ CARBONATO DE │ SPAIN    │ 27/07/2016 │ 09/08/2016 │ 81,000.00  │ 8,100.00  │ 11,474.55 │ 0.14
   │ SA           │              │             │ CALCIO       │          │            │            │            │           │           │
 3 │ PLASTICOS    │ AND          │ 2836500000  │ CALCIUM      │ TURKEY   │ 04/10/2016 │ 11/11/2016 │ 100,000.00 │ 17,500.00 │ 22,533.75 │ 0.23
   │ RIVAL CIA    │ ENDUSTRIYEL  │             │ CARBONATE    │          │            │            │            │           │           │
   │ LTDA         │ HAMMADDELER  │             │ ANADOLU      │          │            │            │            │           │           │
   │              │ DIS TCARET   │             │ ANDCARB CT-1 │          │            │            │            │           │           │
   │              │ LTD.STI.     │             │              │          │            │            │            │           │           │
 4 │ QUIMICA      │ SA REVERTE   │ 2836500000  │ CARBONATO DE │ SPAIN    │ 24/06/2016 │ 12/07/2016 │ 27,000.00  │ 3,258.90  │ 5,585.00  │ 0.21
   │ COMERCIAL    │              │             │ CALCIO       │          │            │            │            │           │           │
   │ QUIMICIAL    │              │             │              │          │            │            │            │           │           │
   │ CIA. LTDA.   │              │             │              │          │            │            │            │           │           │
 5 │ PICA         │ OMYA ANDINA  │ 3824909999  │ CARBONATO DE │ COLOMBIA │ 01/01/1900 │ 18/01/2016 │ 66,500.00  │ 12,635.00 │ 18,670.52 │ 0.28
   │ PLASTICOS    │ S.A          │             │ CALCIO       │          │            │            │            │           │           │
   │ INDUSTRIALES │              │             │              │          │            │            │            │           │           │
   │ C.A.         │              │             │              │          │            │            │            │           │           │
 6 │ PLASTIQUIM   │ OMYA ANDINA  │ 3824909999  │ CARBONATO DE │ COLOMBIA │ 01/01/1900 │ 25/10/2016 │ 33,000.00  │ 6,270.00  │ 9,999.00  │ 0.30
   │ S.A.         │ S.A NIT      │             │ CALCIO       │          │            │            │            │           │           │
   │              │ 830.027.386- │             │ RECUBIERTO   │          │            │            │            │           │           │
   │              │ 6            │             │ CON ACIDO    │          │            │            │            │           │           │
   │              │              │             │ ESTEARICO    │          │            │            │            │           │           │
   │              │              │             │ OMYA CARB 1T │          │            │            │            │           │           │
   │              │              │             │ CG BBS 1000  │          │            │            │            │           │           │
 7 │ QUIMICOS     │ SIBELCO      │ 3824909999  │ CARBONATO DE │ COLOMBIA │ 01/11/2016 │ 03/11/2016 │ 52,000.00  │ 8,944.00  │ 13,039.05 │ 0.25
   │ ANDINOS      │ COLOMBIA SAS │             │ CALCIO       │          │            │            │            │           │           │
   │ QUIMANDI     │              │             │ RECUBIERTO   │          │            │            │            │           │           │
   │ S.A.         │              │             │              │          │            │            │            │           │           │
 8 │ TIGRE        │ OMYA ANDINA  │ 3824909999  │ CARBONATO DE │ COLOMBIA │ 01/01/1900 │ 28/10/2016 │ 66,000.00  │ 11,748.00 │ 18,216.00 │ 0.28
   │ ECUADOR S.A. │ S.A NIT      │             │ CALCIO       │          │            │            │            │           │           │
   │ ECUATIGRE    │ 830.027.386- │             │ RECUBIERTO   │          │            │            │            │           │           │
   │              │ 6            │             │ CON ACIDO    │          │            │            │            │           │           │
   │              │              │             │ ESTEARICO    │          │            │            │            │           │           │
   │              │              │             │ OMYACARB 1T  │          │            │            │            │           │           │
   │              │              │             │ CG BPA 25 NO │          │            │            │            │           │           │
━━━┷━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━┷━━━━━━━━━━━━━┷━━━━━━━━━━━━━━┷━━━━━━━━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━━━━
> open caco3_plastics.tsv | to tsv
importer        shipper tariff_item     name    origin  shipped_at      arrived_at      net_weight      fob_price       cif_price       cif_per_net_weight
PLASTICOS RIVAL CIA LTDA        S A REVERTE     2509000000      CARBONATO DE CALCIO TIPO CALCIPORE 160 T AL     SPAIN   18/03/2016      17/04/2016    81,000.00        14,417.58       18,252.34       0.23
MEXICHEM ECUADOR S.A.   OMYA ANDINA S A 2836500000      CARBONATO       COLOMBIA        07/07/2016      10/07/2016      26,000.00       7,072.00      8,127.18 0.31
PLASTIAZUAY SA  SA REVERTE      2836500000      CARBONATO DE CALCIO     SPAIN   27/07/2016      09/08/2016      81,000.00       8,100.00        11,474.55      0.14
PLASTICOS RIVAL CIA LTDA        AND ENDUSTRIYEL HAMMADDELER DIS TCARET LTD.STI. 2836500000      CALCIUM CARBONATE ANADOLU ANDCARB CT-1  TURKEY  04/10/2016     11/11/2016      100,000.00      17,500.00       22,533.75       0.23
QUIMICA COMERCIAL QUIMICIAL CIA. LTDA.  SA REVERTE      2836500000      CARBONATO DE CALCIO     SPAIN   24/06/2016      12/07/2016      27,000.00     3,258.90 5,585.00        0.21
PICA PLASTICOS INDUSTRIALES C.A.        OMYA ANDINA S.A 3824909999      CARBONATO DE CALCIO     COLOMBIA        01/01/1900      18/01/2016      66,500.00      12,635.00       18,670.52       0.28
PLASTIQUIM S.A. OMYA ANDINA S.A NIT 830.027.386-6       3824909999      CARBONATO DE CALCIO RECUBIERTO CON ACIDO ESTEARICO OMYA CARB 1T CG BBS 1000   COLOMBIA 01/01/1900      25/10/2016      33,000.00       6,270.00        9,999.00        0.30
QUIMICOS ANDINOS QUIMANDI S.A.  SIBELCO COLOMBIA SAS    3824909999      CARBONATO DE CALCIO RECUBIERTO  COLOMBIA        01/11/2016      03/11/2016    52,000.00        8,944.00        13,039.05       0.25
TIGRE ECUADOR S.A. ECUATIGRE    OMYA ANDINA S.A NIT 830.027.386-6       3824909999      CARBONATO DE  CALCIO RECUBIERTO CON ACIDO ESTEARICO OMYACARB 1T CG BPA 25 NO   COLOMBIA        01/01/1900      28/10/2016      66,000.00       11,748.00       18,216.00       0.28

to url

Converts table data into url-encoded text (opens new window).

# Example

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────
 0 │ X │ filesystem │ /home/shaurya
 1 │   │ filesystem │ /home/shaurya/Pictures
 2 │   │ filesystem │ /home/shaurya/Desktop
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━
> shells | to url
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │ value
───┼───────────────────────────────────────────────────────
 0+=X&name=filesystem&path=%2Fhome%2Fshaurya
 1+=+&name=filesystem&path=%2Fhome%2Fshaurya%2FPictures
 2+=+&name=filesystem&path=%2Fhome%2Fshaurya%2FDesktop
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> open sample.url
━━━━━━━━━━┯━━━━━━━━┯━━━━━━┯━━━━━━━━
 bread    │ cheese │ meat │ fat
──────────┼────────┼──────┼────────
 baguette │ comté  │ ham  │ butter
━━━━━━━━━━┷━━━━━━━━┷━━━━━━┷━━━━━━━━
> open sample.url  | to url
bread=baguette&cheese=comt%C3%A9&meat=ham&fat=butter

to xml

Converts table data into XML text.

# Flags

  • -p, --pretty <integer>: Formats the XML text with the provided indentation setting

# Example

> open jonathan.xml
━━━━━━━━━━━━━━━━
 rss
────────────────
 [table: 1 row]
━━━━━━━━━━━━━━━━
> cat jonathan.xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
        <channel>
                <title>Jonathan Turner</title>
                <link>http://www.jonathanturner.org</link>
                <atom:link href="http://www.jonathanturner.org/feed.xml" rel="self" type="application/rss+xml" />

                        <item>
                                <title>Creating crossplatform Rust terminal apps</title>
        <description>&lt;p&gt;&lt;img src=&quot;/images/pikachu.jpg&quot; alt=&quot;Pikachu animation in Windows&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Look Mom, Pikachu running in Windows CMD!&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Part of the adventure is not seeing the way ahead and going anyway.&lt;/p&gt;
</description>
<pubDate>Mon, 05 Oct 2015 00:00:00 +0000</pubDate>
<link>http://www.jonathanturner.org/2015/10/off-to-new-adventures.html</link>
<guid isPermaLink="true">http://www.jonathanturner.org/2015/10/off-to-new-adventures.html</guid>
</item>

        </channel>

</rss>
> open jonathan.xml | to xml --pretty 2
<rss version="2.0">
  <channel>
    <title>Jonathan Turner</title>
    <link>http://www.jonathanturner.org</link>
    <link href="http://www.jonathanturner.org/feed.xml" rel="self" type="application/rss+xml">
    </link>
    <item>
      <title>Creating crossplatform Rust terminal apps</title>
      <description>&lt;p&gt;&lt;img src=&quot;/images/pikachu.jpg&quot; alt=&quot;Pikachu animation in Windows&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Look Mom, Pikachu running in Windows CMD!&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Part of the adventure is not seeing the way ahead and going anyway.&lt;/p&gt;
</description>
<pubDate>Mon, 05 Oct 2015 00:00:00 +0000</pubDate>
<link>http://www.jonathanturner.org/2015/10/off-to-new-adventures.html</link>
<guid isPermaLink="true">http://www.jonathanturner.org/2015/10/off-to-new-adventures.html</guid>
</item>
</channel>
</rss>

Due to XML and internal representation, to xml is currently limited, it will:

  • Only process table data loaded from XML files (e.g. open file.json | to xml will fail)
  • Drop XML prolog declarations
  • Drop namespaces
  • Drop comments

to yaml

Converts table data into yaml text.

# Example

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────
 0 │ X │ filesystem │ /home/shaurya
 1 │   │ filesystem │ /home/shaurya/Pictures
 2 │   │ filesystem │ /home/shaurya/Desktop
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━
> shells | to yaml
---
- " ": X
  name: filesystem
  path: /home/shaurya
- " ": " "
  name: filesystem
  path: /home/shaurya/Pictures
- " ": " "
  name: filesystem
  path: /home/shaurya/Desktop
> open appveyor.yml
━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━┯━━━━━━━┯━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━
 image              │ environment    │ install         │ build │ test_script     │ cache
────────────────────┼────────────────┼─────────────────┼───────┼─────────────────┼─────────────────
 Visual Studio 2017[table: 1 row][table: 5 rows] │       │ [table: 2 rows][table: 2 rows]
━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━┷━━━━━━━┷━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━
> open appveyor.yml | to yaml
---
image: Visual Studio 2017
environment:
  global:
    PROJECT_NAME: nushell
    RUST_BACKTRACE: 1
  matrix:
    - TARGET: x86_64-pc-windows-msvc
      CHANNEL: nightly
      BITS: 64
install:
  - "set PATH=C:\\msys64\\mingw%BITS%\\bin;C:\\msys64\\usr\\bin;%PATH%"
  - "curl -sSf -o rustup-init.exe https://win.rustup.rs"
  - rustup-init.exe -y --default-host %TARGET% --default-toolchain %CHANNEL%-%TARGET%
  - "set PATH=%PATH%;C:\\Users\\appveyor\\.cargo\\bin"
  - "call \"C:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\Community\\VC\\Auxiliary\\Build\\vcvars64.bat\""
build: false
test_script:
  - cargo build --verbose
  - cargo test --all --verbose
cache:
  - target -> Cargo.lock
  - "C:\\Users\\appveyor\\.cargo\\registry -> Cargo.lock"

to

Converts table data into a string or binary. The target format is specified as a subcommand, like to csv or to json.

# Available Subcommands

Subcommands without links are currently missing their documentation.

# Example

> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────
 0 │ X │ filesystem │ /home/shaurya
 1 │   │ filesystem │ /home/shaurya/Pictures
 2 │   │ filesystem │ /home/shaurya/Desktop
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━
> shells | to csv
 ,name,path
X,filesystem,/home/shaurya
 ,filesystem,/home/shaurya/Pictures
 ,filesystem,/home/shaurya/Desktop
> open sample.url
━━━━━━━━━━┯━━━━━━━━┯━━━━━━┯━━━━━━━━
 bread    │ cheese │ meat │ fat
──────────┼────────┼──────┼────────
 baguette │ comté  │ ham  │ butter
━━━━━━━━━━┷━━━━━━━━┷━━━━━━┷━━━━━━━━
> open sample.url  | to url
bread=baguette&cheese=comt%C3%A9&meat=ham&fat=butter

touch

Create one or more files in the current or an already existent directory. It has no effect on existing files. Unlike GNU touch, the access time and the modified time are not updated.

-h, --help Display help message.

# Examples

Create a file in an empty folder. Then touch the file and list files again to observe that the modified time has not been updated.

> ls
> touch file.ext; ls
──────────┬─────────────
 name     │ file.ext
 type     │ File
 size     │ 0 B
 modified │ 0 secs ago
──────────┴─────────────
> touch file.ext; ls
──────────┬───────────
 name     │ file.ext
 type     │ File
 size     │ 0 B
 modified │ 10 secs ago
──────────┴───────────

Create a file within an already existent folder.

> mkdir dir
> touch dir/file.ext; ls dir
──────────┬───────────
 name     │ dir/file.ext
 type     │ File
 size     │ 0 B
 modified │ 0 secs ago
──────────┴───────────

Create three files at once

> touch a b c
> ls
────┬────────────────────┬──────┬──────────┬──────────────
 #  │        name        │ type │   size   │   modified
────┼────────────────────┼──────┼──────────┼──────────────
  0 │ a                  │ File │      0 B │ 0 sec ago
  1 │ b                  │ File │      0 B │ 0 sec ago
  2 │ c                  │ File │      0 B │ 0 sec ago
────┴────────────────────┴──────┴──────────┴──────────────

tree

View the contents of the pipeline as a tree.

# Usage

> tree {flags} 

# Flags

  • -h, --help: Display this help message

uniq

Returns unique rows or values from a dataset.

# Examples

Given a file test.csv

first_name,last_name,rusty_at,type
Andrés,Robalino,10/11/2013,A
Andrés,Robalino,10/11/2013,A
Jonathan,Turner,10/12/2013,B
Yehuda,Katz,10/11/2013,A
> `open test.csv | uniq`
━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━━┯━━━━━━
 # │ first_name │ last_name │ rusty_at   │ type
───┼────────────┼───────────┼────────────┼──────
 0 │ Andrés     │ Robalino  │ 10/11/2013 │ A
 1 │ Jonathan   │ Turner    │ 10/12/2013 │ B
 2 │ Yehuda     │ Katz      │ 10/11/2013 │ A
━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━━┷━━━━━━
> `open test.csv | get type | uniq`
━━━┯━━━━━━━━━
 # │
───┼─────────
 0 │ A
 1 │ B
━━━┷━━━━━━━━━

# Counting

--count or -c is the flag to output a count column.

> `open test.csv | get type | uniq -c`
───┬───────┬───────
 # │ value │ count
───┼───────┼───────
 0 │ A     │     3
 1 │ B     │     2
───┴───────┴───────

update

Updates an existing column on a table. First parameter is the column to update and the second parameter is the value to put.

# Examples

> ls
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━━
 # │ name                       │ type │ readonly │ size   │ accessed  │ modified
───┼────────────────────────────┼──────┼──────────┼────────┼───────────┼───────────
 0 │ zeusiscrazy.txt            │ File │          │ 556 B  │ a day ago │ a day ago
 1 │ coww.txt                   │ File │          │  24 B  │ a day ago │ a day ago
 2 │ randomweirdstuff.txt       │ File │          │ 197 B  │ a day ago │ a day ago
 3 │ abaracadabra.txt           │ File │          │ 401 B  │ a day ago │ a day ago
 4 │ youshouldeatmorecereal.txt │ File │          │ 768 B  │ a day ago │ a day ago
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━━
> ls | update modified neverrrr
━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━
 # │ name                       │ type │ readonly │ size   │ accessed  │ modified
───┼────────────────────────────┼──────┼──────────┼────────┼───────────┼──────────
 0 │ zeusiscrazy.txt            │ File │          │ 556 B  │ a day ago │ neverrrr
 1 │ coww.txt                   │ File │          │  24 B  │ a day ago │ neverrrr
 2 │ randomweirdstuff.txt       │ File │          │ 197 B  │ a day ago │ neverrrr
 3 │ abaracadabra.txt           │ File │          │ 401 B  │ a day ago │ neverrrr
 4 │ youshouldeatmorecereal.txt │ File │          │ 768 B  │ a day ago │ neverrrr
━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━
> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼────────────────────────────────
 0 │ X │ filesystem │ /home/username/stuff/expr/stuff
 1 │   │ filesystem │ /
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> shells | update " " X | update path /
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼──────
 0 │ X │ filesystem │ /
 1 │ X │ filesystem │ /
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━

Collect all the values of a nested column and join them together

> version | update features {get features | str collect ', '}
───┬─────────┬──────────────────────────────────────────┬───────────────────────────
 # │ version │               commit_hash                │         features
───┼─────────┼──────────────────────────────────────────┼───────────────────────────
 00.20.0  │ fdab3368094e938c390f1e5a7892a42da45add3e │ default, clipboard, trash
───┴─────────┴──────────────────────────────────────────┴───────────────────────────

url host

gets the host of a url

# Usage

> url host ...args {flags} 

# Parameters

  • ...args: optionally operate by column path

# Flags

  • -h, --help: Display this help message

# Examples

Get host of a url

> echo 'http://www.example.com/foo/bar' | url host

url path

gets the path of a url

# Usage

> url path ...args {flags} 

# Parameters

  • ...args: optionally operate by column path

# Flags

  • -h, --help: Display this help message

# Examples

Get path of a url

> echo 'http://www.example.com/foo/bar' | url path

A trailing slash will be reflected in the path

> echo 'http://www.example.com' | url path

url query

gets the query of a url

# Usage

> url query ...args {flags} 

# Parameters

  • ...args: optionally operate by column path

# Flags

  • -h, --help: Display this help message

# Examples

Get query of a url

> echo 'http://www.example.com/?foo=bar&baz=quux' | url query

No query gives the empty string

> echo 'http://www.example.com/' | url query

url scheme

gets the scheme (eg http, file) of a url

# Usage

> url scheme ...args {flags} 

# Parameters

  • ...args: optionally operate by path

# Flags

  • -h, --help: Display this help message

# Examples

Get scheme of a url

> echo 'http://www.example.com' | url scheme

You get an empty string if there is no scheme

> echo 'test' | url scheme

url

Apply url function.

# Usage

> url <subcommand> {flags} 

# Subcommands

  • url host - gets the host of a url
  • url path - gets the path of a url
  • url query - gets the query of a url
  • url scheme - gets the scheme (eg http, file) of a url

# Flags

  • -h, --help: Display this help message

version

Outputs the nushell version.

# Examples

> version
─────────┬────────
 version │ 0.15.1
─────────┴────────

where

This command filters the content of a table based on a condition passed as a parameter, which must be a boolean expression making use of any of the table columns. Other commands such as ls are capable of feeding where with their output through pipelines.

Where has two general forms:

  • where <column_name> <comparison> <value>
  • where <column_name>

# Where with comparison

In the first form, where is passed a column name that the filter will run against. Next, is the operator used to compare this column to its value. The following operators are supported:

  • < (less than)
  • <= (less than or equal)
  • > (greater than)
  • >= (greater than or equal)
  • != (not equal)
  • == (equal)

Strings have two additional operators:

  • =~ (fuzzy match to allow)
  • !~ (fuzzy match to not allow)

Dates can also be compared using the duration types. For example, where accessed > 2wk will check the date in accessed to see if it's greater than 2 weeks ago. Durations currently allow these abbreviations:

  • 1sec (one second)
  • 1min (one minute)
  • 1hr (one hour)
  • 1day (one day)
  • 1wk (one week)

# Boolean check

Where with the form | where readonly is used to check boolean values. For example, the command ls --long | where readonly will list only those files that are readonly.

# Usage

> [input-command] | where [condition]

# Examples

> ls | where size > 4kb
───┬────────────┬──────┬──────────┬─────────────
 # │ name       │ type │ size     │ modified
───┼────────────┼──────┼──────────┼─────────────
 0 │ Cargo.lock │ File │ 113.3 KB │ 53 mins ago
 1 │ Cargo.toml │ File │   4.6 KB │ 53 mins ago
 2 │ README.md  │ File │  15.8 KB │ 2 mins ago
───┴────────────┴──────┴──────────┴─────────────
> ps | where cpu > 0
───┬───────┬──────────────────┬─────────┬────────┬──────────┬─────────
 # │ pid   │ name             │ status  │ cpu    │ mem      │ virtual
───┼───────┼──────────────────┼─────────┼────────┼──────────┼─────────
 017917 │ nu_plugin_core_p │ Running │ 4.16782.1 MB │  4.8 GB
 114717 │ Discord Helper ( │ Running │ 1.6842371.9 MB │  8.0 GB
 214713 │ Discord Helper   │ Running │ 0.209927.8 MB │  5.8 GB
 314710 │ Discord          │ Running │ 0.0883105.4 MB │  7.0 GB
 49643 │ Terminal         │ Running │ 4.0313266.4 MB │  7.6 GB
 57864 │ Microsoft.Python │ Running │ 0.9828340.9 MB │  8.0 GB
 624402 │ Code Helper (Ren │ Running │ 1.0644337.3 MB │  8.4 GB
 724401 │ Code Helper (Ren │ Running │ 1.0031593.5 MB │  8.6 GB
 8519 │ EmojiFunctionRow │ Running │ 0.206352.7 MB │  7.5 GB
 9376 │ CommCenter       │ Running │ 0.162030.0 MB │  6.5 GB
───┴───────┴──────────────────┴─────────┴────────┴──────────┴─────────

> ls -l | where accessed <= 1wk
───┬────────────────────┬──────┬────────┬──────────┬───────────┬─────────────┬───────┬──────────┬──────────────┬─────────────┬─────────────
 # │ name               │ type │ target │ readonly │ mode      │ uid         │ group │ size     │ created      │ accessed    │ modified
───┼────────────────────┼──────┼────────┼──────────┼───────────┼─────────────┼───────┼──────────┼──────────────┼─────────────┼─────────────
 0 │ CODE_OF_CONDUCT.md │ File │        │ No       │ rw-r--r-- │ josephlyons │ staff │   3.4 KB │ 52 mins ago  │ 52 secs ago │ 52 mins ago
 1 │ CONTRIBUTING.md    │ File │        │ No       │ rw-r--r-- │ josephlyons │ staff │   1.3 KB │ 52 mins ago  │ 4 mins ago  │ 4 mins ago
 2 │ Cargo.lock         │ File │        │ No       │ rw-r--r-- │ josephlyons │ staff │ 113.3 KB │ 52 mins ago  │ 52 mins ago │ 52 mins ago
 3 │ Cargo.toml         │ File │        │ No       │ rw-r--r-- │ josephlyons │ staff │   4.6 KB │ 52 mins ago  │ 52 mins ago │ 52 mins ago
 4 │ README.md          │ File │        │ No       │ rw-r--r-- │ josephlyons │ staff │  15.8 KB │ 52 mins ago  │ 1 min ago   │ 1 min ago
 5 │ TODO.md            │ File │        │ No       │ rw-r--r-- │ josephlyons │ staff │      0 B │ 52 mins ago  │ 52 mins ago │ 52 mins ago
 6 │ crates             │ Dir  │        │ No       │ rwxr-xr-x │ josephlyons │ staff │    704 B │ 4 months ago │ 52 mins ago │ 52 mins ago
 7 │ docs               │ Dir  │        │ No       │ rwxr-xr-x │ josephlyons │ staff │    192 B │ 5 months ago │ 52 mins ago │ 52 mins ago
 8 │ src                │ Dir  │        │ No       │ rwxr-xr-x │ josephlyons │ staff │    128 B │ 5 months ago │ 1 day ago   │ 1 day ago
 9 │ target             │ Dir  │        │ No       │ rwxr-xr-x │ josephlyons │ staff │    160 B │ 5 days ago   │ 5 days ago  │ 5 days ago
───┴────────────────────┴──────┴────────┴──────────┴───────────┴─────────────┴───────┴──────────┴──────────────┴─────────────┴─────────────
> ls -a | where name =~ "yml"
──────────┬─────────────
 name     │ .gitpod.yml
 type     │ File
 size     │ 866 B
 modified │ 1 month ago
──────────┴─────────────

which

Finds a program file.

Usage:

which {flags}

# Parameters

  • application: the name of the command to find the path to

# Flags

  • --all: list all executables

# Examples

which finds the location of an executable:

> which python
─────────┬─────────────────
 arg     │ python
 path    │ /usr/bin/python
 builtinfalse
─────────┴─────────────────
> which cargo
─────────┬────────────────────────────
 arg     │ cargo
 path    │ /home/bob/.cargo/bin/cargo
 builtinfalse
─────────┴────────────────────────────

which will identify nushell commands:

> which ls
─────────┬──────────────────────────
 arg     │ ls
 path    │ nushell built-in command
 builtintrue
─────────┴──────────────────────────
> which which
─────────┬──────────────────────────
 arg     │ which
 path    │ nushell built-in command
 builtintrue
─────────┴──────────────────────────

Passing the all flag identifies all instances of a command or binary

> which ls --all
───┬─────┬──────────────────────────┬─────────
 # │ arg │ path                     │ builtin
───┼─────┼──────────────────────────┼─────────
 0ls  │ nushell built-in commandtrue
 1ls  │ /bin/ls                  │ false
───┴─────┴──────────────────────────┴─────────

which will also identify local binaries

> touch foo
> chmod +x foo
> which ./foo
─────────┬────────────────────────────────
 arg     │ ./foo
 path    │ /Users/josephlyons/Desktop/foo
 builtinfalse
─────────┴────────────────────────────────

which also identifies aliases

> alias e = echo
> which e
───┬─────┬───────────────┬─────────
 # │ arg │     path      │ builtin
───┼─────┼───────────────┼─────────
 0 │ e   │ Nushell aliasfalse
───┴─────┴───────────────┴─────────

and custom commands

> def my_cool_echo [arg] { echo $arg }
> which my_cool_echo
───┬──────────────┬────────────────────────┬─────────
 # │     arg      │          path          │ builtin
───┼──────────────┼────────────────────────┼─────────
 0 │ my_cool_echo │ Nushell custom commandfalse
───┴──────────────┴────────────────────────┴─────────

with-env

# with-env

Runs a block with an environment variable set.

# Usage

> with-env <variable> <block> {flags} 

# Parameters

  • <variable> the environment variable to temporarily set
  • <block> the block to run once the variable is set

# Flags

  • -h, --help: Display this help message

# Examples

Set the MYENV environment variable

> with-env [MYENV "my env value"] { echo $nu.env.MYENV }

Set by primitive value list

> with-env [X Y W Z] { echo $nu.env.X $nu.env.W }

Set by single row table

> with-env [[X W]; [Y Z]] { echo $nu.env.X $nu.env.W }

Set by row(e.g. open x.json or from json)

> echo '{"X":"Y","W":"Z"}'|from json|with-env $it { echo $nu.env.X $nu.env.W }

wrap

Wraps data in a table

Syntax: wrap <column>

# Parameters

  • column: the (optional) name of the column the data should be stored in.

# Examples

wrap will give a name to a column of <value> data:

> ls | get name
───┬──────────────
 # │
───┼──────────────
 0 │ americas.csv
 1 │ iso.csv
───┴──────────────
> ls | get name | wrap filename
───┬──────────────
 # │ filename
───┼──────────────
 0 │ americas.csv
 1 │ iso.csv
───┴──────────────

wrap will encapsulate rows as embedded tables:

> ls | select name type size
───┬──────────────┬──────┬─────────
 # │ name         │ type │ size
───┼──────────────┼──────┼─────────
 0 │ americas.csv │ File │   317 B
 1 │ iso.csv      │ File │ 20.8 KB
───┴──────────────┴──────┴─────────

> ls | select name type size | each {wrap details}
───┬────────────────
 # │ details
───┼────────────────
 0[table 1 rows]
 1[table 1 rows]
───┴────────────────

wrap will encapsulate a whole table as an embedded table:

> ls | wrap files
───────┬────────────────
 files │ [table 2 rows]
───────┴────────────────

xpath

execute xpath query on xml

# Usage

> xpath <query> {flags} 

# Parameters

  • <query> xpath query

# Flags

  • -h, --help: Display this help message

exit

Exits the nu shell. If you have multiple nu shells, use exit --now to exit all of them.

# Examples

> exit
> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼─────────────────────────────────────
 0 │   │ filesystem │ /home/jonathanturner/Source/nushell
 1 │   │ filesystem │ /home
 2 │ X │ filesystem │ /usr
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> exit
> shells
━━━┯━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # │   │ name       │ path
───┼───┼────────────┼─────────────────────────────────────
 0 │   │ filesystem │ /home/jonathanturner/Source/nushell
 1 │ X │ filesystem │ /home
━━━┷━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> exit --now
exits both the shells

first

Use first to retrieve the first "n" rows of a table. first has a required amount parameter that indicates how many rows you would like returned. If more than one row is returned, an index column will be included showing the row number.

# Examples

> ps | first 1
─────────┬──────────────────
 pid     │ 14733
 name    │ nu_plugin_core_p
 status  │ Running
 cpu     │ 4.1229
 mem     │ 2.1 MB
 virtual │ 4.8 GB
─────────┴──────────────────

> ps | first 5
───┬───────┬──────────────────┬─────────┬──────────┬─────────┬─────────
 # │ pid   │ name             │ status  │ cpu      │ mem     │ virtual
───┼───────┼──────────────────┼─────────┼──────────┼─────────┼─────────
 014747 │ nu_plugin_core_p │ Running │   3.56532.1 MB │  4.8 GB
 114735 │ Python           │ Running │ 100.000827.4 MB │  5.4 GB
 214734 │ mdworker_shared  │ Running │   0.000018.4 MB │  4.7 GB
 314729 │ mdworker_shared  │ Running │   0.00008.2 MB │  5.0 GB
 414728 │ mdworker_shared  │ Running │   0.00008.0 MB │  4.9 GB
───┴───────┴──────────────────┴─────────┴──────────┴─────────┴─────────

fetch

This command loads from a URL into a cell, convert it to table if possible (avoid by appending --raw flag)

# Examples

> fetch http://headers.jsontest.com
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━
 X-Cloud-Trace-Context                                 │ Accept │ Host                 │ Content-Length │ user-agent
───────────────────────────────────────────────────────┼────────┼──────────────────────┼────────────────┼─────────────────────────
 aeee1a8abf08820f6fe19d114dc3bb87/16772233176633589121 │ */*    │ headers.jsontest.com │ 0              │ curl/7.54.0 isahc/0.7.1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━
> fetch http://headers.jsontest.com --raw
{
   "X-Cloud-Trace-Context": "aeee1a8abf08820f6fe19d114dc3bb87/16772233176633589121",
   "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
   "Upgrade-Insecure-Requests": "1",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36",
   "Host": "headers.jsontest.com",
   "Accept-Language": "en-GB,en-US;q=0.9,en;q=0.8"
}
> fetch https://www.jonathanturner.org/feed.xml
━━━━━━━━━━━━━━━━
 rss
────────────────
 [table: 1 row]
━━━━━━━━━━━━━━━━