check version & toc
0.91.0
alias
Alias a command (with optional flags) to a new name.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: abbr, aka, fn, func, function
Usage:
> alias <name> = <initial_value>
Flags:
-h, --help - Display the help message for this command
Parameters:
name <string>: Name of the alias.
"=" + <expression>: Equals sign followed by value.
Examples:
Alias ll to ls -l
> alias ll = ls -l
all
Test if every element of the input fulfills a predicate expression.
Search terms: every, and
Usage:
> all <predicate>
Flags:
-h, --help - Display the help message for this command
Parameters:
predicate <closure(any, int)>: A closure that must evaluate to a boolean.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ bool │
╰───┴───────────┴────────╯
Examples:
Check if each row's status is the string 'UP'
> [[status]; [UP] [UP]] | all {|el| $el.status == UP }
true
Check that each item is a string
> [foo bar 2 baz] | all {|| ($in | describe) == 'string' }
false
Check that all values are equal to twice their index
> [0 2 4 6] | enumerate | all {|i| $i.item == $i.index * 2 }
true
Check that all of the values are even, using a stored closure
> let cond = {|el| ($el mod 2) == 0 }; [2 4 6 8] | all $cond
true
ansi
Output ANSI codes to change color and style of text.
An introduction to what ANSI escape sequences are can be found in the
ANSI escape code Wikipedia page.
Escape sequences usual values:
╭────┬────────────┬────────┬────────┬─────────╮
│ # │ type │ normal │ bright │ name │
├────┼────────────┼────────┼────────┼─────────┤
│ 0 │ foreground │ 30 │ 90 │ black │
│ 1 │ foreground │ 31 │ 91 │ red │
│ 2 │ foreground │ 32 │ 92 │ green │
│ 3 │ foreground │ 33 │ 93 │ yellow │
│ 4 │ foreground │ 34 │ 94 │ blue │
│ 5 │ foreground │ 35 │ 95 │ magenta │
│ 5 │ foreground │ 35 │ 95 │ purple │
│ 6 │ foreground │ 36 │ 96 │ cyan │
│ 7 │ foreground │ 37 │ 97 │ white │
│ 8 │ foreground │ 39 │ │ default │
│ 9 │ background │ 40 │ 100 │ black │
│ 10 │ background │ 41 │ 101 │ red │
│ 11 │ background │ 42 │ 102 │ green │
│ 12 │ background │ 43 │ 103 │ yellow │
│ 13 │ background │ 44 │ 104 │ blue │
│ 14 │ background │ 45 │ 105 │ magenta │
│ 14 │ background │ 45 │ 105 │ purple │
│ 15 │ background │ 46 │ 106 │ cyan │
│ 16 │ background │ 47 │ 107 │ white │
│ 17 │ background │ 49 │ │ default │
╰────┴────────────┴────────┴────────┴─────────╯
Escape sequences attributes:
╭───┬────┬──────────────┬──────────────────────────────╮
│ # │ id │ abbreviation │ description │
├───┼────┼──────────────┼──────────────────────────────┤
│ 0 │ 0 │ │ reset / normal display │
│ 1 │ 1 │ b │ bold or increased intensity │
│ 2 │ 2 │ d │ faint or decreased intensity │
│ 3 │ 3 │ i │ italic on (non-mono font) │
│ 4 │ 4 │ u │ underline on │
│ 5 │ 5 │ l │ slow blink on │
│ 6 │ 6 │ │ fast blink on │
│ 7 │ 7 │ r │ reverse video on │
│ 8 │ 8 │ h │ nondisplayed (invisible) on │
│ 9 │ 9 │ s │ strike-through on │
╰───┴────┴──────────────┴──────────────────────────────╯
Operating system commands:
╭───┬─────┬───────────────────────────────────────╮
│ # │ id │ description │
├───┼─────┼───────────────────────────────────────┤
│ 0 │ 0 │ Set window title and icon name │
│ 1 │ 1 │ Set icon name │
│ 2 │ 2 │ Set window title │
│ 3 │ 4 │ Set/read color palette │
│ 4 │ 9 │ iTerm2 Grown notifications │
│ 5 │ 10 │ Set foreground color (x11 color spec) │
│ 6 │ 11 │ Set background color (x11 color spec) │
│ 7 │ ... │ others │
╰───┴─────┴───────────────────────────────────────╯
Search terms: text-color, text-style, colors
Usage:
> ansi {flags} (code)
Subcommands:
ansi link - Add a link (using OSC 8 escape sequence) to the given string.
ansi strip - Strip ANSI escape sequences from a string.
Flags:
-h, --help - Display the help message for this command
-e, --escape - escape sequence without the escape character(s) ('\x1b[' is not required)
-o, --osc - operating system command (osc) escape sequence without the escape character(s) ('\x1b]' is not required)
-l, --list - list available ansi code names
Parameters:
code <any>: The name of the code to use (from `ansi -l`). (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Change color to green (see how the next example text will be green!)
> ansi green
Reset the color
> ansi reset
Use different colors and styles in the same text
> $'(ansi red_bold)Hello(ansi reset) (ansi green_dimmed)Nu(ansi reset) (ansi purple_italic)World(ansi reset)'
Hello Nu World
The same example as above with short names
> $'(ansi rb)Hello(ansi reset) (ansi gd)Nu(ansi reset) (ansi pi)World(ansi reset)'
Hello Nu World
Use escape codes, without the '\x1b['
> $"(ansi --escape '3;93;41m')Hello(ansi reset)" # italic bright yellow on red background
Hello
Use structured escape codes
> let bold_blue_on_red = { # `fg`, `bg`, `attr` are the acceptable keys, all other keys are considered invalid and will throw errors.
fg: '#0000ff'
bg: '#ff0000'
attr: b
}
$"(ansi --escape $bold_blue_on_red)Hello, Nu World!(ansi reset)"
Hello, Nu World!
ansi link
Add a link (using OSC 8 escape sequence) to the given string.
Usage:
> ansi link {flags} ...(cell path)
Flags:
-h, --help - Display the help message for this command
-t, --text <String> - Link text. Uses uri as text if absent. In case of
tables, records and lists applies this text to all elements
Parameters:
...cell path <cell-path>: For a data structure input, add links to all strings at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Create a link to open some file
> 'file:///file.txt' | ansi link --text 'Open Me!'
Open Me!
Create a link without text
> 'https://www.nushell.sh/' | ansi link
https://www.nushell.sh/
Format a table column into links
> [[url text]; [https://example.com Text]] | ansi link url
ansi strip
Strip ANSI escape sequences from a string.
Usage:
> ansi strip ...(cell path)
Flags:
-h, --help - Display the help message for this command
Parameters:
...cell path <cell-path>: For a data structure input, remove ANSI sequences from strings at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Strip ANSI escape sequences from a string
> $'(ansi green)(ansi cursor_on)hello' | ansi strip
hello
any
Tests if any element of the input fulfills a predicate expression.
Search terms: some, or
Usage:
> any <predicate>
Flags:
-h, --help - Display the help message for this command
Parameters:
predicate <closure(any, int)>: A closure that must evaluate to a boolean.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ bool │
╰───┴───────────┴────────╯
Examples:
Check if any row's status is the string 'DOWN'
> [[status]; [UP] [DOWN] [UP]] | any {|el| $el.status == DOWN }
true
Check that any item is a string
> [1 2 3 4] | any {|| ($in | describe) == 'string' }
false
Check if any value is equal to twice its own index
> [9 8 7 6] | enumerate | any {|i| $i.item == $i.index * 2 }
true
Check if any of the values are odd, using a stored closure
> let cond = {|e| $e mod 2 == 1 }; [2 4 1 6 8] | any $cond
true
append
Append any number of rows to a table.
Be aware that this command 'unwraps' lists passed to it. So, if you pass a variable to it,
and you want the variable's contents to be appended without being unwrapped, it's wise to
pre-emptively wrap the variable in a list, like so: `append [$val]`. This way, `append` will
only unwrap the outer list, and leave the variable's contents untouched.
Search terms: add, concatenate
Usage:
> append <row>
Flags:
-h, --help - Display the help message for this command
Parameters:
row <any>: The row, list, or table to append.
Input/output types:
╭───┬───────┬───────────╮
│ # │ input │ output │
├───┼───────┼───────────┤
│ 0 │ any │ list<any> │
╰───┴───────┴───────────╯
Examples:
Append one int to a list
> [0 1 2 3] | append 4
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ 3 │
│ 4 │ 4 │
╰───┴───╯
Append a list to an item
> 0 | append [1 2 3]
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ 3 │
╰───┴───╯
Append a list of string to a string
> "a" | append ["b"]
╭───┬───╮
│ 0 │ a │
│ 1 │ b │
╰───┴───╯
Append three int items
> [0 1] | append [2 3 4]
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ 3 │
│ 4 │ 4 │
╰───┴───╯
Append ints and strings
> [0 1] | append [2 nu 4 shell]
╭───┬───────╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ nu │
│ 4 │ 4 │
│ 5 │ shell │
╰───┴───────╯
Append a range of ints to a list
> [0 1] | append 2..4
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ 3 │
│ 4 │ 4 │
╰───┴───╯
ast
Print the abstract syntax tree (ast) for a pipeline.
Usage:
> ast {flags} <pipeline>
Flags:
-h, --help - Display the help message for this command
-j, --json - serialize to json
-m, --minify - minify the nuon or json output
Parameters:
pipeline <string>: The pipeline to print the ast for.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ record │
╰───┴────────┴────────╯
Examples:
Print the ast of a string
> ast 'hello'
Print the ast of a pipeline
> ast 'ls | where name =~ README'
Print the ast of a pipeline with an error
> ast 'for x in 1..10 { echo $x '
Print the ast of a pipeline with an error, as json, in a nushell table
> ast 'for x in 1..10 { echo $x ' --json | get block | from json
Print the ast of a pipeline with an error, as json, minified
> ast 'for x in 1..10 { echo $x ' --json --minify
banner
print a banner for nushell, with information about the project
Example:
an example can be found in [this asciinema recording](https://asciinema.org/a/566513)
Usage:
> banner
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
break
Break a loop.
Usage:
> break
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Break out of a loop
> loop { break }
bytes
Various commands for working with byte data.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> bytes
Subcommands:
bytes add - Add specified bytes to the input.
bytes at - Get bytes defined by a range.
bytes build - Create bytes from the arguments.
bytes collect - Concatenate multiple binary into a single binary, with an optional separator between each.
bytes ends-with - Check if bytes ends with a pattern.
bytes index-of - Returns start index of first occurrence of pattern in bytes, or -1 if no match.
bytes length - Output the length of any bytes in the pipeline.
bytes remove - Remove bytes.
bytes replace - Find and replace binary.
bytes reverse - Reverse the bytes in the pipeline.
bytes starts-with - Check if bytes starts with a pattern.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
bytes add
Add specified bytes to the input.
Search terms: append, truncate, padding
Usage:
> bytes add {flags} <data> ...(rest)
Flags:
-h, --help - Display the help message for this command
-i, --index <Int> - index to insert binary data
-e, --end - add to the end of binary
Parameters:
data <binary>: The binary to add.
...rest <cell-path>: For a data structure input, add bytes to the data at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ binary │ binary │
│ 1 │ list<binary> │ list<binary> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Add bytes `0x[AA]` to `0x[1F FF AA AA]`
> 0x[1F FF AA AA] | bytes add 0x[AA]
[170, 31, 255, 170, 170]
Add bytes `0x[AA BB]` to `0x[1F FF AA AA]` at index 1
> 0x[1F FF AA AA] | bytes add 0x[AA BB] --index 1
[31, 170, 187, 255, 170, 170]
Add bytes `0x[11]` to `0x[FF AA AA]` at the end
> 0x[FF AA AA] | bytes add 0x[11] --end
[255, 170, 170, 17]
Add bytes `0x[11 22 33]` to `0x[FF AA AA]` at the end, at index 1(the index is start from end)
> 0x[FF AA BB] | bytes add 0x[11 22 33] --end --index 1
[255, 170, 17, 34, 51, 187]
bytes at
Get bytes defined by a range.
Search terms: slice
Usage:
> bytes at <range> ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
range <range>: The range to get bytes.
...rest <cell-path>: For a data structure input, get bytes from data at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ binary │ binary │
│ 1 │ list<binary> │ list<binary> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Get a subbytes `0x[10 01]` from the bytes `0x[33 44 55 10 01 13]`
> 0x[33 44 55 10 01 13] | bytes at 3..<4
Get a subbytes `0x[10 01 13]` from the bytes `0x[33 44 55 10 01 13]`
> 0x[33 44 55 10 01 13] | bytes at 3..6
Get the remaining characters from a starting index
> { data: 0x[33 44 55 10 01 13] } | bytes at 3.. data
╭──────┬─────────────╮
│ data │ [16, 1, 19] │
╰──────┴─────────────╯
Get the characters from the beginning until ending index
> 0x[33 44 55 10 01 13] | bytes at ..<4
3DU
Or the characters from the beginning until ending index inside a table
> [[ColA ColB ColC]; [0x[11 12 13] 0x[14 15 16] 0x[17 18 19]]] | bytes at 1.. ColB ColC
╭───┬──────────────┬──────────┬──────────╮
│ # │ ColA │ ColB │ ColC │
├───┼──────────────┼──────────┼──────────┤
│ 0 │ [17, 18, 19] │ [21, 22] │ [24, 25] │
╰───┴──────────────┴──────────┴──────────╯
bytes build
Create bytes from the arguments.
Search terms: concatenate, join
Usage:
> bytes build ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <any>: List of bytes.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ binary │
╰───┴─────────┴────────╯
Examples:
Builds binary data from 0x[01 02], 0x[03], 0x[04]
> bytes build 0x[01 02] 0x[03] 0x[04]
bytes collect
Concatenate multiple binary into a single binary, with an optional separator between each.
Search terms: join, concatenate
Usage:
> bytes collect (separator)
Flags:
-h, --help - Display the help message for this command
Parameters:
separator <binary>: Optional separator to use when creating binary. (optional)
Input/output types:
╭───┬──────────────┬────────╮
│ # │ input │ output │
├───┼──────────────┼────────┤
│ 0 │ list<binary> │ binary │
╰───┴──────────────┴────────╯
Examples:
Create a byte array from input
> [0x[11] 0x[13 15]] | bytes collect
Create a byte array from input with a separator
> [0x[11] 0x[33] 0x[44]] | bytes collect 0x[01]
3D
bytes ends-with
Check if bytes ends with a pattern.
Search terms: pattern, match, find, search
Usage:
> bytes ends-with <pattern> ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
pattern <binary>: The pattern to match.
...rest <cell-path>: For a data structure input, check if bytes at the given cell paths end with the pattern.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ bool │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
Checks if binary ends with `0x[AA]`
> 0x[1F FF AA AA] | bytes ends-with 0x[AA]
true
Checks if binary ends with `0x[FF AA AA]`
> 0x[1F FF AA AA] | bytes ends-with 0x[FF AA AA]
true
Checks if binary ends with `0x[11]`
> 0x[1F FF AA AA] | bytes ends-with 0x[11]
false
bytes index-of
Returns start index of first occurrence of pattern in bytes, or -1 if no match.
Search terms: pattern, match, find, search
Usage:
> bytes index-of {flags} <pattern> ...(rest)
Flags:
-h, --help - Display the help message for this command
-a, --all - returns all matched index
-e, --end - search from the end of the binary
Parameters:
pattern <binary>: The pattern to find index of.
...rest <cell-path>: For a data structure input, find the indexes at the given cell paths.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ any │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
Returns index of pattern in bytes
> 0x[33 44 55 10 01 13 44 55] | bytes index-of 0x[44 55]
1
Returns index of pattern, search from end
> 0x[33 44 55 10 01 13 44 55] | bytes index-of --end 0x[44 55]
6
Returns all matched index
> 0x[33 44 55 10 01 33 44 33 44] | bytes index-of --all 0x[33 44]
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 5 │
│ 2 │ 7 │
╰───┴───╯
Returns all matched index, searching from end
> 0x[33 44 55 10 01 33 44 33 44] | bytes index-of --all --end 0x[33 44]
╭───┬───╮
│ 0 │ 7 │
│ 1 │ 5 │
│ 2 │ 0 │
╰───┴───╯
Returns index of pattern for specific column
> [[ColA ColB ColC]; [0x[11 12 13] 0x[14 15 16] 0x[17 18 19]]] | bytes index-of 0x[11] ColA ColC
╭───┬──────┬──────────────┬──────╮
│ # │ ColA │ ColB │ ColC │
├───┼──────┼──────────────┼──────┤
│ 0 │ 0 │ [20, 21, 22] │ -1 │
╰───┴──────┴──────────────┴──────╯
bytes length
Output the length of any bytes in the pipeline.
Search terms: size, count
Usage:
> bytes length ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, find the length of data at the given cell paths.
Input/output types:
╭───┬──────────────┬───────────╮
│ # │ input │ output │
├───┼──────────────┼───────────┤
│ 0 │ binary │ int │
│ 1 │ list<binary> │ list<int> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴───────────╯
Examples:
Return the length of a binary
> 0x[1F FF AA AB] | bytes length
4
Return the lengths of multiple binaries
> [0x[1F FF AA AB] 0x[1F]] | bytes length
╭───┬───╮
│ 0 │ 4 │
│ 1 │ 1 │
╰───┴───╯
bytes remove
Remove bytes.
Search terms: search, shift, switch
Usage:
> bytes remove {flags} <pattern> ...(rest)
Flags:
-h, --help - Display the help message for this command
-e, --end - remove from end of binary
-a, --all - remove occurrences of finding binary
Parameters:
pattern <binary>: The pattern to find.
...rest <cell-path>: For a data structure input, remove bytes from data at the given cell paths.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ binary │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
Remove contents
> 0x[10 AA FF AA FF] | bytes remove 0x[10 AA]
[255, 170, 255]
Remove all occurrences of find binary in record field
> { data: 0x[10 AA 10 BB 10] } | bytes remove --all 0x[10] data
╭──────┬────────────╮
│ data │ [170, 187] │
╰──────┴────────────╯
Remove occurrences of find binary from end
> 0x[10 AA 10 BB CC AA 10] | bytes remove --end 0x[10]
[16, 170, 16, 187, 204, 170]
Remove find binary from end not found
> 0x[10 AA 10 BB CC AA 10] | bytes remove --end 0x[11]
[16, 170, 16, 187, 204, 170, 16]
Remove all occurrences of find binary in table
> [[ColA ColB ColC]; [0x[11 12 13] 0x[14 15 16] 0x[17 18 19]]] | bytes remove 0x[11] ColA ColC
╭───┬──────────┬──────────────┬──────────────╮
│ # │ ColA │ ColB │ ColC │
├───┼──────────┼──────────────┼──────────────┤
│ 0 │ [18, 19] │ [20, 21, 22] │ [23, 24, 25] │
╰───┴──────────┴──────────────┴──────────────╯
bytes replace
Find and replace binary.
Search terms: search, shift, switch
Usage:
> bytes replace {flags} <find> <replace> ...(rest)
Flags:
-h, --help - Display the help message for this command
-a, --all - replace all occurrences of find binary
Parameters:
find <binary>: The pattern to find.
replace <binary>: The replacement pattern.
...rest <cell-path>: For a data structure input, replace bytes in data at the given cell paths.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ binary │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
Find and replace contents
> 0x[10 AA FF AA FF] | bytes replace 0x[10 AA] 0x[FF]
[255, 255, 170, 255]
Find and replace all occurrences of find binary
> 0x[10 AA 10 BB 10] | bytes replace --all 0x[10] 0x[A0]
[160, 170, 160, 187, 160]
Find and replace all occurrences of find binary in table
> [[ColA ColB ColC]; [0x[11 12 13] 0x[14 15 16] 0x[17 18 19]]] | bytes replace --all 0x[11] 0x[13] ColA ColC
╭───┬──────────────┬──────────────┬──────────────╮
│ # │ ColA │ ColB │ ColC │
├───┼──────────────┼──────────────┼──────────────┤
│ 0 │ [19, 18, 19] │ [20, 21, 22] │ [23, 24, 25] │
╰───┴──────────────┴──────────────┴──────────────╯
bytes reverse
Reverse the bytes in the pipeline.
Search terms: convert, inverse, flip
Usage:
> bytes reverse ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, reverse data at the given cell paths.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ binary │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
Reverse bytes `0x[1F FF AA AA]`
> 0x[1F FF AA AA] | bytes reverse
[170, 170, 255, 31]
Reverse bytes `0x[FF AA AA]`
> 0x[FF AA AA] | bytes reverse
[170, 170, 255]
bytes starts-with
Check if bytes starts with a pattern.
Search terms: pattern, match, find, search
Usage:
> bytes starts-with <pattern> ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
pattern <binary>: The pattern to match.
...rest <cell-path>: For a data structure input, check if bytes at the given cell paths start with the pattern.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ bool │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
Checks if binary starts with `0x[1F FF AA]`
> 0x[1F FF AA AA] | bytes starts-with 0x[1F FF AA]
true
Checks if binary starts with `0x[1F]`
> 0x[1F FF AA AA] | bytes starts-with 0x[1F]
true
Checks if binary starts with `0x[1F]`
> 0x[1F FF AA AA] | bytes starts-with 0x[11]
false
cal
Display a calendar.
Usage:
> cal {flags}
Flags:
-h, --help - Display the help message for this command
-y, --year - Display the year column
-q, --quarter - Display the quarter column
-m, --month - Display the month column
--full-year <Int> - 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
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
This month's calendar
> cal
The calendar for all of 2012
> cal --full-year 2012
This month's calendar with the week starting on monday
> cal --week-start monday
cd
Change directory.
Search terms: change, directory, dir, folder, switch
Usage:
> cd (path)
Flags:
-h, --help - Display the help message for this command
Parameters:
path <directory>: The path to change to. (optional)
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
│ 1 │ string │ nothing │
╰───┴─────────┴─────────╯
Examples:
Change to your home directory
> cd ~
Change to the previous working directory ($OLDPWD)
> cd -
char
Output special characters (e.g., 'newline').
Search terms: line break, newline, Unicode
Usage:
> char {flags} (character) ...(rest)
Flags:
-h, --help - Display the help message for this command
-l, --list - List all supported character names
-u, --unicode - Unicode string i.e. 1f378
-i, --integer - Create a codepoint from an integer
Parameters:
character <any>: The name of the character to output. (optional)
...rest <any>: Multiple Unicode bytes.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Output newline
> char newline
List available characters
> char --list
Output prompt character, newline and a hamburger menu character
> (char prompt) + (char newline) + (char hamburger)
▶
≡
Output Unicode character
> char --unicode 1f378
🍸
Create Unicode from integer codepoint values
> char --integer (0x60 + 1) (0x60 + 2)
ab
Output multi-byte Unicode character
> char --unicode 1F468 200D 1F466 200D 1F466
👨👦👦
clear
Clear the terminal.
Usage:
> clear {flags}
Flags:
-h, --help - Display the help message for this command
-a, --all - Clear the terminal and its scroll-back history
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Clear the terminal
> clear
Clear the terminal and its scroll-back history
> clear --all
collect
Collect the stream and pass it to a block.
Usage:
> collect {flags} <closure>
Flags:
-h, --help - Display the help message for this command
--keep-env - let the block affect environment variables
Parameters:
closure <closure(any)>: The closure to run once the stream is collected.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Use the second value in the stream
> [1 2 3] | collect { |x| $x.1 }
2
columns
Given a record or table, produce a list of its columns' names.
This is a counterpart to `values`, which produces a list of columns' values.
Usage:
> columns
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬──────────────╮
│ # │ input │ output │
├───┼────────┼──────────────┤
│ 0 │ table │ list<string> │
│ 1 │ record │ list<string> │
╰───┴────────┴──────────────╯
Examples:
Get the columns from the record
> { acronym:PWD, meaning:'Print Working Directory' } | columns
╭───┬─────────╮
│ 0 │ acronym │
│ 1 │ meaning │
╰───┴─────────╯
Get the columns from the table
> [[name,age,grade]; [bill,20,a]] | columns
╭───┬───────╮
│ 0 │ name │
│ 1 │ age │
│ 2 │ grade │
╰───┴───────╯
Get the first column from the table
> [[name,age,grade]; [bill,20,a]] | columns | first
Get the second column from the table
> [[name,age,grade]; [bill,20,a]] | columns | select 1
commandline
View or modify the current command line input buffer.
Search terms: repl, interactive
Usage:
> commandline {flags} (cmd)
Subcommands:
commandline edit - Modify the current command line input buffer.
commandline get-cursor - Get the current cursor position.
commandline set-cursor - Set the current cursor position.
Flags:
-h, --help - Display the help message for this command
-c, --cursor - Set or get the current cursor position
-e, --cursor-end - Set the current cursor position to the end of the buffer
-a, --append - appends the string to the end of the buffer
-i, --insert - inserts the string into the buffer at the cursor position
-r, --replace - replaces the current contents of the buffer (default)
Parameters:
cmd <string>: the string to perform the operation with (optional)
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
│ 1 │ string │ string │
╰───┴─────────┴─────────╯
commandline edit
Modify the current command line input buffer.
Search terms: repl, interactive
Usage:
> commandline edit {flags} <str>
Flags:
-h, --help - Display the help message for this command
-a, --append - appends the string to the end of the buffer
-i, --insert - inserts the string into the buffer at the cursor position
-r, --replace - replaces the current contents of the buffer (default)
Parameters:
str <string>: the string to perform the operation with
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
commandline get-cursor
Get the current cursor position.
Search terms: repl, interactive
Usage:
> commandline get-cursor
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ int │
╰───┴─────────┴────────╯
commandline set-cursor
Set the current cursor position.
Search terms: repl, interactive
Usage:
> commandline set-cursor {flags} (pos)
Flags:
-h, --help - Display the help message for this command
-e, --end - set the current cursor position to the end of the buffer
Parameters:
pos <int>: Cursor position to be set (optional)
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
compact
Creates a table with non-empty rows.
Usage:
> compact {flags} ...(columns)
Flags:
-h, --help - Display the help message for this command
-e, --empty - also compact empty items like "", {}, and []
Parameters:
...columns <any>: The columns to compact from the table.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Filter out all records where 'Hello' is null
> [["Hello" "World"]; [null 3]] | compact Hello
╭────────────╮
│ empty list │
╰────────────╯
Filter out all records where 'World' is null
> [["Hello" "World"]; [null 3]] | compact World
╭───┬───────┬───────╮
│ # │ Hello │ World │
├───┼───────┼───────┤
│ 0 │ │ 3 │
╰───┴───────┴───────╯
Filter out all instances of null from a list
> [1, null, 2] | compact
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
╰───┴───╯
Filter out all instances of null and empty items from a list
> [1, null, 2, "", 3, [], 4, {}, 5] | compact --empty
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
│ 3 │ 4 │
│ 4 │ 5 │
╰───┴───╯
complete
Capture the outputs and exit code from an external piped in command in a nushell table.
In order to capture stdout, stderr, and exit_code, externally piped in commands need to be wrapped with `do`
Usage:
> complete
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ record │
╰───┴───────┴────────╯
Examples:
Run the external command to completion, capturing stdout and exit_code
> ^external arg1 | complete
Run external command to completion, capturing, stdout, stderr and exit_code
> do { ^external arg1 } | complete
config
Edit nushell configuration files.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Search terms: options, setup
Usage:
> config
Subcommands:
config env - Edit nu environment configurations.
config nu - Edit nu configurations.
config reset - Reset nushell environment configurations to default, and saves old config files in the config location as oldconfig.nu and oldenv.nu.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
config env
Edit nu environment configurations.
Usage:
> config env {flags}
Flags:
-h, --help - Display the help message for this command
-d, --default - Print default `env.nu` file instead.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
allow user to open and update nu env
> config env
allow user to print default `env.nu` file
> config env --default,
allow saving the default `env.nu` locally
> config env --default | save -f ~/.config/nushell/default_env.nu
config nu
Edit nu configurations.
Usage:
> config nu {flags}
Flags:
-h, --help - Display the help message for this command
-d, --default - Print default `config.nu` file instead.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
allow user to open and update nu config
> config nu
allow user to print default `config.nu` file
> config nu --default,
allow saving the default `config.nu` locally
> config nu --default | save -f ~/.config/nushell/default_config.nu
config reset
Reset nushell environment configurations to default, and saves old config files in the config location as oldconfig.nu and oldenv.nu.
Usage:
> config reset {flags}
Flags:
-h, --help - Display the help message for this command
-n, --nu - reset only nu config, config.nu
-e, --env - reset only env config, env.nu
-w, --without-backup - do not make a backup
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
reset nushell configuration files
> config reset
const
Create a parse-time constant.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: set, let
Usage:
> const <const_name> = <initial_value>
Flags:
-h, --help - Display the help message for this command
Parameters:
const_name <vardecl>: Constant name.
"=" + <variable>: Equals sign followed by constant value.
Examples:
Create a new parse-time constant.
> const x = 10
Create a composite constant value
> const x = { a: 10, b: 20 }
continue
Continue a loop from the next iteration.
Usage:
> continue
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Continue a loop from the next iteration
> for i in 1..10 { if $i == 5 { continue }; print $i }
cp
Copy files using uutils/coreutils cp.
Search terms: copy, file, files, coreutils
Usage:
> cp {flags} ...(paths)
Flags:
-h, --help - Display the help message for this command
-r, --recursive - copy directories recursively
-v, --verbose - explicitly state what is being done
-f, --force - if an existing destination file cannot be opened, remove it and try
again (this option is ignored when the -n option is also used).
currently not implemented for windows
-i, --interactive - ask before overwriting files
-u, --update - copy only when the SOURCE file is newer than the destination file or when the destination file is missing
-p, --progress - display a progress bar
-n, --no-clobber - do not overwrite an existing file
--preserve <List(String)> - preserve only the specified attributes (empty list means no attributes preserved)
if not specified only mode is preserved
possible values: mode, ownership (unix only), timestamps, context, link, links, xattr
--debug - explain how a file is copied. Implies -v
Parameters:
...paths <one_of(glob, string)>: Copy SRC file/s to DEST.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Copy myfile to dir_b
> cp myfile dir_b
Recursively copy dir_a to dir_b
> cp -r dir_a dir_b
Recursively copy dir_a to dir_b, and print the feedbacks
> cp -r -v dir_a dir_b
Move many files into a directory
> cp *.txt dir_a
Copy only if source file is newer than target file
> cp -u a b
Copy file preserving mode and timestamps attributes
> cp --preserve [ mode timestamps ] a b
Copy file erasing all attributes
> cp --preserve [] a b
date
Date-related commands.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Search terms: time, now, today, tomorrow, yesterday, weekday, weekday_name, timezone
Usage:
> date
Subcommands:
date humanize - Print a 'humanized' format for the date, relative to now.
date list-timezone - List supported time zones.
date now - Get the current date.
date to-record - Convert the date into a record.
date to-table - Convert the date into a structured table.
date to-timezone - Convert a date to a given time zone.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
date format
Removed command: use `format date` instead.
Usage:
> date format {flags} (format string)
Flags:
-h, --help - Display the help message for this command
-l, --list - lists strftime cheatsheet
Parameters:
format string <string>: The desired date format. (optional)
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ date │ string │
│ 1 │ string │ string │
╰───┴────────┴────────╯
date humanize
Print a 'humanized' format for the date, relative to now.
Search terms: relative, now, today, tomorrow, yesterday, weekday, weekday_name, timezone
Usage:
> date humanize
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ date │ string │
│ 1 │ string │ string │
╰───┴────────┴────────╯
Examples:
Print a 'humanized' format for the date, relative to now.
> "2021-10-22 20:00:12 +01:00" | date humanize
date list-timezone
List supported time zones.
Search terms: UTC, GMT, tz
Usage:
> date list-timezone
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Show time zone(s) that contains 'Shanghai'
> date list-timezone | where timezone =~ Shanghai
╭───┬───────────────╮
│ # │ timezone │
├───┼───────────────┤
│ 0 │ Asia/Shanghai │
╰───┴───────────────╯
date now
Get the current date.
Search terms: present, current-time
Usage:
> date now
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ date │
╰───┴─────────┴────────╯
Examples:
Get the current date and display it in a given format string.
> date now | format date "%Y-%m-%d %H:%M:%S"
Get the time duration since 2019-04-30.
> (date now) - 2019-05-01
Get the time duration since a more specific time.
> (date now) - 2019-05-01T04:12:05.20+08:00
Get current time in full RFC 3339 format with time zone.
> date now | debug
date to-record
Convert the date into a record.
Search terms: structured, table
Usage:
> date to-record
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ date │ record │
│ 1 │ string │ record │
╰───┴────────┴────────╯
Examples:
Convert the current date into a record.
> date now | date to-record
Convert a date string into a record.
> '2020-04-12T22:10:57.123+02:00' | date to-record
╭────────────┬───────────╮
│ year │ 2020 │
│ month │ 4 │
│ day │ 12 │
│ hour │ 22 │
│ minute │ 10 │
│ second │ 57 │
│ nanosecond │ 123000000 │
│ timezone │ +02:00 │
╰────────────┴───────────╯
Convert a date into a record.
> '2020-04-12 22:10:57 +0200' | into datetime | date to-record
╭────────────┬────────╮
│ year │ 2020 │
│ month │ 4 │
│ day │ 12 │
│ hour │ 22 │
│ minute │ 10 │
│ second │ 57 │
│ nanosecond │ 0 │
│ timezone │ +02:00 │
╰────────────┴────────╯
date to-table
Convert the date into a structured table.
Search terms: structured
Usage:
> date to-table
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ date │ table │
│ 1 │ string │ table │
╰───┴────────┴────────╯
Examples:
Convert the current date into a table.
> date now | date to-table
Convert a given date into a table.
> 2020-04-12T22:10:57.000000789+02:00 | date to-table
╭───┬──────┬───────┬─────┬──────┬────────┬────────┬────────────┬──────────╮
│ # │ year │ month │ day │ hour │ minute │ second │ nanosecond │ timezone │
├───┼──────┼───────┼─────┼──────┼────────┼────────┼────────────┼──────────┤
│ 0 │ 2020 │ 4 │ 12 │ 22 │ 10 │ 57 │ 789 │ +02:00 │
╰───┴──────┴───────┴─────┴──────┴────────┴────────┴────────────┴──────────╯
Convert a given date into a table.
> '2020-04-12 22:10:57 +0200' | into datetime | date to-table
╭───┬──────┬───────┬─────┬──────┬────────┬────────┬────────────┬──────────╮
│ # │ year │ month │ day │ hour │ minute │ second │ nanosecond │ timezone │
├───┼──────┼───────┼─────┼──────┼────────┼────────┼────────────┼──────────┤
│ 0 │ 2020 │ 4 │ 12 │ 22 │ 10 │ 57 │ 0 │ +02:00 │
╰───┴──────┴───────┴─────┴──────┴────────┴────────┴────────────┴──────────╯
date to-timezone
Convert a date to a given time zone.
Use 'date list-timezone' to list all supported time zones.
Search terms: tz, transform, convert, UTC, GMT, list, list-timezone
Usage:
> date to-timezone <time zone>
Flags:
-h, --help - Display the help message for this command
Parameters:
time zone <string>: Time zone description.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ date │ date │
│ 1 │ string │ date │
╰───┴────────┴────────╯
Examples:
Get the current date in UTC+05:00.
> date now | date to-timezone '+0500'
Get the current date in the local time zone.
> date now | date to-timezone local
Get the current date in Hawaii.
> date now | date to-timezone US/Hawaii
Get a date in a different time zone, from a string.
> "2020-10-10 10:00:00 +02:00" | date to-timezone "+0500"
Sat, 10 Oct 2020 13:00:00 +0500 (3 years ago)
Get a date in a different time zone, from a datetime.
> "2020-10-10 10:00:00 +02:00" | into datetime | date to-timezone "+0500"
Sat, 10 Oct 2020 13:00:00 +0500 (3 years ago)
debug
Debug print the value(s) piped in.
Usage:
> debug {flags}
Subcommands:
debug info - View process memory info.
Flags:
-h, --help - Display the help message for this command
-r, --raw - Prints the raw value representation
Input/output types:
╭───┬───────────┬──────────────╮
│ # │ input │ output │
├───┼───────────┼──────────────┤
│ 0 │ list<any> │ list<string> │
│ 1 │ any │ string │
╰───┴───────────┴──────────────╯
Examples:
Debug print a string
> 'hello' | debug
hello
Debug print a list
> ['hello'] | debug
╭───┬───────╮
│ 0 │ hello │
╰───┴───────╯
Debug print a table
> [[version patch]; ['0.1.0' false] ['0.1.1' true] ['0.2.0' false]] | debug
╭───┬────────────────────────────────╮
│ 0 │ {version: 0.1.0, patch: false} │
│ 1 │ {version: 0.1.1, patch: true} │
│ 2 │ {version: 0.2.0, patch: false} │
╰───┴────────────────────────────────╯
debug info
View process memory info.
This command is meant for debugging purposes.
It shows you the process information and system memory information.
Usage:
> debug info
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
View process information
> debug info
decode
Decode bytes into a string.
Multiple encodings are supported; here are a few:
big5, euc-jp, euc-kr, gbk, iso-8859-1, utf-16, cp1252, latin5
For a more complete list of encodings please refer to the encoding_rs
documentation link at https://docs.rs/encoding_rs/latest/encoding_rs/#statics
Search terms: text, encoding, decoding
Usage:
> decode (encoding)
Subcommands:
decode base64 - Base64 decode a value.
Flags:
-h, --help - Display the help message for this command
Parameters:
encoding <string>: The text encoding to use. (optional)
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ string │
╰───┴────────┴────────╯
Examples:
Decode the output of an external command
> ^cat myfile.q | decode utf-8
Decode an UTF-16 string into nushell UTF-8 string
> 0x[00 53 00 6F 00 6D 00 65 00 20 00 44 00 61 00 74 00 61] | decode utf-16be
Some Data
decode base64
Base64 decode a value.
Will attempt to decode binary payload as an UTF-8 string by default. Use the `--binary(-b)` argument to force binary output.
Usage:
> decode base64 {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-c, --character-set <String> - specify the character rules for encoding the input.
Valid values are 'standard', 'standard-no-padding', 'url-safe', 'url-safe-no-padding','binhex', 'bcrypt', 'crypt', 'mutf7'
-b, --binary - Output a binary value instead of decoding payload as UTF-8
Parameters:
...rest <cell-path>: For a data structure input, decode data at the given cell paths.
Input/output types:
╭───┬──────────────┬───────────╮
│ # │ input │ output │
├───┼──────────────┼───────────┤
│ 0 │ string │ any │
│ 1 │ list<string> │ list<any> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴───────────╯
Examples:
Base64 decode a value and output as UTF-8 string
> 'U29tZSBEYXRh' | decode base64
Some Data
Base64 decode a value and output as binary
> 'U29tZSBEYXRh' | decode base64 --binary
Some Data
def
Define a custom command.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> def {flags} <def_name> <params> <block>
Flags:
-h, --help - Display the help message for this command
--env - keep the environment defined inside the command
--wrapped - treat unknown flags and arguments as strings (requires ...rest-like parameter in signature)
Parameters:
def_name <string>: Command name.
params <signature>: Parameters.
block <closure()>: Body of the definition.
Examples:
Define a command and run it
> def say-hi [] { echo 'hi' }; say-hi
hi
Define a command and run it with parameter(s)
> def say-sth [sth: string] { echo $sth }; say-sth hi
hi
Set environment variable by call a custom command
> def --env foo [] { $env.BAR = "BAZ" }; foo; $env.BAR
BAZ
Define a custom wrapper for an external command
> def --wrapped my-echo [...rest] { echo $rest }; my-echo spam
╭───┬──────╮
│ 0 │ spam │
╰───┴──────╯
default
Sets a default row's column if missing.
Usage:
> default <default value> (column name)
Flags:
-h, --help - Display the help message for this command
Parameters:
default value <any>: The value to use as a default.
column name <string>: The name of the column. (optional)
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Give a default 'target' column to all file entries
> ls -la | default 'nothing' target
Get the env value of `MY_ENV` with a default value 'abc' if not present
> $env | get --ignore-errors MY_ENV | default 'abc'
Replace the `null` value in a list
> [1, 2, null, 4] | default 3
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
│ 3 │ 4 │
╰───┴───╯
describe
Describe the type and structure of the value(s) piped in.
Search terms: type, typeof, info, structure
Usage:
> describe {flags}
Flags:
-h, --help - Display the help message for this command
-n, --no-collect - do not collect streams of structured data
-d, --detailed - show detailed information about the value
-l, --collect-lazyrecords - collect lazy records
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Describe the type of a string
> 'hello' | describe
string
Describe the type of a record in a detailed way
> {shell:'true', uwu:true, features: {bugs:false, multiplatform:true, speed: 10}, fib: [1 1 2 3 5 8], on_save: {|x| print $'Saving ($x)'}, first_commit: 2019-05-10, my_duration: (4min + 20sec)} | describe -d
╭─────────┬───────────────────╮
│ type │ record │
│ lazy │ false │
│ columns │ {record 7 fields} │
╰─────────┴───────────────────╯
Describe the type of a stream with detailed information
> [1 2 3] | each {|i| echo $i} | describe -d
Describe a stream of data, collecting it first
> [1 2 3] | each {|i| echo $i} | describe
Describe the input but do not collect streams
> [1 2 3] | each {|i| echo $i} | describe --no-collect
detect columns
Attempt to automatically split text into multiple columns.
Search terms: split, tabular
Usage:
> detect columns {flags}
Flags:
-h, --help - Display the help message for this command
-s, --skip <Int> - number of rows to skip before detecting
-n, --no-headers - don't detect headers
-c, --combine-columns <Range> - columns to be combined; listed as a range
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ table │
╰───┴────────┴────────╯
Examples:
Splits string across multiple columns
> 'a b c' | detect columns --no-headers
╭───┬─────────┬─────────┬─────────╮
│ # │ column0 │ column1 │ column2 │
├───┼─────────┼─────────┼─────────┤
│ 0 │ a │ b │ c │
╰───┴─────────┴─────────┴─────────╯
> $'c1 c2 c3 c4 c5(char nl)a b c d e' | detect columns --combine-columns 0..1
Splits a multi-line string into columns with headers detected
> $'c1 c2 c3 c4 c5(char nl)a b c d e' | detect columns --combine-columns -2..-1
Splits a multi-line string into columns with headers detected
> $'c1 c2 c3 c4 c5(char nl)a b c d e' | detect columns --combine-columns 2..
Parse external ls command and combine columns for datetime
> ^ls -lh | detect columns --no-headers --skip 1 --combine-columns 5..7
do
Run a closure, providing it with the pipeline input.
Usage:
> do {flags} <closure> ...(rest)
Flags:
-h, --help - Display the help message for this command
-i, --ignore-errors - ignore errors as the closure runs
-s, --ignore-shell-errors - ignore shell errors as the closure runs
-p, --ignore-program-errors - ignore external program errors as the closure runs
-c, --capture-errors - catch errors as the closure runs, and return them
--env - keep the environment defined inside the command
Parameters:
closure <one_of(closure(), any)>: The closure to run.
...rest <any>: The parameter(s) for the closure.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Run the closure
> do { echo hello }
hello
Run a stored first-class closure
> let text = "I am enclosed"; let hello = {|| echo $text}; do $hello
I am enclosed
Run the closure and ignore both shell and external program errors
> do --ignore-errors { thisisnotarealcommand }
Run the closure and ignore shell errors
> do --ignore-shell-errors { thisisnotarealcommand }
Run the closure and ignore external program errors
> do --ignore-program-errors { nu --commands 'exit 1' }; echo "I'll still run"
Abort the pipeline if a program returns a non-zero exit code
> do --capture-errors { nu --commands 'exit 1' } | myscarycommand
Run the closure, with a positional parameter
> do {|x| 100 + $x } 77
177
Run the closure, with input
> 77 | do {|x| 100 + $in }
Run the closure and keep changes to the environment
> do --env { $env.foo = 'bar' }; $env.foo
bar
drop
Alias for `drop`
Usage:
> drop
Subcommands:
drop column - Remove N columns at the right-hand end of the input table. To remove columns by name, use `reject`.
drop nth - Drop the selected rows.
Flags:
-h, --help - Display the help message for this command
======================
Remove items/rows from the end of the input list/table. Counterpart of `skip`. Opposite of `last`.
Search terms: delete
Usage:
> drop (rows)
Subcommands:
drop column - Remove N columns at the right-hand end of the input table. To remove columns by name, use `reject`.
drop nth - Drop the selected rows.
Flags:
-h, --help - Display the help message for this command
Parameters:
rows <int>: The number of items to remove. (optional)
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ table │ table │
│ 1 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Remove the last item of a list
> [0,1,2,3] | drop
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
╰───┴───╯
Remove zero item of a list
> [0,1,2,3] | drop 0
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ 3 │
╰───┴───╯
Remove the last two items of a list
> [0,1,2,3] | drop 2
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
╰───┴───╯
Remove the last row in a table
> [[a, b]; [1, 2] [3, 4]] | drop 1
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
╰───┴───┴───╯
drop column
Remove N columns at the right-hand end of the input table. To remove columns by name, use `reject`.
Search terms: delete
Usage:
> drop column (columns)
Flags:
-h, --help - Display the help message for this command
Parameters:
columns <int>: Starting from the end, the number of columns to remove. (optional)
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ table │ table │
│ 1 │ record │ record │
╰───┴────────┴────────╯
Examples:
Remove the last column of a table
> [[lib, extension]; [nu-lib, rs] [nu-core, rb]] | drop column
╭───┬─────────╮
│ # │ lib │
├───┼─────────┤
│ 0 │ nu-lib │
│ 1 │ nu-core │
╰───┴─────────╯
Remove the last column of a record
> {lib: nu-lib, extension: rs} | drop column
╭─────┬────────╮
│ lib │ nu-lib │
╰─────┴────────╯
drop nth
Drop the selected rows.
Search terms: delete
Usage:
> drop nth <row number or row range> ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
row number or row range <any>: The number of the row to drop or a range to drop consecutive rows.
...rest <any>: The number of the row to drop.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Drop the first, second, and third row
> [sam,sarah,2,3,4,5] | drop nth 0 1 2
╭───┬───╮
│ 0 │ 3 │
│ 1 │ 4 │
│ 2 │ 5 │
╰───┴───╯
Drop the first, second, and third row
> [0,1,2,3,4,5] | drop nth 0 1 2
╭───┬───╮
│ 0 │ 3 │
│ 1 │ 4 │
│ 2 │ 5 │
╰───┴───╯
Drop rows 0 2 4
> [0,1,2,3,4,5] | drop nth 0 2 4
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 3 │
│ 2 │ 5 │
╰───┴───╯
Drop rows 2 0 4
> [0,1,2,3,4,5] | drop nth 2 0 4
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 3 │
│ 2 │ 5 │
╰───┴───╯
Drop range rows from second to fourth
> [first second third fourth fifth] | drop nth (1..3)
╭───┬───────╮
│ 0 │ first │
│ 1 │ fifth │
╰───┴───────╯
Drop all rows except first row
> [0,1,2,3,4,5] | drop nth 1..
╭───┬───╮
│ 0 │ 0 │
╰───┴───╯
Drop rows 3,4,5
> [0,1,2,3,4,5] | drop nth 3..
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
╰───┴───╯
du
Find disk usage sizes of specified items.
Usage:
> du {flags} (path)
Flags:
-h, --help - Display the help message for this command
-a, --all - Output file sizes as well as directory sizes
-r, --deref - Dereference symlinks to their targets for size
-x, --exclude <GlobPattern> - Exclude these file names
-d, --max-depth <Int> - Directory recursion limit
-m, --min-size <Int> - Exclude files below this size
Parameters:
path <one_of(glob, string)>: Starting directory. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Disk usage of the current directory
> du
each
Run a closure on each row of the input list, creating a new list with the results.
Since tables are lists of records, passing a table into 'each' will
iterate over each record, not necessarily each cell within it.
Avoid passing single records to this command. Since a record is a
one-row structure, 'each' will only run once, behaving similar to 'do'.
To iterate over a record's values, try converting it to a table
with 'transpose' first.
Search terms: for, loop, iterate, map
Usage:
> each {flags} <closure>
Flags:
-h, --help - Display the help message for this command
-k, --keep-empty - keep empty result cells
Parameters:
closure <closure(any, int)>: The closure to run.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
│ 1 │ table │ list<any> │
│ 2 │ any │ any │
╰───┴───────────┴───────────╯
Examples:
Multiplies elements in the list
> [1 2 3] | each {|e| 2 * $e }
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 4 │
│ 2 │ 6 │
╰───┴───╯
Produce a list of values in the record, converted to string
> {major:2, minor:1, patch:4} | values | each {|| into string }
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 1 │
│ 2 │ 4 │
╰───┴───╯
Produce a list that has "two" for each 2 in the input
> [1 2 3 2] | each {|e| if $e == 2 { "two" } }
╭───┬─────╮
│ 0 │ two │
│ 1 │ two │
╰───┴─────╯
Iterate over each element, producing a list showing indexes of any 2s
> [1 2 3] | enumerate | each {|e| if $e.item == 2 { $"found 2 at ($e.index)!"} }
╭───┬───────────────╮
│ 0 │ found 2 at 1! │
╰───┴───────────────╯
Iterate over each element, keeping null results
> [1 2 3] | each --keep-empty {|e| if $e == 2 { "found 2!"} }
╭───┬──────────╮
│ 0 │ │
│ 1 │ found 2! │
│ 2 │ │
╰───┴──────────╯
echo
Returns its arguments, ignoring the piped-in value.
When given no arguments, it returns an empty string. When given one argument,
it returns it. Otherwise, it returns a list of the arguments. There is usually
little reason to use this over just writing the values as-is.
Usage:
> echo ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <any>: The values to echo.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Put a list of numbers in the pipeline. This is the same as [1 2 3].
> echo 1 2 3
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
╰───┴───╯
Returns the piped-in value, by using the special $in variable to obtain it.
> echo $in
encode
Encode a string into bytes.
Multiple encodings are supported; here are a few:
big5, euc-jp, euc-kr, gbk, iso-8859-1, cp1252, latin5
Note that since the Encoding Standard doesn't specify encoders for utf-16le and utf-16be, these are not yet supported.
For a more complete list of encodings, please refer to the encoding_rs
documentation link at https://docs.rs/encoding_rs/latest/encoding_rs/#statics
Search terms: text, encoding, decoding
Usage:
> encode {flags} <encoding>
Subcommands:
encode base64 - Encode a string or binary value using Base64.
Flags:
-h, --help - Display the help message for this command
-i, --ignore-errors - when a character isn't in the given encoding, replace with a HTML entity (like `🎈`)
Parameters:
encoding <string>: The text encoding to use.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ binary │
╰───┴────────┴────────╯
Examples:
Encode an UTF-8 string into Shift-JIS
> "負けると知って戦うのが、遥かに美しいのだ" | encode shift-jis
[149, 137, 130, 175, 130, 233, 130, 198, 146, 109, 130, 193, 130, 196, 144, 237, 130, 164, 130, 204, 130, 170, 129, 65, 151, 121, 130, 169, 130, 201, 148, 252, 130, 181, 130, 162, 130, 204, 130, 190]
Replace characters with HTML entities if they can't be encoded
> "🎈" | encode --ignore-errors shift-jis
🎈
encode base64
Encode a string or binary value using Base64.
Usage:
> encode base64 {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-c, --character-set <String> - specify the character rules for encoding the input.
Valid values are 'standard', 'standard-no-padding', 'url-safe', 'url-safe-no-padding','binhex', 'bcrypt', 'crypt', 'mutf7'
Parameters:
...rest <cell-path>: For a data structure input, encode data at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ binary │ string │
│ 2 │ list<string> │ list<string> │
│ 3 │ list<binary> │ list<string> │
│ 4 │ list<any> │ list<string> │
│ 5 │ table │ table │
│ 6 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Encode binary data
> 0x[09 F9 11 02 9D 74 E3 5B D8 41 56 C5 63 56 88 C0] | encode base64
CfkRAp1041vYQVbFY1aIwA==
Encode a string with default settings
> 'Some Data' | encode base64
U29tZSBEYXRh
Encode a string with the binhex character set
> 'Some Data' | encode base64 --character-set binhex
7epXB5"%A@4J
enumerate
Enumerate the elements in a stream.
Search terms: itemize
Usage:
> enumerate
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ table │
╰───┴───────┴────────╯
Examples:
Add an index to each element of a list
> [a, b, c] | enumerate
╭───┬──────╮
│ # │ item │
├───┼──────┤
│ 0 │ a │
│ 1 │ b │
│ 2 │ c │
╰───┴──────╯
error make
Create an error.
Search terms: panic, crash, throw
Usage:
> error make {flags} <error_struct>
Flags:
-h, --help - Display the help message for this command
-u, --unspanned - remove the origin label from the error
Parameters:
error_struct <record>: The error to create.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ error │
╰───┴─────────┴────────╯
Examples:
Create a simple custom error
> error make {msg: "my custom error message"}
Create a more complex custom error
> error make {
msg: "my custom error message"
label: {
text: "my custom label text" # not mandatory unless $.label exists
# optional
span: {
# if $.label.span exists, both start and end must be present
start: 123
end: 456
}
}
help: "A help string, suggesting a fix to the user" # optional
}
Create a custom error for a custom command that shows the span of the argument
> def foo [x] {
error make {
msg: "this is fishy"
label: {
text: "fish right here"
span: (metadata $x).span
}
}
}
every
Show (or skip) every n-th row, starting from the first one.
Usage:
> every {flags} <stride>
Flags:
-h, --help - Display the help message for this command
-s, --skip - skip the rows that would be returned, instead of selecting them
Parameters:
stride <int>: How many rows to skip between (and including) each row returned.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Get every second row
> [1 2 3 4 5] | every 2
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 3 │
│ 2 │ 5 │
╰───┴───╯
Skip every second row
> [1 2 3 4 5] | every 2 --skip
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 4 │
╰───┴───╯
exec
Execute a command, replacing or exiting the current process, depending on platform.
On Unix-based systems, the current process is replaced with the command.
On Windows based systems, Nushell will wait for the command to finish and then exit with the command's exit code.
Usage:
> exec <command>
Flags:
-h, --help - Display the help message for this command
Parameters:
command <string>: The command to execute.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Execute external 'ps aux' tool
> exec ps aux
Execute 'nautilus'
> exec nautilus
exit
Exit Nu.
Search terms: quit, close, exit_code, error_code, logout
Usage:
> exit (exit_code)
Flags:
-h, --help - Display the help message for this command
Parameters:
exit_code <int>: Exit code to return immediately with. (optional)
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Exit the current shell
> exit
explain
Explain closure contents.
Usage:
> explain <closure>
Flags:
-h, --help - Display the help message for this command
Parameters:
closure <closure(any)>: The closure to run.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ any │ any │
│ 1 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Explain a command within a closure
> explain {|| ls | sort-by name type --ignore-case | get name } | table --expand
explore
Explore acts as a table pager, just like `less` does for text.
Press `:` then `h` to get a help menu.
Usage:
> explore {flags}
Flags:
-h, --help - Display the help message for this command
--head <Boolean> - Show or hide column headers (default true)
-i, --index - Show row indexes when viewing a list
-r, --reverse - Start with the viewport scrolled to the bottom
-p, --peek - When quitting, output the value of the cell the cursor was on
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Explore the system information record
> sys | explore
Explore the output of `ls` without column names
> ls | explore --head false
Explore a list of Markdown files' contents, with row indexes
> glob *.md | each {|| open } | explore --index
Explore a JSON file, then save the last visited sub-structure to a file
> open file.json | explore --peek | to json | save part.json
export
Export definitions or environment variables from a module.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: module
Usage:
> export
Subcommands:
export alias - Alias a command (with optional flags) to a new name and export it from a module.
export const - Use parse-time constant from a module and export them from this module.
export def - Define a custom command and export it from a module.
export extern - Define an extern and export it from a module.
export module - Export a custom module from a module.
export use - Use definitions from a module and export them from this module.
Flags:
-h, --help - Display the help message for this command
Examples:
Export a definition from a module
> module utils { export def my-command [] { "hello" } }; use utils my-command; my-command
hello
export alias
Alias a command (with optional flags) to a new name and export it from a module.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: abbr, aka, fn, func, function
Usage:
> export alias <name> = <initial_value>
Flags:
-h, --help - Display the help message for this command
Parameters:
name <string>: Name of the alias.
"=" + <expression>: Equals sign followed by value.
Examples:
Alias ll to ls -l and export it from a module
> module spam { export alias ll = ls -l }
export const
Use parse-time constant from a module and export them from this module.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: reexport, import, module
Usage:
> export const <const_name> = <initial_value>
Flags:
-h, --help - Display the help message for this command
Parameters:
const_name <vardecl>: Constant name.
"=" + <variable>: Equals sign followed by constant value.
Examples:
Re-export a command from another module
> module spam { export const foo = 3; }
module eggs { export use spam foo }
use eggs foo
foo
3
export def
Define a custom command and export it from a module.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: module
Usage:
> export def {flags} <def_name> <params> <block>
Flags:
-h, --help - Display the help message for this command
--env - keep the environment defined inside the command
--wrapped - treat unknown flags and arguments as strings (requires ...rest-like parameter in signature)
Parameters:
def_name <string>: Command name.
params <signature>: Parameters.
block <block>: Body of the definition.
Examples:
Define a custom command in a module and call it
> module spam { export def foo [] { "foo" } }; use spam foo; foo
foo
export extern
Define an extern and export it from a module.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: signature, module, declare
Usage:
> export extern <def_name> <params>
Flags:
-h, --help - Display the help message for this command
Parameters:
def_name <string>: Definition name.
params <signature>: Parameters.
Examples:
Export the signature for an external command
> export extern echo [text: string]
export module
Export a custom module from a module.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> export module <module> (block)
Flags:
-h, --help - Display the help message for this command
Parameters:
module <string>: Module name or module path.
block <block>: Body of the module if 'module' parameter is not a path. (optional)
Examples:
Define a custom command in a submodule of a module and call it
> module spam {
export module eggs {
export def foo [] { "foo" }
}
}
use spam eggs
eggs foo
foo
export use
Use definitions from a module and export them from this module.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: reexport, import, module
Usage:
> export use <module> (members)
Flags:
-h, --help - Display the help message for this command
Parameters:
module <string>: Module or module file.
members <any>: Which members of the module to import. (optional)
Examples:
Re-export a command from another module
> module spam { export def foo [] { "foo" } }
module eggs { export use spam foo }
use eggs foo
foo
foo
export-env
Run a block and preserve its environment in a current scope.
Usage:
> export-env <block>
Flags:
-h, --help - Display the help message for this command
Parameters:
block <block>: The block to run to set the environment.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Set an environment variable
> export-env { $env.SPAM = 'eggs' }
Set an environment variable and examine its value
> export-env { $env.SPAM = 'eggs' }; $env.SPAM
eggs
extern
Define a signature for an external command.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> extern <def_name> <params>
Flags:
-h, --help - Display the help message for this command
Parameters:
def_name <string>: Definition name.
params <signature>: Parameters.
Examples:
Write a signature for an external command
> extern echo [text: string]
fill
Fill and Align.
Search terms: display, render, format, pad, align
Usage:
> fill {flags}
Flags:
-h, --help - Display the help message for this command
-w, --width <Int> - The width of the output. Defaults to 1
-a, --alignment <String> - The alignment of the output. Defaults to Left (Left(l), Right(r), Center(c/m), MiddleRight(cr/mr))
-c, --character <String> - The character to fill with. Defaults to ' ' (space)
Input/output types:
╭───┬────────────────┬──────────────╮
│ # │ input │ output │
├───┼────────────────┼──────────────┤
│ 0 │ int │ string │
│ 1 │ float │ string │
│ 2 │ string │ string │
│ 3 │ filesize │ string │
│ 4 │ list<int> │ list<string> │
│ 5 │ list<float> │ list<string> │
│ 6 │ list<string> │ list<string> │
│ 7 │ list<filesize> │ list<string> │
│ 8 │ list<any> │ list<string> │
╰───┴────────────────┴──────────────╯
Examples:
Fill a string on the left side to a width of 15 with the character '─'
> 'nushell' | fill --alignment l --character '─' --width 15
nushell────────
Fill a string on the right side to a width of 15 with the character '─'
> 'nushell' | fill --alignment r --character '─' --width 15
────────nushell
Fill a string on both sides to a width of 15 with the character '─'
> 'nushell' | fill --alignment m --character '─' --width 15
────nushell────
Fill a number on the left side to a width of 5 with the character '0'
> 1 | fill --alignment right --character '0' --width 5
00001
Fill a number on both sides to a width of 5 with the character '0'
> 1.1 | fill --alignment center --character '0' --width 5
01.10
Fill a filesize on the left side to a width of 5 with the character '0'
> 1kib | fill --alignment middle --character '0' --width 10
0001024000
filter
Filter values based on a predicate closure.
This command works similar to 'where' but allows reading the predicate closure from
a variable. On the other hand, the "row condition" syntax is not supported.
Search terms: where, find, search, condition
Usage:
> filter <closure>
Flags:
-h, --help - Display the help message for this command
Parameters:
closure <closure(any, int)>: Predicate closure.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
│ 1 │ range │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Filter items of a list according to a condition
> [1 2] | filter {|x| $x > 1}
╭───┬───╮
│ 0 │ 2 │
╰───┴───╯
Filter rows of a table according to a condition
> [{a: 1} {a: 2}] | filter {|x| $x.a > 1}
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 2 │
╰───┴───╯
Filter rows of a table according to a stored condition
> let cond = {|x| $x.a > 1}; [{a: 1} {a: 2}] | filter $cond
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 2 │
╰───┴───╯
Filter items of a range according to a condition
> 9..13 | filter {|el| $el mod 2 != 0}
╭───┬────╮
│ 0 │ 9 │
│ 1 │ 11 │
│ 2 │ 13 │
╰───┴────╯
List all numbers above 3, using an existing closure condition
> let a = {$in > 3}; [1, 2, 5, 6] | filter $a
find
Searches terms in the input.
Search terms: filter, regex, search, condition
Usage:
> find {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-r, --regex <String> - regex to match with
-i, --ignore-case - case-insensitive regex mode; equivalent to (?i)
-m, --multiline - multi-line regex mode: ^ and $ match begin/end of line; equivalent to (?m)
-s, --dotall - dotall regex mode: allow a dot . to match newlines \n; equivalent to (?s)
-c, --columns <List(String)> - column names to be searched (with rest parameter, not regex yet)
-v, --invert - invert the match
Parameters:
...rest <any>: Terms to search.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
│ 1 │ string │ any │
╰───┴───────────┴───────────╯
Examples:
Search for multiple terms in a command output
> ls | find toml md sh
Search and highlight text for a term in a string
> 'Cargo.toml' | find toml
Cargo.toml
Search a number or a file size in a list of numbers
> [1 5 3kb 4 3Mb] | find 5 3kb
╭───┬────────╮
│ 0 │ 5 │
│ 1 │ 3.0 KB │
╰───┴────────╯
Search a char in a list of string
> [moe larry curly] | find l
╭───┬───────╮
│ 0 │ larry │
│ 1 │ curly │
╰───┴───────╯
Find using regex
> [abc bde arc abf] | find --regex "ab"
╭───┬─────╮
│ 0 │ abc │
│ 1 │ abf │
╰───┴─────╯
Find using regex case insensitive
> [aBc bde Arc abf] | find --regex "ab" -i
╭───┬─────╮
│ 0 │ aBc │
│ 1 │ abf │
╰───┴─────╯
Find value in records using regex
> [[version name]; ['0.1.0' nushell] ['0.1.1' fish] ['0.2.0' zsh]] | find --regex "nu"
╭───┬─────────┬─────────╮
│ # │ version │ name │
├───┼─────────┼─────────┤
│ 0 │ 0.1.0 │ nushell │
╰───┴─────────┴─────────╯
Find inverted values in records using regex
> [[version name]; ['0.1.0' nushell] ['0.1.1' fish] ['0.2.0' zsh]] | find --regex "nu" --invert
╭───┬─────────┬──────╮
│ # │ version │ name │
├───┼─────────┼──────┤
│ 0 │ 0.1.1 │ fish │
│ 1 │ 0.2.0 │ zsh │
╰───┴─────────┴──────╯
Find value in list using regex
> [["Larry", "Moe"], ["Victor", "Marina"]] | find --regex "rr"
╭───┬────────────────╮
│ 0 │ [list 2 items] │
╰───┴────────────────╯
Find inverted values in records using regex
> [["Larry", "Moe"], ["Victor", "Marina"]] | find --regex "rr" --invert
╭───┬────────────────╮
│ 0 │ [list 2 items] │
╰───┴────────────────╯
Remove ANSI sequences from result
> [[foo bar]; [abc 123] [def 456]] | find 123 | get bar | ansi strip
Find and highlight text in specific columns
> [[col1 col2 col3]; [moe larry curly] [larry curly moe]] | find moe --columns [col1]
╭───┬──────┬───────┬───────╮
│ # │ col1 │ col2 │ col3 │
├───┼──────┼───────┼───────┤
│ 0 │ moe │ larry │ curly │
╰───┴──────┴───────┴───────╯
first
Return only the first several rows of the input. Counterpart of `last`. Opposite of `skip`.
Usage:
> first (rows)
Flags:
-h, --help - Display the help message for this command
Parameters:
rows <int>: Starting from the front, the number of rows to return. (optional)
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ any │
│ 1 │ binary │ binary │
│ 2 │ range │ any │
╰───┴───────────┴────────╯
Examples:
Return the first item of a list/table
> [1 2 3] | first
1
Return the first 2 items of a list/table
> [1 2 3] | first 2
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
╰───┴───╯
Return the first 2 bytes of a binary value
> 0x[01 23 45] | first 2
#
Return the first item of a range
> 1..3 | first
1
flatten
Flatten the table.
Usage:
> flatten {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-a, --all - flatten inner table one level out
Parameters:
...rest <string>: Optionally flatten data by column.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
│ 1 │ record │ table │
╰───┴───────────┴───────────╯
Examples:
flatten a table
> [[N, u, s, h, e, l, l]] | flatten
╭───┬───╮
│ 0 │ N │
│ 1 │ u │
│ 2 │ s │
│ 3 │ h │
│ 4 │ e │
│ 5 │ l │
│ 6 │ l │
╰───┴───╯
flatten a table, get the first item
> [[N, u, s, h, e, l, l]] | flatten | first
flatten a column having a nested table
> [[origin, people]; [Ecuador, ([[name, meal]; ['Andres', 'arepa']])]] | flatten --all | get meal
restrict the flattening by passing column names
> [[origin, crate, versions]; [World, ([[name]; ['nu-cli']]), ['0.21', '0.22']]] | flatten versions --all | last | get versions
Flatten inner table
> { a: b, d: [ 1 2 3 4 ], e: [ 4 3 ] } | flatten d --all
╭───┬───┬───┬────────────────╮
│ # │ a │ d │ e │
├───┼───┼───┼────────────────┤
│ 0 │ b │ 1 │ [list 2 items] │
│ 1 │ b │ 2 │ [list 2 items] │
│ 2 │ b │ 3 │ [list 2 items] │
│ 3 │ b │ 4 │ [list 2 items] │
╰───┴───┴───┴────────────────╯
for
Loop over a range.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> for {flags} <var_name> in <range> <block>
Flags:
-h, --help - Display the help message for this command
-n, --numbered - return a numbered item ($it.index and $it.item)
Parameters:
var_name <vardecl>: Name of the looping variable.
"in" + <any>: Range of the loop.
block <block>: The block to run.
Examples:
Print the square of each integer
> for x in [1 2 3] { print ($x * $x) }
Work with elements of a range
> for $x in 1..3 { print $x }
Number each item and print a message
> for $it in ['bob' 'fred'] --numbered { print $"($it.index) is ($it.item)" }
format
Various commands for formatting data.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> format
Subcommands:
format date - Format a given date using a format string.
format duration - Outputs duration with a specified unit of time.
format filesize - Converts a column of filesizes to some specified format.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
format date
Format a given date using a format string.
Search terms: fmt, strftime
Usage:
> format date {flags} (format string)
Flags:
-h, --help - Display the help message for this command
-l, --list - lists strftime cheatsheet
Parameters:
format string <string>: The desired format date. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ date │ string │
│ 1 │ string │ string │
│ 2 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Format a given date-time using the default format (RFC 2822).
> '2021-10-22 20:00:12 +01:00' | into datetime | format date
Fri, 22 Oct 2021 20:00:12 +0100
Format a given date-time as a string using the default format (RFC 2822).
> "2021-10-22 20:00:12 +01:00" | format date
Fri, 22 Oct 2021 20:00:12 +0100
Format the current date-time using a given format string.
> date now | format date "%Y-%m-%d %H:%M:%S"
Format the current date using a given format string.
> date now | format date "%Y-%m-%d %H:%M:%S"
Format a given date using a given format string.
> "2021-10-22 20:00:12 +01:00" | format date "%Y-%m-%d"
2021-10-22
format duration
Outputs duration with a specified unit of time.
Search terms: convert, display, pattern, human readable
Usage:
> format duration <format value> ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
format value <string>: The unit in which to display the duration.
...rest <cell-path>: For a data structure input, format duration at the given cell paths.
Input/output types:
╭───┬────────────────┬──────────────╮
│ # │ input │ output │
├───┼────────────────┼──────────────┤
│ 0 │ duration │ string │
│ 1 │ list<duration> │ list<string> │
│ 2 │ table │ table │
╰───┴────────────────┴──────────────╯
Examples:
Convert µs duration to the requested second duration as a string
> 1000000µs | format duration sec
1 sec
Convert durations to µs duration as strings
> [1sec 2sec] | format duration µs
╭───┬────────────╮
│ 0 │ 1000000 µs │
│ 1 │ 2000000 µs │
╰───┴────────────╯
Convert duration to µs as a string if unit asked for was us
> 1sec | format duration us
1000000 µs
format filesize
Converts a column of filesizes to some specified format.
Search terms: convert, display, pattern, human readable
Usage:
> format filesize <format value> ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
format value <string>: The format into which convert the file sizes.
...rest <cell-path>: For a data structure input, format filesizes at the given cell paths.
Input/output types:
╭───┬──────────┬────────╮
│ # │ input │ output │
├───┼──────────┼────────┤
│ 0 │ filesize │ string │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴──────────┴────────╯
Examples:
Convert the size column to KB
> ls | format filesize KB size
Convert the apparent column to B
> du | format filesize B apparent
Convert the size data to MB
> 4Gb | format filesize MB
4000.0 MB
from
Parse a string or binary data into structured data.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> from
Subcommands:
from csv - Parse text as .csv and create table.
from json - Convert from json to structured data.
from nuon - Convert from nuon to structured data.
from ods - Parse OpenDocument Spreadsheet(.ods) data and create table.
from ssv - Parse text as space-separated values and create a table. The default minimum number of spaces counted as a separator is 2.
from toml - Parse text as .toml and create record.
from tsv - Parse text as .tsv and create table.
from xlsx - Parse binary Excel(.xlsx) data and create table.
from xml - Parse text as .xml and create record.
from yaml - Parse text as .yaml/.yml and create table.
from yml - Parse text as .yaml/.yml and create table.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
from csv
Parse text as .csv and create table.
Usage:
> from csv {flags}
Flags:
-h, --help - Display the help message for this command
-s, --separator <String> - a character to separate columns (either single char or 4 byte unicode sequence), defaults to ','
-c, --comment <String> - a comment character to ignore lines starting with it
-q, --quote <String> - a quote character to ignore separators in strings, defaults to '"'
-e, --escape <String> - an escape character for strings containing the quote character
-n, --noheaders - don't treat the first row as column names
--flexible - allow the number of fields in records to be variable
--no-infer - no field type inferencing
-t, --trim <String> - drop leading and trailing whitespaces around headers names and/or field values
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ table │
╰───┴────────┴────────╯
Examples:
Convert comma-separated data to a table
> "ColA,ColB
1,2" | from csv
╭───┬──────┬──────╮
│ # │ ColA │ ColB │
├───┼──────┼──────┤
│ 0 │ 1 │ 2 │
╰───┴──────┴──────╯
Convert comma-separated data to a table, ignoring headers
> open data.txt | from csv --noheaders
Convert semicolon-separated data to a table
> open data.txt | from csv --separator ';'
Convert comma-separated data to a table, ignoring lines starting with '#'
> open data.txt | from csv --comment '#'
Convert comma-separated data to a table, dropping all possible whitespaces around header names and field values
> open data.txt | from csv --trim all
Convert comma-separated data to a table, dropping all possible whitespaces around header names
> open data.txt | from csv --trim headers
Convert comma-separated data to a table, dropping all possible whitespaces around field values
> open data.txt | from csv --trim fields
from json
Convert from json to structured data.
Usage:
> from json {flags}
Flags:
-h, --help - Display the help message for this command
-o, --objects - treat each line as a separate value
-s, --strict - follow the json specification exactly
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ any │
╰───┴────────┴────────╯
Examples:
Converts json formatted string to table
> '{ "a": 1 }' | from json
╭───┬───╮
│ a │ 1 │
╰───┴───╯
Converts json formatted string to table
> '{ "a": 1, "b": [1, 2] }' | from json
╭───┬────────────────╮
│ a │ 1 │
│ b │ [list 2 items] │
╰───┴────────────────╯
Parse json strictly which will error on comments and trailing commas
> '{ "a": 1, "b": 2 }' | from json -s
╭───┬───╮
│ a │ 1 │
│ b │ 2 │
╰───┴───╯
from nuon
Convert from nuon to structured data.
Usage:
> from nuon
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ any │
╰───┴────────┴────────╯
Examples:
Converts nuon formatted string to table
> '{ a:1 }' | from nuon
╭───┬───╮
│ a │ 1 │
╰───┴───╯
Converts nuon formatted string to table
> '{ a:1, b: [1, 2] }' | from nuon
╭───┬────────────────╮
│ a │ 1 │
│ b │ [list 2 items] │
╰───┴────────────────╯
from ods
Parse OpenDocument Spreadsheet(.ods) data and create table.
Usage:
> from ods {flags}
Flags:
-h, --help - Display the help message for this command
-s, --sheets <List(String)> - Only convert specified sheets
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ table │
╰───┴────────┴────────╯
Examples:
Convert binary .ods data to a table
> open --raw test.ods | from ods
Convert binary .ods data to a table, specifying the tables
> open --raw test.ods | from ods --sheets [Spreadsheet1]
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 the help message for this command
-n, --noheaders - don't treat the first row as column names
-a, --aligned-columns - assume columns are aligned
-m, --minimum-spaces <Int> - the minimum spaces to separate columns
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ table │
╰───┴────────┴────────╯
Examples:
Converts ssv formatted string to table
> 'FOO BAR
1 2' | from ssv
╭───┬─────┬─────╮
│ # │ FOO │ BAR │
├───┼─────┼─────┤
│ 0 │ 1 │ 2 │
╰───┴─────┴─────╯
Converts ssv formatted string to table but not treating the first row as column names
> 'FOO BAR
1 2' | from ssv --noheaders
╭───┬─────────┬─────────╮
│ # │ column1 │ column2 │
├───┼─────────┼─────────┤
│ 0 │ FOO │ BAR │
│ 1 │ 1 │ 2 │
╰───┴─────────┴─────────╯
from toml
Parse text as .toml and create record.
Usage:
> from toml
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ record │
╰───┴────────┴────────╯
Examples:
Converts toml formatted string to record
> 'a = 1' | from toml
╭───┬───╮
│ a │ 1 │
╰───┴───╯
Converts toml formatted string to record
> 'a = 1
b = [1, 2]' | from toml
╭───┬────────────────╮
│ a │ 1 │
│ b │ [list 2 items] │
╰───┴────────────────╯
from tsv
Parse text as .tsv and create table.
Usage:
> from tsv {flags}
Flags:
-h, --help - Display the help message for this command
-c, --comment <String> - a comment character to ignore lines starting with it
-q, --quote <String> - a quote character to ignore separators in strings, defaults to '"'
-e, --escape <String> - an escape character for strings containing the quote character
-n, --noheaders - don't treat the first row as column names
--flexible - allow the number of fields in records to be variable
--no-infer - no field type inferencing
-t, --trim <String> - drop leading and trailing whitespaces around headers names and/or field values
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ table │
╰───┴────────┴────────╯
Examples:
Convert tab-separated data to a table
> "ColAColB
12" | from tsv
╭───┬──────┬──────╮
│ # │ ColA │ ColB │
├───┼──────┼──────┤
│ 0 │ 1 │ 2 │
╰───┴──────┴──────╯
Create a tsv file with header columns and open it
> $'c1(char tab)c2(char tab)c3(char nl)1(char tab)2(char tab)3' | save tsv-data | open tsv-data | from tsv
Create a tsv file without header columns and open it
> $'a1(char tab)b1(char tab)c1(char nl)a2(char tab)b2(char tab)c2' | save tsv-data | open tsv-data | from tsv --noheaders
Create a tsv file without header columns and open it, removing all unnecessary whitespaces
> $'a1(char tab)b1(char tab)c1(char nl)a2(char tab)b2(char tab)c2' | save tsv-data | open tsv-data | from tsv --trim all
Create a tsv file without header columns and open it, removing all unnecessary whitespaces in the header names
> $'a1(char tab)b1(char tab)c1(char nl)a2(char tab)b2(char tab)c2' | save tsv-data | open tsv-data | from tsv --trim headers
Create a tsv file without header columns and open it, removing all unnecessary whitespaces in the field values
> $'a1(char tab)b1(char tab)c1(char nl)a2(char tab)b2(char tab)c2' | save tsv-data | open tsv-data | from tsv --trim fields
from xlsx
Parse binary Excel(.xlsx) data and create table.
Usage:
> from xlsx {flags}
Flags:
-h, --help - Display the help message for this command
-s, --sheets <List(String)> - Only convert specified sheets
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ table │
╰───┴────────┴────────╯
Examples:
Convert binary .xlsx data to a table
> open --raw test.xlsx | from xlsx
Convert binary .xlsx data to a table, specifying the tables
> open --raw test.xlsx | from xlsx --sheets [Spreadsheet1]
from xml
Parse text as .xml and create record.
Every XML entry is represented via a record with tag, attribute and content fields.
To represent different types of entries different values are written to this fields:
1. Tag entry: `{tag: <tag name> attrs: {<attr name>: "<string value>" ...} content: [<entries>]}`
2. Comment entry: `{tag: '!' attrs: null content: "<comment string>"}`
3. Processing instruction (PI): `{tag: '?<pi name>' attrs: null content: "<pi content string>"}`
4. Text: `{tag: null attrs: null content: "<text>"}`.
Unlike to xml command all null values are always present and text is never represented via plain
string. This way content of every tag is always a table and is easier to parse
Usage:
> from xml {flags}
Flags:
-h, --help - Display the help message for this command
--keep-comments - add comment nodes to result
--keep-pi - add processing instruction nodes to result
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ record │
╰───┴────────┴────────╯
Examples:
Converts xml formatted string to record
> '<?xml version="1.0" encoding="UTF-8"?>
<note>
<remember>Event</remember>
</note>' | from xml
╭────────────┬───────────────────╮
│ tag │ note │
│ attributes │ {record 0 fields} │
│ content │ [table 1 row] │
╰────────────┴───────────────────╯
from yaml
Parse text as .yaml/.yml and create table.
Usage:
> from yaml
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ any │
╰───┴────────┴────────╯
Examples:
Converts yaml formatted string to table
> 'a: 1' | from yaml
╭───┬───╮
│ a │ 1 │
╰───┴───╯
Converts yaml formatted string to table
> '[ a: 1, b: [1, 2] ]' | from yaml
╭───┬────┬────────────────╮
│ # │ a │ b │
├───┼────┼────────────────┤
│ 0 │ 1 │ ❎ │
│ 1 │ ❎ │ [list 2 items] │
╰───┴────┴────────────────╯
from yml
Parse text as .yaml/.yml and create table.
Usage:
> from yml
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ any │
╰───┴────────┴────────╯
Examples:
Converts yaml formatted string to table
> 'a: 1' | from yaml
╭───┬───╮
│ a │ 1 │
╰───┴───╯
Converts yaml formatted string to table
> '[ a: 1, b: [1, 2] ]' | from yaml
╭───┬────┬────────────────╮
│ # │ a │ b │
├───┼────┼────────────────┤
│ 0 │ 1 │ ❎ │
│ 1 │ ❎ │ [list 2 items] │
╰───┴────┴────────────────╯
generate
Generate a list of values by successively invoking a closure.
The generator closure accepts a single argument and returns a record
containing two optional keys: 'out' and 'next'. Each invocation, the 'out'
value, if present, is added to the stream. If a 'next' key is present, it is
used as the next argument to the closure, otherwise generation stops.
Search terms: unfold, stream, yield, expand
Usage:
> generate <initial> <closure>
Flags:
-h, --help - Display the help message for this command
Parameters:
initial <any>: Initial value.
closure <closure(any)>: Generator function.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ nothing │ list<any> │
│ 1 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Generate a sequence of numbers
> generate 0 {|i| if $i <= 10 { {out: $i, next: ($i + 2)} }}
╭───┬────╮
│ 0 │ 0 │
│ 1 │ 2 │
│ 2 │ 4 │
│ 3 │ 6 │
│ 4 │ 8 │
│ 5 │ 10 │
╰───┴────╯
Generate a stream of fibonacci numbers
> generate [0, 1] {|fib| {out: $fib.0, next: [$fib.1, ($fib.0 + $fib.1)]} } | first 10
╭───┬────╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 1 │
│ 3 │ 2 │
│ 4 │ 3 │
│ 5 │ 5 │
│ 6 │ 8 │
│ 7 │ 13 │
│ 8 │ 21 │
│ 9 │ 34 │
╰───┴────╯
get
Extract data using a cell path.
This is equivalent to using the cell path access syntax: `$env.OS` is the same as `$env | get OS`.
If multiple cell paths are given, this will produce a list of values.
Usage:
> get {flags} <cell_path> ...(rest)
Flags:
-h, --help - Display the help message for this command
-i, --ignore-errors - ignore missing data (make all cell path members optional)
-s, --sensitive - get path in a case sensitive manner
Parameters:
cell_path <cell-path>: The cell path to the data.
...rest <cell-path>: Additional cell paths.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ any │
│ 1 │ table │ any │
│ 2 │ record │ any │
╰───┴───────────┴────────╯
Examples:
Get an item from a list
> [0 1 2] | get 1
1
Get a column from a table
> [{A: A0}] | get A
╭───┬────╮
│ 0 │ A0 │
╰───┴────╯
Get a cell from a table
> [{A: A0}] | get 0.A
A0
Extract the name of the 3rd record in a list (same as `ls | $in.name`)
> ls | get name.2
Extract the name of the 3rd record in a list
> ls | get 2.name
Extract the cpu list from the sys information record
> sys | get cpu
Getting Path/PATH in a case insensitive way
> $env | get paTH
Getting Path in a case sensitive way, won't work for 'PATH'
> $env | get --sensitive Path
glob
Creates a list of files and/or folders based on the glob pattern provided.
For more glob pattern help, please refer to https://docs.rs/crate/wax/latest
Search terms: pattern, files, folders, list, ls
Usage:
> glob {flags} <glob>
Flags:
-h, --help - Display the help message for this command
-d, --depth <Int> - directory depth to search
-D, --no-dir - Whether to filter out directories from the returned paths
-F, --no-file - Whether to filter out files from the returned paths
-S, --no-symlink - Whether to filter out symlinks from the returned paths
-e, --exclude <List(String)> - Patterns to exclude from the search: `glob` will not walk the inside of directories matching the excluded patterns.
Parameters:
glob <string>: The glob expression.
Input/output types:
╭───┬─────────┬──────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────┤
│ 0 │ nothing │ list<string> │
╰───┴─────────┴──────────────╯
Examples:
Search for *.rs files
> glob *.rs
Search for *.rs and *.toml files recursively up to 2 folders deep
> glob **/*.{rs,toml} --depth 2
Search for files and folders that begin with uppercase C or lowercase c
> glob "[Cc]*"
Search for files and folders like abc or xyz substituting a character for ?
> glob "{a?c,x?z}"
A case-insensitive search for files and folders that begin with c
> glob "(?i)c*"
Search for files for folders that do not begin with c, C, b, M, or s
> glob "[!cCbMs]*"
Search for files or folders with 3 a's in a row in the name
> glob <a*:3>
Search for files or folders with only a, b, c, or d in the file name between 1 and 10 times
> glob <[a-d]:1,10>
Search for folders that begin with an uppercase ASCII letter, ignoring files and symlinks
> glob "[A-Z]*" --no-file --no-symlink
Search for files named tsconfig.json that are not in node_modules directories
> glob **/tsconfig.json --exclude [**/node_modules/**]
Search for all files that are not in the target nor .git directories
> glob **/* --exclude [**/target/** **/.git/** */]
grid
Renders the output to a textual terminal grid.
grid was built to give a concise gridded layout for ls. however,
it determines what to put in the grid by looking for a column named
'name'. this works great for tables and records but for lists we
need to do something different. such as with '[one two three] | grid'
it creates a fake column called 'name' for these values so that it
prints out the list properly.
Usage:
> grid {flags}
Flags:
-h, --help - Display the help message for this command
-w, --width <Int> - number of terminal columns wide (not output columns)
-c, --color - draw output with color
-s, --separator <String> - character to separate grid with
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ string │
│ 1 │ record │ string │
╰───┴───────────┴────────╯
Examples:
Render a simple list to a grid
> [1 2 3 a b c] | grid
1 │ 2 │ 3 │ a │ b │ c
The above example is the same as:
> [1 2 3 a b c] | wrap name | grid
1 │ 2 │ 3 │ a │ b │ c
Render a record to a grid
> {name: 'foo', b: 1, c: 2} | grid
foo
Render a list of records to a grid
> [{name: 'A', v: 1} {name: 'B', v: 2} {name: 'C', v: 3}] | grid
A │ B │ C
Render a table with 'name' column in it to a grid
> [[name patch]; [0.1.0 false] [0.1.1 true] [0.2.0 false]] | grid
0.1.0 │ 0.1.1 │ 0.2.0
group
Groups input into groups of `group_size`.
Usage:
> group <group_size>
Flags:
-h, --help - Display the help message for this command
Parameters:
group_size <int>: The size of each group.
Input/output types:
╭───┬───────────┬─────────────────╮
│ # │ input │ output │
├───┼───────────┼─────────────────┤
│ 0 │ list<any> │ list<list<any>> │
╰───┴───────────┴─────────────────╯
Examples:
Group the a list by pairs
> [1 2 3 4] | group 2
╭───┬────────────────╮
│ 0 │ [list 2 items] │
│ 1 │ [list 2 items] │
╰───┴────────────────╯
group-by
Splits a list or table into groups, and returns a record containing those groups.
Usage:
> group-by {flags} (grouper)
Flags:
-h, --help - Display the help message for this command
--to-table - Return a table with "groups" and "items" columns
Parameters:
grouper <one_of(cell-path, block, closure(), closure(any))>: The path to the column to group on. (optional)
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ any │
╰───┴───────────┴────────╯
Examples:
Group items by the "type" column's values
> ls | group-by type
Group items by the "foo" column's values, ignoring records without a "foo" column
> open cool.json | group-by foo?
Group using a block which is evaluated against each input value
> [foo.txt bar.csv baz.txt] | group-by { path parse | get extension }
╭─────┬────────────────╮
│ txt │ [list 2 items] │
│ csv │ [list 1 item] │
╰─────┴────────────────╯
You can also group by raw values by leaving out the argument
> ['1' '3' '1' '3' '2' '1' '1'] | group-by
╭───┬────────────────╮
│ 1 │ [list 4 items] │
│ 3 │ [list 2 items] │
│ 2 │ [list 1 item] │
╰───┴────────────────╯
You can also output a table instead of a record
> ['1' '3' '1' '3' '2' '1' '1'] | group-by --to-table
╭───┬───────┬────────────────╮
│ # │ group │ items │
├───┼───────┼────────────────┤
│ 0 │ 1 │ [list 4 items] │
│ 1 │ 3 │ [list 2 items] │
│ 2 │ 2 │ [list 1 item] │
╰───┴───────┴────────────────╯
hash
Apply hash function.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> hash
Subcommands:
hash md5 - Hash a value using the md5 hash algorithm.
hash sha256 - Hash a value using the sha256 hash algorithm.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
hash md5
Hash a value using the md5 hash algorithm.
Usage:
> hash md5 {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-b, --binary - Output binary instead of hexadecimal representation
Parameters:
...rest <cell-path>: Optionally md5 hash data by cell path.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ any │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
Return the md5 hash of a string, hex-encoded
> 'abcdefghijklmnopqrstuvwxyz' | hash md5
c3fcd3d76192e4007dfb496cca67e13b
Return the md5 hash of a string, as binary
> 'abcdefghijklmnopqrstuvwxyz' | hash md5 --binary
[195, 252, 211, 215, 97, 146, 228, 0, 125, 251, 73, 108, 202, 103, 225, 59]
Return the md5 hash of a file's contents
> open ./nu_0_24_1_windows.zip | hash md5
hash sha256
Hash a value using the sha256 hash algorithm.
Usage:
> hash sha256 {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-b, --binary - Output binary instead of hexadecimal representation
Parameters:
...rest <cell-path>: Optionally sha256 hash data by cell path.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ any │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
Return the sha256 hash of a string, hex-encoded
> 'abcdefghijklmnopqrstuvwxyz' | hash sha256
71c480df93d6ae2f1efad1447c66c9525e316218cf51fc8d9ed832f2daf18b73
Return the sha256 hash of a string, as binary
> 'abcdefghijklmnopqrstuvwxyz' | hash sha256 --binary
[113, 196, 128, 223, 147, 214, 174, 47, 30, 250, 209, 68, 124, 102, 201, 82, 94, 49, 98, 24, 207, 81, 252, 141, 158, 216, 50, 242, 218, 241, 139, 115]
Return the sha256 hash of a file's contents
> open ./nu_0_24_1_windows.zip | hash sha256
headers
Use the first row of the table as column names.
Usage:
> headers
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ table │ table │
│ 1 │ list<any> │ table │
╰───┴───────────┴────────╯
Examples:
Sets the column names for a table created by `split column`
> "a b c|1 2 3" | split row "|" | split column " " | headers
╭───┬───┬───┬───╮
│ # │ a │ b │ c │
├───┼───┼───┼───┤
│ 0 │ 1 │ 2 │ 3 │
╰───┴───┴───┴───╯
Columns which don't have data in their first row are removed
> "a b c|1 2 3|1 2 3 4" | split row "|" | split column " " | headers
╭───┬───┬───┬───╮
│ # │ a │ b │ c │
├───┼───┼───┼───┤
│ 0 │ 1 │ 2 │ 3 │
│ 1 │ 1 │ 2 │ 3 │
╰───┴───┴───┴───╯
help
Display help information about different parts of Nushell.
`help word` searches for "word" in commands, aliases and modules, in that order.
Usage:
> help {flags} ...(rest)
Subcommands:
help aliases - Show help on nushell aliases.
help commands - Show help on nushell commands.
help escapes - Show help on nushell string escapes.
help externs - Show help on nushell externs.
help modules - Show help on nushell modules.
help operators - Show help on nushell operators.
Flags:
-h, --help - Display the help message for this command
-f, --find <String> - string to find in command names, usage, and search terms
Parameters:
...rest <string>: The name of command, alias or module to get help on.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
show help for single command, alias, or module
> help match
show help for single sub-command, alias, or module
> help str lpad
search for string in command names, usage and search terms
> help --find char
help aliases
Show help on nushell aliases.
Usage:
> help aliases {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-f, --find <String> - string to find in alias names and usage
Parameters:
...rest <string>: The name of alias to get help on.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
show all aliases
> help aliases
show help for single alias
> help aliases my-alias
search for string in alias names and usages
> help aliases --find my-alias
help commands
Show help on nushell commands.
Usage:
> help commands {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-f, --find <String> - string to find in command names, usage, and search terms
Parameters:
...rest <string>: The name of command to get help on.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
help escapes
Show help on nushell string escapes.
Usage:
> help escapes
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
help externs
Show help on nushell externs.
Usage:
> help externs {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-f, --find <String> - string to find in extern names and usage
Parameters:
...rest <string>: The name of extern to get help on.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
show all externs
> help externs
show help for single extern
> help externs smth
search for string in extern names and usages
> help externs --find smth
help modules
Show help on nushell modules.
When requesting help for a single module, its commands and aliases will be highlighted if they
are also available in the current scope. Commands/aliases that were imported under a different name
(such as with a prefix after `use some-module`) will be highlighted in parentheses.
Usage:
> help modules {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-f, --find <String> - string to find in module names and usage
Parameters:
...rest <string>: The name of module to get help on.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
show all modules
> help modules
show help for single module
> help modules my-module
search for string in module names and usages
> help modules --find my-module
help operators
Show help on nushell operators.
Usage:
> help operators
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
hide
Hide definitions in the current scope.
Definitions are hidden by priority: First aliases, then custom commands.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> hide <module> (members)
Flags:
-h, --help - Display the help message for this command
Parameters:
module <string>: Module or module file.
members <any>: Which members of the module to import. (optional)
Examples:
Hide the alias just defined
> alias lll = ls -l; hide lll
Hide a custom command
> def say-hi [] { echo 'Hi!' }; hide say-hi
hide-env
Hide environment variables in the current scope.
Usage:
> hide-env {flags} ...(name)
Flags:
-h, --help - Display the help message for this command
-i, --ignore-errors - do not throw an error if an environment variable was not found
Parameters:
...name <string>: Environment variable names to hide.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Hide an environment variable
> $env.HZ_ENV_ABC = 1; hide-env HZ_ENV_ABC; 'HZ_ENV_ABC' in (env).name
false
histogram
Creates a new table with a histogram based on the column name passed in.
Usage:
> histogram {flags} (column-name) (frequency-column-name)
Flags:
-h, --help - Display the help message for this command
-t, --percentage-type <String> - percentage calculate method, can be 'normalize' or 'relative', in 'normalize', defaults to be 'normalize'
Parameters:
column-name <string>: Column name to calc frequency, no need to provide if input is a list. (optional)
frequency-column-name <string>: Histogram's frequency column, default to be frequency column output. (optional)
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ table │
╰───┴───────────┴────────╯
Examples:
Compute a histogram of file types
> ls | histogram type
Compute a histogram for the types of files, with frequency column named freq
> ls | histogram type freq
Compute a histogram for a list of numbers
> [1 2 1] | histogram
╭───┬───────┬───────┬──────────┬────────────┬────────────────────────────────────────────────────────────────────╮
│ # │ value │ count │ quantile │ percentage │ frequency │
├───┼───────┼───────┼──────────┼────────────┼────────────────────────────────────────────────────────────────────┤
│ 0 │ 1 │ 2 │ 0.67 │ 66.67% │ ****************************************************************** │
│ 1 │ 2 │ 1 │ 0.33 │ 33.33% │ ********************************* │
╰───┴───────┴───────┴──────────┴────────────┴────────────────────────────────────────────────────────────────────╯
Compute a histogram for a list of numbers, and percentage is based on the maximum value
> [1 2 3 1 1 1 2 2 1 1] | histogram --percentage-type relative
history
Get the command history.
Usage:
> history {flags}
Subcommands:
history session - Get the command history session.
Flags:
-h, --help - Display the help message for this command
-c, --clear - Clears out the history entries
-l, --long - Show long listing of entries for sqlite history
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Get current history length
> history | length
Show last 5 commands you have ran
> history | last 5
Search all the commands from history that contains 'cargo'
> history | where command =~ cargo | get command
history session
Get the command history session.
Usage:
> history session
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ int │
╰───┴─────────┴────────╯
Examples:
Get current history session
> history session
http
Various commands for working with http methods.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Search terms: network, fetch, pull, request, download, curl, wget
Usage:
> http
Subcommands:
http delete - Delete the specified resource.
http get - Fetch the contents from a URL.
http head - Get the headers from a URL.
http options - Requests permitted communication options for a given URL.
http patch - Patch a body to a URL.
http post - Post a body to a URL.
http put - Put a body to a URL.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
http delete
Delete the specified resource.
Performs HTTP DELETE operation.
Search terms: network, request, curl, wget
Usage:
> http delete {flags} <URL>
Flags:
-h, --help - Display the help message for this command
-u, --user <Any> - the username when authenticating
-p, --password <Any> - the password when authenticating
-d, --data <Any> - the content to post
-t, --content-type <Any> - the MIME type of content to post
-m, --max-time <Int> - timeout period in seconds
-H, --headers <Any> - custom headers you want to add
-r, --raw - fetch contents as text rather than a table
-k, --insecure - allow insecure server connections when using SSL
-f, --full - returns the full response instead of only the body
-e, --allow-errors - do not fail if the server returns an error code
-R, --redirect-mode <String> - What to do when encountering redirects. Default: 'follow'. Valid options: 'follow' ('f'), 'manual' ('m'), 'error' ('e').
Parameters:
URL <string>: The URL to fetch the contents from.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
http delete from example.com
> http delete https://www.example.com
http delete from example.com, with username and password
> http delete --user myuser --password mypass https://www.example.com
http delete from example.com, with custom header
> http delete --headers [my-header-key my-header-value] https://www.example.com
http delete from example.com, with body
> http delete --data 'body' https://www.example.com
http delete from example.com, with JSON body
> http delete --content-type application/json --data { field: value } https://www.example.com
http get
Fetch the contents from a URL.
Performs HTTP GET operation.
Search terms: network, fetch, pull, request, download, curl, wget
Usage:
> http get {flags} <URL>
Flags:
-h, --help - Display the help message for this command
-u, --user <Any> - the username when authenticating
-p, --password <Any> - the password when authenticating
-m, --max-time <Int> - timeout period in seconds
-H, --headers <Any> - custom headers you want to add
-r, --raw - fetch contents as text rather than a table
-k, --insecure - allow insecure server connections when using SSL
-f, --full - returns the full response instead of only the body
-e, --allow-errors - do not fail if the server returns an error code
-R, --redirect-mode <String> - What to do when encountering redirects. Default: 'follow'. Valid options: 'follow' ('f'), 'manual' ('m'), 'error' ('e').
Parameters:
URL <string>: The URL to fetch the contents from.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Get content from example.com
> http get https://www.example.com
Get content from example.com, with username and password
> http get --user myuser --password mypass https://www.example.com
Get content from example.com, with custom header
> http get --headers [my-header-key my-header-value] https://www.example.com
Get content from example.com, with custom headers
> http get --headers [my-header-key-A my-header-value-A my-header-key-B my-header-value-B] https://www.example.com
http head
Get the headers from a URL.
Performs HTTP HEAD operation.
Search terms: network, request, curl, wget, headers, header
Usage:
> http head {flags} <URL>
Flags:
-h, --help - Display the help message for this command
-u, --user <Any> - the username when authenticating
-p, --password <Any> - the password when authenticating
-m, --max-time <Int> - timeout period in seconds
-H, --headers <Any> - custom headers you want to add
-k, --insecure - allow insecure server connections when using SSL
-R, --redirect-mode <String> - What to do when encountering redirects. Default: 'follow'. Valid options: 'follow' ('f'), 'manual' ('m'), 'error' ('e').
Parameters:
URL <string>: The URL to fetch the contents from.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Get headers from example.com
> http head https://www.example.com
Get headers from example.com, with username and password
> http head --user myuser --password mypass https://www.example.com
Get headers from example.com, with custom header
> http head --headers [my-header-key my-header-value] https://www.example.com
http options
Requests permitted communication options for a given URL.
Performs an HTTP OPTIONS request. Most commonly used for making CORS preflight requests.
Search terms: network, fetch, pull, request, curl, wget
Usage:
> http options {flags} <URL>
Flags:
-h, --help - Display the help message for this command
-u, --user <Any> - the username when authenticating
-p, --password <Any> - the password when authenticating
-m, --max-time <Int> - timeout period in seconds
-H, --headers <Any> - custom headers you want to add
-k, --insecure - allow insecure server connections when using SSL
-e, --allow-errors - do not fail if the server returns an error code
Parameters:
URL <string>: The URL to fetch the options from.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Get options from example.com
> http options https://www.example.com
Get options from example.com, with username and password
> http options --user myuser --password mypass https://www.example.com
Get options from example.com, with custom header
> http options --headers [my-header-key my-header-value] https://www.example.com
Get options from example.com, with custom headers
> http options --headers [my-header-key-A my-header-value-A my-header-key-B my-header-value-B] https://www.example.com
Simulate a browser cross-origin preflight request from www.example.com to media.example.com
> http options https://media.example.com/api/ --headers [Origin https://www.example.com Access-Control-Request-Headers "Content-Type, X-Custom-Header" Access-Control-Request-Method GET]
http patch
Patch a body to a URL.
Performs HTTP PATCH operation.
Search terms: network, send, push
Usage:
> http patch {flags} <URL> <data>
Flags:
-h, --help - Display the help message for this command
-u, --user <Any> - the username when authenticating
-p, --password <Any> - the password when authenticating
-t, --content-type <Any> - the MIME type of content to post
-m, --max-time <Int> - timeout period in seconds
-H, --headers <Any> - custom headers you want to add
-r, --raw - return values as a string instead of a table
-k, --insecure - allow insecure server connections when using SSL
-f, --full - returns the full response instead of only the body
-e, --allow-errors - do not fail if the server returns an error code
-R, --redirect-mode <String> - What to do when encountering redirects. Default: 'follow'. Valid options: 'follow' ('f'), 'manual' ('m'), 'error' ('e').
Parameters:
URL <string>: The URL to post to.
data <any>: The contents of the post body.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Patch content to example.com
> http patch https://www.example.com 'body'
Patch content to example.com, with username and password
> http patch --user myuser --password mypass https://www.example.com 'body'
Patch content to example.com, with custom header
> http patch --headers [my-header-key my-header-value] https://www.example.com
Patch content to example.com, with JSON body
> http patch --content-type application/json https://www.example.com { field: value }
http post
Post a body to a URL.
Performs HTTP POST operation.
Search terms: network, send, push
Usage:
> http post {flags} <URL> <data>
Flags:
-h, --help - Display the help message for this command
-u, --user <Any> - the username when authenticating
-p, --password <Any> - the password when authenticating
-t, --content-type <Any> - the MIME type of content to post
-m, --max-time <Int> - timeout period in seconds
-H, --headers <Any> - custom headers you want to add
-r, --raw - return values as a string instead of a table
-k, --insecure - allow insecure server connections when using SSL
-f, --full - returns the full response instead of only the body
-e, --allow-errors - do not fail if the server returns an error code
-R, --redirect-mode <String> - What to do when encountering redirects. Default: 'follow'. Valid options: 'follow' ('f'), 'manual' ('m'), 'error' ('e').
Parameters:
URL <string>: The URL to post to.
data <any>: The contents of the post body.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Post content to example.com
> http post https://www.example.com 'body'
Post content to example.com, with username and password
> http post --user myuser --password mypass https://www.example.com 'body'
Post content to example.com, with custom header
> http post --headers [my-header-key my-header-value] https://www.example.com
Post content to example.com, with JSON body
> http post --content-type application/json https://www.example.com { field: value }
http put
Put a body to a URL.
Performs HTTP PUT operation.
Search terms: network, send, push
Usage:
> http put {flags} <URL> <data>
Flags:
-h, --help - Display the help message for this command
-u, --user <Any> - the username when authenticating
-p, --password <Any> - the password when authenticating
-t, --content-type <Any> - the MIME type of content to post
-m, --max-time <Int> - timeout period in seconds
-H, --headers <Any> - custom headers you want to add
-r, --raw - return values as a string instead of a table
-k, --insecure - allow insecure server connections when using SSL
-f, --full - returns the full response instead of only the body
-e, --allow-errors - do not fail if the server returns an error code
-R, --redirect-mode <String> - What to do when encountering redirects. Default: 'follow'. Valid options: 'follow' ('f'), 'manual' ('m'), 'error' ('e').
Parameters:
URL <string>: The URL to post to.
data <any>: The contents of the post body.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Put content to example.com
> http put https://www.example.com 'body'
Put content to example.com, with username and password
> http put --user myuser --password mypass https://www.example.com 'body'
Put content to example.com, with custom header
> http put --headers [my-header-key my-header-value] https://www.example.com
Put content to example.com, with JSON body
> http put --content-type application/json https://www.example.com { field: value }
if
Conditionally run a block.
Usage:
> if <cond> <then_block> (else <else_expression>)
Flags:
-h, --help - Display the help message for this command
Parameters:
cond <variable>: Condition to check.
then_block <block>: Block to run if check succeeds.
"else" + <one_of(block, expression)>: Expression or block to run when the condition is false. (optional)
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Output a value if a condition matches, otherwise return nothing
> if 2 < 3 { 'yes!' }
yes!
Output a value if a condition matches, else return another value
> if 5 < 3 { 'yes!' } else { 'no!' }
no!
Chain multiple if's together
> if 5 < 3 { 'yes!' } else if 4 < 5 { 'no!' } else { 'okay!' }
no!
ignore
Ignore the output of the previous command in the pipeline.
Search terms: silent, quiet, out-null
Usage:
> ignore
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────┬─────────╮
│ # │ input │ output │
├───┼───────┼─────────┤
│ 0 │ any │ nothing │
╰───┴───────┴─────────╯
Examples:
Ignore the output of an echo command
> echo done | ignore
input
Get input from the user.
Search terms: prompt, interactive
Usage:
> input {flags} (prompt)
Subcommands:
input list - Interactive list selection.
input listen - Listen for user interface event.
Flags:
-h, --help - Display the help message for this command
-u, --bytes-until-any <String> - read bytes (not text) until any of the given stop bytes is seen
-n, --numchar <Int> - number of characters to read; suppresses output
-s, --suppress-output - don't print keystroke values
Parameters:
prompt <string>: Prompt to show the user. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Get input from the user, and assign to a variable
> let user_input = (input)
Get two characters from the user, and assign to a variable
> let user_input = (input --numchar 2)
input list
Interactive list selection.
Abort with esc or q.
Search terms: prompt, ask, menu
Usage:
> input list {flags} (prompt)
Flags:
-h, --help - Display the help message for this command
-m, --multi - Use multiple results, you can press a to toggle all options on/off
-f, --fuzzy - Use a fuzzy select.
-i, --index - Returns list indexes.
-d, --display <CellPath> - Field to use as display value
Parameters:
prompt <string>: The prompt to display. (optional)
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ any │
│ 1 │ range │ int │
╰───┴───────────┴────────╯
Examples:
Return a single value from a list
> [1 2 3 4 5] | input list 'Rate it'
Return multiple values from a list
> [Banana Kiwi Pear Peach Strawberry] | input list --multi 'Add fruits to the basket'
Return a single record from a table with fuzzy search
> ls | input list --fuzzy 'Select the target'
Choose an item from a range
> 1..10 | input list
Return the index of a selected item
> [Banana Kiwi Pear Peach Strawberry] | input list --index
Choose an item from a table using a column as display value
> [[name price]; [Banana 12] [Kiwi 4] [Pear 7]] | input list -d name
input listen
Listen for user interface event.
There are 5 different type of events: focus, key, mouse, paste, resize. Each will produce a
corresponding record, distinguished by type field:
{ type: focus event: (gained|lost) }
{ type: key key_type: <key_type> code: <string> modifiers: [ <modifier> ... ] }
{ type: mouse col: <int> row: <int> kind: <string> modifiers: [ <modifier> ... ] }
{ type: paste content: <string> }
{ type: resize col: <int> row: <int> }
There are 6 `modifier` variants: shift, control, alt, super, hyper, meta.
There are 4 `key_type` variants:
f - f1, f2, f3 ... keys
char - alphanumeric and special symbols (a, A, 1, $ ...)
media - dedicated media keys (play, pause, tracknext ...)
other - keys not falling under previous categories (up, down, backspace, enter ...)
Search terms: prompt, interactive, keycode
Usage:
> input listen {flags}
Flags:
-h, --help - Display the help message for this command
-t, --types <List(String)> - Listen for event of specified types only (can be one of: focus, key, mouse, paste, resize)
-r, --raw - Add raw_code field with numeric value of keycode and raw_flags with bit mask flags
Input/output types:
╭───┬─────────┬──────────────────────────────────────────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────────────────────────────────────────┤
│ 0 │ nothing │ record<keycode: string, modifiers: list<string>> │
╰───┴─────────┴──────────────────────────────────────────────────╯
Examples:
Listen for a keyboard shortcut and find out how nu receives it
> input listen --types [key]
insert
Insert a new column, using an expression or closure to create each row's values.
Search terms: add
Usage:
> insert <field> <new value>
Flags:
-h, --help - Display the help message for this command
Parameters:
field <cell-path>: The name of the column to insert.
new value <any>: The new value to give the cell(s).
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
│ 2 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Insert a new entry into a single record
> {'name': 'nu', 'stars': 5} | insert alias 'Nushell'
╭───────┬─────────╮
│ name │ nu │
│ stars │ 5 │
│ alias │ Nushell │
╰───────┴─────────╯
Insert a new column into a table, populating all rows
> [[project, lang]; ['Nushell', 'Rust']] | insert type 'shell'
╭───┬─────────┬──────┬───────╮
│ # │ project │ lang │ type │
├───┼─────────┼──────┼───────┤
│ 0 │ Nushell │ Rust │ shell │
╰───┴─────────┴──────┴───────╯
Insert a new column with values computed based off the other columns
> [[foo]; [7] [8] [9]] | insert bar {|row| $row.foo * 2 }
╭───┬─────┬─────╮
│ # │ foo │ bar │
├───┼─────┼─────┤
│ 0 │ 7 │ 14 │
│ 1 │ 8 │ 16 │
│ 2 │ 9 │ 18 │
╰───┴─────┴─────╯
Insert a new value into a list at an index
> [1 2 4] | insert 2 3
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
│ 3 │ 4 │
╰───┴───╯
Insert a new value at the end of a list
> [1 2 3] | insert 3 4
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
│ 3 │ 4 │
╰───┴───╯
inspect
Inspect pipeline results while running a pipeline.
Usage:
> inspect
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Inspect pipeline results
> ls | inspect | get name | inspect
interleave
Read multiple streams in parallel and combine them into one stream.
This combinator is useful for reading output from multiple commands.
If input is provided to `interleave`, the input will be combined with the
output of the closures. This enables `interleave` to be used at any position
within a pipeline.
Because items from each stream will be inserted into the final stream as soon
as they are available, there is no guarantee of how the final output will be
ordered. However, the order of items from any given stream is guaranteed to be
preserved as they were in that stream.
If interleaving streams in a fair (round-robin) manner is desired, consider
using `zip { ... } | flatten` instead.
Usage:
> interleave {flags} ...(closures)
Flags:
-h, --help - Display the help message for this command
-b, --buffer-size <Int> - Number of items to buffer from the streams. Increases memory usage, but can help performance when lots of output is produced.
Parameters:
...closures <closure()>: The closures that will generate streams to be combined.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
│ 1 │ nothing │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Read two sequences of numbers into separate columns of a table.
Note that the order of rows with 'a' columns and rows with 'b' columns is arbitrary.
> seq 1 50 | wrap a | interleave { seq 1 50 | wrap b }
Read two sequences of numbers, one from input. Sort for consistency.
> seq 1 3 | interleave { seq 4 6 } | sort
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
│ 3 │ 4 │
│ 4 │ 5 │
│ 5 │ 6 │
╰───┴───╯
Read two sequences, but without any input. Sort for consistency.
> interleave { "foo\nbar\n" | lines } { "baz\nquux\n" | lines } | sort
╭───┬──────╮
│ 0 │ bar │
│ 1 │ baz │
│ 2 │ foo │
│ 3 │ quux │
╰───┴──────╯
Run two commands in parallel and annotate their output.
> (
interleave
{ nu -c "print hello; print world" | lines | each { "greeter: " ++ $in } }
{ nu -c "print nushell; print rocks" | lines | each { "evangelist: " ++ $in } }
)
Use a buffer to increase the performance of high-volume streams.
> seq 1 20000 | interleave --buffer-size 16 { seq 1 20000 } | math sum
into
Commands to convert data from one type to another.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> into
Subcommands:
into binary - Convert value to a binary primitive.
into bool - Convert value to boolean.
into cell-path - Convert value to a cell-path.
into datetime - Convert text or timestamp into a datetime.
into duration - Convert value to duration.
into filesize - Convert value to filesize.
into float - Convert data into floating point number.
into glob - Convert value to glob.
into int - Convert value to integer.
into record - Convert value to record.
into sqlite - Convert table into a SQLite database.
into string - Convert value to string.
into value - Infer nushell datatype for each cell.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
into binary
Convert value to a binary primitive.
Search terms: convert, bytes
Usage:
> into binary {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-c, --compact - output without padding zeros
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭───┬──────────┬────────╮
│ # │ input │ output │
├───┼──────────┼────────┤
│ 0 │ binary │ binary │
│ 1 │ int │ binary │
│ 2 │ number │ binary │
│ 3 │ string │ binary │
│ 4 │ bool │ binary │
│ 5 │ filesize │ binary │
│ 6 │ date │ binary │
│ 7 │ table │ table │
│ 8 │ record │ record │
╰───┴──────────┴────────╯
Examples:
convert string to a nushell binary primitive
> 'This is a string that is exactly 52 characters long.' | into binary
This is a string that is exactly 52 characters long.
convert a number to a nushell binary primitive
> 1 | into binary
convert a boolean to a nushell binary primitive
> 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 float to a nushell binary primitive
> 1.234 | into binary
[88, 57, 180, 200, 118, 190, 243, 63]
convert an int to a nushell binary primitive with compact enabled
> 10 | into binary --compact
into bool
Convert value to boolean.
Search terms: convert, boolean, true, false, 1, 0
Usage:
> into bool ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ int │ bool │
│ 1 │ number │ bool │
│ 2 │ string │ bool │
│ 3 │ bool │ bool │
│ 4 │ list<any> │ table │
│ 5 │ table │ table │
│ 6 │ record │ record │
╰───┴───────────┴────────╯
Examples:
Convert value to boolean in table
> [[value]; ['false'] ['1'] [0] [1.0] [true]] | into bool value
╭───┬───────╮
│ # │ value │
├───┼───────┤
│ 0 │ false │
│ 1 │ true │
│ 2 │ false │
│ 3 │ true │
│ 4 │ true │
╰───┴───────╯
Convert bool to boolean
> true | into bool
true
convert int to boolean
> 1 | into bool
true
convert float to boolean
> 0.3 | into bool
true
convert float string to boolean
> '0.0' | into bool
false
convert string to boolean
> 'true' | into bool
true
into cell-path
Convert value to a cell-path.
Converting a string directly into a cell path is intentionally not supported.
Search terms: convert
Usage:
> into cell-path
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬──────────────────────────────────────────┬───────────╮
│ # │ input │ output │
├───┼──────────────────────────────────────────┼───────────┤
│ 0 │ int │ cell-path │
│ 1 │ list<any> │ cell-path │
│ 2 │ list<record<value: any, optional: bool>> │ cell-path │
╰───┴──────────────────────────────────────────┴───────────╯
Examples:
Convert integer into cell path
> 5 | into cell-path
5
Convert string into cell path
> 'some.path' | split row '.' | into cell-path
some.path
Convert list into cell path
> [5 c 7 h] | into cell-path
5.c.7.h
Convert table into cell path
> [[value, optional]; [5 true] [c false]] | into cell-path
5.c
into datetime
Convert text or timestamp into a datetime.
Search terms: convert, timezone, UTC
Usage:
> into datetime {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-z, --timezone <String> - Specify timezone if the input is a Unix timestamp. Valid options: 'UTC' ('u') or 'LOCAL' ('l')
-o, --offset <Int> - Specify timezone by offset from UTC if the input is a Unix timestamp, like '+8', '-4'
-f, --format <String> - Specify expected format of INPUT string to parse to datetime. Use --list to see options
-l, --list - Show all possible variables for use in --format flag
-n, --list-human - Show human-readable datetime parsing examples
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭───┬──────────────┬────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────┤
│ 0 │ int │ date │
│ 1 │ string │ date │
│ 2 │ list<string> │ list<date> │
│ 3 │ table │ table │
│ 4 │ record │ record │
╰───┴──────────────┴────────────╯
Examples:
Convert any standard timestamp string to datetime
> '27.02.2021 1:55 pm +0000' | into datetime
Sat, 27 Feb 2021 13:55:00 +0000 (3 years ago)
Convert any standard timestamp string to datetime
> '2021-02-27T13:55:40.2246+00:00' | into datetime
Sat, 27 Feb 2021 13:55:40 +0000 (3 years ago)
Convert non-standard timestamp string to datetime using a custom format
> '20210227_135540+0000' | into datetime --format '%Y%m%d_%H%M%S%z'
Sat, 27 Feb 2021 13:55:40 +0000 (3 years ago)
Convert nanosecond-precision unix timestamp to a datetime with offset from UTC
> 1614434140123456789 | into datetime --offset -5
Sat, 27 Feb 2021 13:55:40 +0000 (3 years ago)
Convert standard (seconds) unix timestamp to a UTC datetime
> 1614434140 * 1_000_000_000 | into datetime
Sat, 27 Feb 2021 13:55:40 +0000 (3 years ago)
Convert list of timestamps to datetimes
> ["2023-03-30 10:10:07 -05:00", "2023-05-05 13:43:49 -05:00", "2023-06-05 01:37:42 -05:00"] | into datetime
╭───┬───────────────╮
│ 0 │ a year ago │
│ 1 │ 11 months ago │
│ 2 │ 10 months ago │
╰───┴───────────────╯
Parsing human readable datetimes
> 'Today at 18:30' | into datetime
Parsing human readable datetimes
> 'Last Friday at 19:45' | into datetime
Parsing human readable datetimes
> 'In 5 minutes and 30 seconds' | into datetime
into duration
Convert value to duration.
Max duration value is i64::MAX nanoseconds; max duration time unit is wk (weeks).
Search terms: convert, time, period
Usage:
> into duration {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-u, --unit <String> - Unit to convert number into (will have an effect only with integer input)
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭───┬──────────┬──────────╮
│ # │ input │ output │
├───┼──────────┼──────────┤
│ 0 │ int │ duration │
│ 1 │ string │ duration │
│ 2 │ duration │ duration │
│ 3 │ table │ table │
╰───┴──────────┴──────────╯
Examples:
Convert duration string to duration value
> '7min' | into duration
7min
Convert compound duration string to duration value
> '1day 2hr 3min 4sec' | into duration
1day 2hr 3min 4sec
Convert table of duration strings to table of duration values
> [[value]; ['1sec'] ['2min'] ['3hr'] ['4day'] ['5wk']] | into duration value
╭───┬───────╮
│ # │ value │
├───┼───────┤
│ 0 │ 1sec │
│ 1 │ 2min │
│ 2 │ 3hr │
│ 3 │ 4day │
│ 4 │ 5wk │
╰───┴───────╯
Convert duration to duration
> 420sec | into duration
7min
Convert a number of ns to duration
> 1_234_567 | into duration
1ms 234µs 567ns
Convert a number of an arbitrary unit to duration
> 1_234 | into duration --unit ms
1sec 234ms
into filesize
Convert value to filesize.
Search terms: convert, number, bytes
Usage:
> into filesize ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭────┬────────────────┬────────────────╮
│ # │ input │ output │
├────┼────────────────┼────────────────┤
│ 0 │ int │ filesize │
│ 1 │ number │ filesize │
│ 2 │ string │ filesize │
│ 3 │ filesize │ filesize │
│ 4 │ table │ table │
│ 5 │ record │ record │
│ 6 │ list<int> │ list<filesize> │
│ 7 │ list<number> │ list<filesize> │
│ 8 │ list<string> │ list<filesize> │
│ 9 │ list<filesize> │ list<filesize> │
│ 10 │ list<any> │ list<filesize> │
╰────┴────────────────┴────────────────╯
Examples:
Convert string to filesize in table
> [[device size]; ["/dev/sda1" "200"] ["/dev/loop0" "50"]] | into filesize size
╭───┬────────────┬───────╮
│ # │ device │ size │
├───┼────────────┼───────┤
│ 0 │ /dev/sda1 │ 200 B │
│ 1 │ /dev/loop0 │ 50 B │
╰───┴────────────┴───────╯
Convert string to filesize
> '2' | into filesize
2 B
Convert float to filesize
> 8.3 | into filesize
8 B
Convert int to filesize
> 5 | into filesize
5 B
Convert file size to filesize
> 4KB | into filesize
4.0 KB
into float
Convert data into floating point number.
Search terms: convert, number, floating, decimal
Usage:
> into float ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭───┬───────────┬─────────────╮
│ # │ input │ output │
├───┼───────────┼─────────────┤
│ 0 │ int │ float │
│ 1 │ string │ float │
│ 2 │ bool │ float │
│ 3 │ float │ float │
│ 4 │ table │ table │
│ 5 │ record │ record │
│ 6 │ list<any> │ list<float> │
╰───┴───────────┴─────────────╯
Examples:
Convert string to float in table
> [[num]; ['5.01']] | into float num
╭───┬──────╮
│ # │ num │
├───┼──────┤
│ 0 │ 5.01 │
╰───┴──────╯
Convert string to floating point number
> '1.345' | into float
1.345
Coerce list of ints and floats to float
> [4 -5.9] | into float
╭───┬───────╮
│ 0 │ 4.00 │
│ 1 │ -5.90 │
╰───┴───────╯
Convert boolean to float
> true | into float
1
into glob
Convert value to glob.
Search terms: convert, text
Usage:
> into glob ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭───┬──────────────┬────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────┤
│ 0 │ string │ glob │
│ 1 │ list<string> │ list<glob> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴────────────╯
Examples:
convert string to glob
> '1234' | into glob
1234
convert filepath to glob
> ls Cargo.toml | get name | into glob
into int
Convert value to integer.
Search terms: convert, number, natural
Usage:
> into int {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-r, --radix <Number> - radix of integer
-e, --endian <String> - byte encode endian, available options: native(default), little, big
-s, --signed - always treat input number as a signed number
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭────┬────────────────┬───────────╮
│ # │ input │ output │
├────┼────────────────┼───────────┤
│ 0 │ string │ int │
│ 1 │ number │ int │
│ 2 │ bool │ int │
│ 3 │ date │ int │
│ 4 │ duration │ int │
│ 5 │ filesize │ int │
│ 6 │ binary │ int │
│ 7 │ table │ table │
│ 8 │ record │ record │
│ 9 │ list<string> │ list<int> │
│ 10 │ list<number> │ list<int> │
│ 11 │ list<bool> │ list<int> │
│ 12 │ list<date> │ list<int> │
│ 13 │ list<duration> │ list<int> │
│ 14 │ list<filesize> │ list<int> │
│ 15 │ list<any> │ list<int> │
╰────┴────────────────┴───────────╯
Examples:
Convert string to int in table
> [[num]; ['-5'] [4] [1.5]] | into int num
Convert string to int
> '2' | into int
2
Convert float to int
> 5.9 | into int
5
Convert decimal string to int
> '5.9' | into int
5
Convert file size to int
> 4KB | into int
4000
Convert bool to int
> [false, true] | into int
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
╰───┴───╯
Convert date to int (Unix nanosecond timestamp)
> 1983-04-13T12:09:14.123456789-05:00 | into int
419101754123456789
Convert to int from binary data (radix: 2)
> '1101' | into int --radix 2
13
Convert to int from hex
> 'FF' | into int --radix 16
255
Convert octal string to int
> '0o10132' | into int
4186
Convert 0 padded string to int
> '0010132' | into int
10132
Convert 0 padded string to int with radix 8
> '0010132' | into int --radix 8
4186
Convert binary value to int
> 0x[10] | into int
16
Convert binary value to signed int
> 0x[a0] | into int --signed
-96
into record
Convert value to record.
Search terms: convert
Usage:
> into record
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ date │ record │
│ 1 │ duration │ record │
│ 2 │ list<any> │ record │
│ 3 │ range │ record │
│ 4 │ record │ record │
╰───┴───────────┴────────╯
Examples:
Convert from one row table to record
> [[value]; [false]] | into record
╭───────┬───────╮
│ value │ false │
╰───────┴───────╯
Convert from list to record
> [1 2 3] | into record
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
╰───┴───╯
Convert from range to record
> 0..2 | into record
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
╰───┴───╯
convert duration to record (weeks max)
> (-500day - 4hr - 5sec) | into record
╭────────┬────╮
│ week │ 71 │
│ day │ 3 │
│ hour │ 4 │
│ second │ 5 │
│ sign │ - │
╰────────┴────╯
convert record to record
> {a: 1, b: 2} | into record
╭───┬───╮
│ a │ 1 │
│ b │ 2 │
╰───┴───╯
convert date to record
> 2020-04-12T22:10:57+02:00 | into record
╭──────────┬────────╮
│ year │ 2020 │
│ month │ 4 │
│ day │ 12 │
│ hour │ 22 │
│ minute │ 10 │
│ second │ 57 │
│ timezone │ +02:00 │
╰──────────┴────────╯
into sqlite
Convert table into a SQLite database.
Search terms: convert, database
Usage:
> into sqlite {flags} <file-name>
Flags:
-h, --help - Display the help message for this command
-t, --table-name <String> - Specify table name to store the data in
Parameters:
file-name <string>: Specify the filename to save the database to.
Input/output types:
╭───┬────────┬─────────╮
│ # │ input │ output │
├───┼────────┼─────────┤
│ 0 │ table │ nothing │
│ 1 │ record │ nothing │
╰───┴────────┴─────────╯
Examples:
Convert ls entries into a SQLite database with 'main' as the table name
> ls | into sqlite my_ls.db
Convert ls entries into a SQLite database with 'my_table' as the table name
> ls | into sqlite my_ls.db -t my_table
Convert table literal into a SQLite database with 'main' as the table name
> [[name]; [-----] [someone] [=====] [somename] ['(((((']] | into sqlite filename.db
Insert a single record into a SQLite database
> { foo: bar, baz: quux } | into sqlite filename.db
into string
Convert value to string.
Search terms: convert, text
Usage:
> into string {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-d, --decimals <Int> - decimal digits to which to round
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭────┬───────────┬──────────────╮
│ # │ input │ output │
├────┼───────────┼──────────────┤
│ 0 │ binary │ string │
│ 1 │ int │ string │
│ 2 │ number │ string │
│ 3 │ string │ string │
│ 4 │ glob │ string │
│ 5 │ bool │ string │
│ 6 │ filesize │ string │
│ 7 │ date │ string │
│ 8 │ duration │ string │
│ 9 │ list<any> │ list<string> │
│ 10 │ table │ table │
│ 11 │ record │ record │
╰────┴───────────┴──────────────╯
Examples:
convert int to string and append three decimal places
> 5 | into string --decimals 3
5.000
convert float to string and round to nearest integer
> 1.7 | into string --decimals 0
2
convert float to string
> 1.7 | into string --decimals 1
1.7
convert float to string and limit to 2 decimals
> 1.734 | into string --decimals 2
1.73
convert float to string
> 4.3 | into string
4.3
convert string to string
> '1234' | into string
1234
convert boolean to string
> true | into string
true
convert date to string
> '2020-10-10 10:00:00 +02:00' | into datetime | into string
Sat Oct 10 10:00:00 2020
convert filepath to string
> ls Cargo.toml | get name | into string
convert filesize to string
> 1KiB | into string
1.0 KiB
convert duration to string
> 9day | into string
1wk 2day
into value
Infer nushell datatype for each cell.
Usage:
> into value {flags}
Flags:
-h, --help - Display the help message for this command
-c, --columns <Table([])> - list of columns to update
-f, --prefer-filesizes - For ints display them as human-readable file sizes
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ table │ table │
╰───┴───────┴────────╯
Examples:
Infer Nushell values for each cell.
> $table | into value
Infer Nushell values for each cell in the given columns.
> $table | into value -c [column1, column5]
is-admin
Check if nushell is running with administrator or root privileges.
Search terms: root, administrator, superuser, supervisor
Usage:
> is-admin
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ bool │
╰───┴─────────┴────────╯
Examples:
Return 'iamroot' if nushell is running with admin/root privileges, and 'iamnotroot' if not.
> if (is-admin) { "iamroot" } else { "iamnotroot" }
iamnotroot
is-empty
Check for empty values.
Usage:
> is-empty ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: The names of the columns to check emptiness.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ bool │
╰───┴───────┴────────╯
Examples:
Check if a string is empty
> '' | is-empty
true
Check if a list is empty
> [] | is-empty
true
Check if more than one column are empty
> [[meal size]; [arepa small] [taco '']] | is-empty meal size
false
is-not-empty
Check for non-empty values.
Usage:
> is-not-empty ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: The names of the columns to check emptiness.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ bool │
╰───┴───────┴────────╯
Examples:
Check if a string is empty
> '' | is-not-empty
false
Check if a list is empty
> [] | is-not-empty
false
Check if more than one column are empty
> [[meal size]; [arepa small] [taco '']] | is-not-empty meal size
true
is-terminal
Check if stdin, stdout, or stderr is a terminal.
Search terms: input, output, stdin, stdout, stderr, tty
Usage:
> is-terminal {flags}
Flags:
-h, --help - Display the help message for this command
-i, --stdin - Check if stdin is a terminal
-o, --stdout - Check if stdout is a terminal
-e, --stderr - Check if stderr is a terminal
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ bool │
╰───┴─────────┴────────╯
Examples:
Return "terminal attached" if standard input is attached to a terminal, and "no terminal" if not.
> if (is-terminal --stdin) { "terminal attached" } else { "no terminal" }
terminal attached
items
Given a record, iterate on each pair of column name and associated value.
This is a the fusion of `columns`, `values` and `each`.
Usage:
> items <closure>
Flags:
-h, --help - Display the help message for this command
Parameters:
closure <closure(any, any)>: The closure to run.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ any │
╰───┴────────┴────────╯
Examples:
Iterate over each key-value pair of a record
> { new: york, san: francisco } | items {|key, value| echo $'($key) ($value)' }
╭───┬───────────────╮
│ 0 │ new york │
│ 1 │ san francisco │
╰───┴───────────────╯
join
Join two tables.
Search terms: sql
Usage:
> join {flags} <right-table> <left-on> (right-on)
Flags:
-h, --help - Display the help message for this command
-i, --inner - Inner join (default)
-l, --left - Left-outer join
-r, --right - Right-outer join
-o, --outer - Outer join
Parameters:
right-table <list<any>>: The right table in the join.
left-on <string>: Name of column in input (left) table to join on.
right-on <string>: Name of column in right table to join on. Defaults to same column as left table. (optional)
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ table │ table │
╰───┴───────┴────────╯
Examples:
Join two tables
> [{a: 1 b: 2}] | join [{a: 1 c: 3}] a
╭───┬───┬───┬───╮
│ # │ a │ b │ c │
├───┼───┼───┼───┤
│ 0 │ 1 │ 2 │ 3 │
╰───┴───┴───┴───╯
keybindings
Keybindings related commands.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
For more information on input and keybindings, check:
https://www.nushell.sh/book/line_editor.html
Search terms: shortcut, hotkey
Usage:
> keybindings
Subcommands:
keybindings default - List default keybindings.
keybindings list - List available options that can be used to create keybindings.
keybindings listen - Get input from the user.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
keybindings default
List default keybindings.
Usage:
> keybindings default
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Get list with default keybindings
> keybindings default
keybindings list
List available options that can be used to create keybindings.
Usage:
> keybindings list {flags}
Flags:
-h, --help - Display the help message for this command
-m, --modifiers - list of modifiers
-k, --keycodes - list of keycodes
-o, --modes - list of edit modes
-e, --events - list of reedline event
-d, --edits - list of edit commands
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Get list of key modifiers
> keybindings list --modifiers
Get list of reedline events and edit commands
> keybindings list -e -d
Get list with all the available options
> keybindings list
keybindings listen
Get input from the user.
This is an internal debugging tool. For better output, try `input listen --types [key]`
Usage:
> keybindings listen
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Type and see key event codes
> keybindings listen
kill
Kill a process using the process id.
Search terms: stop, end, close
Usage:
> kill {flags} <pid> ...(rest)
Flags:
-h, --help - Display the help message for this command
-f, --force - forcefully kill the process
-q, --quiet - won't print anything to the console
Parameters:
pid <int>: Process id of process that is to be killed.
...rest <int>: Rest of processes to kill.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Kill the pid using the most memory
> ps | sort-by mem | last | kill $in.pid
Force kill a given pid
> kill --force 12345
last
Return only the last several rows of the input. Counterpart of `first`. Opposite of `drop`.
Usage:
> last (rows)
Flags:
-h, --help - Display the help message for this command
Parameters:
rows <int>: Starting from the back, the number of rows to return. (optional)
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ any │
│ 1 │ binary │ binary │
│ 2 │ range │ any │
╰───┴───────────┴────────╯
Examples:
Return the last 2 items of a list/table
> [1,2,3] | last 2
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 3 │
╰───┴───╯
Return the last item of a list/table
> [1,2,3] | last
3
Return the last 2 bytes of a binary value
> 0x[01 23 45] | last 2
#E
Return the last item of a range
> 1..3 | last
3
lazy make
Create a lazy record.
Lazy records are special records that only evaluate their values once the property is requested.
For example, when printing a lazy record, all of its fields will be collected. But when accessing
a specific property, only it will be evaluated.
Note that this is unrelated to the lazyframes feature bundled with dataframes.
Search terms: deferred, record, procedural
Usage:
> lazy make {flags}
Flags:
-h, --help - Display the help message for this command
-c, --columns (required parameter) List(String) - Closure that gets called when the LazyRecord needs to list the available column names
-g, --get-value (required parameter) Closure(Some([String])) - Closure to call when a value needs to be produced on demand
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
Create a lazy record
> lazy make --columns ["haskell", "futures", "nushell"] --get-value { |lazything| $lazything + "!" }
Test the laziness of lazy records
> lazy make --columns ["hello"] --get-value { |key| print $"getting ($key)!"; $key | str upcase }
length
Count the number of items in an input list or rows in a table.
Search terms: count, size, wc
Usage:
> length
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ int │
╰───┴───────────┴────────╯
Examples:
Count the number of items in a list
> [1 2 3 4 5] | length
5
Count the number of rows in a table
> [{a:1 b:2}, {a:2 b:3}] | length
2
let
Create a variable and give it a value.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: set, const
Usage:
> let <var_name> = <initial_value>
Flags:
-h, --help - Display the help message for this command
Parameters:
var_name <vardecl>: Variable name.
"=" + <variable>: Equals sign followed by value.
Examples:
Set a variable to a value
> let x = 10
Set a variable to the result of an expression
> let x = 10 + 100
Set a variable based on the condition
> let x = if false { -1 } else { 1 }
let-env
`let-env FOO = ...` has been removed, use `$env.FOO = ...` instead.
Usage:
> let-env (var_name) (= <initial_value>)
Flags:
-h, --help - Display the help message for this command
Parameters:
var_name <string>: Variable name. (optional)
"=" + <variable>: Equals sign followed by value. (optional)
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
lines
Converts input to lines.
Usage:
> lines {flags}
Flags:
-h, --help - Display the help message for this command
-s, --skip-empty - skip empty lines
Input/output types:
╭───┬───────┬──────────────╮
│ # │ input │ output │
├───┼───────┼──────────────┤
│ 0 │ any │ list<string> │
╰───┴───────┴──────────────╯
Examples:
Split multi-line string into lines
> $"two\nlines" | lines
╭───┬───────╮
│ 0 │ two │
│ 1 │ lines │
╰───┴───────╯
load-env
Loads an environment update from a record.
Usage:
> load-env (update)
Flags:
-h, --help - Display the help message for this command
Parameters:
update <record>: The record to use for updates. (optional)
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ record │ nothing │
│ 1 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Load variables from an input stream
> {NAME: ABE, AGE: UNKNOWN} | load-env; $env.NAME
ABE
Load variables from an argument
> load-env {NAME: ABE, AGE: UNKNOWN}; $env.NAME
ABE
loop
Run a block in a loop.
Usage:
> loop <block>
Flags:
-h, --help - Display the help message for this command
Parameters:
block <block>: Block to loop.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Loop while a condition is true
> mut x = 0; loop { if $x > 10 { break }; $x = $x + 1 }; $x
11
ls
List the filenames, sizes, and modification times of items in a directory.
Search terms: dir
Usage:
> ls {flags} (pattern)
Flags:
-h, --help - Display the help message for this command
-a, --all - Show hidden files
-l, --long - Get all available columns for each entry (slower; columns are platform-dependent)
-s, --short-names - Only print the file names, and not the path
-f, --full-paths - display paths as absolute paths
-d, --du - Display the apparent directory size ("disk usage") in place of the directory metadata size
-D, --directory - List the specified directory itself instead of its contents
-m, --mime-type - Show mime-type in type column instead of 'file' (based on filenames only; files' contents are not examined)
Parameters:
pattern <one_of(glob, string)>: The glob pattern to use. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
List visible files in the current directory
> ls
List visible files in a subdirectory
> ls subdir
List visible files with full path in the parent directory
> ls -f ..
List Rust files
> ls *.rs
List files and directories whose name do not contain 'bar'
> ls -s | where name !~ bar
List all dirs in your home directory
> ls -a ~ | where type == dir
List all dirs in your home directory which have not been modified in 7 days
> ls -as ~ | where type == dir and modified < ((date now) - 7day)
List given paths and show directories themselves
> ['/path/to/directory' '/path/to/file'] | each {|| ls -D $in } | flatten
match
Conditionally run a block on a matched value.
Usage:
> match <value> <match_block>
Flags:
-h, --help - Display the help message for this command
Parameters:
value <any>: Value to check.
match_block <match-block>: Block to run if check succeeds.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Match on a value in range
> match 3 { 1..10 => 'yes!' }
yes!
Match on a field in a record
> match {a: 100} { {a: $my_value} => { $my_value } }
100
Match with a catch-all
> match 3 { 1 => { 'yes!' }, _ => { 'no!' } }
no!
Match against a list
> match [1, 2, 3] { [$a, $b, $c] => { $a + $b + $c }, _ => 0 }
6
Match against pipeline input
> {a: {b: 3}} | match $in {{a: { $b }} => ($b + 10) }
13
Match with a guard
> match [1 2 3] {
[$x, ..$y] if $x == 1 => { 'good list' },
_ => { 'not a very good list' }
}
good list
math
Use mathematical functions as aggregate functions on a list of numbers or tables.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> math
Subcommands:
math abs - Returns the absolute value of a number.
math avg - Returns the average of a list of numbers.
math ceil - Returns the ceil of a number (smallest integer greater than or equal to that number).
math floor - Returns the floor of a number (largest integer less than or equal to that number).
math log - Returns the logarithm for an arbitrary base.
math max - Returns the maximum of a list of values, or of columns in a table.
math median - Computes the median of a list of numbers.
math min - Finds the minimum within a list of values or tables.
math mode - Returns the most frequent element(s) from a list of numbers or tables.
math product - Returns the product of a list of numbers or the products of each column of a table.
math round - Returns the input number rounded to the specified precision.
math sqrt - Returns the square root of the input number.
math stddev - Returns the standard deviation of a list of numbers, or of each column in a table.
math sum - Returns the sum of a list of numbers or of each column in a table.
math variance - Returns the variance of a list of numbers or of each column in a table.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
math abs
Returns the absolute value of a number.
Search terms: absolute, modulus, positive, distance
Usage:
> math abs
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────────────┬────────────────╮
│ # │ input │ output │
├───┼────────────────┼────────────────┤
│ 0 │ number │ number │
│ 1 │ duration │ duration │
│ 2 │ list<number> │ list<number> │
│ 3 │ list<duration> │ list<duration> │
╰───┴────────────────┴────────────────╯
Examples:
Compute absolute value of each number in a list of numbers
> [-50 -100.0 25] | math abs
╭───┬────────╮
│ 0 │ 50 │
│ 1 │ 100.00 │
│ 2 │ 25 │
╰───┴────────╯
math avg
Returns the average of a list of numbers.
Search terms: average, mean, statistics
Usage:
> math avg
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────────────┬──────────╮
│ # │ input │ output │
├───┼────────────────┼──────────┤
│ 0 │ list<duration> │ duration │
│ 1 │ duration │ duration │
│ 2 │ list<filesize> │ filesize │
│ 3 │ filesize │ filesize │
│ 4 │ list<number> │ number │
│ 5 │ number │ number │
│ 6 │ range │ number │
│ 7 │ table │ record │
│ 8 │ record │ record │
╰───┴────────────────┴──────────╯
Examples:
Compute the average of a list of numbers
> [-50 100.0 25] | math avg
25
Compute the average of a list of durations
> [2sec 1min] | math avg
31sec
Compute the average of each column in a table
> [[a b]; [1 2] [3 4]] | math avg
╭───┬───╮
│ a │ 2 │
│ b │ 3 │
╰───┴───╯
math ceil
Returns the ceil of a number (smallest integer greater than or equal to that number).
Search terms: ceiling, round up, rounding, integer
Usage:
> math ceil
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬──────────────┬───────────╮
│ # │ input │ output │
├───┼──────────────┼───────────┤
│ 0 │ number │ int │
│ 1 │ list<number> │ list<int> │
╰───┴──────────────┴───────────╯
Examples:
Apply the ceil function to a list of numbers
> [1.5 2.3 -3.1] | math ceil
╭───┬────╮
│ 0 │ 2 │
│ 1 │ 3 │
│ 2 │ -3 │
╰───┴────╯
math floor
Returns the floor of a number (largest integer less than or equal to that number).
Search terms: round down, rounding, integer
Usage:
> math floor
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬──────────────┬───────────╮
│ # │ input │ output │
├───┼──────────────┼───────────┤
│ 0 │ number │ int │
│ 1 │ list<number> │ list<int> │
╰───┴──────────────┴───────────╯
Examples:
Apply the floor function to a list of numbers
> [1.5 2.3 -3.1] | math floor
╭───┬────╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ -4 │
╰───┴────╯
math log
Returns the logarithm for an arbitrary base.
Search terms: base, exponent, inverse, euler
Usage:
> math log <base>
Flags:
-h, --help - Display the help message for this command
Parameters:
base <number>: Base for which the logarithm should be computed.
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Get the logarithm of 100 to the base 10
> 100 | math log 10
2
Get the log2 of a list of values
> [16 8 4] | math log 2
╭───┬──────╮
│ 0 │ 4.00 │
│ 1 │ 3.00 │
│ 2 │ 2.00 │
╰───┴──────╯
math max
Returns the maximum of a list of values, or of columns in a table.
Search terms: maximum, largest
Usage:
> math max
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────────────┬──────────╮
│ # │ input │ output │
├───┼────────────────┼──────────┤
│ 0 │ list<number> │ number │
│ 1 │ list<duration> │ duration │
│ 2 │ list<filesize> │ filesize │
│ 3 │ list<any> │ any │
│ 4 │ range │ number │
│ 5 │ table │ record │
│ 6 │ record │ record │
╰───┴────────────────┴──────────╯
Examples:
Find the maximum of a list of numbers
> [-50 100 25] | math max
100
Find the maxima of the columns of a table
> [{a: 1 b: 3} {a: 2 b: -1}] | math max
╭───┬───╮
│ a │ 2 │
│ b │ 3 │
╰───┴───╯
Find the maximum of a list of dates
> [2022-02-02 2022-12-30 2012-12-12] | math max
Fri, 30 Dec 2022 00:00:00 +0000 (a year ago)
math median
Computes the median of a list of numbers.
Search terms: middle, statistics
Usage:
> math median
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────────────┬──────────╮
│ # │ input │ output │
├───┼────────────────┼──────────┤
│ 0 │ list<number> │ number │
│ 1 │ list<duration> │ duration │
│ 2 │ list<filesize> │ filesize │
│ 3 │ range │ number │
│ 4 │ table │ record │
│ 5 │ record │ record │
╰───┴────────────────┴──────────╯
Examples:
Compute the median of a list of numbers
> [3 8 9 12 12 15] | math median
10.5
Compute the medians of the columns of a table
> [{a: 1 b: 3} {a: 2 b: -1} {a: -3 b: 5}] | math median
╭───┬───╮
│ a │ 1 │
│ b │ 3 │
╰───┴───╯
Find the median of a list of file sizes
> [5KB 10MB 200B] | math median
5.0 KB
math min
Finds the minimum within a list of values or tables.
Search terms: minimum, smallest
Usage:
> math min
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────────────┬──────────╮
│ # │ input │ output │
├───┼────────────────┼──────────┤
│ 0 │ list<number> │ number │
│ 1 │ list<duration> │ duration │
│ 2 │ list<filesize> │ filesize │
│ 3 │ list<any> │ any │
│ 4 │ range │ number │
│ 5 │ table │ record │
│ 6 │ record │ record │
╰───┴────────────────┴──────────╯
Examples:
Compute the minimum of a list of numbers
> [-50 100 25] | math min
-50
Compute the minima of the columns of a table
> [{a: 1 b: 3} {a: 2 b: -1}] | math min
╭───┬────╮
│ a │ 1 │
│ b │ -1 │
╰───┴────╯
Find the minimum of a list of arbitrary values (Warning: Weird)
> [-50 'hello' true] | math min
true
math mode
Returns the most frequent element(s) from a list of numbers or tables.
Search terms: common, often
Usage:
> math mode
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────────────┬────────────────╮
│ # │ input │ output │
├───┼────────────────┼────────────────┤
│ 0 │ list<number> │ list<number> │
│ 1 │ list<duration> │ list<duration> │
│ 2 │ list<filesize> │ list<filesize> │
│ 3 │ table │ record │
╰───┴────────────────┴────────────────╯
Examples:
Compute the mode(s) of a list of numbers
> [3 3 9 12 12 15] | math mode
╭───┬────╮
│ 0 │ 3 │
│ 1 │ 12 │
╰───┴────╯
Compute the mode(s) of the columns of a table
> [{a: 1 b: 3} {a: 2 b: -1} {a: 1 b: 5}] | math mode
╭───┬────────────────╮
│ a │ [list 1 item] │
│ b │ [list 3 items] │
╰───┴────────────────╯
math product
Returns the product of a list of numbers or the products of each column of a table.
Search terms: times, multiply, x, *
Usage:
> math product
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬──────────────┬────────╮
│ # │ input │ output │
├───┼──────────────┼────────┤
│ 0 │ list<number> │ number │
│ 1 │ range │ number │
│ 2 │ table │ record │
│ 3 │ record │ record │
╰───┴──────────────┴────────╯
Examples:
Compute the product of a list of numbers
> [2 3 3 4] | math product
72
Compute the product of each column in a table
> [[a b]; [1 2] [3 4]] | math product
╭───┬───╮
│ a │ 3 │
│ b │ 8 │
╰───┴───╯
math round
Returns the input number rounded to the specified precision.
Search terms: approx, closest, nearest
Usage:
> math round {flags}
Flags:
-h, --help - Display the help message for this command
-p, --precision <Number> - digits of precision
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ number │ number │
│ 1 │ list<number> │ list<number> │
╰───┴──────────────┴──────────────╯
Examples:
Apply the round function to a list of numbers
> [1.5 2.3 -3.1] | math round
╭───┬────╮
│ 0 │ 2 │
│ 1 │ 2 │
│ 2 │ -3 │
╰───┴────╯
Apply the round function with precision specified
> [1.555 2.333 -3.111] | math round --precision 2
╭───┬───────╮
│ 0 │ 1.56 │
│ 1 │ 2.33 │
│ 2 │ -3.11 │
╰───┴───────╯
Apply negative precision to a list of numbers
> [123, 123.3, -123.4] | math round --precision -1
╭───┬──────╮
│ 0 │ 120 │
│ 1 │ 120 │
│ 2 │ -120 │
╰───┴──────╯
math sqrt
Returns the square root of the input number.
Search terms: square, root
Usage:
> math sqrt
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Compute the square root of each number in a list
> [9 16] | math sqrt
╭───┬──────╮
│ 0 │ 3.00 │
│ 1 │ 4.00 │
╰───┴──────╯
math stddev
Returns the standard deviation of a list of numbers, or of each column in a table.
Search terms: SD, standard, deviation, dispersion, variation, statistics
Usage:
> math stddev {flags}
Flags:
-h, --help - Display the help message for this command
-s, --sample - calculate sample standard deviation (i.e. using N-1 as the denominator)
Input/output types:
╭───┬──────────────┬────────╮
│ # │ input │ output │
├───┼──────────────┼────────┤
│ 0 │ list<number> │ number │
│ 1 │ table │ record │
│ 2 │ record │ record │
╰───┴──────────────┴────────╯
Examples:
Compute the standard deviation of a list of numbers
> [1 2 3 4 5] | math stddev
1.4142135623730951
Compute the sample standard deviation of a list of numbers
> [1 2 3 4 5] | math stddev --sample
1.5811388300841898
Compute the standard deviation of each column in a table
> [[a b]; [1 2] [3 4]] | math stddev
╭───┬───╮
│ a │ 1 │
│ b │ 1 │
╰───┴───╯
math sum
Returns the sum of a list of numbers or of each column in a table.
Search terms: plus, add, total, +
Usage:
> math sum
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────────────┬──────────╮
│ # │ input │ output │
├───┼────────────────┼──────────┤
│ 0 │ list<number> │ number │
│ 1 │ list<duration> │ duration │
│ 2 │ list<filesize> │ filesize │
│ 3 │ range │ number │
│ 4 │ table │ record │
│ 5 │ record │ record │
╰───┴────────────────┴──────────╯
Examples:
Sum a list of numbers
> [1 2 3] | math sum
6
Get the disk usage for the current directory
> ls | get size | math sum
Compute the sum of each column in a table
> [[a b]; [1 2] [3 4]] | math sum
╭───┬───╮
│ a │ 4 │
│ b │ 6 │
╰───┴───╯
math variance
Returns the variance of a list of numbers or of each column in a table.
Search terms: deviation, dispersion, variation, statistics
Usage:
> math variance {flags}
Flags:
-h, --help - Display the help message for this command
-s, --sample - calculate sample variance (i.e. using N-1 as the denominator)
Input/output types:
╭───┬──────────────┬────────╮
│ # │ input │ output │
├───┼──────────────┼────────┤
│ 0 │ list<number> │ number │
│ 1 │ table │ record │
│ 2 │ record │ record │
╰───┴──────────────┴────────╯
Examples:
Get the variance of a list of numbers
> [1 2 3 4 5] | math variance
2
Get the sample variance of a list of numbers
> [1 2 3 4 5] | math variance --sample
2.5
Compute the variance of each column in a table
> [[a b]; [1 2] [3 4]] | math variance
╭───┬───╮
│ a │ 1 │
│ b │ 1 │
╰───┴───╯
merge
Merge the input with a record or table, overwriting values in matching columns.
You may provide a column structure to merge
When merging tables, row 0 of the input table is overwritten
with values from row 0 of the provided table, then
repeating this process with row 1, and so on.
Usage:
> merge <value>
Flags:
-h, --help - Display the help message for this command
Parameters:
value <any>: The new value to merge with.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
╰───┴────────┴────────╯
Examples:
Add an 'index' column to the input table
> [a b c] | wrap name | merge ( [1 2 3] | wrap index )
╭───┬──────╮
│ # │ name │
├───┼──────┤
│ 1 │ a │
│ 2 │ b │
│ 3 │ c │
╰───┴──────╯
Merge two records
> {a: 1, b: 2} | merge {c: 3}
╭───┬───╮
│ a │ 1 │
│ b │ 2 │
│ c │ 3 │
╰───┴───╯
Merge two tables, overwriting overlapping columns
> [{columnA: A0 columnB: B0}] | merge [{columnA: 'A0*'}]
╭───┬─────────┬─────────╮
│ # │ columnA │ columnB │
├───┼─────────┼─────────┤
│ 0 │ A0* │ B0 │
╰───┴─────────┴─────────╯
metadata
Get the metadata for items in the stream.
Usage:
> metadata (expression)
Flags:
-h, --help - Display the help message for this command
Parameters:
expression <any>: The expression you want metadata for. (optional)
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ record │
╰───┴───────┴────────╯
Examples:
Get the metadata of a variable
> let a = 42; metadata $a
Get the metadata of the input
> ls | metadata
mkdir
Create directories, with intermediary directories if required using uutils/coreutils mkdir.
Search terms: directory, folder, create, make_dirs, coreutils
Usage:
> mkdir {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-v, --verbose - print a message for each created directory.
Parameters:
...rest <directory>: The name(s) of the path(s) to create.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Make a directory named foo
> mkdir foo
Make multiple directories and show the paths created
> mkdir -v foo/bar foo2
mktemp
Create temporary files or directories using uutils/coreutils mktemp.
Search terms: coreutils, create, directory, file, folder, temporary
Usage:
> mktemp {flags} (template)
Flags:
-h, --help - Display the help message for this command
--suffix <String> - Append suffix to template; must not contain a slash.
-p, --tmpdir-path <Filepath> - Interpret TEMPLATE relative to tmpdir-path. If tmpdir-path is not set use $TMPDIR
-t, --tmpdir - Interpret TEMPLATE relative to the system temporary directory.
-d, --directory - Create a directory instead of a file.
Parameters:
template <string>: Optional pattern from which the name of the file or directory is derived. Must contain at least three 'X's in last component. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Make a temporary file with the given suffix in the current working directory.
> mktemp --suffix .txt
<WORKING_DIR>/tmp.lekjbhelyx.txt
Make a temporary file named testfile.XXX with the 'X's as random characters in the current working directory.
> mktemp testfile.XXX
<WORKING_DIR>/testfile.4kh
Make a temporary file with a template in the system temp directory.
> mktemp -t testfile.XXX
/tmp/testfile.4kh
Make a temporary directory with randomly generated name in the temporary directory.
> mktemp -d
/tmp/tmp.NMw9fJr8K0
module
Define a custom module.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> module <module> (block)
Flags:
-h, --help - Display the help message for this command
Parameters:
module <string>: Module name or module path.
block <block>: Body of the module if 'module' parameter is not a module path. (optional)
Examples:
Define a custom command in a module and call it
> module spam { export def foo [] { "foo" } }; use spam foo; foo
foo
Define an environment variable in a module
> module foo { export-env { $env.FOO = "BAZ" } }; use foo; $env.FOO
BAZ
Define a custom command that participates in the environment in a module and call it
> module foo { export def --env bar [] { $env.FOO_BAR = "BAZ" } }; use foo bar; bar; $env.FOO_BAR
BAZ
move
Move columns before or after other columns.
Usage:
> move {flags} ...(columns)
Flags:
-h, --help - Display the help message for this command
--after <String> - the column that will precede the columns moved
--before <String> - the column that will be the next after the columns moved
Parameters:
...columns <string>: The columns to move.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
╰───┴────────┴────────╯
Examples:
Move a column before the first column
> [[name value index]; [foo a 1] [bar b 2] [baz c 3]] | move index --before name
╭───┬──────┬───────╮
│ # │ name │ value │
├───┼──────┼───────┤
│ 1 │ foo │ a │
│ 2 │ bar │ b │
│ 3 │ baz │ c │
╰───┴──────┴───────╯
Move multiple columns after the last column and reorder them
> [[name value index]; [foo a 1] [bar b 2] [baz c 3]] | move value name --after index
╭───┬───────┬──────╮
│ # │ value │ name │
├───┼───────┼──────┤
│ 1 │ a │ foo │
│ 2 │ b │ bar │
│ 3 │ c │ baz │
╰───┴───────┴──────╯
Move columns of a record
> { name: foo, value: a, index: 1 } | move name --before index
╭───────┬─────╮
│ value │ a │
│ name │ foo │
│ index │ 1 │
╰───────┴─────╯
mut
Create a mutable variable and give it a value.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: set, mutable
Usage:
> mut <var_name> = <initial_value>
Flags:
-h, --help - Display the help message for this command
Parameters:
var_name <vardecl>: Variable name.
"=" + <variable>: Equals sign followed by value.
Examples:
Set a mutable variable to a value, then update it
> mut x = 10; $x = 12
Upsert a value inside a mutable data structure
> mut a = {b:{c:1}}; $a.b.c = 2
Set a mutable variable to the result of an expression
> mut x = 10 + 100
Set a mutable variable based on the condition
> mut x = if false { -1 } else { 1 }
mv
Move files or directories using uutils/coreutils mv.
Search terms: move
Usage:
> mv {flags} ...(paths)
Flags:
-h, --help - Display the help message for this command
-f, --force - do not prompt before overwriting
-v, --verbose - explain what is being done.
-p, --progress - display a progress bar
-i, --interactive - prompt before overwriting
-n, --no-clobber - do not overwrite an existing file
Parameters:
...paths <one_of(glob, string)>: Rename SRC to DST, or move SRC to DIR.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
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
nu-check
Validate and parse input content.
Search terms: syntax, parse, debug
Usage:
> nu-check {flags} (path)
Flags:
-h, --help - Display the help message for this command
-m, --as-module - Parse content as module
-d, --debug - Show error messages
-a, --all - Parse content as script first, returns result if success, otherwise, try with module
Parameters:
path <string>: File path to parse. (optional)
Input/output types:
╭───┬─────────────┬────────╮
│ # │ input │ output │
├───┼─────────────┼────────┤
│ 0 │ string │ bool │
│ 1 │ list-stream │ bool │
│ 2 │ list<any> │ bool │
╰───┴─────────────┴────────╯
Examples:
Parse a input file as script(Default)
> nu-check script.nu
Parse a input file as module
> nu-check --as-module module.nu
Parse a input file by showing error message
> nu-check --debug script.nu
Parse an external stream as script by showing error message
> open foo.nu | nu-check --debug script.nu
Parse an internal stream as module by showing error message
> open module.nu | lines | nu-check --debug --as-module module.nu
Parse a string as script
> $'two(char nl)lines' | nu-check
Heuristically parse which begins with script first, if it sees a failure, try module afterwards
> nu-check -a script.nu
Heuristically parse by showing error message
> open foo.nu | lines | nu-check --all --debug
nu-highlight
Syntax highlight the input string.
Search terms: syntax, color, convert
Usage:
> nu-highlight
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ string │
╰───┴────────┴────────╯
Examples:
Describe the type of a string
> 'let x = 3' | nu-highlight
open
Load a file into a cell, converting to table if possible (avoid by appending '--raw').
Support to automatically parse files with an extension `.xyz` can be provided by a `from xyz` command in scope.
Search terms: load, read, load_file, read_file
Usage:
> open {flags} ...(files)
Flags:
-h, --help - Display the help message for this command
-r, --raw - open file as raw binary
Parameters:
...files <one_of(glob, string)>: The file(s) to open.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
│ 1 │ string │ any │
╰───┴─────────┴────────╯
Examples:
Open a file, with structure (based on file extension or SQLite database header)
> open myfile.json
Open a file, as raw bytes
> open myfile.json --raw
Open a file, using the input to get filename
> 'myfile.txt' | open
Open a file, and decode it by the specified encoding
> open myfile.txt --raw | decode utf-8
Create a custom `from` parser to open newline-delimited JSON files with `open`
> def "from ndjson" [] { from json -o }; open myfile.ndjson
overlay
Commands for manipulating overlays.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> overlay
Subcommands:
overlay hide - Hide an active overlay.
overlay list - List all active overlays.
overlay new - Create an empty overlay.
overlay use - Use definitions from a module as an overlay.
Flags:
-h, --help - Display the help message for this command
overlay hide
Hide an active overlay.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> overlay hide {flags} (name)
Flags:
-h, --help - Display the help message for this command
-k, --keep-custom - Keep all newly added commands and aliases in the next activated overlay.
-e, --keep-env <List(String)> - List of environment variables to keep in the next activated overlay
Parameters:
name <string>: Overlay to hide. (optional)
Examples:
Keep a custom command after hiding the overlay
> module spam { export def foo [] { "foo" } }
overlay use spam
def bar [] { "bar" }
overlay hide spam --keep-custom
bar
Hide an overlay created from a file
> 'export alias f = "foo"' | save spam.nu
overlay use spam.nu
overlay hide spam
Hide the last activated overlay
> module spam { export-env { $env.FOO = "foo" } }
overlay use spam
overlay hide
Keep the current working directory when removing an overlay
> overlay new spam
cd some-dir
overlay hide --keep-env [ PWD ] spam
overlay list
List all active overlays.
The overlays are listed in the order they were activated.
Usage:
> overlay list
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬──────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────┤
│ 0 │ nothing │ list<string> │
╰───┴─────────┴──────────────╯
Examples:
Get the last activated overlay
> module spam { export def foo [] { "foo" } }
overlay use spam
overlay list | last
spam
overlay new
Create an empty overlay.
The command will first create an empty module, then add it as an overlay.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> overlay new <name>
Flags:
-h, --help - Display the help message for this command
Parameters:
name <string>: Name of the overlay.
Examples:
Create an empty overlay
> overlay new spam
overlay use
Use definitions from a module as an overlay.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> overlay use {flags} <name> (as <as>)
Flags:
-h, --help - Display the help message for this command
-p, --prefix - Prepend module name to the imported commands and aliases
-r, --reload - If the overlay already exists, reload its definitions and environment.
Parameters:
name <string>: Module name to use overlay for.
"as" + <string>: `as` keyword followed by a new name. (optional)
Examples:
Create an overlay from a module
> module spam { export def foo [] { "foo" } }
overlay use spam
foo
Create an overlay from a module and rename it
> module spam { export def foo [] { "foo" } }
overlay use spam as spam_new
foo
Create an overlay with a prefix
> 'export def foo { "foo" }'
overlay use --prefix spam
spam foo
Create an overlay from a file
> 'export-env { $env.FOO = "foo" }' | save spam.nu
overlay use spam.nu
$env.FOO
panic
Executes a rust panic, useful only for testing.
Usage:
> panic (msg)
Flags:
-h, --help - Display the help message for this command
Parameters:
msg <string>: The glob pattern to use. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
par-each
Run a closure on each row of the input list in parallel, creating a new list with the results.
Usage:
> par-each {flags} <closure>
Flags:
-h, --help - Display the help message for this command
-t, --threads <Int> - the number of threads to use
-k, --keep-order - keep sequence of output same as the order of input
Parameters:
closure <closure(any, int)>: The closure to run.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
│ 1 │ table │ list<any> │
│ 2 │ any │ any │
╰───┴───────────┴───────────╯
Examples:
Multiplies each number. Note that the list will become arbitrarily disordered.
> [1 2 3] | par-each {|e| $e * 2 }
Multiplies each number, keeping an original order
> [1 2 3] | par-each --keep-order {|e| $e * 2 }
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 4 │
│ 2 │ 6 │
╰───┴───╯
Enumerate and sort-by can be used to reconstruct the original order
> 1..3 | enumerate | par-each {|p| update item ($p.item * 2)} | sort-by item | get item
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 4 │
│ 2 │ 6 │
╰───┴───╯
Output can still be sorted afterward
> [foo bar baz] | par-each {|e| $e + '!' } | sort
╭───┬──────╮
│ 0 │ bar! │
│ 1 │ baz! │
│ 2 │ foo! │
╰───┴──────╯
Iterate over each element, producing a list showing indexes of any 2s
> [1 2 3] | enumerate | par-each { |e| if $e.item == 2 { $"found 2 at ($e.index)!"} }
╭───┬───────────────╮
│ 0 │ found 2 at 1! │
╰───┴───────────────╯
parse
Parse columns from string data using a simple pattern.
Search terms: pattern, match, regex
Usage:
> parse {flags} <pattern>
Flags:
-h, --help - Display the help message for this command
-r, --regex - use full regex syntax for patterns
Parameters:
pattern <string>: The pattern to match.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ string │ table │
│ 1 │ list<any> │ table │
╰───┴───────────┴────────╯
Examples:
Parse a string into two named columns
> "hi there" | parse "{foo} {bar}"
╭───┬─────┬───────╮
│ # │ foo │ bar │
├───┼─────┼───────┤
│ 0 │ hi │ there │
╰───┴─────┴───────╯
Parse a string using regex pattern
> "hi there" | parse --regex '(?P<foo>\w+) (?P<bar>\w+)'
╭───┬─────┬───────╮
│ # │ foo │ bar │
├───┼─────┼───────┤
│ 0 │ hi │ there │
╰───┴─────┴───────╯
Parse a string using fancy-regex named capture group pattern
> "foo bar." | parse --regex '\s*(?<name>\w+)(?=\.)'
╭───┬──────╮
│ # │ name │
├───┼──────┤
│ 0 │ bar │
╰───┴──────╯
Parse a string using fancy-regex capture group pattern
> "foo! bar." | parse --regex '(\w+)(?=\.)|(\w+)(?=!)'
╭───┬──────────┬──────────╮
│ # │ capture0 │ capture1 │
├───┼──────────┼──────────┤
│ 0 │ │ foo │
│ 1 │ bar │ │
╰───┴──────────┴──────────╯
Parse a string using fancy-regex look behind pattern
> " @another(foo bar) " | parse --regex '\s*(?<=[() ])(@\w+)(\([^)]*\))?\s*'
╭───┬──────────┬───────────╮
│ # │ capture0 │ capture1 │
├───┼──────────┼───────────┤
│ 0 │ @another │ (foo bar) │
╰───┴──────────┴───────────╯
Parse a string using fancy-regex look ahead atomic group pattern
> "abcd" | parse --regex '^a(bc(?=d)|b)cd$'
╭───┬──────────╮
│ # │ capture0 │
├───┼──────────┤
│ 0 │ b │
╰───┴──────────╯
path
Explore and manipulate paths.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
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 a list of path parts, e.g., '[ / home viking spam.txt ]'. Splitting into
parts is done by the `path split` command.
All subcommands accept all three variants as an input. Furthermore, the 'path
join' subcommand can be used to join the structured path or path parts back into
the path literal.
Usage:
> path
Subcommands:
path basename - Get the final component of a path.
path dirname - Get the parent directory of a path.
path exists - Check whether a path exists.
path expand - Try to expand a path to its absolute form.
path join - Join a structured path or a list of path parts.
path parse - Convert a path into structured data.
path relative-to - Express a path as relative to another path.
path split - Split a path into a list based on the system's path separator.
path type - Get the type of the object a path refers to (e.g., file, dir, symlink).
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
path basename
Get the final component of a path.
Usage:
> path basename {flags}
Flags:
-h, --help - Display the help message for this command
-r, --replace <String> - Return original path with basename replaced by this string
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
Get basename of a path
> 'C:\Users\joe\test.txt' | path basename
test.txt
Get basename of a list of paths
> [ C:\Users\joe, C:\Users\doe ] | path basename
╭───┬─────╮
│ 0 │ joe │
│ 1 │ doe │
╰───┴─────╯
Replace basename of a path
> 'C:\Users\joe\test.txt' | path basename --replace 'spam.png'
C:\Users\joe\spam.png
path dirname
Get the parent directory of a path.
Usage:
> path dirname {flags}
Flags:
-h, --help - Display the help message for this command
-r, --replace <String> - Return original path with dirname replaced by this string
-n, --num-levels <Int> - Number of directories to walk up
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
Get dirname of a path
> 'C:\Users\joe\code\test.txt' | path dirname
C:\Users\joe\code
Get dirname of a list of paths
> [ C:\Users\joe\test.txt, C:\Users\doe\test.txt ] | path dirname
╭───┬──────────────╮
│ 0 │ C:\Users\joe │
│ 1 │ C:\Users\doe │
╰───┴──────────────╯
Walk up two levels
> 'C:\Users\joe\code\test.txt' | path dirname --num-levels 2
C:\Users\joe
Replace the part that would be returned with a custom path
> 'C:\Users\joe\code\test.txt' | path dirname --num-levels 2 --replace C:\Users\viking
C:\Users\viking\code\test.txt
path exists
Check whether a path exists.
This only checks if it is possible to either `open` or `cd` to the given path.
If you need to distinguish dirs and files, please use `path type`.
Usage:
> path exists {flags}
Flags:
-h, --help - Display the help message for this command
-n, --no-symlink - Do not resolve symbolic links
Input/output types:
╭───┬──────────────┬────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────┤
│ 0 │ string │ bool │
│ 1 │ list<string> │ list<bool> │
╰───┴──────────────┴────────────╯
Examples:
Check if a file exists
> 'C:\Users\joe\todo.txt' | path exists
false
Check if files in list exist
> [ C:\joe\todo.txt, C:\Users\doe\todo.txt ] | path exists
╭───┬───────╮
│ 0 │ false │
│ 1 │ false │
╰───┴───────╯
path expand
Try to expand a path to its absolute form.
Usage:
> path expand {flags}
Flags:
-h, --help - Display the help message for this command
-s, --strict - Throw an error if the path could not be expanded
-n, --no-symlink - Do not resolve symbolic links
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
Expand an absolute path
> 'C:\Users\joe\foo\..\bar' | path expand
C:\Users\joe\bar
Expand a relative path
> 'foo\..\bar' | path expand
Expand a list of paths
> [ C:\foo\..\bar, C:\foo\..\baz ] | path expand
╭───┬────────╮
│ 0 │ C:\bar │
│ 1 │ C:\baz │
╰───┴────────╯
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 ...(append)
Flags:
-h, --help - Display the help message for this command
Parameters:
...append <string>: Path to append to the input.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ string │
│ 2 │ record │ string │
│ 3 │ table │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
Append a filename to a path
> 'C:\Users\viking' | path join spam.txt
C:\Users\viking\spam.txt
Append a filename to a path
> 'C:\Users\viking' | path join spams this_spam.txt
C:\Users\viking\spams\this_spam.txt
Use relative paths, e.g. '..' will go up one directory
> 'C:\Users\viking' | path join .. folder
C:\Users\viking\..\folder
Use absolute paths, e.g. '/' will bring you to the top level directory
> 'C:\Users\viking' | path join / folder
C:/folder
Join a list of parts into a path
> [ 'C:' '\' 'Users' 'viking' 'spam.txt' ] | path join
C:\Users\viking\spam.txt
Join a structured path into a path
> { parent: 'C:\Users\viking', stem: 'spam', extension: 'txt' } | path join
C:\Users\viking\spam.txt
Join a table of structured paths into a list of paths
> [ [parent stem extension]; ['C:\Users\viking' 'spam' 'txt']] | path join
╭───┬──────────────────────────╮
│ 0 │ C:\Users\viking\spam.txt │
╰───┴──────────────────────────╯
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 {flags}
Flags:
-h, --help - Display the help message for this command
-e, --extension <String> - Manually supply the extension (without the dot)
Input/output types:
╭───┬──────────────┬────────╮
│ # │ input │ output │
├───┼──────────────┼────────┤
│ 0 │ string │ record │
│ 1 │ list<string> │ table │
╰───┴──────────────┴────────╯
Examples:
Parse a single path
> 'C:\Users\viking\spam.txt' | path parse
╭───────────┬─────────────────╮
│ prefix │ C: │
│ parent │ C:\Users\viking │
│ stem │ spam │
│ extension │ txt │
╰───────────┴─────────────────╯
Replace a complex extension
> 'C:\Users\viking\spam.tar.gz' | path parse --extension tar.gz | upsert extension { 'txt' }
Ignore the extension
> 'C:\Users\viking.d' | path parse --extension ''
╭───────────┬──────────╮
│ prefix │ C: │
│ parent │ C:\Users │
│ stem │ viking.d │
│ extension │ │
╰───────────┴──────────╯
Parse all paths in a list
> [ C:\Users\viking.d C:\Users\spam.txt ] | path parse
╭───┬────────┬──────────┬────────┬───────────╮
│ # │ prefix │ parent │ stem │ extension │
├───┼────────┼──────────┼────────┼───────────┤
│ 0 │ C: │ C:\Users │ viking │ d │
│ 1 │ C: │ C:\Users │ spam │ txt │
╰───┴────────┴──────────┴────────┴───────────╯
path relative-to
Express 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>
Flags:
-h, --help - Display the help message for this command
Parameters:
path <string>: Parent shared with the input path.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
Find a relative path from two absolute paths
> 'C:\Users\viking' | path relative-to 'C:\Users'
viking
Find a relative path from absolute paths in list
> [ C:\Users\viking, C:\Users\spam ] | path relative-to C:\Users
╭───┬────────╮
│ 0 │ viking │
│ 1 │ spam │
╰───┴────────╯
Find a relative path from two relative paths
> 'eggs\bacon\sausage\spam' | path relative-to 'eggs\bacon\sausage'
spam
path split
Split a path into a list based on the system's path separator.
Usage:
> path split
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬──────────────┬────────────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────────────┤
│ 0 │ string │ list<string> │
│ 1 │ list<string> │ list<list<string>> │
╰───┴──────────────┴────────────────────╯
Examples:
Split a path into parts
> 'C:\Users\viking\spam.txt' | path split
╭───┬──────────╮
│ 0 │ C:\ │
│ 1 │ Users │
│ 2 │ viking │
│ 3 │ spam.txt │
╰───┴──────────╯
Split paths in list into parts
> [ C:\Users\viking\spam.txt C:\Users\viking\eggs.txt ] | path split
╭───┬────────────────╮
│ 0 │ [list 4 items] │
│ 1 │ [list 4 items] │
╰───┴────────────────╯
path type
Get the type of the object a path refers to (e.g., file, dir, symlink).
This checks the file system to confirm the path's object type.
If nothing is found, an empty string will be returned.
Usage:
> path type
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
Show type of a filepath
> '.' | path type
dir
Show type of a filepaths in a list
> ls | get name | path type
port
Get a free port from system.
Search terms: network, http
Usage:
> port (start) (end)
Flags:
-h, --help - Display the help message for this command
Parameters:
start <int>: The start port to scan (inclusive). (optional)
end <int>: The end port to scan (inclusive). (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ int │
╰───┴─────────┴────────╯
Examples:
get a free port between 3121 and 4000
> port 3121 4000
3121
get a free port from system
> port
prepend
Prepend any number of rows to a table.
Be aware that this command 'unwraps' lists passed to it. So, if you pass a variable to it,
and you want the variable's contents to be prepended without being unwrapped, it's wise to
pre-emptively wrap the variable in a list, like so: `prepend [$val]`. This way, `prepend` will
only unwrap the outer list, and leave the variable's contents untouched.
Search terms: add, concatenate
Usage:
> prepend <row>
Flags:
-h, --help - Display the help message for this command
Parameters:
row <any>: The row, list, or table to prepend.
Input/output types:
╭───┬───────┬───────────╮
│ # │ input │ output │
├───┼───────┼───────────┤
│ 0 │ any │ list<any> │
╰───┴───────┴───────────╯
Examples:
prepend a list to an item
> 0 | prepend [1 2 3]
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
│ 3 │ 0 │
╰───┴───╯
Prepend a list of strings to a string
> "a" | prepend ["b"]
╭───┬───╮
│ 0 │ b │
│ 1 │ a │
╰───┴───╯
Prepend one int item
> [1 2 3 4] | prepend 0
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ 3 │
│ 4 │ 4 │
╰───┴───╯
Prepend two int items
> [2 3 4] | prepend [0 1]
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ 3 │
│ 4 │ 4 │
╰───┴───╯
Prepend ints and strings
> [2 nu 4 shell] | prepend [0 1 rocks]
╭───┬───────╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ rocks │
│ 3 │ 2 │
│ 4 │ nu │
│ 5 │ 4 │
│ 6 │ shell │
╰───┴───────╯
Prepend a range
> [3 4] | prepend 0..2
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ 3 │
│ 4 │ 4 │
╰───┴───╯
Print the given values to stdout.
Unlike `echo`, this command does not return any value (`print | describe` will return "nothing").
Since this command has no output, there is no point in piping it with other commands.
`print` may be used inside blocks of code (e.g.: hooks) to display text during execution without interfering with the pipeline.
Search terms: display
Usage:
> print {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-n, --no-newline - print without inserting a newline for the line ending
-e, --stderr - print to stderr instead of stdout
Parameters:
...rest <any>: the values to print
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
│ 1 │ any │ nothing │
╰───┴─────────┴─────────╯
Examples:
Print 'hello world'
> print "hello world"
Print the sum of 2 and 3
> print (2 + 3)
ps
View information about system processes.
Search terms: procedures, operations, tasks, ops
Usage:
> ps {flags}
Flags:
-h, --help - Display the help message for this command
-l, --long - list all available columns for each entry
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
List the system processes
> ps
List the top 5 system processes with the highest memory usage
> ps | sort-by mem | last 5
List the top 3 system processes with the highest CPU usage
> ps | sort-by cpu | last 3
List the system processes with 'nu' in their names
> ps | where name =~ 'nu'
Get the parent process id of the current nu process
> ps | where pid == $nu.pid | get ppid
query db
Query a database using SQL.
Search terms: database, SQLite
Usage:
> query db <SQL>
Flags:
-h, --help - Display the help message for this command
Parameters:
SQL <string>: SQL to execute against the database.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Execute SQL against a SQLite database
> open foo.db | query db "SELECT * FROM Bar"
random
Generate a random value.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Search terms: generate, generator
Usage:
> random
Subcommands:
random bool - Generate a random boolean value.
random chars - Generate random chars.
random dice - Generate a random dice roll.
random float - Generate a random float within a range [min..max].
random int - Generate a random integer [min..max].
random uuid - Generate a random uuid4 string.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
random bool
Generate a random boolean value.
Search terms: generate, boolean, true, false, 1, 0
Usage:
> random bool {flags}
Flags:
-h, --help - Display the help message for this command
-b, --bias <Number> - Adjusts the probability of a "true" outcome
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ bool │
╰───┴─────────┴────────╯
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.
Search terms: generate, character, symbol, alphanumeric
Usage:
> random chars {flags}
Flags:
-h, --help - Display the help message for this command
-l, --length <Int> - Number of chars
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Generate random chars
> random chars
Generate random chars with specified length
> random chars --length 20
random dice
Generate a random dice roll.
Search terms: generate, die, 1-6
Usage:
> random dice {flags}
Flags:
-h, --help - Display the help message for this command
-d, --dice <Int> - The amount of dice being rolled
-s, --sides <Int> - The amount of sides a die has
Input/output types:
╭───┬─────────┬─────────────╮
│ # │ input │ output │
├───┼─────────┼─────────────┤
│ 0 │ nothing │ list-stream │
╰───┴─────────┴─────────────╯
Examples:
Roll 1 dice with 6 sides each
> random dice
Roll 10 dice with 12 sides each
> random dice --dice 10 --sides 12
random float
Generate a random float within a range [min..max].
Search terms: generate
Usage:
> random float (range)
Flags:
-h, --help - Display the help message for this command
Parameters:
range <range>: Range of values. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ float │
╰───┴─────────┴────────╯
Examples:
Generate a default float value between 0 and 1
> random float
Generate a random float less than or equal to 500
> random float ..500
Generate a random float greater than or equal to 100000
> random float 100000..
Generate a random float between 1.0 and 1.1
> random float 1.0..1.1
random int
Generate a random integer [min..max].
Search terms: generate, natural, number
Usage:
> random int (range)
Flags:
-h, --help - Display the help message for this command
Parameters:
range <range>: Range of values. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ int │
╰───┴─────────┴────────╯
Examples:
Generate an unconstrained random integer
> random int
Generate a random integer less than or equal to 500
> random int ..500
Generate a random integer greater than or equal to 100000
> random int 100000..
Generate a random integer between 1 and 10
> random int 1..10
random uuid
Generate a random uuid4 string.
Search terms: generate, uuid4
Usage:
> random uuid
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Generate a random uuid4 string
> random uuid
range
Return only the selected rows.
Search terms: filter, head, tail
Usage:
> range <rows>
Flags:
-h, --help - Display the help message for this command
Parameters:
rows <range>: Range of rows to return.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Get the last 2 items
> [0,1,2,3,4,5] | range 4..5
╭───┬───╮
│ 0 │ 4 │
│ 1 │ 5 │
╰───┴───╯
Get the last 2 items
> [0,1,2,3,4,5] | range (-2)..
╭───┬───╮
│ 0 │ 4 │
│ 1 │ 5 │
╰───┴───╯
Get the next to last 2 items
> [0,1,2,3,4,5] | range (-3)..-2
╭───┬───╮
│ 0 │ 3 │
│ 1 │ 4 │
╰───┴───╯
reduce
Aggregate a list to a single value using an accumulator closure.
Search terms: map, fold, foldl
Usage:
> reduce {flags} <closure>
Flags:
-h, --help - Display the help message for this command
-f, --fold <Any> - reduce with initial value
Parameters:
closure <closure(any, any, int)>: Reducing function.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ any │
│ 1 │ table │ any │
│ 2 │ range │ any │
╰───┴───────────┴────────╯
Examples:
Sum values of a list (same as 'math sum')
> [ 1 2 3 4 ] | reduce {|it, acc| $it + $acc }
10
Sum values of a list, plus their indexes
> [ 8 7 6 ] | enumerate | reduce --fold 0 {|it, acc| $acc + $it.item + $it.index }
24
Sum values with a starting value (fold)
> [ 1 2 3 4 ] | reduce --fold 10 {|it, acc| $acc + $it }
20
Replace selected characters in a string with 'X'
> [ i o t ] | reduce --fold "Arthur, King of the Britons" {|it, acc| $acc | str replace --all $it "X" }
ArXhur, KXng Xf Xhe BrXXXns
Add ascending numbers to each of the filenames, and join with semicolons.
> ['foo.gz', 'bar.gz', 'baz.gz'] | enumerate | reduce --fold '' {|str all| $"($all)(if $str.index != 0 {'; '})($str.index + 1)-($str.item)" }
1-foo.gz; 2-bar.gz; 3-baz.gz
Concatenate a string with itself, using a range to determine the number of times.
> let s = "Str"; 0..2 | reduce --fold '' {|it, acc| $acc + $s}
StrStrStr
register
Register a plugin.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> register {flags} <plugin> (signature)
Flags:
-h, --help - Display the help message for this command
-s, --shell <Filepath> - path of shell used to run plugin (cmd, sh, python, etc)
Parameters:
plugin <path>: Path of executable for plugin.
signature <any>: Block with signature description as json object. (optional)
Examples:
Register `nu_plugin_query` plugin from ~/.cargo/bin/ dir
> register ~/.cargo/bin/nu_plugin_query
Register `nu_plugin_query` plugin from `nu -c` (writes/updates $nu.plugin-path)
> let plugin = ((which nu).path.0 | path dirname | path join 'nu_plugin_query'); nu -c $'register ($plugin); version'
registry query
Query the Windows registry.
Currently supported only on Windows systems.
Usage:
> registry query {flags} <key> (value)
Flags:
-h, --help - Display the help message for this command
--hkcr - query the hkey_classes_root hive
--hkcu - query the hkey_current_user hive
--hklm - query the hkey_local_machine hive
--hku - query the hkey_users hive
--hkpd - query the hkey_performance_data hive
--hkpt - query the hkey_performance_text hive
--hkpnls - query the hkey_performance_nls_text hive
--hkcc - query the hkey_current_config hive
--hkdd - query the hkey_dyn_data hive
--hkculs - query the hkey_current_user_local_settings hive
-u, --no-expand - do not expand %ENV% placeholders in REG_EXPAND_SZ
Parameters:
key <string>: Registry key to query.
value <string>: Optionally supply a registry value to query. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Query the HKEY_CURRENT_USER hive
> registry query --hkcu environment
Query the HKEY_LOCAL_MACHINE hive
> registry query --hklm 'SYSTEM\CurrentControlSet\Control\Session Manager\Environment'
reject
Remove the given columns or rows from the table. Opposite of `select`.
To remove a quantity of rows or columns, use `skip`, `drop`, or `drop column`.
Search terms: drop, key
Usage:
> reject {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-i, --ignore-errors - ignore missing data (make all cell path members optional)
Parameters:
...rest <cell-path>: The names of columns to remove from the table.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
╰───┴────────┴────────╯
Examples:
Reject a column in the `ls` table
> ls | reject modified
Reject a column in a table
> [[a, b]; [1, 2]] | reject a
╭───┬───╮
│ # │ b │
├───┼───┤
│ 0 │ 2 │
╰───┴───╯
Reject a row in a table
> [[a, b]; [1, 2] [3, 4]] | reject 1
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
╰───┴───┴───╯
Reject the specified field in a record
> {a: 1, b: 2} | reject a
╭───┬───╮
│ b │ 2 │
╰───┴───╯
Reject a nested field in a record
> {a: {b: 3, c: 5}} | reject a.b
╭───┬──────────────────╮
│ a │ {record 1 field} │
╰───┴──────────────────╯
Reject multiple rows
> [[name type size]; [Cargo.toml toml 1kb] [Cargo.lock toml 2kb] [file.json json 3kb]] | reject 0 2
Reject multiple columns
> [[name type size]; [Cargo.toml toml 1kb] [Cargo.lock toml 2kb]] | reject type size
╭───┬────────────╮
│ # │ name │
├───┼────────────┤
│ 0 │ Cargo.toml │
│ 1 │ Cargo.lock │
╰───┴────────────╯
Reject multiple columns by spreading a list
> let cols = [type size]; [[name type size]; [Cargo.toml toml 1kb] [Cargo.lock toml 2kb]] | reject ...$cols
╭───┬────────────╮
│ # │ name │
├───┼────────────┤
│ 0 │ Cargo.toml │
│ 1 │ Cargo.lock │
╰───┴────────────╯
rename
Creates a new table with columns renamed.
Usage:
> rename {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-c, --column <Record([])> - column name to be changed
-b, --block <Closure(Some([Any]))> - A closure to apply changes on each column
Parameters:
...rest <string>: The new names for the columns.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
╰───┴────────┴────────╯
Examples:
Rename a column
> [[a, b]; [1, 2]] | rename my_column
╭───┬───────────┬───╮
│ # │ my_column │ b │
├───┼───────────┼───┤
│ 0 │ 1 │ 2 │
╰───┴───────────┴───╯
Rename many columns
> [[a, b, c]; [1, 2, 3]] | rename eggs ham bacon
╭───┬──────┬─────┬───────╮
│ # │ eggs │ ham │ bacon │
├───┼──────┼─────┼───────┤
│ 0 │ 1 │ 2 │ 3 │
╰───┴──────┴─────┴───────╯
Rename a specific column
> [[a, b, c]; [1, 2, 3]] | rename --column { a: ham }
╭───┬─────┬───┬───╮
│ # │ ham │ b │ c │
├───┼─────┼───┼───┤
│ 0 │ 1 │ 2 │ 3 │
╰───┴─────┴───┴───╯
Rename the fields of a record
> {a: 1 b: 2} | rename x y
╭───┬───╮
│ x │ 1 │
│ y │ 2 │
╰───┴───╯
Rename fields based on a given closure
> {abc: 1, bbc: 2} | rename --block {str replace --all 'b' 'z'}
╭─────┬───╮
│ azc │ 1 │
│ zzc │ 2 │
╰─────┴───╯
return
Return early from a function.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> return (return_value)
Flags:
-h, --help - Display the help message for this command
Parameters:
return_value <any>: Optional value to return. (optional)
Examples:
Return early
> def foo [] { return }
reverse
Reverses the input list or table.
Search terms: convert, inverse, flip
Usage:
> reverse
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Reverse a list
> [0,1,2,3] | reverse
╭───┬───╮
│ 0 │ 3 │
│ 1 │ 2 │
│ 2 │ 1 │
│ 3 │ 0 │
╰───┴───╯
Reverse a table
> [{a: 1} {a: 2}] | reverse
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 2 │
│ 1 │ 1 │
╰───┴───╯
rm
Remove files and directories.
Search terms: delete, remove
Usage:
> rm {flags} ...(paths)
Flags:
-h, --help - Display the help message for this command
-t, --trash - move to the platform's trash instead of permanently deleting. not used on android and ios
-p, --permanent - delete permanently, ignoring the 'always_trash' config option. always enabled on android and ios
-r, --recursive - delete subdirectories recursively
-f, --force - suppress error when no file
-v, --verbose - print names of deleted files
-i, --interactive - ask user to confirm action
-I, --interactive-once - ask user to confirm action only once
Parameters:
...paths <one_of(glob, string)>: The file paths(s) to remove.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Delete, or move a file to the trash (based on the 'always_trash' config option)
> rm file.txt
Move a file to the trash
> rm --trash file.txt
Delete a file permanently, even if the 'always_trash' config option is true
> rm --permanent file.txt
Delete a file, ignoring 'file not found' errors
> rm --force file.txt
Delete all 0KB files in the current directory
> ls | where size == 0KB and type == file | each { rm $in.name } | null
run-external
Runs external command.
Usage:
> run-external {flags} <command> ...(args)
Flags:
-h, --help - Display the help message for this command
--redirect-stdout - redirect stdout to the pipeline
--redirect-stderr - redirect stderr to the pipeline
--redirect-combine - redirect both stdout and stderr combined to the pipeline (collected in stdout)
--trim-end-newline - trimming end newlines
Parameters:
command <string>: External command to run.
...args <any>: Arguments for external command.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Run an external command
> run-external "echo" "-n" "hello"
Redirect stdout from an external command into the pipeline
> run-external --redirect-stdout "echo" "-n" "hello" | split chars
save
Save a file.
Search terms: write, write_file, append, redirection, file, io, >, >>
Usage:
> save {flags} <filename>
Flags:
-h, --help - Display the help message for this command
-e, --stderr <Filepath> - the filename used to save stderr, only works with `-r` flag
-r, --raw - save file as raw binary
-a, --append - append input to the end of the file
-f, --force - overwrite the destination
-p, --progress - enable progress bar
Parameters:
filename <path>: The filename to use.
Input/output types:
╭───┬───────┬─────────╮
│ # │ input │ output │
├───┼───────┼─────────┤
│ 0 │ any │ nothing │
╰───┴───────┴─────────╯
Examples:
Save a string to foo.txt in the current directory
> 'save me' | save foo.txt
Append a string to the end of foo.txt
> 'append me' | save --append foo.txt
Save a record to foo.json in the current directory
> { a: 1, b: 2 } | save foo.json
Save a running program's stderr to foo.txt
> do -i {} | save foo.txt --stderr foo.txt
Save a running program's stderr to separate file
> do -i {} | save foo.txt --stderr bar.txt
schema
Show the schema of a SQLite database.
Search terms: database, info, SQLite
Usage:
> schema
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Show the schema of a SQLite database
> open foo.db | schema
scope
Commands for getting info about what is in scope.
Usage:
> scope
Subcommands:
scope aliases - Output info on the aliases in the current scope.
scope commands - Output info on the commands in the current scope.
scope engine-stats - Output stats on the engine in the current state.
scope externs - Output info on the known externals in the current scope.
scope modules - Output info on the modules in the current scope.
scope variables - Output info on the variables in the current scope.
Flags:
-h, --help - Display the help message for this command
scope aliases
Output info on the aliases in the current scope.
Usage:
> scope aliases
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Show the aliases in the current scope
> scope aliases
scope commands
Output info on the commands in the current scope.
Usage:
> scope commands
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Show the commands in the current scope
> scope commands
scope engine-stats
Output stats on the engine in the current state.
Usage:
> scope engine-stats
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Show the stats on the current engine state
> scope engine-stats
scope externs
Output info on the known externals in the current scope.
Usage:
> scope externs
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Show the known externals in the current scope
> scope externs
scope modules
Output info on the modules in the current scope.
Usage:
> scope modules
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Show the modules in the current scope
> scope modules
scope variables
Output info on the variables in the current scope.
Usage:
> scope variables
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Show the variables in the current scope
> scope variables
select
Select only these columns or rows from the input. Opposite of `reject`.
This differs from `get` in that, rather than accessing the given value in the data structure,
it removes all non-selected values from the structure. Hence, using `select` on a table will
produce a table, a list will produce a list, and a record will produce a record.
Search terms: pick, choose, get
Usage:
> select {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-i, --ignore-errors - ignore missing data (make all cell path members optional)
Parameters:
...rest <cell-path>: The columns to select from the table.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
│ 2 │ list<any> │ any │
╰───┴───────────┴────────╯
Examples:
Select a column in a table
> [{a: a b: b}] | select a
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ a │
╰───┴───╯
Select a field in a record
> {a: a b: b} | select a
╭───┬───╮
│ a │ a │
╰───┴───╯
Select just the `name` column
> ls | select name
Select the first four rows (this is the same as `first 4`)
> ls | select 0 1 2 3
Select multiple columns
> [[name type size]; [Cargo.toml toml 1kb] [Cargo.lock toml 2kb]] | select name type
╭───┬────────────┬──────╮
│ # │ name │ type │
├───┼────────────┼──────┤
│ 0 │ Cargo.toml │ toml │
│ 1 │ Cargo.lock │ toml │
╰───┴────────────┴──────╯
Select multiple columns by spreading a list
> let cols = [name type]; [[name type size]; [Cargo.toml toml 1kb] [Cargo.lock toml 2kb]] | select ...$cols
╭───┬────────────┬──────╮
│ # │ name │ type │
├───┼────────────┼──────┤
│ 0 │ Cargo.toml │ toml │
│ 1 │ Cargo.lock │ toml │
╰───┴────────────┴──────╯
seq
Output sequences of numbers.
Usage:
> seq ...(rest)
Subcommands:
seq char - Print a sequence of ASCII characters.
seq date - Print sequences of dates.
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <number>: Sequence values.
Input/output types:
╭───┬─────────┬──────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────┤
│ 0 │ nothing │ list<number> │
╰───┴─────────┴──────────────╯
Examples:
sequence 1 to 10
> seq 1 10
╭───┬────╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
│ 3 │ 4 │
│ 4 │ 5 │
│ 5 │ 6 │
│ 6 │ 7 │
│ 7 │ 8 │
│ 8 │ 9 │
│ 9 │ 10 │
╰───┴────╯
sequence 1.0 to 2.0 by 0.1s
> seq 1.0 0.1 2.0
╭────┬──────╮
│ 0 │ 1.00 │
│ 1 │ 1.10 │
│ 2 │ 1.20 │
│ 3 │ 1.30 │
│ 4 │ 1.40 │
│ 5 │ 1.50 │
│ 6 │ 1.60 │
│ 7 │ 1.70 │
│ 8 │ 1.80 │
│ 9 │ 1.90 │
│ 10 │ 2.00 │
╰────┴──────╯
sequence 1 to 5, then convert to a string with a pipe separator
> seq 1 5 | str join '|'
seq char
Print a sequence of ASCII characters.
Usage:
> seq char <start> <end>
Flags:
-h, --help - Display the help message for this command
Parameters:
start <string>: Start of character sequence (inclusive).
end <string>: End of character sequence (inclusive).
Input/output types:
╭───┬─────────┬──────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────┤
│ 0 │ nothing │ list<string> │
╰───┴─────────┴──────────────╯
Examples:
sequence a to e
> seq char a e
╭───┬───╮
│ 0 │ a │
│ 1 │ b │
│ 2 │ c │
│ 3 │ d │
│ 4 │ e │
╰───┴───╯
sequence a to e, and put the characters in a pipe-separated string
> seq char a e | str join '|'
seq date
Print sequences of dates.
Usage:
> seq date {flags}
Flags:
-h, --help - Display the help message for this command
-o, --output-format <String> - prints dates in this format (defaults to %Y-%m-%d)
-i, --input-format <String> - give argument dates in this format (defaults to %Y-%m-%d)
-b, --begin-date <String> - beginning date range
-e, --end-date <String> - ending date
-n, --increment <Int> - increment dates by this number
-d, --days <Int> - number of days to print
-r, --reverse - print dates in reverse
Input/output types:
╭───┬─────────┬──────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────┤
│ 0 │ nothing │ list<string> │
╰───┴─────────┴──────────────╯
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 --reverse
print the previous 10 days starting today in MM/DD/YYYY format with newline separator
> seq date --days 10 -o '%m/%d/%Y' --reverse
print the first 10 days in January, 2020
> seq date --begin-date '2020-01-01' --end-date '2020-01-10'
╭───┬────────────╮
│ 0 │ 2020-01-01 │
│ 1 │ 2020-01-02 │
│ 2 │ 2020-01-03 │
│ 3 │ 2020-01-04 │
│ 4 │ 2020-01-05 │
│ 5 │ 2020-01-06 │
│ 6 │ 2020-01-07 │
│ 7 │ 2020-01-08 │
│ 8 │ 2020-01-09 │
│ 9 │ 2020-01-10 │
╰───┴────────────╯
print every fifth day between January 1st 2020 and January 31st 2020
> seq date --begin-date '2020-01-01' --end-date '2020-01-31' --increment 5
╭───┬────────────╮
│ 0 │ 2020-01-01 │
│ 1 │ 2020-01-06 │
│ 2 │ 2020-01-11 │
│ 3 │ 2020-01-16 │
│ 4 │ 2020-01-21 │
│ 5 │ 2020-01-26 │
│ 6 │ 2020-01-31 │
╰───┴────────────╯
shuffle
Shuffle rows randomly.
Usage:
> shuffle
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Shuffle rows randomly (execute it several times and see the difference)
> [[version patch]; ['1.0.0' false] ['3.0.1' true] ['2.0.0' false]] | shuffle
skip
Skip the first several rows of the input. Counterpart of `drop`. Opposite of `first`.
To skip specific numbered rows, try `drop nth`. To skip specific named columns, try `reject`.
Search terms: ignore, remove, last, slice, tail
Usage:
> skip (n)
Subcommands:
skip until - Skip elements of the input until a predicate is true.
skip while - Skip elements of the input while a predicate is true.
Flags:
-h, --help - Display the help message for this command
Parameters:
n <int>: The number of elements to skip. (optional)
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ table │ table │
│ 1 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Skip the first value of a list
> [2 4 6 8] | skip 1
╭───┬───╮
│ 0 │ 4 │
│ 1 │ 6 │
│ 2 │ 8 │
╰───┴───╯
Skip two rows of a table
> [[editions]; [2015] [2018] [2021]] | skip 2
╭───┬──────────╮
│ # │ editions │
├───┼──────────┤
│ 0 │ 2021 │
╰───┴──────────╯
skip until
Skip elements of the input until a predicate is true.
Search terms: ignore
Usage:
> skip until <predicate>
Flags:
-h, --help - Display the help message for this command
Parameters:
predicate <closure(any, int)>: The predicate that skipped element must not match.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ table │ table │
│ 1 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Skip until the element is positive
> [-2 0 2 -1] | skip until {|x| $x > 0 }
╭───┬────╮
│ 0 │ 2 │
│ 1 │ -1 │
╰───┴────╯
Skip until the element is positive using stored condition
> let cond = {|x| $x > 0 }; [-2 0 2 -1] | skip until $cond
╭───┬────╮
│ 0 │ 2 │
│ 1 │ -1 │
╰───┴────╯
Skip until the field value is positive
> [{a: -2} {a: 0} {a: 2} {a: -1}] | skip until {|x| $x.a > 0 }
╭───┬────╮
│ # │ a │
├───┼────┤
│ 0 │ 2 │
│ 1 │ -1 │
╰───┴────╯
skip while
Skip elements of the input while a predicate is true.
Search terms: ignore
Usage:
> skip while <predicate>
Flags:
-h, --help - Display the help message for this command
Parameters:
predicate <closure(any, int)>: The predicate that skipped element must match.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ table │ table │
│ 1 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Skip while the element is negative
> [-2 0 2 -1] | skip while {|x| $x < 0 }
╭───┬────╮
│ 0 │ 0 │
│ 1 │ 2 │
│ 2 │ -1 │
╰───┴────╯
Skip while the element is negative using stored condition
> let cond = {|x| $x < 0 }; [-2 0 2 -1] | skip while $cond
╭───┬────╮
│ 0 │ 0 │
│ 1 │ 2 │
│ 2 │ -1 │
╰───┴────╯
Skip while the field value is negative
> [{a: -2} {a: 0} {a: 2} {a: -1}] | skip while {|x| $x.a < 0 }
╭───┬────╮
│ # │ a │
├───┼────┤
│ 0 │ 0 │
│ 1 │ 2 │
│ 2 │ -1 │
╰───┴────╯
sleep
Delay for a specified amount of time.
Search terms: delay, wait, timer
Usage:
> sleep <duration> ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
duration <duration>: Time to sleep.
...rest <duration>: Additional time.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Sleep for 1sec
> sleep 1sec
Sleep for 3sec
> sleep 1sec 1sec 1sec
Send output after 1sec
> sleep 1sec; echo done
sort
Sort in increasing order.
Usage:
> sort {flags}
Flags:
-h, --help - Display the help message for this command
-r, --reverse - Sort in reverse order
-i, --ignore-case - Sort string-based data case-insensitively
-v, --values - If input is a single record, sort the record by values; ignored if input is not a single record
-n, --natural - Sort alphanumeric string-based values naturally (1, 9, 10, 99, 100, ...)
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
│ 1 │ record │ record │
╰───┴───────────┴───────────╯
Examples:
sort the list by increasing value
> [2 0 1] | sort
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
╰───┴───╯
sort the list by decreasing value
> [2 0 1] | sort --reverse
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 1 │
│ 2 │ 0 │
╰───┴───╯
sort a list of strings
> [betty amy sarah] | sort
╭───┬───────╮
│ 0 │ amy │
│ 1 │ betty │
│ 2 │ sarah │
╰───┴───────╯
sort a list of strings in reverse
> [betty amy sarah] | sort --reverse
╭───┬───────╮
│ 0 │ sarah │
│ 1 │ betty │
│ 2 │ amy │
╰───┴───────╯
Sort strings (case-insensitive)
> [airplane Truck Car] | sort -i
╭───┬──────────╮
│ 0 │ airplane │
│ 1 │ Car │
│ 2 │ Truck │
╰───┴──────────╯
Sort strings (reversed case-insensitive)
> [airplane Truck Car] | sort -i -r
╭───┬──────────╮
│ 0 │ Truck │
│ 1 │ Car │
│ 2 │ airplane │
╰───┴──────────╯
Sort record by key (case-insensitive)
> {b: 3, a: 4} | sort
╭───┬───╮
│ a │ 4 │
│ b │ 3 │
╰───┴───╯
Sort record by value
> {b: 4, a: 3, c:1} | sort -v
╭───┬───╮
│ c │ 1 │
│ a │ 3 │
│ b │ 4 │
╰───┴───╯
sort-by
Sort by the given columns, in increasing order.
Usage:
> sort-by {flags} ...(columns)
Flags:
-h, --help - Display the help message for this command
-r, --reverse - Sort in reverse order
-i, --ignore-case - Sort string-based columns case-insensitively
-n, --natural - Sort alphanumeric string-based columns naturally (1, 9, 10, 99, 100, ...)
Parameters:
...columns <any>: The column(s) to sort by.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
│ 1 │ record │ table │
│ 2 │ table │ table │
╰───┴───────────┴───────────╯
Examples:
Sort files by modified date
> ls | sort-by modified
Sort files by name (case-insensitive)
> ls | sort-by name --ignore-case
Sort a table by a column (reversed order)
> [[fruit count]; [apple 9] [pear 3] [orange 7]] | sort-by fruit --reverse
╭───┬────────┬───────╮
│ # │ fruit │ count │
├───┼────────┼───────┤
│ 0 │ pear │ 3 │
│ 1 │ orange │ 7 │
│ 2 │ apple │ 9 │
╰───┴────────┴───────╯
source
Runs a script file in the current context.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> source <filename>
Flags:
-h, --help - Display the help message for this command
Parameters:
filename <path>: The filepath to the script file to source.
Examples:
Runs foo.nu in the current context
> source foo.nu
Runs foo.nu in current context and call the command defined, suppose foo.nu has content: `def say-hi [] { echo 'Hi!' }`
> source ./foo.nu; say-hi
source-env
Source the environment from a source file into the current environment.
Usage:
> source-env <filename>
Flags:
-h, --help - Display the help message for this command
Parameters:
filename <string>: The filepath to the script file to source the environment from.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Sources the environment from foo.nu in the current context
> source-env foo.nu
split
Split contents across desired subcommand (like row, column) via the separator.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> split
Subcommands:
split chars - Split a string into a list of characters.
split column - Split a string into multiple columns using a separator.
split list - Split a list into multiple lists using a separator.
split row - Split a string into multiple rows using a separator.
split words - Split a string's words into separate rows.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
split chars
Split a string into a list of characters.
Search terms: character, separate, divide
Usage:
> split chars {flags}
Flags:
-h, --help - Display the help message for this command
-g, --grapheme-clusters - split on grapheme clusters
-c, --code-points - split on code points (default; splits combined characters)
Input/output types:
╭───┬──────────────┬────────────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────────────┤
│ 0 │ string │ list<string> │
│ 1 │ list<string> │ list<list<string>> │
╰───┴──────────────┴────────────────────╯
Examples:
Split the string into a list of characters
> 'hello' | split chars
╭───┬───╮
│ 0 │ h │
│ 1 │ e │
│ 2 │ l │
│ 3 │ l │
│ 4 │ o │
╰───┴───╯
Split on grapheme clusters
> '🇯🇵ほげ' | split chars --grapheme-clusters
╭───┬────╮
│ 0 │ 🇯🇵 │
│ 1 │ ほ │
│ 2 │ げ │
╰───┴────╯
Split multiple strings into lists of characters
> ['hello', 'world'] | split chars
╭───┬────────────────╮
│ 0 │ [list 5 items] │
│ 1 │ [list 5 items] │
╰───┴────────────────╯
split column
Split a string into multiple columns using a separator.
Search terms: separate, divide, regex
Usage:
> split column {flags} <separator> ...(rest)
Flags:
-h, --help - Display the help message for this command
-c, --collapse-empty - remove empty columns
-r, --regex - separator is a regular expression
Parameters:
separator <string>: The character or string that denotes what separates columns.
...rest <string>: Column names to give the new columns.
Input/output types:
╭───┬──────────────┬────────╮
│ # │ input │ output │
├───┼──────────────┼────────┤
│ 0 │ string │ table │
│ 1 │ list<string> │ table │
╰───┴──────────────┴────────╯
Examples:
Split a string into columns by the specified separator
> 'a--b--c' | split column '--'
╭───┬─────────┬─────────┬─────────╮
│ # │ column1 │ column2 │ column3 │
├───┼─────────┼─────────┼─────────┤
│ 0 │ a │ b │ c │
╰───┴─────────┴─────────┴─────────╯
Split a string into columns of char and remove the empty columns
> 'abc' | split column --collapse-empty ''
╭───┬─────────┬─────────┬─────────╮
│ # │ column1 │ column2 │ column3 │
├───┼─────────┼─────────┼─────────┤
│ 0 │ a │ b │ c │
╰───┴─────────┴─────────┴─────────╯
Split a list of strings into a table
> ['a-b' 'c-d'] | split column -
╭───┬─────────┬─────────╮
│ # │ column1 │ column2 │
├───┼─────────┼─────────┤
│ 0 │ a │ b │
│ 1 │ c │ d │
╰───┴─────────┴─────────╯
Split a list of strings into a table, ignoring padding
> ['a - b' 'c - d'] | split column --regex '\s*-\s*'
╭───┬─────────┬─────────╮
│ # │ column1 │ column2 │
├───┼─────────┼─────────┤
│ 0 │ a │ b │
│ 1 │ c │ d │
╰───┴─────────┴─────────╯
split list
Split a list into multiple lists using a separator.
Search terms: separate, divide, regex
Usage:
> split list {flags} <separator>
Flags:
-h, --help - Display the help message for this command
-r, --regex - separator is a regular expression, matching values that can be coerced into a string
Parameters:
separator <any>: The value that denotes what separates the list.
Input/output types:
╭───┬───────────┬─────────────────╮
│ # │ input │ output │
├───┼───────────┼─────────────────┤
│ 0 │ list<any> │ list<list<any>> │
╰───┴───────────┴─────────────────╯
Examples:
Split a list of chars into two lists
> [a, b, c, d, e, f, g] | split list d
╭───┬────────────────╮
│ 0 │ [list 3 items] │
│ 1 │ [list 3 items] │
╰───┴────────────────╯
Split a list of lists into two lists of lists
> [[1,2], [2,3], [3,4]] | split list [2,3]
╭───┬───────────────╮
│ 0 │ [list 1 item] │
│ 1 │ [list 1 item] │
╰───┴───────────────╯
Split a list of chars into two lists
> [a, b, c, d, a, e, f, g] | split list a
╭───┬────────────────╮
│ 0 │ [list 3 items] │
│ 1 │ [list 3 items] │
╰───┴────────────────╯
Split a list of chars into lists based on multiple characters
> [a, b, c, d, a, e, f, g] | split list --regex '(b|e)'
╭───┬────────────────╮
│ 0 │ [list 1 item] │
│ 1 │ [list 3 items] │
│ 2 │ [list 2 items] │
╰───┴────────────────╯
split row
Split a string into multiple rows using a separator.
Search terms: separate, divide, regex
Usage:
> split row {flags} <separator>
Flags:
-h, --help - Display the help message for this command
-n, --number <Int> - Split into maximum number of items
-r, --regex - use regex syntax for separator
Parameters:
separator <string>: A character or regex that denotes what separates rows.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ list<string> │
│ 1 │ list<string> │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
Split a string into rows of char
> 'abc' | split row ''
╭───┬───╮
│ 0 │ │
│ 1 │ a │
│ 2 │ b │
│ 3 │ c │
│ 4 │ │
╰───┴───╯
Split a string into rows by the specified separator
> 'a--b--c' | split row '--'
╭───┬───╮
│ 0 │ a │
│ 1 │ b │
│ 2 │ c │
╰───┴───╯
Split a string by '-'
> '-a-b-c-' | split row '-'
╭───┬───╮
│ 0 │ │
│ 1 │ a │
│ 2 │ b │
│ 3 │ c │
│ 4 │ │
╰───┴───╯
Split a string by regex
> 'a b c' | split row -r '\s+'
╭───┬───╮
│ 0 │ a │
│ 1 │ b │
│ 2 │ c │
╰───┴───╯
split words
Split a string's words into separate rows.
Search terms: separate, divide
Usage:
> split words {flags}
Flags:
-h, --help - Display the help message for this command
-l, --min-word-length <Int> - The minimum word length
-g, --grapheme-clusters - measure word length in grapheme clusters (requires -l)
-b, --utf-8-bytes - measure word length in UTF-8 bytes (default; requires -l; non-ASCII chars are length 2+)
Input/output types:
╭───┬──────────────┬────────────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────────────┤
│ 0 │ string │ list<string> │
│ 1 │ list<string> │ list<list<string>> │
╰───┴──────────────┴────────────────────╯
Examples:
Split the string's words into separate rows
> 'hello world' | split words
╭───┬───────╮
│ 0 │ hello │
│ 1 │ world │
╰───┴───────╯
Split the string's words, of at least 3 characters, into separate rows
> 'hello to the world' | split words --min-word-length 3
╭───┬───────╮
│ 0 │ hello │
│ 1 │ the │
│ 2 │ world │
╰───┴───────╯
A real-world example of splitting words
> http get https://www.gutenberg.org/files/11/11-0.txt | str downcase | split words --min-word-length 2 | uniq --count | sort-by count --reverse | first 10
split-by
Split a record into groups.
Usage:
> split-by (splitter)
Flags:
-h, --help - Display the help message for this command
Parameters:
splitter <any>: The splitter value to use. (optional)
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ record │
╰───┴────────┴────────╯
Examples:
split items by column named "lang"
> {
'2019': [
{ name: 'andres', lang: 'rb', year: '2019' },
{ name: 'jt', lang: 'rs', year: '2019' }
],
'2021': [
{ name: 'storm', lang: 'rs', 'year': '2021' }
]
} | split-by lang
╭────┬───────────────────╮
│ rb │ {record 1 field} │
│ rs │ {record 2 fields} │
╰────┴───────────────────╯
start
Open a folder, file or website in the default application or viewer.
Search terms: load, folder, directory, run, open
Usage:
> start <path>
Flags:
-h, --help - Display the help message for this command
Parameters:
path <string>: Path to open.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
│ 1 │ string │ any │
╰───┴─────────┴────────╯
Examples:
Open a text file with the default text editor
> start file.txt
Open an image with the default image viewer
> start file.jpg
Open the current directory with the default file manager
> start .
Open a pdf with the default pdf viewer
> start file.pdf
Open a website with default browser
> start https://www.nushell.sh
stor
Various commands for working with the in-memory sqlite database.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> stor
Subcommands:
stor create - Create a table in the in-memory sqlite database.
stor delete - Delete a table or specified rows in the in-memory sqlite database.
stor export - Export the in-memory sqlite database to a sqlite database file.
stor import - Import a sqlite database file into the in-memory sqlite database.
stor insert - Insert information into a specified table in the in-memory sqlite database.
stor open - Opens the in-memory sqlite database.
stor reset - Reset the in-memory database by dropping all tables.
stor update - Update information in a specified table in the in-memory sqlite database.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
stor create
Create a table in the in-memory sqlite database.
Search terms: sqlite, storing, table
Usage:
> stor create {flags}
Flags:
-h, --help - Display the help message for this command
-t, --table-name (required parameter) String - name of the table you want to create
-c, --columns (required parameter) Record([]) - a record of column names and datatypes
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Create an in-memory sqlite database with specified table name, column names, and column data types
> stor create --table-name nudb --columns {bool1: bool, int1: int, float1: float, str1: str, datetime1: datetime}
stor delete
Delete a table or specified rows in the in-memory sqlite database.
Search terms: sqlite, remove, table, saving, drop
Usage:
> stor delete {flags}
Flags:
-h, --help - Display the help message for this command
-t, --table-name (required parameter) String - name of the table you want to insert into
-w, --where-clause <String> - a sql string to use as a where clause without the WHERE keyword
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Delete a table from the in-memory sqlite database
> stor delete --table-name nudb
Delete some rows from the in-memory sqlite database with a where clause
> stor delete --table-name nudb --where-clause "int1 == 5"
stor export
Export the in-memory sqlite database to a sqlite database file.
Search terms: sqlite, save, database, saving, file
Usage:
> stor export {flags}
Flags:
-h, --help - Display the help message for this command
-f, --file-name (required parameter) String - file name to export the sqlite in-memory database to
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Export the in-memory sqlite database
> stor export --file-name nudb.sqlite
stor import
Import a sqlite database file into the in-memory sqlite database.
Search terms: sqlite, open, database, restore, file
Usage:
> stor import {flags}
Flags:
-h, --help - Display the help message for this command
-f, --file-name (required parameter) String - file name to export the sqlite in-memory database to
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Import a sqlite database file into the in-memory sqlite database
> stor import --file-name nudb.sqlite
stor insert
Insert information into a specified table in the in-memory sqlite database.
Search terms: sqlite, storing, table, saving
Usage:
> stor insert {flags}
Flags:
-h, --help - Display the help message for this command
-t, --table-name (required parameter) String - name of the table you want to insert into
-d, --data-record (required parameter) Record([]) - a record of column names and column values to insert into the specified table
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Insert data the in-memory sqlite database using a data-record of column-name and column-value pairs
> stor insert --table-name nudb --data-record {bool1: true, int1: 5, float1: 1.1, str1: fdncred, datetime1: 2023-04-17}
stor open
Opens the in-memory sqlite database.
Search terms: sqlite, storing, access
Usage:
> stor open
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬──────────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────────┤
│ 0 │ nothing │ sqlite-in-memory │
╰───┴─────────┴──────────────────╯
Examples:
Open the in-memory sqlite database
> stor open
stor reset
Reset the in-memory database by dropping all tables.
Search terms: sqlite, remove, table, saving, drop
Usage:
> stor reset
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Reset the in-memory sqlite database
> stor reset
stor update
Update information in a specified table in the in-memory sqlite database.
Search terms: sqlite, storing, table, saving, changing
Usage:
> stor update {flags}
Flags:
-h, --help - Display the help message for this command
-t, --table-name (required parameter) String - name of the table you want to insert into
-u, --update-record (required parameter) Record([]) - a record of column names and column values to update in the specified table
-w, --where-clause <String> - a sql string to use as a where clause without the WHERE keyword
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Update the in-memory sqlite database
> stor update --table-name nudb --update-record {str1: nushell datetime1: 2020-04-17}
Update the in-memory sqlite database with a where clause
> stor update --table-name nudb --update-record {str1: nushell datetime1: 2020-04-17} --where-clause "bool1 = 1"
str
Various commands for working with string data.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> str
Subcommands:
str capitalize - Capitalize first letter of text.
str contains - Checks if string input contains a substring.
str distance - Compare two strings and return the edit distance/Levenshtein distance.
str downcase - Make text lowercase.
str ends-with - Check if an input ends with a string.
str escape-glob - Escape glob pattern.
str expand - Generates all possible combinations defined in brace expansion syntax.
str index-of - Returns start index of first occurrence of string in input, or -1 if no match.
str join - Concatenate multiple strings into a single string, with an optional separator between each.
str length - Output the length of any strings in the pipeline.
str replace - Find and replace text.
str reverse - Reverse every string in the pipeline.
str starts-with - Check if an input starts with a string.
str stats - Gather word count statistics on the text.
str substring - Get part of a string. Note that the start is included but the end is excluded, and that the first character of a string is index 0.
str trim - Trim whitespace or specific character.
str upcase - Make text uppercase.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
str capitalize
Capitalize first letter of text.
Search terms: convert, style, caps, upper
Usage:
> str capitalize ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, convert strings at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Capitalize contents
> 'good day' | str capitalize
Good day
Capitalize contents
> 'anton' | str capitalize
Anton
Capitalize a column in a table
> [[lang, gems]; [nu_test, 100]] | str capitalize lang
╭───┬─────────┬──────╮
│ # │ lang │ gems │
├───┼─────────┼──────┤
│ 0 │ Nu_test │ 100 │
╰───┴─────────┴──────╯
str contains
Checks if string input contains a substring.
Search terms: substring, match, find, search
Usage:
> str contains {flags} <string> ...(rest)
Flags:
-h, --help - Display the help message for this command
-i, --ignore-case - search is case insensitive
-n, --not - does not contain
Parameters:
string <string>: The substring to find.
...rest <cell-path>: For a data structure input, check strings at the given cell paths, and replace with result.
Input/output types:
╭───┬──────────────┬────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────┤
│ 0 │ string │ bool │
│ 1 │ table │ table │
│ 2 │ record │ record │
│ 3 │ list<string> │ list<bool> │
╰───┴──────────────┴────────────╯
Examples:
Check if input contains string
> 'my_library.rb' | str contains '.rb'
true
Check if input contains string case insensitive
> 'my_library.rb' | str contains --ignore-case '.RB'
true
Check if input contains string in a record
> { ColA: test, ColB: 100 } | str contains 'e' ColA
╭──────┬──────╮
│ ColA │ true │
│ ColB │ 100 │
╰──────┴──────╯
Check if input contains string in a table
> [[ColA ColB]; [test 100]] | str contains --ignore-case 'E' ColA
╭───┬──────┬──────╮
│ # │ ColA │ ColB │
├───┼──────┼──────┤
│ 0 │ true │ 100 │
╰───┴──────┴──────╯
Check if input contains string in a table
> [[ColA ColB]; [test hello]] | str contains 'e' ColA ColB
╭───┬──────┬──────╮
│ # │ ColA │ ColB │
├───┼──────┼──────┤
│ 0 │ true │ true │
╰───┴──────┴──────╯
Check if input string contains 'banana'
> 'hello' | str contains 'banana'
false
Check if list contains string
> [one two three] | str contains o
╭───┬───────╮
│ 0 │ true │
│ 1 │ true │
│ 2 │ false │
╰───┴───────╯
Check if list does not contain string
> [one two three] | str contains --not o
╭───┬───────╮
│ 0 │ false │
│ 1 │ false │
│ 2 │ true │
╰───┴───────╯
str distance
Compare two strings and return the edit distance/Levenshtein distance.
Search terms: edit, levenshtein
Usage:
> str distance <compare-string> ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
compare-string <string>: The first string to compare.
...rest <cell-path>: For a data structure input, check strings at the given cell paths, and replace with result.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ int │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
get the edit distance between two strings
> 'nushell' | str distance 'nutshell'
1
Compute edit distance between strings in table and another string, using cell paths
> [{a: 'nutshell' b: 'numetal'}] | str distance 'nushell' 'a' 'b'
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 4 │
╰───┴───┴───╯
Compute edit distance between strings in record and another string, using cell paths
> {a: 'nutshell' b: 'numetal'} | str distance 'nushell' a b
╭───┬───╮
│ a │ 1 │
│ b │ 4 │
╰───┴───╯
str downcase
Make text lowercase.
Search terms: lower case, lowercase
Usage:
> str downcase ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, convert strings at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Downcase contents
> 'NU' | str downcase
nu
Downcase contents
> 'TESTa' | str downcase
testa
Downcase contents
> [[ColA ColB]; [Test ABC]] | str downcase ColA
╭───┬──────┬──────╮
│ # │ ColA │ ColB │
├───┼──────┼──────┤
│ 0 │ test │ ABC │
╰───┴──────┴──────╯
Downcase contents
> [[ColA ColB]; [Test ABC]] | str downcase ColA ColB
╭───┬──────┬──────╮
│ # │ ColA │ ColB │
├───┼──────┼──────┤
│ 0 │ test │ abc │
╰───┴──────┴──────╯
str ends-with
Check if an input ends with a string.
Search terms: suffix, match, find, search
Usage:
> str ends-with {flags} <string> ...(rest)
Flags:
-h, --help - Display the help message for this command
-i, --ignore-case - search is case insensitive
Parameters:
string <string>: The string to match.
...rest <cell-path>: For a data structure input, check strings at the given cell paths, and replace with result.
Input/output types:
╭───┬──────────────┬────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────┤
│ 0 │ string │ bool │
│ 1 │ list<string> │ list<bool> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴────────────╯
Examples:
Checks if string ends with '.rb'
> 'my_library.rb' | str ends-with '.rb'
true
Checks if strings end with '.txt'
> ['my_library.rb', 'README.txt'] | str ends-with '.txt'
╭───┬───────╮
│ 0 │ false │
│ 1 │ true │
╰───┴───────╯
Checks if string ends with '.RB', case-insensitive
> 'my_library.rb' | str ends-with --ignore-case '.RB'
true
str escape-glob
Escape glob pattern.
Search terms: pattern, list, ls
Usage:
> str escape-glob ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, turn strings at the given cell paths into substrings.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
escape glob pattern before list
> let f = 'test[a]'; ls ($f | str escape-glob)
str expand
Generates all possible combinations defined in brace expansion syntax.
This syntax may seem familiar with `glob {A,B}.C`. The difference is glob relies on filesystem, but str expand is not. Inside braces, we put variants. Then basically we're creating all possible outcomes.
Usage:
> str expand {flags}
Flags:
-h, --help - Display the help message for this command
--path - Replaces all backslashes with double backslashes, useful for Path.
Input/output types:
╭───┬──────────────┬────────────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────────────┤
│ 0 │ string │ list<string> │
│ 1 │ list<string> │ list<list<string>> │
╰───┴──────────────┴────────────────────╯
Examples:
Define a range inside braces to produce a list of string.
> "{3..5}" | str expand
╭───┬───╮
│ 0 │ 3 │
│ 1 │ 4 │
│ 2 │ 5 │
╰───┴───╯
Ignore the next character after the backslash ('\')
> 'A{B\,,C}' | str expand
╭───┬─────╮
│ 0 │ AB, │
│ 1 │ AC │
╰───┴─────╯
Commas that are not inside any braces need to be skipped.
> 'Welcome\, {home,mon ami}!' | str expand
╭───┬───────────────────╮
│ 0 │ Welcome, home! │
│ 1 │ Welcome, mon ami! │
╰───┴───────────────────╯
Use double backslashes to add a backslash.
> 'A{B\\,C}' | str expand
╭───┬─────╮
│ 0 │ AB\ │
│ 1 │ AC │
╰───┴─────╯
Export comma separated values inside braces (`{}`) to a string list.
> "{apple,banana,cherry}" | str expand
╭───┬────────╮
│ 0 │ apple │
│ 1 │ banana │
│ 2 │ cherry │
╰───┴────────╯
If the piped data is path, you may want to use --path flag, or else manually replace the backslashes with double backslashes.
> 'C:\{Users,Windows}' | str expand --path
╭───┬────────────╮
│ 0 │ C:\Users │
│ 1 │ C:\Windows │
╰───┴────────────╯
Brace expressions can be used one after another.
> "A{b,c}D{e,f}G" | str expand
╭───┬───────╮
│ 0 │ AbDeG │
│ 1 │ AbDfG │
│ 2 │ AcDeG │
│ 3 │ AcDfG │
╰───┴───────╯
Collection may include an empty item. It can be put at the start of the list.
> "A{,B,C}" | str expand
╭───┬────╮
│ 0 │ A │
│ 1 │ AB │
│ 2 │ AC │
╰───┴────╯
Empty item can be at the end of the collection.
> "A{B,C,}" | str expand
╭───┬────╮
│ 0 │ AB │
│ 1 │ AC │
│ 2 │ A │
╰───┴────╯
Empty item can be in the middle of the collection.
> "A{B,,C}" | str expand
╭───┬────╮
│ 0 │ AB │
│ 1 │ A │
│ 2 │ AC │
╰───┴────╯
Also, it is possible to use one inside another. Here is a real-world example, that creates files:
> "A{B{1,3},C{2,5}}D" | str expand
╭───┬──────╮
│ 0 │ AB1D │
│ 1 │ AB3D │
│ 2 │ AC2D │
│ 3 │ AC5D │
╰───┴──────╯
str index-of
Returns start index of first occurrence of string in input, or -1 if no match.
Search terms: match, find, search
Usage:
> str index-of {flags} <string> ...(rest)
Flags:
-h, --help - Display the help message for this command
-g, --grapheme-clusters - count indexes using grapheme clusters (all visible chars have length 1)
-b, --utf-8-bytes - count indexes using UTF-8 bytes (default; non-ASCII chars have length 2+)
-r, --range <Range> - optional start and/or end index
-e, --end - search from the end of the input
Parameters:
string <string>: The string to find in the input.
...rest <cell-path>: For a data structure input, search strings at the given cell paths, and replace with result.
Input/output types:
╭───┬──────────────┬───────────╮
│ # │ input │ output │
├───┼──────────────┼───────────┤
│ 0 │ string │ int │
│ 1 │ list<string> │ list<int> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴───────────╯
Examples:
Returns index of string in input
> 'my_library.rb' | str index-of '.rb'
10
Count length using grapheme clusters
> '🇯🇵ほげ ふが ぴよ' | str index-of --grapheme-clusters 'ふが'
4
Returns index of string in input within a`rhs open range`
> '.rb.rb' | str index-of '.rb' --range 1..
3
Returns index of string in input within a lhs open range
> '123456' | str index-of '6' --range ..4
-1
Returns index of string in input within a range
> '123456' | str index-of '3' --range 1..4
2
Returns index of string in input
> '/this/is/some/path/file.txt' | str index-of '/' -e
18
str join
Concatenate multiple strings into a single string, with an optional separator between each.
Search terms: collect, concatenate
Usage:
> str join (separator)
Flags:
-h, --help - Display the help message for this command
Parameters:
separator <string>: Optional separator to use when creating string. (optional)
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ string │
│ 1 │ string │ string │
╰───┴───────────┴────────╯
Examples:
Create a string from input
> ['nu', 'shell'] | str join
nushell
Create a string from input with a separator
> ['nu', 'shell'] | str join '-'
nu-shell
str length
Output the length of any strings in the pipeline.
Search terms: size, count
Usage:
> str length {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-g, --grapheme-clusters - count length using grapheme clusters (all visible chars have length 1)
-b, --utf-8-bytes - count length using UTF-8 bytes (default; all non-ASCII chars have length 2+)
Parameters:
...rest <cell-path>: For a data structure input, replace strings at the given cell paths with their length.
Input/output types:
╭───┬──────────────┬───────────╮
│ # │ input │ output │
├───┼──────────────┼───────────┤
│ 0 │ string │ int │
│ 1 │ list<string> │ list<int> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴───────────╯
Examples:
Return the lengths of a string
> 'hello' | str length
5
Count length using grapheme clusters
> '🇯🇵ほげ ふが ぴよ' | str length --grapheme-clusters
9
Return the lengths of multiple strings
> ['hi' 'there'] | str length
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 5 │
╰───┴───╯
str replace
Find and replace text.
Search terms: search, shift, switch, regex
Usage:
> str replace {flags} <find> <replace> ...(rest)
Flags:
-h, --help - Display the help message for this command
-a, --all - replace all occurrences of the pattern
-n, --no-expand - do not expand capture groups (like $name) in the replacement string
-r, --regex - match the pattern as a regular expression in the input, instead of a substring
-m, --multiline - multi-line regex mode (implies --regex): ^ and $ match begin/end of line; equivalent to (?m)
Parameters:
find <string>: The pattern to find.
replace <string>: The replacement string.
...rest <cell-path>: For a data structure input, operate on strings at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ table │ table │
│ 2 │ record │ record │
│ 3 │ list<string> │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
Find and replace the first occurrence of a substring
> 'c:\some\cool\path' | str replace 'c:\some\cool' '~'
~\path
Find and replace all occurrences of a substring
> 'abc abc abc' | str replace --all 'b' 'z'
azc azc azc
Find and replace contents with capture group using regular expression
> 'my_library.rb' | str replace -r '(.+).rb' '$1.nu'
my_library.nu
Find and replace all occurrences of find string using regular expression
> 'abc abc abc' | str replace --all --regex 'b' 'z'
azc azc azc
Find and replace all occurrences of find string in table using regular expression
> [[ColA ColB ColC]; [abc abc ads]] | str replace --all --regex 'b' 'z' ColA ColC
╭───┬──────┬──────┬──────╮
│ # │ ColA │ ColB │ ColC │
├───┼──────┼──────┼──────┤
│ 0 │ azc │ abc │ ads │
╰───┴──────┴──────┴──────╯
Find and replace all occurrences of find string in record using regular expression
> { KeyA: abc, KeyB: abc, KeyC: ads } | str replace --all --regex 'b' 'z' KeyA KeyC
╭──────┬─────╮
│ KeyA │ azc │
│ KeyB │ abc │
│ KeyC │ ads │
╰──────┴─────╯
Find and replace contents without using the replace parameter as a regular expression
> 'dogs_$1_cats' | str replace -r '\$1' '$2' -n
dogs_$2_cats
Use captures to manipulate the input text using regular expression
> "abc-def" | str replace -r "(.+)-(.+)" "${2}_${1}"
def_abc
Find and replace with fancy-regex using regular expression
> 'a successful b' | str replace -r '\b([sS])uc(?:cs|s?)e(ed(?:ed|ing|s?)|ss(?:es|ful(?:ly)?|i(?:ons?|ve(?:ly)?)|ors?)?)\b' '${1}ucce$2'
a successful b
Find and replace with fancy-regex using regular expression
> 'GHIKK-9+*' | str replace -r '[*[:xdigit:]+]' 'z'
GHIKK-z+*
Find and replace on individual lines using multiline regular expression
> "non-matching line\n123. one line\n124. another line\n" | str replace --all --multiline '^[0-9]+\. ' ''
non-matching line
one line
another line
str reverse
Reverse every string in the pipeline.
Search terms: convert, inverse, flip
Usage:
> str reverse ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, reverse strings at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Reverse a single string
> 'Nushell' | str reverse
llehsuN
Reverse multiple strings in a list
> ['Nushell' 'is' 'cool'] | str reverse
╭───┬─────────╮
│ 0 │ llehsuN │
│ 1 │ si │
│ 2 │ looc │
╰───┴─────────╯
str starts-with
Check if an input starts with a string.
Search terms: prefix, match, find, search
Usage:
> str starts-with {flags} <string> ...(rest)
Flags:
-h, --help - Display the help message for this command
-i, --ignore-case - search is case insensitive
Parameters:
string <string>: The string to match.
...rest <cell-path>: For a data structure input, check strings at the given cell paths, and replace with result.
Input/output types:
╭───┬──────────────┬────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────┤
│ 0 │ string │ bool │
│ 1 │ list<string> │ list<bool> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴────────────╯
Examples:
Checks if input string starts with 'my'
> 'my_library.rb' | str starts-with 'my'
true
Checks if input string starts with 'Car'
> 'Cargo.toml' | str starts-with 'Car'
true
Checks if input string starts with '.toml'
> 'Cargo.toml' | str starts-with '.toml'
false
Checks if input string starts with 'cargo', case-insensitive
> 'Cargo.toml' | str starts-with --ignore-case 'cargo'
true
str stats
Gather word count statistics on the text.
Search terms: count, word, character, unicode, wc
Usage:
> str stats
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ record │
╰───┴────────┴────────╯
Examples:
Count the number of words in a string
> "There are seven words in this sentence" | str stats
╭───────────┬────╮
│ lines │ 1 │
│ words │ 7 │
│ bytes │ 38 │
│ chars │ 38 │
│ graphemes │ 38 │
╰───────────┴────╯
Counts unicode characters
> '今天天气真好' | str stats
╭───────────┬────╮
│ lines │ 1 │
│ words │ 6 │
│ bytes │ 18 │
│ chars │ 6 │
│ graphemes │ 6 │
╰───────────┴────╯
Counts Unicode characters correctly in a string
> "Amélie Amelie" | str stats
╭───────────┬────╮
│ lines │ 1 │
│ words │ 2 │
│ bytes │ 15 │
│ chars │ 14 │
│ graphemes │ 13 │
╰───────────┴────╯
str substring
Get part of a string. Note that the start is included but the end is excluded, and that the first character of a string is index 0.
Search terms: slice
Usage:
> str substring {flags} <range> ...(rest)
Flags:
-h, --help - Display the help message for this command
-g, --grapheme-clusters - count indexes and split using grapheme clusters (all visible chars have length 1)
-b, --utf-8-bytes - count indexes and split using UTF-8 bytes (default; non-ASCII chars have length 2+)
Parameters:
range <any>: The indexes to substring [start end].
...rest <cell-path>: For a data structure input, turn strings at the given cell paths into substrings.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Get a substring "nushell" from the text "good nushell" using a range
> 'good nushell' | str substring 5..12
nushell
Count indexes and split using grapheme clusters
> '🇯🇵ほげ ふが ぴよ' | str substring --grapheme-clusters 4..6
ふが
str trim
Trim whitespace or specific character.
Search terms: whitespace, strip, lstrip, rstrip
Usage:
> str trim {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-c, --char <String> - character to trim (default: whitespace)
-l, --left - trims characters only from the beginning of the string
-r, --right - trims characters only from the end of the string
Parameters:
...rest <cell-path>: For a data structure input, trim strings at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Trim whitespace
> 'Nu shell ' | str trim
Nu shell
Trim a specific character (not the whitespace)
> '=== Nu shell ===' | str trim --char '='
Nu shell
Trim whitespace from the beginning of string
> ' Nu shell ' | str trim --left
Nu shell
Trim whitespace from the end of string
> ' Nu shell ' | str trim --right
Nu shell
Trim a specific character only from the end of the string
> '=== Nu shell ===' | str trim --right --char '='
=== Nu shell
str upcase
Make text uppercase.
Search terms: uppercase, upper case
Usage:
> str upcase ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, convert strings at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Upcase contents
> 'nu' | str upcase
NU
sys
View information about the system.
Usage:
> sys
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
Show info about the system
> sys
Show the os system name with get
> (sys).host | get name
Show the os system name
> (sys).host.name
table
Render the table.
If the table contains a column called 'index', this column is used as the table index instead of the usual continuous index.
Search terms: display, render
Usage:
> table {flags}
Flags:
-h, --help - Display the help message for this command
-t, --theme <String> - set a table mode/theme
-i, --index <Any> - enable (true) or disable (false) the #/index column or set the starting index
-w, --width <Int> - number of terminal columns wide (not output columns)
-e, --expand - expand the table structure in a light mode
-d, --expand-deep <Int> - an expand limit of recursion which will take place, must be used with --expand
--flatten - Flatten simple arrays
--flatten-separator <String> - sets a separator when 'flatten' used
-c, --collapse - expand the table structure in collapse mode.
Be aware collapse mode currently doesn't support width control
-a, --abbreviated <Int> - abbreviate the data in the table by truncating the middle part and only showing amount provided on top and bottom
-l, --list - list available table modes/themes
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
List the files in current directory, with indexes starting from 1
> ls | table --index 1
Render data in table view
> [[a b]; [1 2] [3 4]] | table
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Render data in table view (expanded)
> [[a b]; [1 2] [2 [4 4]]] | table --expand
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Render data in table view (collapsed)
> [[a b]; [1 2] [2 [4 4]]] | table --collapse
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Change the table theme to the specified theme for a single run
> [[a b]; [1 2] [2 [4 4]]] | table --theme basic
Force showing of the #/index column for a single run
> [[a b]; [1 2] [2 [4 4]]] | table -i true
Set the starting number of the #/index column to 100 for a single run
> [[a b]; [1 2] [2 [4 4]]] | table -i 100
Force hiding of the #/index column for a single run
> [[a b]; [1 2] [2 [4 4]]] | table -i false
take
Take only the first n elements of a list, or the first n bytes of a binary value.
Search terms: first, slice, head
Usage:
> take <n>
Subcommands:
take until - Take elements of the input until a predicate is true.
take while - Take elements of the input while a predicate is true.
Flags:
-h, --help - Display the help message for this command
Parameters:
n <int>: Starting from the front, the number of elements to return.
Input/output types:
╭───┬───────────┬──────────────╮
│ # │ input │ output │
├───┼───────────┼──────────────┤
│ 0 │ table │ table │
│ 1 │ list<any> │ list<any> │
│ 2 │ binary │ binary │
│ 3 │ range │ list<number> │
╰───┴───────────┴──────────────╯
Examples:
Return the first item of a list/table
> [1 2 3] | take 1
╭───┬───╮
│ 0 │ 1 │
╰───┴───╯
Return the first 2 items of a list/table
> [1 2 3] | take 2
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
╰───┴───╯
Return the first two rows of a table
> [[editions]; [2015] [2018] [2021]] | take 2
╭───┬──────────╮
│ # │ editions │
├───┼──────────┤
│ 0 │ 2015 │
│ 1 │ 2018 │
╰───┴──────────╯
Return the first 2 bytes of a binary value
> 0x[01 23 45] | take 2
#
Return the first 3 elements of a range
> 1..10 | take 3
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
╰───┴───╯
take until
Take elements of the input until a predicate is true.
Usage:
> take until <predicate>
Flags:
-h, --help - Display the help message for this command
Parameters:
predicate <closure(any, int)>: The predicate that element(s) must not match.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ table │ table │
│ 1 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Take until the element is positive
> [-1 -2 9 1] | take until {|x| $x > 0 }
╭───┬────╮
│ 0 │ -1 │
│ 1 │ -2 │
╰───┴────╯
Take until the element is positive using stored condition
> let cond = {|x| $x > 0 }; [-1 -2 9 1] | take until $cond
╭───┬────╮
│ 0 │ -1 │
│ 1 │ -2 │
╰───┴────╯
Take until the field value is positive
> [{a: -1} {a: -2} {a: 9} {a: 1}] | take until {|x| $x.a > 0 }
╭───┬────╮
│ # │ a │
├───┼────┤
│ 0 │ -1 │
│ 1 │ -2 │
╰───┴────╯
take while
Take elements of the input while a predicate is true.
Usage:
> take while <predicate>
Flags:
-h, --help - Display the help message for this command
Parameters:
predicate <closure(any, int)>: The predicate that element(s) must match.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ table │ table │
│ 1 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Take while the element is negative
> [-1 -2 9 1] | take while {|x| $x < 0 }
╭───┬────╮
│ 0 │ -1 │
│ 1 │ -2 │
╰───┴────╯
Take while the element is negative using stored condition
> let cond = {|x| $x < 0 }; [-1 -2 9 1] | take while $cond
╭───┬────╮
│ 0 │ -1 │
│ 1 │ -2 │
╰───┴────╯
Take while the field value is negative
> [{a: -1} {a: -2} {a: 9} {a: 1}] | take while {|x| $x.a < 0 }
╭───┬────╮
│ # │ a │
├───┼────┤
│ 0 │ -1 │
│ 1 │ -2 │
╰───┴────╯
tee
Copy a stream to another command in parallel.
This is useful for doing something else with a stream while still continuing to
use it in your pipeline.
Usage:
> tee {flags} <closure>
Flags:
-h, --help - Display the help message for this command
-e, --stderr - For external commands: copy the standard error stream instead.
Parameters:
closure <closure()>: The other command to send the stream to.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Save a webpage to a file while also printing it
> http get http://example.org/ | tee { save example.html }
Save error messages from an external command to a file without redirecting them
> do { nu --commands 'print -e error; print ok' } | tee --stderr { save error.log } | complete
Print numbers and their sum
> 1..100 | tee { each { print } } | math sum | wrap sum
term size
Returns a record containing the number of columns (width) and rows (height) of the terminal.
Usage:
> term size
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬─────────────────────────────────╮
│ # │ input │ output │
├───┼─────────┼─────────────────────────────────┤
│ 0 │ nothing │ record<columns: int, rows: int> │
╰───┴─────────┴─────────────────────────────────╯
Examples:
Return the columns (width) and rows (height) of the terminal
> term size
Return the columns (width) of the terminal
> (term size).columns
Return the rows (height) of the terminal
> (term size).rows
timeit
Time the running time of a block.
Search terms: timing, timer, benchmark, measure
Usage:
> timeit <command>
Flags:
-h, --help - Display the help message for this command
Parameters:
command <one_of(block, expression)>: The command or block to run.
Input/output types:
╭───┬─────────┬──────────╮
│ # │ input │ output │
├───┼─────────┼──────────┤
│ 0 │ any │ duration │
│ 1 │ nothing │ duration │
╰───┴─────────┴──────────╯
Examples:
Times a command within a closure
> timeit { sleep 500ms }
Times a command using an existing input
> http get https://www.nushell.sh/book/ | timeit { split chars }
Times a command invocation
> timeit ls -la
to
Translate structured data to a format.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> to
Subcommands:
to csv - Convert table into .csv text .
to json - Converts table data into JSON text.
to md - Convert table into simple Markdown.
to nuon - Converts table data into Nuon (Nushell Object Notation) text.
to text - Converts data into simple text.
to toml - Convert record into .toml text.
to tsv - Convert table into .tsv text.
to xml - Convert special record structure into .xml text.
to yaml - Convert table into .yaml/.yml text.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
to csv
Convert table into .csv text .
Usage:
> to csv {flags}
Flags:
-h, --help - Display the help message for this command
-s, --separator <String> - a character to separate columns, defaults to ','
-n, --noheaders - do not output the columns names as the first row
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ string │
│ 1 │ table │ string │
╰───┴────────┴────────╯
Examples:
Outputs an CSV string representing the contents of this table
> [[foo bar]; [1 2]] | to csv
foo,bar
1,2
Outputs an CSV string representing the contents of this table
> [[foo bar]; [1 2]] | to csv --separator ';'
foo;bar
1;2
Outputs an CSV string representing the contents of this record
> {a: 1 b: 2} | to csv
a,b
1,2
to json
Converts table data into JSON text.
Usage:
> to json {flags}
Flags:
-h, --help - Display the help message for this command
-r, --raw - remove all of the whitespace
-i, --indent <Number> - specify indentation width
-t, --tabs <Number> - specify indentation tab quantity
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ string │
╰───┴───────┴────────╯
Examples:
Outputs a JSON string, with default indentation, representing the contents of this table
> [a b c] | to json
[
"a",
"b",
"c"
]
Outputs a JSON string, with 4-space indentation, representing the contents of this table
> [Joe Bob Sam] | to json --indent 4
[
"Joe",
"Bob",
"Sam"
]
Outputs an unformatted JSON string representing the contents of this table
> [1 2 3] | to json -r
[1,2,3]
to md
Convert table into simple Markdown.
Usage:
> to md {flags}
Flags:
-h, --help - Display the help message for this command
-p, --pretty - Formats the Markdown table to vertically align items
-e, --per-element - treat each row as markdown syntax element
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ string │
╰───┴───────┴────────╯
Examples:
Outputs an MD string representing the contents of this table
> [[foo bar]; [1 2]] | to md
|foo|bar|
|-|-|
|1|2|
Optionally, output a formatted markdown string
> [[foo bar]; [1 2]] | to md --pretty
| foo | bar |
| --- | --- |
| 1 | 2 |
Treat each row as a markdown element
> [{"H1": "Welcome to Nushell" } [[foo bar]; [1 2]]] | to md --per-element --pretty
# Welcome to Nushell
| foo | bar |
| --- | --- |
| 1 | 2 |
Render a list
> [0 1 2] | to md --pretty
0
1
2
to nuon
Converts table data into Nuon (Nushell Object Notation) text.
Usage:
> to nuon {flags}
Flags:
-h, --help - Display the help message for this command
-r, --raw - remove all of the whitespace (default behaviour and overwrites -i and -t)
-i, --indent <Number> - specify indentation width
-t, --tabs <Number> - specify indentation tab quantity
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ string │
╰───┴───────┴────────╯
Examples:
Outputs a NUON string representing the contents of this list, compact by default
> [1 2 3] | to nuon
[1, 2, 3]
Outputs a NUON array of ints, with pretty indentation
> [1 2 3] | to nuon --indent 2
[
1,
2,
3
]
Overwrite any set option with --raw
> [1 2 3] | to nuon --indent 2 --raw
[1, 2, 3]
A more complex record with multiple data types
> {date: 2000-01-01, data: [1 [2 3] 4.56]} | to nuon --indent 2
{
date: 2000-01-01T00:00:00+00:00,
data: [
1,
[
2,
3
],
4.56
]
}
to text
Converts data into simple text.
Usage:
> to text
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ string │
╰───┴───────┴────────╯
Examples:
Outputs data as simple text
> 1 | to text
1
Outputs external data as simple text
> git help -a | lines | find -r '^ ' | to text
Outputs records as simple text
> ls | to text
to toml
Convert record into .toml text.
Usage:
> to toml
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ string │
╰───┴────────┴────────╯
Examples:
Outputs an TOML string representing the contents of this record
> {foo: 1 bar: 'qwe'} | to toml
bar = "qwe"
foo = 1
to tsv
Convert table into .tsv text.
Usage:
> to tsv {flags}
Flags:
-h, --help - Display the help message for this command
-n, --noheaders - do not output the column names as the first row
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ string │
│ 1 │ table │ string │
╰───┴────────┴────────╯
Examples:
Outputs an TSV string representing the contents of this table
> [[foo bar]; [1 2]] | to tsv
foobar
12
Outputs an TSV string representing the contents of this record
> {a: 1 b: 2} | to tsv
ab
12
to xml
Convert special record structure into .xml text.
Every XML entry is represented via a record with tag, attribute and content fields.
To represent different types of entries different values must be written to this fields:
1. Tag entry: `{tag: <tag name> attributes: {<attr name>: "<string value>" ...} content: [<entries>]}`
2. Comment entry: `{tag: '!' attributes: null content: "<comment string>"}`
3. Processing instruction (PI): `{tag: '?<pi name>' attributes: null content: "<pi content string>"}`
4. Text: `{tag: null attributes: null content: "<text>"}`. Or as plain `<text>` instead of record.
Additionally any field which is: empty record, empty list or null, can be omitted.
Usage:
> to xml {flags}
Flags:
-h, --help - Display the help message for this command
-i, --indent <Int> - Formats the XML text with the provided indentation setting
-p, --partial-escape - Only escape mandatory characters in text and attributes
-s, --self-closed - Output empty tags as self closing
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ string │
╰───┴────────┴────────╯
Examples:
Outputs an XML string representing the contents of this table
> {tag: note attributes: {} content : [{tag: remember attributes: {} content : [{tag: null attributes: null content : Event}]}]} | to xml
<note><remember>Event</remember></note>
When formatting xml null and empty record fields can be omitted and strings can be written without a wrapping record
> {tag: note content : [{tag: remember content : [Event]}]} | to xml
<note><remember>Event</remember></note>
Optionally, formats the text with a custom indentation setting
> {tag: note content : [{tag: remember content : [Event]}]} | to xml --indent 3
<note>
<remember>Event</remember>
</note>
Produce less escaping sequences in resulting xml
> {tag: note attributes: {a: "'qwe'\\"} content: ["\"'"]} | to xml --partial-escape
<note a="'qwe'\">"'</note>
Save space using self-closed tags
> {tag: root content: [[tag]; [a] [b] [c]]} | to xml --self-closed
<root><a/><b/><c/></root>
to yaml
Convert table into .yaml/.yml text.
Usage:
> to yaml
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ string │
╰───┴───────┴────────╯
Examples:
Outputs an YAML string representing the contents of this table
> [[foo bar]; ["1" "2"]] | to yaml
- foo: '1'
bar: '2'
touch
Creates one or more files.
Search terms: create, file
Usage:
> touch {flags} ...(files)
Flags:
-h, --help - Display the help message for this command
-r, --reference <String> - change the file or directory time to the time of the reference file/directory
-m, --modified - change the modification time of the file or directory. If no timestamp, date or reference file/directory is given, the current time is used
-a, --access - change the access time of the file or directory. If no timestamp, date or reference file/directory is given, the current time is used
-c, --no-create - do not create the file if it does not exist
Parameters:
...files <path>: The file(s) to create.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Creates "fixture.json"
> touch fixture.json
Creates files a, b and c
> touch a b c
Changes the last modified time of "fixture.json" to today's date
> touch -m fixture.json
Changes the last modified time of files a, b and c to a date
> touch -m -d "yesterday" a b c
Changes the last modified time of file d and e to "fixture.json"'s last modified time
> touch -m -r fixture.json d e
Changes the last accessed time of "fixture.json" to a date
> touch -a -d "August 24, 2019; 12:30:30" fixture.json
transpose
Transposes the table contents so rows become columns and columns become rows.
Search terms: pivot
Usage:
> transpose {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-r, --header-row - treat the first row as column names
-i, --ignore-titles - don't transpose the column names into values
-d, --as-record - transfer to record if the result is a table and contains only one row
-l, --keep-last - on repetition of record fields due to `header-row`, keep the last value obtained
-a, --keep-all - on repetition of record fields due to `header-row`, keep all the values obtained
Parameters:
...rest <string>: The names to give columns once transposed.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ table │ any │
│ 1 │ record │ table │
╰───┴────────┴────────╯
Examples:
Transposes the table contents with default column names
> [[c1 c2]; [1 2]] | transpose
╭───┬─────────┬─────────╮
│ # │ column0 │ column1 │
├───┼─────────┼─────────┤
│ 0 │ c1 │ 1 │
│ 1 │ c2 │ 2 │
╰───┴─────────┴─────────╯
Transposes the table contents with specified column names
> [[c1 c2]; [1 2]] | transpose key val
╭───┬─────┬─────╮
│ # │ key │ val │
├───┼─────┼─────┤
│ 0 │ c1 │ 1 │
│ 1 │ c2 │ 2 │
╰───┴─────┴─────╯
Transposes the table without column names and specify a new column name
> [[c1 c2]; [1 2]] | transpose --ignore-titles val
╭───┬─────╮
│ # │ val │
├───┼─────┤
│ 0 │ 1 │
│ 1 │ 2 │
╰───┴─────╯
Transfer back to record with -d flag
> {c1: 1, c2: 2} | transpose | transpose --ignore-titles -r -d
╭────┬───╮
│ c1 │ 1 │
│ c2 │ 2 │
╰────┴───╯
try
Try to run a block, if it fails optionally run a catch block.
Usage:
> try <try_block> (catch <catch_block>)
Flags:
-h, --help - Display the help message for this command
Parameters:
try_block <block>: Block to run.
"catch" + <one_of(closure(), closure(any))>: Block to run if try block fails. (optional)
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Try to run a missing command
> try { asdfasdf }
Try to run a missing command
> try { asdfasdf } catch { 'missing' }
missing
tutor
Run the tutorial. To begin, run: tutor.
Search terms: help, learn, tutorial
Usage:
> tutor {flags} (search)
Flags:
-h, --help - Display the help message for this command
-f, --find <String> - Search tutorial for a phrase
Parameters:
search <string>: Item to search for, or 'list' to list available tutorials. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Begin the tutorial
> tutor begin
Search a tutorial by phrase
> tutor --find "$in"
uniq
Return the distinct values in the input.
Search terms: distinct, deduplicate
Usage:
> uniq {flags}
Flags:
-h, --help - Display the help message for this command
-c, --count - Return a table containing the distinct input values together with their counts
-d, --repeated - Return the input values that occur more than once
-i, --ignore-case - Compare input values case-insensitively
-u, --unique - Return the input values that occur once only
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Return the distinct values of a list/table (remove duplicates so that each value occurs once only)
> [2 3 3 4] | uniq
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 3 │
│ 2 │ 4 │
╰───┴───╯
Return the input values that occur more than once
> [1 2 2] | uniq -d
╭───┬───╮
│ 0 │ 2 │
╰───┴───╯
Return the input values that occur once only
> [1 2 2] | uniq --unique
╭───┬───╮
│ 0 │ 1 │
╰───┴───╯
Ignore differences in case when comparing input values
> ['hello' 'goodbye' 'Hello'] | uniq --ignore-case
╭───┬─────────╮
│ 0 │ hello │
│ 1 │ goodbye │
╰───┴─────────╯
Return a table containing the distinct input values together with their counts
> [1 2 2] | uniq --count
╭───┬───────┬───────╮
│ # │ value │ count │
├───┼───────┼───────┤
│ 0 │ 1 │ 1 │
│ 1 │ 2 │ 2 │
╰───┴───────┴───────╯
uniq-by
Return the distinct values in the input by the given column(s).
Search terms: distinct, deduplicate
Usage:
> uniq-by {flags} ...(columns)
Flags:
-h, --help - Display the help message for this command
-c, --count - Return a table containing the distinct input values together with their counts
-d, --repeated - Return the input values that occur more than once
-i, --ignore-case - Ignore differences in case when comparing input values
-u, --unique - Return the input values that occur once only
Parameters:
...columns <any>: The column(s) to filter by.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ table │ table │
│ 1 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Get rows from table filtered by column uniqueness
> [[fruit count]; [apple 9] [apple 2] [pear 3] [orange 7]] | uniq-by fruit
╭───┬────────┬───────╮
│ # │ fruit │ count │
├───┼────────┼───────┤
│ 0 │ apple │ 9 │
│ 1 │ pear │ 3 │
│ 2 │ orange │ 7 │
╰───┴────────┴───────╯
update
Update an existing column to have a new value.
Usage:
> update <field> <replacement value>
Flags:
-h, --help - Display the help message for this command
Parameters:
field <cell-path>: The name of the column to update.
replacement value <any>: The new value to give the cell(s), or a closure to create the value.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
│ 2 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Update a column value
> {'name': 'nu', 'stars': 5} | update name 'Nushell'
╭───────┬─────────╮
│ name │ Nushell │
│ stars │ 5 │
╰───────┴─────────╯
Use a closure to alter each value in the 'authors' column to a single string
> [[project, authors]; ['nu', ['Andrés', 'JT', 'Yehuda']]] | update authors {|row| $row.authors | str join ',' }
╭───┬─────────┬──────────────────╮
│ # │ project │ authors │
├───┼─────────┼──────────────────┤
│ 0 │ nu │ Andrés,JT,Yehuda │
╰───┴─────────┴──────────────────╯
You can also use a simple command to update 'authors' to a single string
> [[project, authors]; ['nu', ['Andrés', 'JT', 'Yehuda']]] | update authors { str join ',' }
╭───┬─────────┬──────────────────╮
│ # │ project │ authors │
├───┼─────────┼──────────────────┤
│ 0 │ nu │ Andrés,JT,Yehuda │
╰───┴─────────┴──────────────────╯
Update a value at an index in a list
> [1 2 3] | update 1 4
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 4 │
│ 2 │ 3 │
╰───┴───╯
Use a closure to compute a new value at an index
> [1 2 3] | update 1 {|i| $i + 2 }
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 4 │
│ 2 │ 3 │
╰───┴───╯
upsert
Update an existing column to have a new value, or insert a new column.
Search terms: add
Usage:
> upsert <field> <replacement value>
Flags:
-h, --help - Display the help message for this command
Parameters:
field <cell-path>: The name of the column to update or insert.
replacement value <any>: The new value to give the cell(s), or a closure to create the value.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
│ 2 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Update a record's value
> {'name': 'nu', 'stars': 5} | upsert name 'Nushell'
╭───────┬─────────╮
│ name │ Nushell │
│ stars │ 5 │
╰───────┴─────────╯
Insert a new entry into a record
> {'name': 'nu', 'stars': 5} | upsert language 'Rust'
╭──────────┬──────╮
│ name │ nu │
│ stars │ 5 │
│ language │ Rust │
╰──────────┴──────╯
Update each row of a table
> [[name lang]; [Nushell ''] [Reedline '']] | upsert lang 'Rust'
╭───┬──────────┬──────╮
│ # │ name │ lang │
├───┼──────────┼──────┤
│ 0 │ Nushell │ Rust │
│ 1 │ Reedline │ Rust │
╰───┴──────────┴──────╯
Insert a new column with values computed based off the other columns
> [[foo]; [7] [8] [9]] | upsert bar {|row| $row.foo * 2 }
╭───┬─────┬─────╮
│ # │ foo │ bar │
├───┼─────┼─────┤
│ 0 │ 7 │ 14 │
│ 1 │ 8 │ 16 │
│ 2 │ 9 │ 18 │
╰───┴─────┴─────╯
Update null values in a column to a default value
> [[foo]; [2] [null] [4]] | upsert foo { default 0 }
╭───┬─────╮
│ # │ foo │
├───┼─────┤
│ 0 │ 2 │
│ 1 │ 0 │
│ 2 │ 4 │
╰───┴─────╯
Upsert into a list, updating an existing value at an index
> [1 2 3] | upsert 0 2
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 2 │
│ 2 │ 3 │
╰───┴───╯
Upsert into a list, inserting a new value at the end
> [1 2 3] | upsert 3 4
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
│ 3 │ 4 │
╰───┴───╯
url
Various commands for working with URLs.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Search terms: network, parse
Usage:
> url
Subcommands:
url build-query - Converts record or table into query string applying percent-encoding.
url decode - Converts a percent-encoded web safe string to a string.
url encode - Converts a string to a percent encoded web safe string.
url join - Converts a record to url.
url parse - Parses a url.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
url build-query
Converts record or table into query string applying percent-encoding.
Search terms: convert, record, table
Usage:
> url build-query
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ string │
│ 1 │ table │ string │
╰───┴────────┴────────╯
Examples:
Outputs a query string representing the contents of this record
> { mode:normal userid:31415 } | url build-query
mode=normal&userid=31415
Outputs a query string representing the contents of this 1-row table
> [[foo bar]; ["1" "2"]] | url build-query
foo=1&bar=2
Outputs a query string representing the contents of this record
> {a:"AT&T", b: "AT T"} | url build-query
a=AT%26T&b=AT+T
url decode
Converts a percent-encoded web safe string to a string.
Search terms: string, text, convert
Usage:
> url decode ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: For a data structure input, url decode strings at the given cell paths.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Decode a url with escape characters
> 'https://example.com/foo%20bar' | url decode
https://example.com/foo bar
Decode multiple urls with escape characters in list
> ['https://example.com/foo%20bar' 'https://example.com/a%3Eb' '%E4%B8%AD%E6%96%87%E5%AD%97/eng/12%2034'] | url decode
╭───┬─────────────────────────────╮
│ 0 │ https://example.com/foo bar │
│ 1 │ https://example.com/a>b │
│ 2 │ 中文字/eng/12 34 │
╰───┴─────────────────────────────╯
url encode
Converts a string to a percent encoded web safe string.
Search terms: string, text, convert
Usage:
> url encode {flags} ...(rest)
Flags:
-h, --help - Display the help message for this command
-a, --all - encode all non-alphanumeric chars including `/`, `.`, `:`
Parameters:
...rest <cell-path>: For a data structure input, check strings at the given cell paths, and replace with result.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ string │ string │
│ 1 │ list<string> │ list<string> │
│ 2 │ table │ table │
│ 3 │ record │ record │
╰───┴──────────────┴──────────────╯
Examples:
Encode a url with escape characters
> 'https://example.com/foo bar' | url encode
https://example.com/foo%20bar
Encode multiple urls with escape characters in list
> ['https://example.com/foo bar' 'https://example.com/a>b' '中文字/eng/12 34'] | url encode
╭───┬─────────────────────────────────────────╮
│ 0 │ https://example.com/foo%20bar │
│ 1 │ https://example.com/a%3Eb │
│ 2 │ %E4%B8%AD%E6%96%87%E5%AD%97/eng/12%2034 │
╰───┴─────────────────────────────────────────╯
Encode all non alphanumeric chars with all flag
> 'https://example.com/foo bar' | url encode --all
https%3A%2F%2Fexample%2Ecom%2Ffoo%20bar
url join
Converts a record to url.
Search terms: scheme, username, password, hostname, port, path, query, fragment
Usage:
> url join
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ string │
╰───┴────────┴────────╯
Examples:
Outputs a url representing the contents of this record
> {
"scheme": "http",
"username": "",
"password": "",
"host": "www.pixiv.net",
"port": "",
"path": "/member_illust.php",
"query": "mode=medium&illust_id=99260204",
"fragment": "",
"params":
{
"mode": "medium",
"illust_id": "99260204"
}
} | url join
http://www.pixiv.net/member_illust.php?mode=medium&illust_id=99260204
Outputs a url representing the contents of this record
> {
"scheme": "http",
"username": "user",
"password": "pwd",
"host": "www.pixiv.net",
"port": "1234",
"query": "test=a",
"fragment": ""
} | url join
http://user:[email protected]:1234?test=a
Outputs a url representing the contents of this record
> {
"scheme": "http",
"host": "www.pixiv.net",
"port": "1234",
"path": "user",
"fragment": "frag"
} | url join
http://www.pixiv.net:1234/user#frag
url parse
Parses a url.
Search terms: scheme, username, password, hostname, port, path, query, fragment
Usage:
> url parse ...(rest)
Flags:
-h, --help - Display the help message for this command
Parameters:
...rest <cell-path>: Optionally operate by cell path.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ record │
│ 1 │ table │ table │
│ 2 │ record │ record │
╰───┴────────┴────────╯
Examples:
Parses a url
> 'http://user123:[email protected]:8081/foo/bar?param1=section&p2=&f[name]=vldc#hello' | url parse
╭──────────┬─────────────────────────────────╮
│ scheme │ http │
│ username │ user123 │
│ password │ pass567 │
│ host │ www.example.com │
│ port │ 8081 │
│ path │ /foo/bar │
│ query │ param1=section&p2=&f[name]=vldc │
│ fragment │ hello │
│ params │ {record 3 fields} │
╰──────────┴─────────────────────────────────╯
use
Use definitions from a module, making them available in your shell.
See `help std` for the standard library module.
See `help modules` to list all available modules.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: module, import, include, scope
Usage:
> use <module> ...(members)
Flags:
-h, --help - Display the help message for this command
Parameters:
module <string>: Module or module file.
...members <any>: Which members of the module to import.
Examples:
Define a custom command in a module and call it
> module spam { export def foo [] { "foo" } }; use spam foo; foo
foo
Define a custom command that participates in the environment in a module and call it
> module foo { export def --env bar [] { $env.FOO_BAR = "BAZ" } }; use foo bar; bar; $env.FOO_BAR
BAZ
Use a plain module name to import its definitions qualified by the module name
> module spam { export def foo [] { "foo" }; export def bar [] { "bar" } }; use spam; (spam foo) + (spam bar)
foobar
Specify * to use all definitions in a module
> module spam { export def foo [] { "foo" }; export def bar [] { "bar" } }; use spam *; (foo) + (bar)
foobar
To use commands with spaces, like subcommands, surround them with quotes
> module spam { export def 'foo bar' [] { "baz" } }; use spam 'foo bar'; foo bar
baz
To use multiple definitions from a module, wrap them in a list
> module spam { export def foo [] { "foo" }; export def 'foo bar' [] { "baz" } }; use spam ['foo', 'foo bar']; (foo) + (foo bar)
foobaz
values
Given a record or table, produce a list of its columns' values.
This is a counterpart to `columns`, which produces a list of columns' names.
Usage:
> values
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬────────┬───────────╮
│ # │ input │ output │
├───┼────────┼───────────┤
│ 0 │ record │ list<any> │
│ 1 │ table │ list<any> │
╰───┴────────┴───────────╯
Examples:
Get the values from the record (produce a list)
> { mode:normal userid:31415 } | values
╭───┬────────╮
│ 0 │ normal │
│ 1 │ 31415 │
╰───┴────────╯
Values are ordered by the column order of the record
> { f:250 g:191 c:128 d:1024 e:2000 a:16 b:32 } | values
╭───┬──────╮
│ 0 │ 250 │
│ 1 │ 191 │
│ 2 │ 128 │
│ 3 │ 1024 │
│ 4 │ 2000 │
│ 5 │ 16 │
│ 6 │ 32 │
╰───┴──────╯
Get the values from the table (produce a list of lists)
> [[name meaning]; [ls list] [mv move] [cd 'change directory']] | values
╭───┬────────────────╮
│ 0 │ [list 3 items] │
│ 1 │ [list 3 items] │
╰───┴────────────────╯
version
Display Nu version, and its build configuration.
Usage:
> version
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
Display Nu version
> version
view
Various commands for viewing debug information.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> view
Subcommands:
view files - View the files registered in nushell's EngineState memory.
view source - View a block, module, or a definition.
view span - View the contents of a span.
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
view files
View the files registered in nushell's EngineState memory.
These are files parsed and loaded at runtime.
Usage:
> view files
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬──────────────────────────────────────────────────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────────────────────────────────────────────────┤
│ 0 │ nothing │ table<filename: string, start: int, end: int, size: int> │
╰───┴─────────┴──────────────────────────────────────────────────────────╯
Examples:
View the files registered in Nushell's EngineState memory
> view files
View how Nushell was originally invoked
> view files | get 0
view source
View a block, module, or a definition.
Usage:
> view source <item>
Flags:
-h, --help - Display the help message for this command
Parameters:
item <any>: Name or block to view.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
View the source of a code block
> let abc = {|| echo 'hi' }; view source $abc
{|| echo 'hi' }
View the source of a custom command
> def hi [] { echo 'Hi!' }; view source hi
def hi [] { echo 'Hi!' }
View the source of a custom command, which participates in the caller environment
> def --env foo [] { $env.BAR = 'BAZ' }; view source foo
def foo [] { $env.BAR = 'BAZ' }
View the source of a custom command with flags and arguments
> def test [a?:any --b:int ...rest:string] { echo 'test' }; view source test
def test [ a?: any --b: int ...rest: string] { echo 'test' }
View the source of a module
> module mod-foo { export-env { $env.FOO_ENV = 'BAZ' } }; view source mod-foo
export-env { $env.FOO_ENV = 'BAZ' }
View the source of an alias
> alias hello = echo hi; view source hello
echo hi
view span
View the contents of a span.
This command is meant for debugging purposes.
It allows you to view the contents of nushell spans.
One way to get spans is to pipe something into 'debug --raw'.
Then you can use the Span { start, end } values as the start and end values for this command.
Usage:
> view span <start> <end>
Flags:
-h, --help - Display the help message for this command
Parameters:
start <int>: Start of the span.
end <int>: End of the span.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
View the source of a span. 1 and 2 are just example values. Use the return of debug --raw to get the actual values
> some | pipeline | or | variable | debug --raw; view span 1 2
watch
Watch for file changes and execute Nu code when they happen.
Search terms: watcher, reload, filesystem
Usage:
> watch {flags} <path> <closure>
Flags:
-h, --help - Display the help message for this command
-d, --debounce-ms <Int> - Debounce changes for this many milliseconds (default: 100). Adjust if you find that single writes are reported as multiple events
-g, --glob <String> - Only report changes for files that match this glob pattern (default: all files)
-r, --recursive <Boolean> - Watch all directories under `<path>` recursively. Will be ignored if `<path>` is a file (default: true)
-v, --verbose - Operate in verbose mode (default: false)
Parameters:
path <path>: The path to watch. Can be a file or directory.
closure <closure(string, string, string)>: Some Nu code to run whenever a file changes. The closure will be passed `operation`, `path`, and `new_path` (for renames only) arguments in that order.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Run `cargo test` whenever a Rust file changes
> watch . --glob=**/*.rs {|| cargo test }
Watch all changes in the current directory
> watch . { |op, path, new_path| $"($op) ($path) ($new_path)"}
Log all changes in a directory
> watch /foo/bar { |op, path| $"($op) - ($path)(char nl)" | save --append changes_in_bar.log }
Note: if you are looking to run a command every N units of time, this can be accomplished with a loop and sleep
> loop { command; sleep duration }
where
Filter values based on a row condition.
This command works similar to 'filter' but allows extra shorthands for working with
tables, known as "row conditions". On the other hand, reading the condition from a variable is
not supported.
Search terms: filter, find, search, condition
Usage:
> where <row_condition>
Flags:
-h, --help - Display the help message for this command
Parameters:
row_condition <condition>: Filter condition.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ list<any> │ list<any> │
│ 1 │ table │ table │
│ 2 │ range │ any │
╰───┴───────────┴───────────╯
Examples:
Filter rows of a table according to a condition
> [{a: 1} {a: 2}] | where a > 1
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 2 │
╰───┴───╯
Filter items of a list according to a condition
> [1 2] | where {|x| $x > 1}
╭───┬───╮
│ 0 │ 2 │
╰───┴───╯
List all files in the current directory with sizes greater than 2kb
> ls | where size > 2kb
List only the files in the current directory
> ls | where type == file
List all files with names that contain "Car"
> ls | where name =~ "Car"
List all files that were modified in the last two weeks
> ls | where modified >= (date now) - 2wk
Find files whose filenames don't begin with the correct sequential number
> ls | where type == file | sort-by name --natural | enumerate | where {|e| $e.item.name !~ $'^($e.index + 1)' } | each {|| get item }
Find case-insensitively files called "readme", without an explicit closure
> ls | where ($it.name | str downcase) =~ readme
same as above but with regex only
> ls | where name =~ '(?i)readme'
which
Finds a program file, alias or custom command.
Search terms: find, path, location, command
Usage:
> which {flags} <application> ...(rest)
Flags:
-h, --help - Display the help message for this command
-a, --all - list all executables
Parameters:
application <string>: Application.
...rest <string>: Additional applications.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Find if the 'myapp' application is available
> which myapp
while
Conditionally run a block in a loop.
Search terms: loop
Usage:
> while <cond> <block>
Flags:
-h, --help - Display the help message for this command
Parameters:
cond <variable>: Condition to check.
block <block>: Block to loop if check succeeds.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Loop while a condition is true
> mut x = 0; while $x < 10 { $x = $x + 1 }
whoami
Get the current username using uutils/coreutils whoami.
Search terms: username, coreutils
Usage:
> whoami
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Get the current username
> whoami
window
Creates a sliding window of `window_size` that slide by n rows/elements across input.
Usage:
> window {flags} <window_size>
Flags:
-h, --help - Display the help message for this command
-s, --stride <Int> - the number of rows to slide over between windows
-r, --remainder - yield last chunks even if they have fewer elements than size
Parameters:
window_size <int>: The size of each window.
Input/output types:
╭───┬───────────┬─────────────────╮
│ # │ input │ output │
├───┼───────────┼─────────────────┤
│ 0 │ list<any> │ list<list<any>> │
╰───┴───────────┴─────────────────╯
Examples:
A sliding window of two elements
> [1 2 3 4] | window 2
╭───┬────────────────╮
│ 0 │ [list 2 items] │
│ 1 │ [list 2 items] │
│ 2 │ [list 2 items] │
╰───┴────────────────╯
A sliding window of two elements, with a stride of 3
> [1, 2, 3, 4, 5, 6, 7, 8] | window 2 --stride 3
╭───┬────────────────╮
│ 0 │ [list 2 items] │
│ 1 │ [list 2 items] │
│ 2 │ [list 2 items] │
╰───┴────────────────╯
A sliding window of equal stride that includes remainder. Equivalent to chunking
> [1, 2, 3, 4, 5] | window 3 --stride 3 --remainder
╭───┬────────────────╮
│ 0 │ [list 3 items] │
│ 1 │ [list 2 items] │
╰───┴────────────────╯
with-env
Runs a block with an environment variable set.
Usage:
> with-env <variable> <block>
Flags:
-h, --help - Display the help message for this command
Parameters:
variable <any>: The environment variable to temporarily set.
block <closure()>: The block to run once the variable is set.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Set the MYENV environment variable
> with-env [MYENV "my env value"] { $env.MYENV }
my env value
Set by primitive value list
> with-env [X Y W Z] { $env.X }
Y
Set by single row table
> with-env [[X W]; [Y Z]] { $env.W }
Z
Set by key-value record
> with-env {X: "Y", W: "Z"} { [$env.X $env.W] }
╭───┬───╮
│ 0 │ Y │
│ 1 │ Z │
╰───┴───╯
wrap
Wrap the value into a column.
Usage:
> wrap <name>
Flags:
-h, --help - Display the help message for this command
Parameters:
name <string>: The name of the column.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ table │
│ 1 │ range │ table │
│ 2 │ any │ record │
╰───┴───────────┴────────╯
Examples:
Wrap a list into a table with a given column name
> [1 2 3] | wrap num
╭───┬─────╮
│ # │ num │
├───┼─────┤
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
╰───┴─────╯
Wrap a range into a table with a given column name
> 1..3 | wrap num
╭───┬─────╮
│ # │ num │
├───┼─────┤
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
╰───┴─────╯
zip
Combine a stream with the input.
Usage:
> zip <other>
Flags:
-h, --help - Display the help message for this command
Parameters:
other <any>: The other input.
Input/output types:
╭───┬───────────┬─────────────────╮
│ # │ input │ output │
├───┼───────────┼─────────────────┤
│ 0 │ list<any> │ list<list<any>> │
│ 1 │ range │ list<list<any>> │
╰───┴───────────┴─────────────────╯
Examples:
Zip two lists
> [1 2] | zip [3 4]
╭───┬────────────────╮
│ 0 │ [list 2 items] │
│ 1 │ [list 2 items] │
╰───┴────────────────╯
Zip two ranges
> 1..3 | zip 4..6
╭───┬────────────────╮
│ 0 │ [list 2 items] │
│ 1 │ [list 2 items] │
│ 2 │ [list 2 items] │
╰───┴────────────────╯
Zip two streams
> seq 1 3 | zip { seq 4 600000000 }
╭───┬────────────────╮
│ 0 │ [list 2 items] │
│ 1 │ [list 2 items] │
│ 2 │ [list 2 items] │
╰───┴────────────────╯
Rename .ogg files to match an existing list of filenames
> glob *.ogg | zip ['bang.ogg', 'fanfare.ogg', 'laser.ogg'] | each {|| mv $in.0 $in.1 }