toc
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)>: A closure that must evaluate to a boolean.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ bool │
╰───┴───────────┴────────╯
Examples:
Check if a list contains only true values
> [false true true false] | all {}
false
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 style attributes:
╭────┬────┬──────────────┬─────────────────────────────────────────╮
│ # │ id │ abbreviation │ description │
├────┼────┼──────────────┼─────────────────────────────────────────┤
│ 0 │ 0 │ rst │ reset / normal display │
│ 1 │ 1 │ bo │ bold on │
│ 2 │ 2 │ d │ dimmed on │
│ 3 │ 3 │ i │ italic on (non-mono font) │
│ 4 │ 4 │ u │ underline on │
│ 5 │ 5 │ bl │ blink on │
│ 6 │ 6 │ bf │ fast blink on │
│ 7 │ 7 │ r │ reverse video on │
│ 8 │ 8 │ h │ hidden (invisible) on │
│ 9 │ 9 │ s │ strike-through on │
│ 10 │ 21 │ rst_bo │ bold or dimmed off │
│ 11 │ 22 │ du │ double underline (not widely supported) │
│ 12 │ 23 │ rst_i │ italic off (non-mono font) │
│ 13 │ 24 │ rst_u │ underline off │
│ 14 │ 25 │ rst_bl │ blink off │
│ 15 │ 26 │ │ <reserved> │
│ 16 │ 27 │ rst_r │ reverse video off │
│ 17 │ 28 │ rst_h │ hidden (invisible) off │
│ 18 │ 29 │ rst_s │ strike-through off │
╰────┴────┴──────────────┴─────────────────────────────────────────╯
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 gradient - Add a color gradient (using ANSI color codes) to the given string.
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 all styles and colors
> 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 rst) (ansi gd)Nu(ansi rst) (ansi pi)World(ansi rst)'
Hello Nu World
Avoid resetting color when setting/resetting different style codes
> $'Set color to (ansi g)GREEN then style to (ansi bo)BOLD(ansi rst_bo) or (ansi d)DIMMED(ansi rst_d) or (ansi i)ITALICS(ansi rst_i) or (ansi u)UNDERLINE(ansi rst_u) or (ansi re)REVERSE(ansi rst_re) or (ansi h)HIDDEN(ansi rst_h) or (ansi s)STRIKE(ansi rst_s) then (ansi rst)reset everything'
Set color to GREEN then style to BOLD or DIMMED or ITALICS or UNDERLINE or REVERSE or HIDDEN or STRIKE then reset everything
Use escape codes, without the '\x1b['
> $"(ansi --escape '3;93;41m')Hello(ansi reset)" # italic bright yellow on red background
Hello
Use simple hex string
> $"(ansi '#4169E1')Hello(ansi reset)" # royal blue foreground color
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 gradient
Add a color gradient (using ANSI color codes) to the given string.
Usage:
> ansi gradient {flags} ...(cell path)
Flags:
-h, --help: Display the help message for this command
-a, --fgstart <string>: foreground gradient start color in hex (0x123456)
-b, --fgend <string>: foreground gradient end color in hex
-c, --bgstart <string>: background gradient start color in hex
-d, --bgend <string>: background gradient end color in hex
Parameters:
...cell path <cell-path>: For a data structure input, add a gradient to 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:
draw text in a gradient with foreground start and end colors
> 'Hello, Nushell! This is a gradient.' | ansi gradient --fgstart '0x40c9ff' --fgend '0xe81cff'
draw text in a gradient with foreground start and end colors and background start and end colors
> 'Hello, Nushell! This is a gradient.' | ansi gradient --fgstart '0x40c9ff' --fgend '0xe81cff' --bgstart '0xe81cff' --bgend '0x40c9ff'
draw text in a gradient by specifying foreground start color - end color is assumed to be black
> 'Hello, Nushell! This is a gradient.' | ansi gradient --fgstart '0x40c9ff'
draw text in a gradient by specifying foreground end color - start color is assumed to be black
> 'Hello, Nushell! This is a gradient.' | ansi gradient --fgend '0xe81cff'
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)>: A closure that must evaluate to a boolean.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ list<any> │ bool │
╰───┴───────────┴────────╯
Examples:
Check if a list contains any true values
> [false true true false] | any {}
true
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
-f, --flatten: An easier to read version of the ast
Parameters:
pipeline <string>: The pipeline to print the ast for.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
│ 1 │ nothing │ record │
│ 2 │ nothing │ string │
╰───┴─────────┴────────╯
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
Print the ast of a string flattened
> ast "'hello'" --flatten
╭───┬─────────┬──────────────┬───────────────╮
│ # │ content │ shape │ span │
├───┼─────────┼──────────────┼───────────────┤
│ 0 │ 'hello' │ shape_string │ ╭───────┬───╮ │
│ │ │ │ │ start │ 0 │ │
│ │ │ │ │ end │ 7 │ │
│ │ │ │ ╰───────┴───╯ │
╰───┴─────────┴──────────────┴───────────────╯
Print the ast of a string flattened, as json, minified
> ast "'hello'" --flatten --json --minify
[{"content":"'hello'","shape":"shape_string","span":{"start":0,"end":7}}]
Print the ast of a pipeline flattened
> ast 'ls | sort-by type name -i' --flatten
╭───┬─────────┬────────────────────┬────────────────╮
│ # │ content │ shape │ span │
├───┼─────────┼────────────────────┼────────────────┤
│ 0 │ ls │ shape_external │ ╭───────┬───╮ │
│ │ │ │ │ start │ 0 │ │
│ │ │ │ │ end │ 2 │ │
│ │ │ │ ╰───────┴───╯ │
│ 1 │ | │ shape_pipe │ ╭───────┬───╮ │
│ │ │ │ │ start │ 3 │ │
│ │ │ │ │ end │ 4 │ │
│ │ │ │ ╰───────┴───╯ │
│ 2 │ sort-by │ shape_internalcall │ ╭───────┬────╮ │
│ │ │ │ │ start │ 5 │ │
│ │ │ │ │ end │ 12 │ │
│ │ │ │ ╰───────┴────╯ │
│ 3 │ type │ shape_string │ ╭───────┬────╮ │
│ │ │ │ │ start │ 13 │ │
│ │ │ │ │ end │ 17 │ │
│ │ │ │ ╰───────┴────╯ │
│ 4 │ name │ shape_string │ ╭───────┬────╮ │
│ │ │ │ │ start │ 18 │ │
│ │ │ │ │ end │ 22 │ │
│ │ │ │ ╰───────┴────╯ │
│ 5 │ -i │ shape_flag │ ╭───────┬────╮ │
│ │ │ │ │ start │ 23 │ │
│ │ │ │ │ end │ 25 │ │
│ │ │ │ ╰───────┴────╯ │
╰───┴─────────┴────────────────────┴────────────────╯
attr
Various attributes for custom commands.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> attr
Subcommands:
attr category - Attribute for adding a category to custom commands.
attr complete - Attribute for using another command as a completion source for all arguments.
attr complete external - Attribute for enabling use of the external completer for internal commands.
attr deprecated - Attribute for marking a command or flag as deprecated.
attr example - Attribute for adding examples to custom commands.
attr search-terms - Attribute for adding search terms to custom commands.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
attr category
Attribute for adding a category to custom commands.
Usage:
> attr category <category>
Flags:
-h, --help: Display the help message for this command
Parameters:
category <string>: Category of the custom command.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Add a category to a custom command
> # Double numbers
@category math
def double []: [number -> number] { $in * 2 }
attr complete
Attribute for using another command as a completion source for all arguments.
Usage:
> attr complete <completer>
Subcommands:
attr complete external - Attribute for enabling use of the external completer for internal commands.
Flags:
-h, --help: Display the help message for this command
Parameters:
completer <string>: Name of the completion command.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Use another command as completion source
> def complete-foo [spans: list<string>] {
[bar baz qux spam eggs] | where $it not-in $spans
}
@complete 'complete-foo'
def foo [...args] { $args }
attr complete external
Attribute for enabling use of the external completer for internal commands.
Usage:
> attr complete external
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Use the external completer for a wrapper command
> @complete external
def --wrapped jc [...args] {
^jc ...$args | from json
}
attr deprecated
Attribute for marking a command or flag as deprecated.
Mark a command (default) or flag/switch (--flag) as deprecated. By default, only the first usage will trigger a deprecation warning.
A help message can be included to provide more context for the deprecation, such as what to use as a replacement.
Also consider setting the category to deprecated with @category deprecated
Usage:
> attr deprecated {flags} (message)
Flags:
-h, --help: Display the help message for this command
--flag <string>: Mark a flag as deprecated rather than the command
-s, --since <string>: Denote a version when this item was deprecated
-r, --remove <string>: Denote a version when this item will be removed
--report <string>: How to warn about this item. One of: first (default), every
Parameters:
message <string>: Help message to include with deprecation warning. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
Add a deprecation warning to a custom command
> @deprecated
def outdated [] {}
Add a deprecation warning with a custom message
> @deprecated "Use my-new-command instead."
@category deprecated
def my-old-command [] {}
Use my-new-command instead.
attr example
Attribute for adding examples to custom commands.
Usage:
> attr example {flags} <description> <example>
Flags:
-h, --help: Display the help message for this command
--result <any>: Expected output of example.
Parameters:
description <string>: Description of the example.
example <oneof<block, string>>: Example code snippet.
Input/output types:
╭───┬─────────┬──────────────────────────────────────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────────────────────────────────────┤
│ 0 │ nothing │ record<description: string, example: string> │
╰───┴─────────┴──────────────────────────────────────────────╯
Examples:
Add examples to custom command
> # Double numbers
@example "double an int" { 2 | double } --result 4
@example "double a float" { 0.25 | double } --result 0.5
def double []: [number -> number] { $in * 2 }
attr search-terms
Attribute for adding search terms to custom commands.
Usage:
> attr search-terms ...(terms)
Flags:
-h, --help: Display the help message for this command
Parameters:
...terms <string>: Search terms.
Input/output types:
╭───┬─────────┬──────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────┤
│ 0 │ nothing │ list<string> │
╰───┴─────────┴──────────────╯
Examples:
Add search terms to a custom command
> # Double numbers
@search-terms multiply times
def double []: [number -> number] { $in * 2 }
bits
Various commands for working with bits.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> bits
Subcommands:
bits and - Performs bitwise and for ints or binary values.
bits not - Performs logical negation on each bit.
bits or - Performs bitwise or for ints or binary values.
bits rol - Bitwise rotate left for ints or binary values.
bits ror - Bitwise rotate right for ints or binary values.
bits shl - Bitwise shift left for ints or binary values.
bits shr - Bitwise shift right for ints or binary values.
bits xor - Performs bitwise xor for ints or binary values.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
bits and
Performs bitwise and for ints or binary values.
Search terms: logic and
Usage:
> bits and {flags} <target>
Flags:
-h, --help: Display the help message for this command
-e, --endian <string>: byte encode endian, available options: native(default), little, big
Parameters:
target <oneof<binary, int>>: Right-hand side of the operation.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ int │ int │
│ 1 │ binary │ binary │
│ 2 │ list<int> │ list<int> │
│ 3 │ list<binary> │ list<binary> │
╰───┴──────────────┴──────────────╯
Examples:
Apply bitwise and to two numbers
> 2 | bits and 2
2
Apply bitwise and to two binary values
> 0x[ab cd] | bits and 0x[99 99]
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 89 89 ××
Apply bitwise and to a list of numbers
> [4 3 2] | bits and 2
╭───┬───╮
│ 0 │ 0 │
│ 1 │ 2 │
│ 2 │ 2 │
╰───┴───╯
Apply bitwise and to a list of binary data
> [0x[7f ff] 0x[ff f0]] | bits and 0x[99 99]
╭───┬────────────╮
│ 0 │ [25, 153] │
│ 1 │ [153, 144] │
╰───┴────────────╯
Apply bitwise and to binary data of varying lengths with specified endianness
> 0x[c0 ff ee] | bits and 0x[ff] --endian big
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: 00 00 ee 00×
Apply bitwise and to input binary data smaller than the operand
> 0x[ff] | bits and 0x[12 34 56] --endian little
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: 12 00 00 •00
bits not
Performs logical negation on each bit.
Search terms: negation
Usage:
> bits not {flags}
Flags:
-h, --help: Display the help message for this command
-s, --signed: always treat input number as a signed number
-n, --number-bytes <int>: the size of unsigned number in bytes, it can be 1, 2, 4, 8, auto
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ int │ int │
│ 1 │ binary │ binary │
│ 2 │ list<int> │ list<int> │
│ 3 │ list<binary> │ list<binary> │
╰───┴──────────────┴──────────────╯
Examples:
Apply logical negation to a list of numbers
> [4 3 2] | bits not
╭───┬─────╮
│ 0 │ 251 │
│ 1 │ 252 │
│ 2 │ 253 │
╰───┴─────╯
Apply logical negation to a list of numbers, treat input as 2 bytes number
> [4 3 2] | bits not --number-bytes 2
╭───┬───────╮
│ 0 │ 65531 │
│ 1 │ 65532 │
│ 2 │ 65533 │
╰───┴───────╯
Apply logical negation to a list of numbers, treat input as signed number
> [4 3 2] | bits not --signed
╭───┬────╮
│ 0 │ -5 │
│ 1 │ -4 │
│ 2 │ -3 │
╰───┴────╯
Apply logical negation to binary data
> 0x[ff 00 7f] | bits not
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: 00 ff 80 0××
bits or
Performs bitwise or for ints or binary values.
Search terms: logic or
Usage:
> bits or {flags} <target>
Flags:
-h, --help: Display the help message for this command
-e, --endian <string>: byte encode endian, available options: native(default), little, big
Parameters:
target <oneof<binary, int>>: Right-hand side of the operation.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ int │ int │
│ 1 │ binary │ binary │
│ 2 │ list<int> │ list<int> │
│ 3 │ list<binary> │ list<binary> │
╰───┴──────────────┴──────────────╯
Examples:
Apply bits or to two numbers
> 2 | bits or 6
6
Apply bitwise or to a list of numbers
> [8 3 2] | bits or 2
╭───┬────╮
│ 0 │ 10 │
│ 1 │ 3 │
│ 2 │ 2 │
╰───┴────╯
Apply bitwise or to binary data
> 0x[88 cc] | bits or 0x[42 32]
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: ca fe ××
Apply bitwise or to binary data of varying lengths with specified endianness
> 0x[c0 ff ee] | bits or 0x[ff] --endian big
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: c0 ff ff ×××
Apply bitwise or to input binary data smaller than the operor
> 0x[ff] | bits or 0x[12 34 56] --endian little
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: ff 34 56 ×4V
bits rol
Bitwise rotate left for ints or binary values.
Search terms: rotate left
Usage:
> bits rol {flags} <bits>
Flags:
-h, --help: Display the help message for this command
-s, --signed: always treat input number as a signed number
-n, --number-bytes <int>: the word size in number of bytes. Must be 1, 2, 4, or 8 (defaults to the smallest of those that fits the input number)
Parameters:
bits <int>: Number of bits to rotate left.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ int │ int │
│ 1 │ binary │ binary │
│ 2 │ list<int> │ list<int> │
│ 3 │ list<binary> │ list<binary> │
╰───┴──────────────┴──────────────╯
Examples:
Rotate left a number with 2 bits
> 17 | bits rol 2
68
Rotate left a list of numbers with 2 bits
> [5 3 2] | bits rol 2
╭───┬────╮
│ 0 │ 20 │
│ 1 │ 12 │
│ 2 │ 8 │
╰───┴────╯
rotate left binary data
> 0x[c0 ff ee] | bits rol 10
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: ff bb 03 ×ו
bits ror
Bitwise rotate right for ints or binary values.
Search terms: rotate right
Usage:
> bits ror {flags} <bits>
Flags:
-h, --help: Display the help message for this command
-s, --signed: always treat input number as a signed number
-n, --number-bytes <int>: the word size in number of bytes. Must be 1, 2, 4, or 8 (defaults to the smallest of those that fits the input number)
Parameters:
bits <int>: Number of bits to rotate right.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ int │ int │
│ 1 │ binary │ binary │
│ 2 │ list<int> │ list<int> │
│ 3 │ list<binary> │ list<binary> │
╰───┴──────────────┴──────────────╯
Examples:
rotate right a number with 2 bits
> 17 | bits ror 2
68
rotate right a list of numbers of two bytes
> [15 33 92] | bits ror 2 --number-bytes 2
╭───┬───────╮
│ 0 │ 49155 │
│ 1 │ 16392 │
│ 2 │ 23 │
╰───┴───────╯
rotate right binary data
> 0x[ff bb 03] | bits ror 10
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: c0 ff ee ×××
bits shl
Bitwise shift left for ints or binary values.
Search terms: shift left
Usage:
> bits shl {flags} <bits>
Flags:
-h, --help: Display the help message for this command
-s, --signed: always treat input number as a signed number
-n, --number-bytes <int>: the word size in number of bytes. Must be 1, 2, 4, or 8 (defaults to the smallest of those that fits the input number)
Parameters:
bits <int>: Number of bits to shift left.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ int │ int │
│ 1 │ binary │ binary │
│ 2 │ list<int> │ list<int> │
│ 3 │ list<binary> │ list<binary> │
╰───┴──────────────┴──────────────╯
Examples:
Shift left a number by 7 bits
> 2 | bits shl 7
0
Shift left a number with 2 byte by 7 bits
> 2 | bits shl 7 --number-bytes 2
256
Shift left a signed number by 1 bit
> 0x7F | bits shl 1 --signed
-2
Shift left a list of numbers
> [5 3 2] | bits shl 2
╭───┬────╮
│ 0 │ 20 │
│ 1 │ 12 │
│ 2 │ 8 │
╰───┴────╯
Shift left a binary value
> 0x[4f f4] | bits shl 4
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: ff 40 ×@
bits shr
Bitwise shift right for ints or binary values.
Search terms: shift right
Usage:
> bits shr {flags} <bits>
Flags:
-h, --help: Display the help message for this command
-s, --signed: always treat input number as a signed number
-n, --number-bytes <int>: the word size in number of bytes. Must be 1, 2, 4, or 8 (defaults to the smallest of those that fits the input number)
Parameters:
bits <int>: Number of bits to shift right.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ int │ int │
│ 1 │ binary │ binary │
│ 2 │ list<int> │ list<int> │
│ 3 │ list<binary> │ list<binary> │
╰───┴──────────────┴──────────────╯
Examples:
Shift right a number with 2 bits
> 8 | bits shr 2
2
Shift right a list of numbers
> [15 35 2] | bits shr 2
╭───┬───╮
│ 0 │ 3 │
│ 1 │ 8 │
│ 2 │ 0 │
╰───┴───╯
Shift right a binary value
> 0x[4f f4] | bits shr 4
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 04 ff •×
bits xor
Performs bitwise xor for ints or binary values.
Search terms: logic xor
Usage:
> bits xor {flags} <target>
Flags:
-h, --help: Display the help message for this command
-e, --endian <string>: byte encode endian, available options: native(default), little, big
Parameters:
target <oneof<binary, int>>: Right-hand side of the operation.
Input/output types:
╭───┬──────────────┬──────────────╮
│ # │ input │ output │
├───┼──────────────┼──────────────┤
│ 0 │ int │ int │
│ 1 │ binary │ binary │
│ 2 │ list<int> │ list<int> │
│ 3 │ list<binary> │ list<binary> │
╰───┴──────────────┴──────────────╯
Examples:
Apply bits xor to two numbers
> 2 | bits xor 2
0
Apply bitwise xor to a list of numbers
> [8 3 2] | bits xor 2
╭───┬────╮
│ 0 │ 10 │
│ 1 │ 1 │
│ 2 │ 0 │
╰───┴────╯
Apply bitwise xor to binary data
> 0x[ca fe] | bits xor 0x[ba be]
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 70 40 p@
Apply bitwise xor to binary data of varying lengths with specified endianness
> 0x[ca fe] | bits xor 0x[aa] --endian big
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: ca 54 ×T
Apply bitwise xor to input binary data smaller than the operand
> 0x[ff] | bits xor 0x[12 34 56] --endian little
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: ed 34 56 ×4V
break
Break a loop.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
break can only be used in while, loop, and for loops. It can not be used with each or other filter commands
Usage:
> break
Flags:
-h, --help: Display the help message for this command
Examples:
Break out of a loop
> loop { break }
if
Conditionally run a block.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: else, conditional
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" + <oneof<block, expression>>: Expression or block to run when the condition is false. (optional)
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!
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 split - Split input into multiple items using a separator.
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]
Length: 5 (0x5) bytes | printable whitespace ascii_other non_ascii
00000000: aa 1f ff aa aa ו×××
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
Length: 6 (0x6) bytes | printable whitespace ascii_other non_ascii
00000000: 1f aa bb ff aa aa •×××××
Add bytes 0x[11] to 0x[FF AA AA] at the end
> 0x[FF AA AA] | bytes add 0x[11] --end
Length: 4 (0x4) bytes | printable whitespace ascii_other non_ascii
00000000: ff aa aa 11 ××ו
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
Length: 6 (0x6) bytes | printable whitespace ascii_other non_ascii
00000000: ff aa 11 22 33 bb ×ו"3×
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:
Extract bytes starting from a specific index
> { data: 0x[33 44 55 10 01 13 10] } | bytes at 3.. data
╭──────┬─────────────────╮
│ data │ [16, 1, 19, 16] │
╰──────┴─────────────────╯
Slice out 0x[10 01 13] from 0x[33 44 55 10 01 13]
> 0x[33 44 55 10 01 13] | bytes at 3..5
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: 10 01 13 •••
Extract bytes from the start up to a specific index
> 0x[33 44 55 10 01 13 10] | bytes at ..4
Length: 5 (0x5) bytes | printable whitespace ascii_other non_ascii
00000000: 33 44 55 10 01 3DU••
Extract byte 0x[10] using an exclusive end index
> 0x[33 44 55 10 01 13 10] | bytes at 3..<4
Length: 1 (0x1) bytes | printable whitespace ascii_other non_ascii
00000000: 10 •
Extract bytes up to a negative index (inclusive)
> 0x[33 44 55 10 01 13 10] | bytes at ..-4
Length: 4 (0x4) bytes | printable whitespace ascii_other non_ascii
00000000: 33 44 55 10 3DU•
Slice bytes across multiple table columns
> [[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] │
╰───┴──────────────┴──────────┴──────────╯
Extract the last three bytes using a negative start index
> 0x[33 44 55 10 01 13 10] | bytes at (-3)..
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: 01 13 10 •••
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]
Length: 4 (0x4) bytes | printable whitespace ascii_other non_ascii
00000000: 01 02 03 04 ••••
Builds binary data from byte numbers
> bytes build 255 254 253 252
Length: 4 (0x4) bytes | printable whitespace ascii_other non_ascii
00000000: ff fe fd fc ××××
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
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: 11 13 15 •••
Create a byte array from input with a separator
> [0x[11] 0x[33] 0x[44]] | bytes collect 0x[01]
Length: 5 (0x5) bytes | printable whitespace ascii_other non_ascii
00000000: 11 01 33 01 44 ••3•D
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]
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: ff aa ff ×××
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]
Length: 6 (0x6) bytes | printable whitespace ascii_other non_ascii
00000000: 10 aa 10 bb cc aa •×•×××
Remove find binary from end not found
> 0x[10 AA 10 BB CC AA 10] | bytes remove --end 0x[11]
Length: 7 (0x7) bytes | printable whitespace ascii_other non_ascii
00000000: 10 aa 10 bb cc aa 10 •×•××ו
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]
Length: 4 (0x4) bytes | printable whitespace ascii_other non_ascii
00000000: ff ff aa ff ××××
Find and replace all occurrences of find binary
> 0x[10 AA 10 BB 10] | bytes replace --all 0x[10] 0x[A0]
Length: 5 (0x5) bytes | printable whitespace ascii_other non_ascii
00000000: a0 aa a0 bb a0 ×××××
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
Length: 4 (0x4) bytes | printable whitespace ascii_other non_ascii
00000000: aa aa ff 1f ××ו
Reverse bytes 0x[FF AA AA]
> 0x[FF AA AA] | bytes reverse
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: aa aa ff ×××
bytes split
Split input into multiple items using a separator.
Search terms: separate, stream
Usage:
> bytes split <separator>
Flags:
-h, --help: Display the help message for this command
Parameters:
separator <oneof<binary, string>>: Bytes or string that the input will be split on (must be non-empty).
Input/output types:
╭───┬────────┬──────────────╮
│ # │ input │ output │
├───┼────────┼──────────────┤
│ 0 │ binary │ list<binary> │
╰───┴────────┴──────────────╯
Examples:
Split a binary value using a binary separator
> 0x[66 6F 6F 20 62 61 72 20 62 61 7A 20] | bytes split 0x[20]
╭───┬─────────────────╮
│ 0 │ [102, 111, 111] │
│ 1 │ [98, 97, 114] │
│ 2 │ [98, 97, 122] │
│ 3 │ [] │
╰───┴─────────────────╯
Split a binary value using a string separator
> 0x[61 2D 2D 62 2D 2D 63] | bytes split "--"
╭───┬──────╮
│ 0 │ [97] │
│ 1 │ [98] │
│ 2 │ [99] │
╰───┴──────╯
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
-t, --as-table: output as a table
--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 │ string │
│ 1 │ 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 mo
How many 'Friday the Thirteenths' occurred in 2015?
> cal --as-table --full-year 2015 | where fr == 13 | length
cd
Change directory.
Search terms: change, directory, dir, folder, switch
Usage:
> cd {flags} (path)
Flags:
-h, --help: Display the help message for this command
-P, --physical: use the physical directory structure; resolve symbolic links before processing instances of ..
Parameters:
path <directory>: The path to change to. (optional)
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Change to your home directory
> cd ~
Change to the previous working directory (same as "cd $env.OLDPWD")
> cd -
Changing directory with a custom command requires 'def --env'
> def --env gohome [] { cd ~ }
Move two directories up in the tree (the parent directory's parent). Additional dots can be added for additional levels.
> cd ...
The cd command itself is often optional. Simply entering a path to a directory will cd to it.
> /home
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
👨👦👦
chunk-by
Divides a sequence into sub-sequences based on a closure.
chunk-by applies the given closure to each value of the input list, and groups
consecutive elements that share the same closure result value into lists.
Usage:
> chunk-by <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 │ list<any> │ list<list<any>> │
│ 1 │ range │ list<list<any>> │
╰───┴───────────┴─────────────────╯
Examples:
Chunk data into runs of larger than zero or not.
> [1, 3, -2, -2, 0, 1, 2] | chunk-by {|it| $it >= 0 }
╭───┬────────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 3 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬────╮ │
│ │ │ 0 │ -2 │ │
│ │ │ 1 │ -2 │ │
│ │ ╰───┴────╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ 0 │ │
│ │ │ 1 │ 1 │ │
│ │ │ 2 │ 2 │ │
│ │ ╰───┴───╯ │
╰───┴────────────╯
Identify repetitions in a string
> [a b b c c c] | chunk-by { |it| $it }
╭───┬───────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ a │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ b │ │
│ │ │ 1 │ b │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ c │ │
│ │ │ 1 │ c │ │
│ │ │ 2 │ c │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
Chunk values of range by predicate
> (0..8) | chunk-by { |it| $it // 3 }
╭───┬───────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 0 │ │
│ │ │ 1 │ 1 │ │
│ │ │ 2 │ 2 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 3 │ │
│ │ │ 1 │ 4 │ │
│ │ │ 2 │ 5 │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ 6 │ │
│ │ │ 1 │ 7 │ │
│ │ │ 2 │ 8 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
chunks
Divide a list, table or binary input into chunks of chunk_size.
This command will error if chunk_size is negative or zero.
Search terms: batch, group, split, bytes
Usage:
> chunks <chunk_size>
Flags:
-h, --help: Display the help message for this command
Parameters:
chunk_size <int>: The size of each chunk.
Input/output types:
╭───┬───────────┬─────────────────╮
│ # │ input │ output │
├───┼───────────┼─────────────────┤
│ 0 │ table │ list<table> │
│ 1 │ list<any> │ list<list<any>> │
│ 2 │ binary │ list<binary> │
╰───┴───────────┴─────────────────╯
Examples:
Chunk a list into pairs
> [1 2 3 4] | chunks 2
╭───┬───────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 3 │ │
│ │ │ 1 │ 4 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
Chunk the rows of a table into triplets
> [[foo bar]; [0 1] [2 3] [4 5] [6 7] [8 9]] | chunks 3
╭───┬───────────────────╮
│ 0 │ ╭───┬─────┬─────╮ │
│ │ │ # │ foo │ bar │ │
│ │ ├───┼─────┼─────┤ │
│ │ │ 0 │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ 3 │ │
│ │ │ 2 │ 4 │ 5 │ │
│ │ ╰───┴─────┴─────╯ │
│ 1 │ ╭───┬─────┬─────╮ │
│ │ │ # │ foo │ bar │ │
│ │ ├───┼─────┼─────┤ │
│ │ │ 0 │ 6 │ 7 │ │
│ │ │ 1 │ 8 │ 9 │ │
│ │ ╰───┴─────┴─────╯ │
╰───┴───────────────────╯
Chunk the bytes of a binary into triplets
> 0x[11 22 33 44 55 66 77 88] | chunks 3
╭───┬───────────────╮
│ 0 │ [17, 34, 51] │
│ 1 │ [68, 85, 102] │
│ 2 │ [119, 136] │
╰───┴───────────────╯
clear
Clear the terminal.
By default clears the current screen and the off-screen scrollback buffer.
Usage:
> clear {flags}
Flags:
-h, --help: Display the help message for this command
-k, --keep-scrollback: Do not clear the scrollback history
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Clear the terminal
> clear
Clear the terminal but not its scrollback history
> clear --keep-scrollback
collect
Collect a stream into a value.
If provided, run a closure with the collected value as input.
The entire stream will be collected into one value in memory, so if the stream
is particularly large, this can cause high memory usage.
Usage:
> collect {flags} (closure)
Flags:
-h, --help: Display the help message for this command
--keep-env: let the closure affect environment variables
Parameters:
closure <closure(any)>: The closure to run once the stream is collected. (optional)
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Use the second value in the stream
> [1 2 3] | collect { |x| $x.1 }
2
Read and write to the same file
> open file.txt | collect | save -f file.txt
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 the current command line input buffer.
Search terms: repl, interactive
Usage:
> commandline
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
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ 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)
-A, --accept: immediately executes the result after edit
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.
Can be used to remove null or empty values from lists and records too.
Search terms: empty, remove
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 │ record │ record │
│ 1 │ 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 │
╰───┴───╯
Filter out all instances of null from a record
> {a: 1, b: null, c: 3} | compact
╭───┬───╮
│ a │ 1 │
│ c │ 3 │
╰───┴───╯
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, stderr, and exit_code
> ^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 flatten - Show the current configuration in a flattened form.
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.
config use-colors - Get the configuration for color output.
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 the internal default env.nu file instead.
-s, --doc: Print a commented env.nu with documentation instead.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
open user's env.nu in the default editor
> config env
pretty-print a commented env.nu that explains common settings
> config env --doc | nu-highlight,
pretty-print the internal env.nu file which is loaded before the user's environment
> config env --default | nu-highlight,
config flatten
Show the current configuration in a flattened form.
Usage:
> config flatten
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
Show the current configuration in a flattened form
> config flatten
config nu
Edit nu configurations.
Usage:
> config nu {flags}
Flags:
-h, --help: Display the help message for this command
-d, --default: Print the internal default config.nu file instead.
-s, --doc: Print a commented config.nu with documentation instead.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
open user's config.nu in the default editor
> config nu
pretty-print a commented config.nu that explains common settings
> config nu --doc | nu-highlight
pretty-print the internal config.nu file which is loaded before user's config
> config nu --default | nu-highlight
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
config use-colors
Get the configuration for color output.
Use this command instead of checking $env.config.use_ansi_coloring to properly handle the "auto" setting, including environment variables that influence its behavior.
Usage:
> config use-colors
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ bool │
╰───┴─────────┴────────╯
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.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
continue can only be used in while, loop, and for loops. It can not be used with each or other filter commands
Usage:
> continue
Flags:
-h, --help: Display the help message for this command
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 <oneof<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 myfile newfile
Copy file preserving mode and timestamps attributes
> cp --preserve [ mode timestamps ] myfile newfile
Copy file erasing all attributes
> cp --preserve [] myfile newfile
Copy file to a directory three levels above its current location
> cp myfile ....
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 from-human - Convert a human readable datetime string to a datetime.
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-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 │ datetime │ string │
│ 1 │ string │ string │
╰───┴──────────┴────────╯
date from-human
Convert a human readable datetime string to a datetime.
Search terms: relative, now, today, tomorrow, yesterday, weekday, weekday_name, timezone
Usage:
> date from-human {flags}
Flags:
-h, --help: Display the help message for this command
-l, --list: Show human-readable datetime parsing examples
Input/output types:
╭───┬─────────┬──────────╮
│ # │ input │ output │
├───┼─────────┼──────────┤
│ 0 │ string │ datetime │
│ 1 │ nothing │ table │
╰───┴─────────┴──────────╯
Examples:
Parsing human readable datetime
> 'Today at 18:30' | date from-human
Parsing human readable datetime
> 'Last Friday at 19:45' | date from-human
Parsing human readable datetime
> 'In 5 minutes and 30 seconds' | date from-human
PShow human-readable datetime parsing examples
> date from-human --list
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 │ datetime │ 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 │ datetime │
╰───┴─────────┴──────────╯
Examples:
Get the current date and format it in a given format string.
> date now | format date "%Y-%m-%d %H:%M:%S"
Get the current date and format it according to the RFC 3339 standard.
> date now | format date "%+"
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 and format it in the debug format (RFC 2822 with timezone)
> date now | debug
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 │ datetime │ datetime │
│ 1 │ string │ datetime │
╰───┴──────────┴──────────╯
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 (5 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 (5 years ago)
debug
Debug print the value(s) piped in.
Usage:
> debug {flags}
Subcommands:
debug env - Show environment variables as external commands would get it.
debug experimental-options - Show all experimental options.
debug info - View process memory info.
debug profile - Profile pipeline elements in a closure.
Flags:
-h, --help: Display the help message for this command
-r, --raw: Prints the raw value representation
-v, --raw-value: Prints the raw value representation but not the nushell value part
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 print an ansi escape encoded string and get the raw value
> $'(ansi red)nushell(ansi reset)' | debug -v
"\u{1b}[31mnushell\u{1b}[0m"
debug env
Show environment variables as external commands would get it.
Usage:
> debug env
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
Get PATH variable that externals see
> debug env | get PATH!
Create a .env file
> debug env | transpose key value | each {$"($in.key)=($in.value | to json)"} | save .env
debug experimental-options
Show all experimental options.
Usage:
> debug experimental-options
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ # │ input │ output │
├───┼─────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 0 │ nothing │ table<identifier: string, enabled: bool, status: string, description: string, since: string, issue: string> │
╰───┴─────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
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
debug profile
Profile pipeline elements in a closure.
The profiler profiles every evaluated instruction inside a closure, stepping into all
commands calls and other blocks/closures.
The output can be heavily customized. By default, the following columns are included:
- depth : Depth of the instruction. Each entered block adds one level of depth. How many
blocks deep to step into is controlled with the --max-depth option.
- id : ID of the instruction
- parent_id : ID of the instruction that created the parent scope
- source : Source code that generated the instruction. If the source code has multiple lines,
only the first line is used and ... is appended to the end. Full source code can
be shown with the --expand-source flag.
- pc : The index of the instruction within the block.
- instruction : The pretty printed instruction being evaluated.
- duration : How long it took to run the instruction.
- (optional) span : Span associated with the instruction. Can be viewed via the view span
command. Enabled with the --spans flag.
- (optional) output : The output value of the instruction. Enabled with the --values flag.
To illustrate the depth and IDs, consider debug profile { do { if true { echo 'spam' } } }. A unique ID is generated each time an instruction is executed, and there are two levels of depth:
depth id parent_id source pc instruction
0 0 0 debug profile { do { if true { ‘spam’ } } } 0
1 1 0 { if true { ‘spam’ } } 0 load-literal %1, closure(2164)
1 2 0 { if true { ‘spam’ } } 1 push-positional %1
1 3 0 { do { if true { ‘spam’ } } } 2 redirect-out caller
1 4 0 { do { if true { ‘spam’ } } } 3 redirect-err caller
1 5 0 do 4 call decl 7 “do”, %0
2 6 5 true 0 load-literal %1, bool(true)
2 7 5 if 1 not %1
2 8 5 if 2 branch-if %1, 5
2 9 5 ‘spam’ 3 load-literal %0, string(“spam”)
2 10 5 if 4 jump 6
2 11 5 { if true { ‘spam’ } } 6 return %0
1 12 0 { do { if true { ‘spam’ } } } 5 return %0
Each block entered increments depth by 1 and each block left decrements it by one. This way you can
control the profiling granularity. Passing --max-depth=1 to the above would stop inside the do
at if true { 'spam' }. The id is used to identify each element. The parent_id tells you that the
instructions inside the block are being executed because of do (5), which in turn was spawned from
the root debug profile { ... }.
For a better understanding of how instructions map to source code, see the view ir command.
Note: In some cases, the ordering of pipeline elements might not be intuitive. For example,
[ a bb cc ] | each { $in | str length } involves some implicit collects and lazy evaluation
confusing the id/parent_id hierarchy. The --expr flag is helpful for investigating these issues.
Usage:
> debug profile {flags} <closure>
Flags:
-h, --help: Display the help message for this command
-s, --spans: Collect spans of profiled elements
-e, --expand-source: Collect full source fragments of profiled elements
-v, --values: Collect pipeline element output values
-l, --lines: Collect line numbers
-d, --duration-values: Report instruction duration as duration values rather than milliseconds
-m, --max-depth <int>: How many blocks/closures deep to step into (default 2)
Parameters:
closure <closure()>: The closure to profile.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ table │
╰───┴───────┴────────╯
Examples:
Profile config evaluation
> debug profile { source $nu.config-path }
Profile config evaluation with more granularity
> debug profile { source $nu.config-path } --max-depth 4
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 base32 - Decode a Base32 value.
decode base32hex - Encode a base32hex value.
decode base64 - Decode a Base64 value.
decode hex - Hex 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 base32
Decode a Base32 value.
The default alphabet is taken from RFC 4648, section 6.
Note this command will collect stream input.
Usage:
> decode base32 {flags}
Flags:
-h, --help: Display the help message for this command
--nopad: Do not pad the output.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ binary │
╰───┴────────┴────────╯
Examples:
Decode arbitrary binary data
> "AEBAGBAF" | decode base32
Length: 5 (0x5) bytes | printable whitespace ascii_other non_ascii
00000000: 01 02 03 04 05 •••••
Decode an encoded string
> "NBUQ====" | decode base32 | decode
Parse a string without padding
> "NBUQ" | decode base32 --nopad
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 68 69 hi
decode base32hex
Encode a base32hex value.
This command uses an alternative Base32 alphabet, defined in RFC 4648, section 7.
Note this command will collect stream input.
Usage:
> decode base32hex {flags}
Flags:
-h, --help: Display the help message for this command
--nopad: Reject input with padding.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ binary │
╰───┴────────┴────────╯
Examples:
Decode arbitrary binary data
> "ATNAQ===" | decode base32hex
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: 57 6e ad Wn×
Decode an encoded string
> "D1KG====" | decode base32hex | decode
Parse a string without padding
> "ATNAQ" | decode base32hex --nopad
Length: 3 (0x3) bytes | printable whitespace ascii_other non_ascii
00000000: 57 6e ad Wn×
decode base64
Decode a Base64 value.
The default alphabet is taken from RFC 4648, section 4. A URL-safe version is available.
Note this command will collect stream input.
Usage:
> decode base64 {flags}
Flags:
-h, --help: Display the help message for this command
--url: Decode the URL-safe Base64 version.
--nopad: Reject padding.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ binary │
╰───┴────────┴────────╯
Examples:
Decode a Base64 string
> "U29tZSBEYXRh" | decode base64 | decode
Decode arbitrary data
> "/w==" | decode base64
Length: 1 (0x1) bytes | printable whitespace ascii_other non_ascii
00000000: ff ×
Decode a URL-safe Base64 string
> "_w==" | decode base64 --url
Length: 1 (0x1) bytes | printable whitespace ascii_other non_ascii
00000000: ff ×
decode hex
Hex decode a value.
Usage:
> decode hex
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ binary │
╰───┴────────┴────────╯
Examples:
Decode arbitrary binary data
> "09FD" | decode hex
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 09 fd _×
Lowercase Hex is also accepted
> "09fd" | decode hex
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 09 fd _×
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
cd affects the environment, so '--env' is required to change directory from within a command
> def --env gohome [] { cd ~ }; gohome; $env.PWD == ('~' | path expand)
true
Define a custom wrapper for an external command
> def --wrapped my-echo [...rest] { ^echo ...$rest }; my-echo -e 'spam\tspam'
spamspam
Define a custom command with a type signature. Passing a non-int value will result in an error
> def only_int []: int -> int { $in }; 42 | only_int
42
default
Sets a default value if a row's column is missing or null.
Usage:
> default {flags} <default value> ...(column name)
Flags:
-h, --help: Display the help message for this command
-e, --empty: also replace empty items like "", {}, and []
Parameters:
default value <any>: The value to use as a default.
...column name <string>: The name of the column.
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 --optional MY_ENV | default 'abc'
abc
Replace the null value in a list
> [1, 2, null, 4] | each { default 3 }
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
│ 3 │ 4 │
╰───┴───╯
Replace the missing value in the "a" column of a list
> [{a:1 b:2} {b:1}] | default 'N/A' a
╭───┬─────┬───╮
│ # │ a │ b │
├───┼─────┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ N/A │ 1 │
╰───┴─────┴───╯
Replace the empty string in the "a" column of a list
> [{a:1 b:2} {a:'' b:1}] | default -e 'N/A' a
╭───┬─────┬───╮
│ # │ a │ b │
├───┼─────┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ N/A │ 1 │
╰───┴─────┴───╯
Generate a default value from a closure
> null | default { 1 + 2 }
3
Fill missing column values based on other columns
> [{a:1 b:2} {b:1}] | upsert a {|rc| default { $rc.b + 1 } }
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 2 │ 1 │
╰───┴───┴───╯
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
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| $'Saving ($x)'}, first_commit: 2019-05-10, my_duration: (4min + 20sec)} | describe -d
╭───────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ type │ record │
│ detailed_type │ record<shell: string, uwu: bool, features: record<bugs: bool, multiplatform: bool, speed: int>, fib: list<int>, on_save: │
│ │ closure, first_commit: datetime, my_duration: duration> │
│ │ ╭──────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ columns │ │ │ ╭───────────────┬────────────────────────╮ │ │
│ │ │ shell │ │ type │ string │ │ │
│ │ │ │ │ detailed_type │ string │ │ │
│ │ │ │ │ rust_type │ &alloc::string::String │ │ │
│ │ │ │ │ value │ true │ │ │
│ │ │ │ ╰───────────────┴────────────────────────╯ │ │
│ │ │ │ ╭───────────────┬──────╮ │ │
│ │ │ uwu │ │ type │ bool │ │ │
│ │ │ │ │ detailed_type │ bool │ │ │
│ │ │ │ │ rust_type │ bool │ │ │
│ │ │ │ │ value │ true │ │ │
│ │ │ │ ╰───────────────┴──────╯ │ │
│ │ │ │ ╭──────────────────────┬─────────────────────────────────────────────────────────────────────────────╮ │ │
│ │ │ features │ │ type │ record │ │ │
│ │ │ │ │ detailed_type │ record<bugs: bool, multiplatform: bool, speed: int> │ │ │
│ │ │ │ │ │ ╭───────────────┬───────────────────────────╮ │ │ │
│ │ │ │ │ columns │ │ │ ╭───────────────┬───────╮ │ │ │ │
│ │ │ │ │ │ │ bugs │ │ type │ bool │ │ │ │ │
│ │ │ │ │ │ │ │ │ detailed_type │ bool │ │ │ │ │
│ │ │ │ │ │ │ │ │ rust_type │ bool │ │ │ │ │
│ │ │ │ │ │ │ │ │ value │ false │ │ │ │ │
│ │ │ │ │ │ │ │ ╰───────────────┴───────╯ │ │ │ │
│ │ │ │ │ │ │ │ ╭───────────────┬──────╮ │ │ │ │
│ │ │ │ │ │ │ multiplatform │ │ type │ bool │ │ │ │ │
│ │ │ │ │ │ │ │ │ detailed_type │ bool │ │ │ │ │
│ │ │ │ │ │ │ │ │ rust_type │ bool │ │ │ │ │
│ │ │ │ │ │ │ │ │ value │ true │ │ │ │ │
│ │ │ │ │ │ │ │ ╰───────────────┴──────╯ │ │ │ │
│ │ │ │ │ │ │ │ ╭───────────────┬─────╮ │ │ │ │
│ │ │ │ │ │ │ speed │ │ type │ int │ │ │ │ │
│ │ │ │ │ │ │ │ │ detailed_type │ int │ │ │ │ │
│ │ │ │ │ │ │ │ │ rust_type │ i64 │ │ │ │ │
│ │ │ │ │ │ │ │ │ value │ 10 │ │ │ │ │
│ │ │ │ │ │ │ │ ╰───────────────┴─────╯ │ │ │ │
│ │ │ │ │ │ ╰───────────────┴───────────────────────────╯ │ │ │
│ │ │ │ │ rust_type │ &nu_utils::shared_cow::SharedCow<nu_protocol::value::record::Record> │ │ │
│ │ │ │ ╰──────────────────────┴─────────────────────────────────────────────────────────────────────────────╯ │ │
│ │ │ │ ╭───────────────┬──────────────────────────────────────────────────╮ │ │
│ │ │ fib │ │ type │ list │ │ │
│ │ │ │ │ detailed_type │ list<int> │ │ │
│ │ │ │ │ length │ 6 │ │ │
│ │ │ │ │ rust_type │ &mut alloc::vec::Vec<nu_protocol::value::Value> │ │ │
│ │ │ │ │ │ ╭───┬──────┬───────────────┬───────────┬───────╮ │ │ │
│ │ │ │ │ value │ │ # │ type │ detailed_type │ rust_type │ value │ │ │ │
│ │ │ │ │ │ ├───┼──────┼───────────────┼───────────┼───────┤ │ │ │
│ │ │ │ │ │ │ 0 │ int │ int │ i64 │ 1 │ │ │ │
│ │ │ │ │ │ │ 1 │ int │ int │ i64 │ 1 │ │ │ │
│ │ │ │ │ │ │ 2 │ int │ int │ i64 │ 2 │ │ │ │
│ │ │ │ │ │ │ 3 │ int │ int │ i64 │ 3 │ │ │ │
│ │ │ │ │ │ │ 4 │ int │ int │ i64 │ 5 │ │ │ │
│ │ │ │ │ │ │ 5 │ int │ int │ i64 │ 8 │ │ │ │
│ │ │ │ │ │ ╰───┴──────┴───────────────┴───────────┴───────╯ │ │ │
│ │ │ │ ╰───────────────┴──────────────────────────────────────────────────╯ │ │
│ │ │ │ ╭───────────────┬───────────────────────────────────────────────────────────╮ │ │
│ │ │ on_save │ │ type │ closure │ │ │
│ │ │ │ │ detailed_type │ closure │ │ │
│ │ │ │ │ rust_type │ &alloc::boxed::Box<nu_protocol::engine::closure::Closure> │ │ │
│ │ │ │ │ value │ closure_1 │ │ │
│ │ │ │ │ │ ╭──────────┬─────────╮ │ │ │
│ │ │ │ │ signature │ │ name │ │ │ │ │
│ │ │ │ │ │ │ category │ default │ │ │ │
│ │ │ │ │ │ ╰──────────┴─────────╯ │ │ │
│ │ │ │ ╰───────────────┴───────────────────────────────────────────────────────────╯ │ │
│ │ │ │ ╭─────────────────────────┬──────────────────────────────────────────────────────────────────────────╮ │ │
│ │ │ first_commit │ │ type │ datetime │ │ │
│ │ │ │ │ detailed_type │ datetime │ │ │
│ │ │ │ │ rust_type │ chrono::datetime::DateTime<chrono::offset::fixed::FixedOffset> │ │ │
│ │ │ │ │ value │ 6 years ago │ │ │
│ │ │ │ ╰─────────────────────────┴──────────────────────────────────────────────────────────────────────────╯ │ │
│ │ │ │ ╭───────────────┬────────────╮ │ │
│ │ │ my_duration │ │ type │ duration │ │ │
│ │ │ │ │ detailed_type │ duration │ │ │
│ │ │ │ │ rust_type │ i64 │ │ │
│ │ │ │ │ value │ 4min 20sec │ │ │
│ │ │ │ ╰───────────────┴────────────╯ │ │
│ │ ╰──────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ rust_type │ &nu_utils::shared_cow::SharedCow<nu_protocol::value::record::Record> │
╰───────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
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
Various commands for detecting things.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> detect
Subcommands:
detect columns - Attempt to automatically split text into multiple columns.
detect type - Infer Nushell datatype from a string.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
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
--guess: detect columns by guessing width, it may be useful if default one doesn't work
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ table │
╰───┴────────┴────────╯
Examples:
use --guess if you find default algorithm not working
>
'Filesystem 1K-blocks Used Available Use% Mounted on
none 8150224 4 8150220 1% /mnt/c' | detect columns --guess
╭───┬────────────┬───────────┬──────┬───────────┬──────┬────────────╮
│ # │ Filesystem │ 1K-blocks │ Used │ Available │ Use% │ Mounted on │
├───┼────────────┼───────────┼──────┼───────────┼──────┼────────────┤
│ 0 │ none │ 8150224 │ 4 │ 8150220 │ 1% │ /mnt/c │
╰───┴────────────┴───────────┴──────┴───────────┴──────┴────────────╯
detect columns with no headers
> '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
detect type
Infer Nushell datatype from a string.
Search terms: convert, conversion
Usage:
> detect type {flags}
Flags:
-h, --help: Display the help message for this command
-f, --prefer-filesize: For ints display them as human-readable file sizes
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ any │
│ 1 │ any │ any │
╰───┴────────┴────────╯
Examples:
Bool from string
> 'true' | detect type
true
Bool is case insensitive
> 'FALSE' | detect type
false
Int from plain digits
> '42' | detect type
42
Int with underscores
> '1_000_000' | detect type
1000000
Int with commas
> '1,234,567' | detect type
1234567
Float from decimal
> '3.14' | detect type
3.14
Float in scientific notation
> '6.02e23' | detect type
601999999999999995805696.0
Prefer filesize for ints
> '1024' | detect type -f
1.0 kB
Date Y-M-D
> '2022-01-01' | detect type
Sat, 1 Jan 2022 00:00:00 +0900 (3 years ago)
Date with time and offset
> '2022-01-01T00:00:00Z' | detect type
Sat, 1 Jan 2022 00:00:00 +0000 (3 years ago)
Date D-M-Y
> '31-12-2021' | detect type
Fri, 31 Dec 2021 00:00:00 +0900 (3 years ago)
Unknown stays a string
> 'not-a-number' | detect type
not-a-number
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
-c, --capture-errors: catch errors as the closure runs, and return them
--env: keep the environment defined inside the command
Parameters:
closure <closure()>: 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 }
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, type-checked parameter
> do {|x:int| 100 + $x } 77
177
Run the closure with pipeline input
> 77 | do { 100 + $in }
177
Run the closure with a default parameter value
> 77 | do {|x=100| $x + $in }
177
Run the closure with two positional parameters
> do {|x,y| $x + $y } 77 100
177
Run the closure and keep changes to the environment
> do --env { $env.foo = 'bar' }; $env.foo
bar
drop
Remove items/rows from the end of the input list/table. Counterpart of skip. Opposite of last.
Search terms: delete, remove
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, remove
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, remove, index
Usage:
> drop nth ...(rest)
Flags:
-h, --help: Display the help message for this command
Parameters:
...rest <any>: The row numbers or ranges to drop.
Input/output types:
╭───┬───────────┬──────────────╮
│ # │ input │ output │
├───┼───────────┼──────────────┤
│ 0 │ range │ list<number> │
│ 1 │ 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
-r, --deref: Dereference symlinks to their targets for size
-l, --long: Get underlying directories and files for each entry
-x, --exclude <glob>: Exclude these file names
-d, --max-depth <int>: Directory recursion limit
-m, --min-size <int>: Exclude files below this size
Parameters:
...path <oneof<glob, string>>: Starting directory.
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, use 'items' or try converting it to a table
with 'transpose' first.
By default, for each input there is a single output value.
If the closure returns a stream rather than value, the stream is collected
completely, and the resulting value becomes one of the items in each's output.
To receive items from those streams without waiting for the whole stream to be
collected, each --flatten can be used.
Instead of waiting for the stream to be collected before returning the result as
a single item, each --flatten will return each item as soon as they are received.
This "flattens" the output, turning an output that would otherwise be a
list of lists like list<list<string>> into a flat list like list<string>.
Search terms: for, loop, iterate, map
Usage:
> each {flags} <closure>
Subcommands:
each while - Run a closure on each row of the input list until a null is found, then create a new list with the results.
Flags:
-h, --help: Display the help message for this command
-k, --keep-empty: keep empty result cells
-f, --flatten: combine outputs into a single stream instead ofcollecting them to separate values
Parameters:
closure <closure(any)>: 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 │
╰───┴───╯
'null' items will be dropped from the result list. It has the same effect as 'filter_map' in other languages.
> [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 │ │
╰───┴──────────╯
Update value if not null, otherwise do nothing
> $env.name? | each { $"hello ($in)" } | default "bye"
Scan through multiple files without pause
> ls *.txt | each --flatten {|f| open $f.name | lines } | find -i 'note: ' | str join "\n"
each while
Run a closure on each row of the input list until a null is found, then create a new list with the results.
Search terms: for, loop, iterate
Usage:
> each while <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 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Produces a list of each element before the 3, doubled
> [1 2 3 2 1] | each while {|e| if $e < 3 { $e * 2 } }
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 4 │
╰───┴───╯
Output elements until reaching 'stop'
> [1 2 stop 3 4] | each while {|e| if $e != 'stop' { $"Output: ($e)" } }
╭───┬───────────╮
│ 0 │ Output: 1 │
│ 1 │ Output: 2 │
╰───┴───────────╯
Iterate over each element, printing the matching value and its index
> [1 2 3] | enumerate | each while {|e| if $e.item < 2 { $"value ($e.item) at ($e.index)!"} }
╭───┬───────────────╮
│ 0 │ value 1 at 0! │
╰───┴───────────────╯
echo
Returns its arguments, ignoring the piped-in value.
Unlike print, which prints unstructured text to stdout, echo is like an
identity function and simply returns its arguments. When given no arguments,
it returns an empty string. When given one argument, it returns it as a
nushell value. 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.
More information can be found here: https://docs.rs/encoding_rs/latest/encoding_rs/#utf-16le-utf-16be-and-unicode-encoding-schemes
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 base32 - Encode a string or binary value using Base32.
encode base32hex - Encode a binary value or a string using base32hex.
encode base64 - Encode a string or binary value using Base64.
encode hex - Hex encode a binary value or a string.
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
Length: 40 (0x28) bytes | printable whitespace ascii_other non_ascii
00000000: 95 89 82 af 82 e9 82 c6 92 6d 82 c1 82 c4 90 ed ×××××××××m××××××
00000010: 82 a4 82 cc 82 aa 81 41 97 79 82 a9 82 c9 94 fc ×××××××A×y××××××
00000020: 82 b5 82 a2 82 cc 82 be ××××××××
Replace characters with HTML entities if they can't be encoded
> "🎈" | encode --ignore-errors shift-jis
Length: 9 (0x9) bytes | printable whitespace ascii_other non_ascii
00000000: 26 23 31 32 37 38 38 30 3b 🎈
encode base32
Encode a string or binary value using Base32.
The default alphabet is taken from RFC 4648, section 6.
Note this command will collect stream input.
Usage:
> encode base32 {flags}
Flags:
-h, --help: Display the help message for this command
--nopad: Don't accept padding.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ string │
│ 1 │ binary │ string │
╰───┴────────┴────────╯
Examples:
Encode a binary value
> 0x[01 02 10] | encode base32
AEBBA===
Encode a string
> "hello there" | encode base32
NBSWY3DPEB2GQZLSMU======
Don't apply padding to the output
> "hi" | encode base32 --nopad
NBUQ
encode base32hex
Encode a binary value or a string using base32hex.
This command uses an alternative Base32 alphabet, defined in RFC 4648, section 7.
Note this command will collect stream input.
Usage:
> encode base32hex {flags}
Flags:
-h, --help: Display the help message for this command
--nopad: Don't pad the output.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ string │
│ 1 │ binary │ string │
╰───┴────────┴────────╯
Examples:
Encode a binary value
> 0x[57 6E AD] | encode base32hex
ATNAQ===
Encode a string
> "hello there" | encode base32hex
D1IMOR3F41Q6GPBICK======
Don't apply padding to the output
> "hello there" | encode base32hex --nopad
D1IMOR3F41Q6GPBICK
encode base64
Encode a string or binary value using Base64.
The default alphabet is taken from RFC 4648, section 4. A URL-safe version is available.
Note this command will collect stream input.
Usage:
> encode base64 {flags}
Flags:
-h, --help: Display the help message for this command
--url: Use the URL-safe Base64 version.
--nopad: Don't pad the output.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ string │
│ 1 │ binary │ string │
╰───┴────────┴────────╯
Examples:
Encode a string with Base64
> "Alphabet from A to Z" | encode base64
QWxwaGFiZXQgZnJvbSBBIHRvIFo=
Encode arbitrary data
> 0x[BE EE FF] | encode base64
vu7/
Use a URL-safe alphabet
> 0x[BE EE FF] | encode base64 --url
vu7_
encode hex
Hex encode a binary value or a string.
Usage:
> encode hex {flags}
Flags:
-h, --help: Display the help message for this command
--lower: Encode to lowercase hex.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ string │
│ 1 │ binary │ string │
╰───┴────────┴────────╯
Examples:
Encode a binary value
> 0x[C3 06] | encode hex
C306
Encode a string
> "hello" | encode hex
68656C6C6F
Output a Lowercase version of the encoding
> 0x[AD EF] | encode hex --lower
adef
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
Various commands for working with errors.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> error
Subcommands:
error make - Create an error.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
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 <oneof<glob, any>>: External command to run, with arguments.
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 <bool>: Show or hide column headers (default true)
-i, --index: Show row indexes when viewing a list
-t, --tail: 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 host information record
> sys host | 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.
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.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
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.
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, repeat
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 an empty string with 10 '─' characters
> '' | fill --character '─' --width 10
──────────
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 both sides to a width of 10 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 can only use a closure as a predicate.
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)>: 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, grep
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; when in regex mode, this is equivalent to (?i)
-m, --multiline: don't split multi-line strings into lists of lines. you should use this option when using the (?m) or (?s) flags in regex mode
-s, --dotall: dotall regex mode: allow a dot . to match newlines \n; equivalent to (?s)
-c, --columns <list<string>>: column names to be searched
-n, --no-highlight: no-highlight mode: find without marking with ansi code
-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 Cargo
Cargo.toml
Search a number or a file size in a list of numbers
> [1 5 3kb 4 35 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 │
╰───┴───────╯
Search using regex
> [abc odb arc abf] | find --regex "b."
╭───┬─────╮
│ 0 │ abc │
│ 1 │ abf │
╰───┴─────╯
Case insensitive search
> [aBc bde Arc abf] | find "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 │ ╭───┬───────╮ │
│ │ │ 0 │ Larry │ │
│ │ │ 1 │ Moe │ │
│ │ ╰───┴───────╯ │
╰───┴───────────────╯
Find inverted values in records using regex
> [["Larry", "Moe"], ["Victor", "Marina"]] | find --regex "rr" --invert
╭───┬────────────────╮
│ 0 │ ╭───┬────────╮ │
│ │ │ 0 │ Victor │ │
│ │ │ 1 │ Marina │ │
│ │ ╰───┴────────╯ │
╰───┴────────────────╯
Remove ANSI sequences from result
> [[foo bar]; [abc 123] [def 456]] | find --no-highlight 123
╭───┬─────┬─────╮
│ # │ foo │ bar │
├───┼─────┼─────┤
│ 0 │ abc │ 123 │
╰───┴─────┴─────╯
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 │
╰───┴──────┴───────┴───────╯
Find in a multi-line string
> "Violets are red\nAnd roses are blue\nWhen metamaterials\nAlter their hue" | find "ue"
╭───┬────────────────────╮
│ 0 │ And roses are blue │
│ 1 │ Alter their hue │
╰───┴────────────────────╯
Find in a multi-line string without splitting the input into a list of lines
> "Violets are red\nAnd roses are blue\nWhen metamaterials\nAlter their hue" | find --multiline "ue"
Violets are red
And roses are blue
When metamaterials
Alter their hue
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
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 01 23 •#
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 │ ╭───┬───╮ │
│ │ │ │ │ 0 │ 4 │ │
│ │ │ │ │ 1 │ 3 │ │
│ │ │ │ ╰───┴───╯ │
│ 1 │ b │ 2 │ ╭───┬───╮ │
│ │ │ │ │ 0 │ 4 │ │
│ │ │ │ │ 1 │ 3 │ │
│ │ │ │ ╰───┴───╯ │
│ 2 │ b │ 3 │ ╭───┬───╮ │
│ │ │ │ │ 0 │ 4 │ │
│ │ │ │ │ 1 │ 3 │ │
│ │ │ │ ╰───┴───╯ │
│ 3 │ b │ 4 │ ╭───┬───╮ │
│ │ │ │ │ 0 │ 4 │ │
│ │ │ │ │ 1 │ 3 │ │
│ │ │ │ ╰───┴───╯ │
╰───┴───┴───┴───────────╯
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 <var_name> in <range> <block>
Flags:
-h, --help: Display the help message for this command
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'] | enumerate) { 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 bits - Convert value to a string of binary data represented by 0 and 1.
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.
format number - Format a number.
format pattern - Format columns into a string using a simple pattern.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
format bits
Convert value to a string of binary data represented by 0 and 1.
Search terms: convert, cast, binary
Usage:
> format bits {flags} ...(rest)
Flags:
-h, --help: Display the help message for this command
-e, --endian <string>: Byte encode endian. Only applies to int, filesize, duration and bool, as well as tables and records of those. Available options: native, little, big(default)
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 │ filesize │ string │
│ 3 │ duration │ string │
│ 4 │ string │ string │
│ 5 │ bool │ string │
│ 6 │ table │ table │
│ 7 │ record │ record │
╰───┴──────────┴────────╯
Examples:
convert a binary value into a string, padded to 8 places with 0s
> 0x[1] | format bits
00000001
convert an int into a string, padded to 8 places with 0s
> 1 | format bits
00000001
convert an int into a string, padded to 8 places with 0s (big endian)
> 258 | format bits
00000001 00000010
convert an int into a string, padded to 8 places with 0s (little endian)
> 258 | format bits --endian little
00000010 00000001
convert a filesize value into a string, padded to 8 places with 0s
> 1b | format bits
00000001
convert a duration value into a string, padded to 8 places with 0s
> 1ns | format bits
00000001
convert a boolean value into a string, padded to 8 places with 0s
> true | format bits
00000001
convert a string into a raw binary string, padded with 0s to 8 places
> 'nushell.sh' | format bits
01101110 01110101 01110011 01101000 01100101 01101100 01101100 00101110 01110011 01101000
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 │ datetime │ string │
│ 1 │ string │ string │
│ 2 │ nothing │ table │
│ 3 │ any │ 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 a given date-time according to the RFC 3339 standard.
> '2021-10-22 20:00:12 +01:00' | into datetime | format date "%+"
2021-10-22T20:00:12+01:00
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 MB
format number
Format a number.
Search terms: display, render, fmt
Usage:
> format number {flags}
Flags:
-h, --help: Display the help message for this command
-n, --no-prefix: don't include the binary, hex or octal prefixes
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ number │ record │
╰───┴────────┴────────╯
Examples:
Get a record containing multiple formats for the number 42
> 42 | format number
╭──────────┬──────────╮
│ debug │ 42 │
│ display │ 42 │
│ binary │ 0b101010 │
│ lowerexp │ 4.2e1 │
│ upperexp │ 4.2E1 │
│ lowerhex │ 0x2a │
│ upperhex │ 0x2A │
│ octal │ 0o52 │
╰──────────┴──────────╯
Format float without prefixes
> 3.14 | format number --no-prefix
╭──────────┬─────────────────────────────────────────────────────────────────╮
│ debug │ 3.14 │
│ display │ 3.14 │
│ binary │ 100000000001001000111101011100001010001111010111000010100011111 │
│ lowerexp │ 3.14e0 │
│ upperexp │ 3.14E0 │
│ lowerhex │ 40091eb851eb851f │
│ upperhex │ 40091EB851EB851F │
│ octal │ 400110753412172702437 │
╰──────────┴─────────────────────────────────────────────────────────────────╯
format pattern
Format columns into a string using a simple pattern.
Usage:
> format pattern <pattern>
Flags:
-h, --help: Display the help message for this command
Parameters:
pattern <string>: The pattern to output. e.g.) "{foo}: {bar}".
Input/output types:
╭───┬────────┬──────────────╮
│ # │ input │ output │
├───┼────────┼──────────────┤
│ 0 │ table │ list<string> │
│ 1 │ record │ any │
╰───┴────────┴──────────────╯
Examples:
Print filenames with their sizes
> ls | format pattern '{name}: {size}'
Print elements from some columns of a table
> [[col1, col2]; [v1, v2] [v3, v4]] | format pattern '{col2}'
╭───┬────╮
│ 0 │ v2 │
│ 1 │ v4 │
╰───┴────╯
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 eml (plugin) - Parse text as .eml and create record.
from ics (plugin) - Parse text as .ics and create table.
from ini (plugin) - Parse text as .ini and create table.
from json - Convert from json to structured data.
from msgpack - Convert MessagePack data into Nu values.
from msgpackz - Convert brotli-compressed MessagePack data into Nu values.
from nuon - Convert from nuon to structured data.
from ods - Parse OpenDocument Spreadsheet(.ods) data and create table.
from plist (plugin) - Convert plist to Nushell values
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 url - Parse url-encoded string as a record.
from vcf (plugin) - Parse text as .vcf 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, allowing variable number of columns per row
> "ColA,ColB
1,2
3,4,5
6" | from csv --flexible
╭───┬──────┬──────┬─────────╮
│ # │ ColA │ ColB │ column2 │
├───┼──────┼──────┼─────────┤
│ 0 │ 1 │ 2 │ ❎ │
│ 1 │ 3 │ 4 │ 5 │
│ 2 │ 6 │ ❎ │ ❎ │
╰───┴──────┴──────┴─────────╯
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 eml
Parse text as .eml and create record.
Usage:
> from eml {flags}
Flags:
-h, --help: Display the help message for this command
-b, --preview-body <int>: How many bytes of the body to preview
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ record │
╰───┴────────┴────────╯
Examples:
Convert eml structured data into record
> 'From: test@email.com
Subject: Welcome
To: someone@somewhere.com
Test' | from eml
╭─────────┬─────────────────────────────────────╮
│ Subject │ Welcome │
│ │ ╭─────────┬────────────────╮ │
│ From │ │ Name │ │ │
│ │ │ Address │ test@email.com │ │
│ │ ╰─────────┴────────────────╯ │
│ │ ╭─────────┬───────────────────────╮ │
│ To │ │ Name │ │ │
│ │ │ Address │ someone@somewhere.com │ │
│ │ ╰─────────┴───────────────────────╯ │
│ Body │ Test │
╰─────────┴─────────────────────────────────────╯
Convert eml structured data into record
> 'From: test@email.com
Subject: Welcome
To: someone@somewhere.com
Test' | from eml -b 1
╭─────────┬─────────────────────────────────────╮
│ Subject │ Welcome │
│ │ ╭─────────┬────────────────╮ │
│ From │ │ Name │ │ │
│ │ │ Address │ test@email.com │ │
│ │ ╰─────────┴────────────────╯ │
│ │ ╭─────────┬───────────────────────╮ │
│ To │ │ Name │ │ │
│ │ │ Address │ someone@somewhere.com │ │
│ │ ╰─────────┴───────────────────────╯ │
│ Body │ T │
╰─────────┴─────────────────────────────────────╯
from ics
Parse text as .ics and create table.
Usage:
> from ics
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ table │
╰───┴────────┴────────╯
Examples:
Converts ics formatted string to table
> 'BEGIN:VCALENDAR
END:VCALENDAR' | from ics
╭──────┬──────────────────┬──────────────────┬──────────────────┬──────────────────┬──────────────────┬──────────────────┬──────────────────╮
│ # │ properties │ events │ alarms │ to-Dos │ journals │ free-busys │ timezones │
├──────┼──────────────────┼──────────────────┼──────────────────┼──────────────────┼──────────────────┼──────────────────┼──────────────────┤
│ 0 │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │ [list 0 items] │
╰──────┴──────────────────┴──────────────────┴──────────────────┴──────────────────┴──────────────────┴──────────────────┴──────────────────╯
from ini
Parse text as .ini and create table.
Usage:
> from ini
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ record │
╰───┴────────┴────────╯
Examples:
Converts ini formatted string to record
> '[foo]
a=1
b=2' | from ini
╭─────┬───────────╮
│ │ ╭───┬───╮ │
│ foo │ │ a │ 1 │ │
│ │ │ b │ 2 │ │
│ │ ╰───┴───╯ │
╰─────┴───────────╯
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 │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
Parse json strictly which will error on comments and trailing commas
> '{ "a": 1, "b": 2 }' | from json -s
╭───┬───╮
│ a │ 1 │
│ b │ 2 │
╰───┴───╯
Parse a stream of line-delimited JSON values
> '{ "a": 1 }
{ "b": 2 }' | from json --objects
╭───┬────┬────╮
│ # │ a │ b │
├───┼────┼────┤
│ 0 │ 1 │ ❎ │
│ 1 │ ❎ │ 2 │
╰───┴────┴────╯
from msgpack
Convert MessagePack data into Nu values.
Not all values are representable as MessagePack.
The datetime extension type is read as dates. MessagePack binary values are
read to their Nu equivalent. Most other types are read in an analogous way to
from json, and may not convert to the exact same type if to msgpack was
used originally to create the data.
MessagePack: https://msgpack.org/
Usage:
> from msgpack {flags}
Flags:
-h, --help: Display the help message for this command
--objects: Read multiple objects from input
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ any │
╰───┴────────┴────────╯
Examples:
Read a list of values from MessagePack
> 0x[93A3666F6F2AC2] | from msgpack
╭───┬───────╮
│ 0 │ foo │
│ 1 │ 42 │
│ 2 │ false │
╰───┴───────╯
Read a stream of multiple values from MessagePack
> 0x[81A76E757368656C6CA5726F636B73A9736572696F75736C79] | from msgpack --objects
╭───┬─────────────────────╮
│ 0 │ ╭─────────┬───────╮ │
│ │ │ nushell │ rocks │ │
│ │ ╰─────────┴───────╯ │
│ 1 │ seriously │
╰───┴─────────────────────╯
Read a table from MessagePack
> 0x[9282AA6576656E745F6E616D65B141706F6C6C6F203131204C616E64696E67A474696D65C70CFF00000000FFFFFFFFFF2CAB5B82AA6576656E745F6E616D65B44E757368656C6C20666972737420636F6D6D6974A474696D65D6FF5CD5ADE0] | from msgpack
╭───┬──────────────────────┬──────────────╮
│ # │ event_name │ time │
├───┼──────────────────────┼──────────────┤
│ 0 │ Apollo 11 Landing │ 56 years ago │
│ 1 │ Nushell first commit │ 6 years ago │
╰───┴──────────────────────┴──────────────╯
from msgpackz
Convert brotli-compressed MessagePack data into Nu values.
This is the format used by the plugin registry file ($nu.plugin-path).
Usage:
> from msgpackz {flags}
Flags:
-h, --help: Display the help message for this command
--objects: Read multiple objects from input
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ binary │ any │
╰───┴────────┴────────╯
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 │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
Converts raw nuon formatted string to table
> '{a:1,b:[1,2]}' | from nuon
╭───┬───────────╮
│ a │ 1 │
│ │ ╭───┬───╮ │
│ b │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
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
╭───┬─────────┬─────────╮
│ # │ column0 │ column1 │
├───┼─────────┼─────────┤
│ 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 │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
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 │
╰───┴──────┴──────╯
Convert comma-separated data to a table, allowing variable number of columns per row and ignoring headers
> "value 1
value 2description 2" | from tsv --flexible --noheaders
╭───┬─────────┬───────────────╮
│ # │ column0 │ column1 │
├───┼─────────┼───────────────┤
│ 0 │ value 1 │ ❎ │
│ 1 │ value 2 │ description 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 url
Parse url-encoded string as a record.
Usage:
> from url
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ record │
╰───┴────────┴────────╯
Examples:
Convert url encoded string into a record
> 'bread=baguette&cheese=comt%C3%A9&meat=ham&fat=butter' | from url
╭────────┬──────────╮
│ bread │ baguette │
│ cheese │ comté │
│ meat │ ham │
│ fat │ butter │
╰────────┴──────────╯
from vcf
Parse text as .vcf and create table.
Usage:
> from vcf
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ table │
╰───┴────────┴────────╯
Examples:
Converts ics formatted string to table
> 'BEGIN:VCARD
N:Foo
FN:Bar
EMAIL:foo@bar.com
END:VCARD' | from vcf
╭───┬──────────────────────────────────────╮
│ # │ properties │
├───┼──────────────────────────────────────┤
│ 0 │ ╭───┬───────┬─────────────┬────────╮ │
│ │ │ # │ name │ value │ params │ │
│ │ ├───┼───────┼─────────────┼────────┤ │
│ │ │ 0 │ N │ Foo │ │ │
│ │ │ 1 │ FN │ Bar │ │ │
│ │ │ 2 │ EMAIL │ foo@bar.com │ │ │
│ │ ╰───┴───────┴─────────────┴────────╯ │
╰───┴──────────────────────────────────────╯
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
--allow-dtd: allow parsing documents with DTDs (may result in exponential entity expansion)
--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 │ │ # │ tag │ attributes │ content │ │
│ │ ├───┼──────────┼───────────────────┼────────────────────────────────────┤ │
│ │ │ 0 │ remember │ {record 0 fields} │ ╭───┬─────┬────────────┬─────────╮ │ │
│ │ │ │ │ │ │ # │ tag │ attributes │ content │ │ │
│ │ │ │ │ │ ├───┼─────┼────────────┼─────────┤ │ │
│ │ │ │ │ │ │ 0 │ │ │ Event │ │ │
│ │ │ │ │ │ ╰───┴─────┴────────────┴─────────╯ │ │
│ │ ╰───┴──────────┴───────────────────┴────────────────────────────────────╯ │
╰────────────┴───────────────────────────────────────────────────────────────────────────╯
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 │ ❎ │ ╭───┬───╮ │
│ │ │ │ 0 │ 1 │ │
│ │ │ │ 1 │ 2 │ │
│ │ │ ╰───┴───╯ │
╰───┴────┴───────────╯
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 │ ❎ │ ╭───┬───╮ │
│ │ │ │ 0 │ 1 │ │
│ │ │ │ 1 │ 2 │ │
│ │ │ ╰───┴───╯ │
╰───┴────┴───────────╯
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.
Additionally, if an input stream is provided, the generator closure accepts two
arguments. On each invocation an element of the input stream is provided as the
first argument. The second argument is the next value from the last invocation.
In this case, generation also stops when the input stream stops.
Search terms: unfold, stream, yield, expand, state, scan
Usage:
> generate <closure> (initial)
Flags:
-h, --help: Display the help message for this command
Parameters:
closure <closure(any, any)>: Generator function.
initial <any>: Initial value. (optional)
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ nothing │ list<any> │
│ 1 │ list<any> │ list<any> │
│ 2 │ table │ list<any> │
│ 3 │ range │ list<any> │
╰───┴───────────┴───────────╯
Examples:
Generate a sequence of numbers
> generate {|i| if $i <= 10 { {out: $i, next: ($i + 2)} }} 0
╭───┬────╮
│ 0 │ 0 │
│ 1 │ 2 │
│ 2 │ 4 │
│ 3 │ 6 │
│ 4 │ 8 │
│ 5 │ 10 │
╰───┴────╯
Generate a continuous stream of Fibonacci numbers
> generate {|fib| {out: $fib.0, next: [$fib.1, ($fib.0 + $fib.1)]} } [0, 1]
Generate a continuous stream of Fibonacci numbers, using default parameters
> generate {|fib=[0, 1]| {out: $fib.0, next: [$fib.1, ($fib.0 + $fib.1)]} }
Generate a running sum of the inputs
> 1..5 | generate {|e, sum=0| let sum = $e + $sum; {out: $sum, next: $sum} }
╭───┬────╮
│ 0 │ 1 │
│ 1 │ 3 │
│ 2 │ 6 │
│ 3 │ 10 │
│ 4 │ 15 │
╰───┴────╯
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
-o, --optional: make all cell path members optional (returns null for missing values)
--ignore-case: make all cell path members case insensitive
-i, --ignore-errors: ignore missing data (make all cell path members optional) (deprecated)
-s, --sensitive: get path in a case sensitive manner (deprecated)
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 │
│ 3 │ nothing │ nothing │
╰───┴───────────┴─────────╯
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 column from a table where some rows don't have that column, using optional cell-path syntax
> [{A: A0, B: B0}, {B: B1}, {A: A2, B: B2}] | get A?
╭───┬────╮
│ 0 │ A0 │
│ 1 │ │
│ 2 │ A2 │
╰───┴────╯
Get a column from a table where some rows don't have that column, using the optional flag
> [{A: A0, B: B0}, {B: B1}, {A: A2, B: B2}] | get -o A
╭───┬────╮
│ 0 │ A0 │
│ 1 │ │
│ 2 │ A2 │
╰───┴────╯
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.2)
> ls | get name.2
Extract the name of the 3rd record in a list
> ls | get 2.name
Getting environment variables in a case insensitive way, using case insensitive cell-path syntax
> $env | get home! path!
Getting environment variables in a case insensitive way, using the '--ignore-case' flag
> $env | get --ignore-case home path
Getting Path in a case sensitive way, won't work for 'PATH'
> $env | get 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
-l, --follow-symlinks: Whether to follow symbolic links to their targets
-e, --exclude <list<string>>: Patterns to exclude from the search: glob will not walk the inside of directories matching the excluded patterns.
Parameters:
glob <oneof<string, glob>>: 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 or 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/** */]
Search for files following symbolic links to their targets
> glob "**/*.txt" --follow-symlinks
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
-i, --icons: draw output with icons (assumes nerd font is used)
-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
Render a table with 'name' column in it to a grid with icons and colors
> [[name patch]; [Cargo.toml false] [README.md true] [SECURITY.md false]] | grid --icons --color
group-by
Splits a list or table into groups, and returns a record containing those groups.
the group-by command makes some assumptions:
- if the input data is not a string, the grouper will convert the key to string but the values will remain in their original format. e.g. with bools, "true" and true would be in the same group (see example).
- datetime is formatted based on your configuration setting. use format date to change the format.
- filesize is formatted based on your configuration setting. use format filesize to change the format.
- some nushell values are not supported, such as closures.
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 <oneof<cell-path, closure(), closure(any)>>: The path to the column to group on.
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 │ │ 0 │ foo.txt │ │
│ │ │ 1 │ baz.txt │ │
│ │ ╰───┴─────────╯ │
│ │ ╭───┬─────────╮ │
│ csv │ │ 0 │ bar.csv │ │
│ │ ╰───┴─────────╯ │
╰─────┴─────────────────╯
You can also group by raw values by leaving out the argument
> ['1' '3' '1' '3' '2' '1' '1'] | group-by
╭───┬───────────╮
│ │ ╭───┬───╮ │
│ 1 │ │ 0 │ 1 │ │
│ │ │ 1 │ 1 │ │
│ │ │ 2 │ 1 │ │
│ │ │ 3 │ 1 │ │
│ │ ╰───┴───╯ │
│ │ ╭───┬───╮ │
│ 3 │ │ 0 │ 3 │ │
│ │ │ 1 │ 3 │ │
│ │ ╰───┴───╯ │
│ │ ╭───┬───╮ │
│ 2 │ │ 0 │ 2 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
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 │ ╭───┬───╮ │
│ │ │ │ 0 │ 1 │ │
│ │ │ │ 1 │ 1 │ │
│ │ │ │ 2 │ 1 │ │
│ │ │ │ 3 │ 1 │ │
│ │ │ ╰───┴───╯ │
│ 1 │ 3 │ ╭───┬───╮ │
│ │ │ │ 0 │ 3 │ │
│ │ │ │ 1 │ 3 │ │
│ │ │ ╰───┴───╯ │
│ 2 │ 2 │ ╭───┬───╮ │
│ │ │ │ 0 │ 2 │ │
│ │ │ ╰───┴───╯ │
╰───┴───────┴───────────╯
Group bools, whether they are strings or actual bools
> [true "true" false "false"] | group-by
╭───────┬───────────────╮
│ │ ╭───┬──────╮ │
│ true │ │ 0 │ true │ │
│ │ │ 1 │ true │ │
│ │ ╰───┴──────╯ │
│ │ ╭───┬───────╮ │
│ false │ │ 0 │ false │ │
│ │ │ 1 │ false │ │
│ │ ╰───┴───────╯ │
╰───────┴───────────────╯
Group items by multiple columns' values
> [
[name, lang, year];
[andres, rb, "2019"],
[jt, rs, "2019"],
[storm, rs, "2021"]
]
| group-by lang year
╭────┬─────────────────────────────────────────╮
│ │ ╭──────┬──────────────────────────────╮ │
│ rb │ │ │ ╭───┬────────┬──────┬──────╮ │ │
│ │ │ 2019 │ │ # │ name │ lang │ year │ │ │
│ │ │ │ ├───┼────────┼──────┼──────┤ │ │
│ │ │ │ │ 0 │ andres │ rb │ 2019 │ │ │
│ │ │ │ ╰───┴────────┴──────┴──────╯ │ │
│ │ ╰──────┴──────────────────────────────╯ │
│ │ ╭──────┬─────────────────────────────╮ │
│ rs │ │ │ ╭───┬──────┬──────┬──────╮ │ │
│ │ │ 2019 │ │ # │ name │ lang │ year │ │ │
│ │ │ │ ├───┼──────┼──────┼──────┤ │ │
│ │ │ │ │ 0 │ jt │ rs │ 2019 │ │ │
│ │ │ │ ╰───┴──────┴──────┴──────╯ │ │
│ │ │ │ ╭───┬───────┬──────┬──────╮ │ │
│ │ │ 2021 │ │ # │ name │ lang │ year │ │ │
│ │ │ │ ├───┼───────┼──────┼──────┤ │ │
│ │ │ │ │ 0 │ storm │ rs │ 2021 │ │ │
│ │ │ │ ╰───┴───────┴──────┴──────╯ │ │
│ │ ╰──────┴─────────────────────────────╯ │
╰────┴─────────────────────────────────────────╯
Group items by multiple columns' values
> [
[name, lang, year];
[andres, rb, "2019"],
[jt, rs, "2019"],
[storm, rs, "2021"]
]
| group-by lang year --to-table
╭───┬──────┬──────┬──────────────────────────────╮
│ # │ lang │ year │ items │
├───┼──────┼──────┼──────────────────────────────┤
│ 0 │ rb │ 2019 │ ╭───┬────────┬──────┬──────╮ │
│ │ │ │ │ # │ name │ lang │ year │ │
│ │ │ │ ├───┼────────┼──────┼──────┤ │
│ │ │ │ │ 0 │ andres │ rb │ 2019 │ │
│ │ │ │ ╰───┴────────┴──────┴──────╯ │
│ 1 │ rs │ 2019 │ ╭───┬──────┬──────┬──────╮ │
│ │ │ │ │ # │ name │ lang │ year │ │
│ │ │ │ ├───┼──────┼──────┼──────┤ │
│ │ │ │ │ 0 │ jt │ rs │ 2019 │ │
│ │ │ │ ╰───┴──────┴──────┴──────╯ │
│ 2 │ rs │ 2021 │ ╭───┬───────┬──────┬──────╮ │
│ │ │ │ │ # │ name │ lang │ year │ │
│ │ │ │ ├───┼───────┼──────┼──────┤ │
│ │ │ │ │ 0 │ storm │ rs │ 2021 │ │
│ │ │ │ ╰───┴───────┴──────┴──────╯ │
╰───┴──────┴──────┴──────────────────────────────╯
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 │ binary │ any │
│ 2 │ table │ table │
│ 3 │ 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
Length: 16 (0x10) bytes | printable whitespace ascii_other non_ascii
00000000: c3 fc d3 d7 61 92 e4 00 7d fb 49 6c ca 67 e1 3b ××××a××0}×Il×g×;
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 │ binary │ any │
│ 2 │ table │ table │
│ 3 │ 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
Length: 32 (0x20) bytes | printable whitespace ascii_other non_ascii
00000000: 71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 q××××××/•××D|f×R
00000010: 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 ^1b•×Q××××2××××s
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 │
╰───┴───────┴────────╯
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.
If you want your own help implementation, create a custom command named help and it will also be used for --help invocations.
There already is an alternative help command in the standard library you can try with use std/help.
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.
help pipe-and-redirect - Show help on nushell pipes and redirects.
Flags:
-h, --help: Display the help message for this command
-f, --find <string>: string to find in command names, descriptions, 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 join
search for string in command names, descriptions, 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 descriptions
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 descriptions
> 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, descriptions, 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 descriptions
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 descriptions
> 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 descriptions
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 descriptions
> 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 │
╰───┴─────────┴────────╯
help pipe-and-redirect
Show help on nushell pipes and redirects.
This command contains basic usage of pipe and redirect symbol, for more detail, check:
https://www.nushell.sh/lang-guide/chapters/pipelines.html
Usage:
> help pipe-and-redirect
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
Search terms: unset
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 hide. (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.
Search terms: unset, drop
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
false
highlight
Syntax highlight source code.
Search terms: syntax, highlight, highlighting
Usage:
> highlight {flags} (language)
Flags:
-h, --help: Display the help message for this command
-t, --theme <string>: them used for highlighting
--list-themes: list all possible themes
Parameters:
language <string>: language or file extension to help language detection (optional)
Input/output types:
╭───┬────────┬────────────────────────────────────────────────────────────────╮
│ # │ input │ output │
├───┼────────┼────────────────────────────────────────────────────────────────┤
│ 0 │ string │ string │
│ 1 │ any │ table<id: string, name: string, author: string, default: bool> │
╰───┴────────┴────────────────────────────────────────────────────────────────╯
Examples:
Highlight a Markdown file by guessing the type from the pipeline metadata
> open README.md | highlight
Highlight a toml file by its file extension
> open Cargo.toml -r | echo $in | highlight toml
Highlight a rust file by programming language
> open src/main.rs | echo $in | highlight Rust
Highlight a bash script by inferring the language (needs shebang)
> open example.sh | echo $in | highlight
Highlight a toml file with another theme
> open Cargo.toml -r | highlight -t ansi
List all available themes
> highlight --list-themes
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 import - Import command line history.
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 import
Import command line history.
Can import history from input, either successive command lines or more detailed records. If providing records, available fields are:
command, start_timestamp, hostname, cwd, duration, exit_status.
If no input is provided, will import all history items from existing history in the other format: if current history is stored in sqlite, it will store it in plain text and vice versa.
Note that history item IDs are ignored when importing from file.
Usage:
> history import
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────╮
│ # │ input │ output │
├───┼──────────────┼─────────┤
│ 0 │ nothing │ nothing │
│ 1 │ string │ nothing │
│ 2 │ list<string> │ nothing │
│ 3 │ table │ nothing │
╰───┴──────────────┴─────────╯
Examples:
Append all items from history in the other format to the current history
> history import
Append foo to the current history
> echo foo | history import
Append foo ran from /home to the current history
> [[ command cwd ]; [ foo /home ]] | history import
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.
Without a subcommand but with a URL provided, it performs a GET request by default or a POST request if data is provided. You can use one of the following subcommands. Using this command as-is will only display this help message.
Search terms: network, fetch, pull, request, download, curl, wget
Usage:
> http {flags} (URL) (data)
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
-t, --content-type <any>: the MIME type of content to post
-u, --user <any>: the username when authenticating
-p, --password <any>: the password when authenticating
-m, --max-time <duration>: max duration before timeout occurs
-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 record, containing metainformation about the exchange in addition to the response.
Returning record fields:
- urls: list of url redirects this command had to make to get to the destination
- headers.request: list of headers passed when doing the request
- headers.response: list of received headers
- body: the http body of the response
- status: the http status of the response
-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. (optional)
data <any>: The contents of the post body. Required unless part of a pipeline. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Get content from example.com with default verb
> http https://www.example.com
Post content to example.com with default verb
> http https://www.example.com 'body'
Get content from example.com with explicit verb
> http get https://www.example.com
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 <duration>: max duration before timeout occurs
-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 │ any │ 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 using a record
> http delete --headers {my-header-key: my-header-value} https://www.example.com
http delete from example.com, with custom header using a list
> http delete --headers [my-header-key-A my-header-value-A my-header-key-B my-header-value-B] 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
Perform an HTTP delete with JSON content from a pipeline to example.com
> open foo.json | http delete 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 <duration>: max duration before timeout occurs
-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 using a record
> http get --headers {my-header-key: my-header-value} https://www.example.com
Get content from example.com, with custom headers using a list
> http get --headers [my-header-key-A my-header-value-A my-header-key-B my-header-value-B] https://www.example.com
Get the response status code
> http get https://www.example.com | metadata | get http_response.status
Check response status while streaming
> http get --allow-errors https://example.com/file | metadata access {|m| if $m.http_response.status != 200 { error make {msg: "failed"} } else { } } | lines
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 <duration>: max duration before timeout occurs
-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 using a record
> http head --headers {my-header-key: my-header-value} https://www.example.com
Get headers from example.com, with custom header using a list
> http head --headers [my-header-key-A my-header-value-A my-header-key-B my-header-value-B] 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 <duration>: max duration before timeout occurs
-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 using a record
> http options --headers {my-header-key: my-header-value} https://www.example.com
Get options from example.com, with custom headers using a list
> 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 <duration>: max duration before timeout occurs
-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. (optional)
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ 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 using a record
> http patch --headers {my-header-key: my-header-value} https://www.example.com
Patch content to example.com, with custom header using a list
> http patch --headers [my-header-key-A my-header-value-A my-header-key-B my-header-value-B] https://www.example.com
Patch content to example.com, with JSON body
> http patch --content-type application/json https://www.example.com { field: value }
Patch JSON content from a pipeline to example.com
> open --raw foo.json | http patch https://www.example.com
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 <duration>: max duration before timeout occurs
-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. Required unless part of a pipeline. (optional)
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ 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 using a record
> http post --headers {my-header-key: my-header-value} https://www.example.com
Post content to example.com, with custom header using a list
> http post --headers [my-header-key-A my-header-value-A my-header-key-B my-header-value-B] https://www.example.com
Post content to example.com, with JSON body
> http post --content-type application/json https://www.example.com { field: value }
Post JSON content from a pipeline to example.com
> open --raw foo.json | http post https://www.example.com
Upload a binary file to example.com
> http post --content-type multipart/form-data https://www.example.com { file: (open -r file.mp3) }
Convert a text file into binary and upload it to example.com
> http post --content-type multipart/form-data https://www.example.com { file: (open -r file.txt | into binary) }
Get the response status code
> http post https://www.example.com 'body' | metadata | get http_response.status
Check response status while streaming
> http post --allow-errors https://example.com/upload 'data' | metadata access {|m| if $m.http_response.status != 200 { error make {msg: "failed"} } else { } } | lines
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 <duration>: max duration before timeout occurs
-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. Required unless part of a pipeline. (optional)
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ 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 using a record
> http put --headers {my-header-key: my-header-value} https://www.example.com
Put content to example.com, with custom header using a list
> http put --headers [my-header-key-A my-header-value-A my-header-key-B my-header-value-B] https://www.example.com
Put content to example.com, with JSON body
> http put --content-type application/json https://www.example.com { field: value }
Put JSON content from a pipeline to example.com
> open --raw foo.json | http put https://www.example.com
if
Conditionally run a block.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Search terms: else, conditional
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" + <oneof<block, expression>>: Expression or block to run when the condition is false. (optional)
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
inc
Increment a value or version. Optionally use the column of a table.
Usage:
> inc {flags} (cell_path)
Flags:
-h, --help: Display the help message for this command
-M, --major: increment the major version (eg 1.2.1 -> 2.0.0)
-m, --minor: increment the minor version (eg 1.2.1 -> 1.3.0)
-p, --patch: increment the patch version (eg 1.2.1 -> 1.2.2)
Parameters:
cell_path <cell-path>: cell path to update (optional)
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
-d, --default <string>: default value if no input is provided
--reedline: use the reedline library, defaults to false
--history-file <path>: Path to a file to read and write command history. This is a text file and will be created if it doesn't exist. Will be used as the selection list. Implies --reedline.
--max-history <int>: The maximum number of entries to keep in the history, defaults to $env.config.history.max_size. Implies --reedline.
-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 │
│ 1 │ list<string> │ 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)
Get input from the user with default value, and assign to a variable
> let user_input = (input --default 10)
Get multiple lines of input from the user (newlines can be entered using Alt + Enter or Ctrl + Enter), and assign to a variable
> let multiline_input = (input --reedline)
Get input from the user with history, and assign to a variable
> let user_input = ([past,command,entries] | input --reedline)
Get input from the user with history backed by a file, and assign to a variable
> let user_input = (input --reedline --history-file ./history.txt)
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 <cell-path>: 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.
When inserting a column, the closure will be run for each row, and the current row will be passed as the first argument.
When inserting into a specific index, the closure will instead get the current value at the index or null if inserting at the end of a list/table.
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 │
╰───┴───╯
Insert into a nested path, creating new values as needed
> [{} {a: [{}]}] | insert a.0.b "value"
╭───┬───────────────╮
│ # │ a │
├───┼───────────────┤
│ 0 │ ╭───┬───────╮ │
│ │ │ # │ b │ │
│ │ ├───┼───────┤ │
│ │ │ 0 │ value │ │
│ │ ╰───┴───────╯ │
│ 1 │ ╭───┬───────╮ │
│ │ │ # │ b │ │
│ │ ├───┼───────┤ │
│ │ │ 0 │ value │ │
│ │ ╰───┴───────╯ │
╰───┴───────────────╯
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 - Convert custom values into base values.
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
-e, --endian <string>: byte encode endian. Does not affect string, date or binary. In containers, only individual elements are affected. Available options: native(default), little, big
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 │ datetime │ 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
Length: 52 (0x34) bytes | printable whitespace ascii_other non_ascii
00000000: 54 68 69 73 20 69 73 20 61 20 73 74 72 69 6e 67 This is a string
00000010: 20 74 68 61 74 20 69 73 20 65 78 61 63 74 6c 79 that is exactly
00000020: 20 35 32 20 63 68 61 72 61 63 74 65 72 73 20 6c 52 characters l
00000030: 6f 6e 67 2e ong.
convert a number to a nushell binary primitive
> 1 | into binary
Length: 8 (0x8) bytes | printable whitespace ascii_other non_ascii
00000000: 01 00 00 00 00 00 00 00 •0000000
convert a number to a nushell binary primitive (big endian)
> 258 | into binary --endian big
Length: 8 (0x8) bytes | printable whitespace ascii_other non_ascii
00000000: 00 00 00 00 00 00 01 02 000000••
convert a number to a nushell binary primitive (little endian)
> 258 | into binary --endian little
Length: 8 (0x8) bytes | printable whitespace ascii_other non_ascii
00000000: 02 01 00 00 00 00 00 00 ••000000
convert a boolean to a nushell binary primitive
> true | into binary
Length: 8 (0x8) bytes | printable whitespace ascii_other non_ascii
00000000: 01 00 00 00 00 00 00 00 •0000000
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
Length: 8 (0x8) bytes | printable whitespace ascii_other non_ascii
00000000: 58 39 b4 c8 76 be f3 3f X9××v××?
convert an int to a nushell binary primitive with compact enabled
> 10 | into binary --compact
Length: 1 (0x1) bytes | printable whitespace ascii_other non_ascii
00000000: 0a _
into bool
Convert value to boolean.
Search terms: convert, boolean, true, false, 1, 0
Usage:
> into bool {flags} ...(rest)
Flags:
-h, --help: Display the help message for this command
--relaxed: Relaxes conversion to also allow null and any strings.
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 │ nothing │ bool │
│ 5 │ list<any> │ table │
│ 6 │ table │ table │
│ 7 │ 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
interpret a null as false
> null | into bool --relaxed
false
interpret any non-false, non-zero string as true
> 'something' | into bool --relaxed
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 │ cell-path │ cell-path │
│ 1 │ int │ cell-path │
│ 2 │ list<any> │ cell-path │
│ 3 │ list<record<value: any, optional: bool, insensitive: bool>> │ cell-path │
╰───┴─────────────────────────────────────────────────────────────┴───────────╯
Examples:
Convert integer into cell path
> 5 | into cell-path
$.5
Convert cell path into cell path
> 5 | into cell-path | 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, insensitive]; [5 true false] [c false false] [d false true]] | into cell-path
$.5?.c.d!
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
Parameters:
...rest <cell-path>: For a data structure input, convert data at the given cell paths.
Input/output types:
╭───┬──────────────┬────────────────╮
│ # │ input │ output │
├───┼──────────────┼────────────────┤
│ 0 │ datetime │ datetime │
│ 1 │ int │ datetime │
│ 2 │ string │ datetime │
│ 3 │ list<string> │ list<datetime> │
│ 4 │ table │ table │
│ 5 │ nothing │ table │
│ 6 │ record │ record │
│ 7 │ record │ datetime │
│ 8 │ any │ table │
╰───┴──────────────┴────────────────╯
Examples:
Convert timestamp string to datetime with timezone offset
> '27.02.2021 1:55 pm +0000' | into datetime
Sat, 27 Feb 2021 13:55:00 +0000 (4 years ago)
Convert standard timestamp string to datetime with timezone offset
> '2021-02-27T13:55:40.2246+00:00' | into datetime
Sat, 27 Feb 2021 13:55:40 +0000 (4 years ago)
Convert non-standard timestamp string, with timezone offset, 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 (4 years ago)
Convert non-standard timestamp string, without timezone offset, to datetime with custom formatting
> '16.11.1984 8:00 am' | into datetime --format '%d.%m.%Y %H:%M %P'
Fri, 16 Nov 1984 08:00:00 +0900 (41 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 (4 years ago)
Convert standard (seconds) unix timestamp to a UTC datetime
> 1614434140 | into datetime -f '%s'
Sat, 27 Feb 2021 13:55:40 +0000 (4 years ago)
Using a datetime as input simply returns the value
> 2021-02-27T13:55:40 | into datetime
Sat, 27 Feb 2021 13:55:40 +0000 (4 years ago)
Using a record as input
> {year: 2025, month: 3, day: 30, hour: 12, minute: 15, second: 59, timezone: '+02:00'} | into datetime
Sun, 30 Mar 2025 10:15:59 +0000 (8 months 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 │ 2 years ago │
│ 1 │ 2 years ago │
│ 2 │ 2 years ago │
╰───┴─────────────╯
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 │ float │ duration │
│ 2 │ string │ duration │
│ 3 │ duration │ duration │
│ 4 │ record │ record │
│ 5 │ record │ duration │
│ 6 │ 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
Convert a floating point number of an arbitrary unit to duration
> 1.234 | into duration --unit sec
1sec 234ms
Convert a record to a duration
> {day: 10, hour: 2, minute: 6, second: 50, sign: '+'} | into duration
1wk 3day 2hr 6min 50sec
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
Convert string with unit to filesize
> '-1KB' | into filesize
-1.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.0
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 │ glob │ glob │
│ 1 │ string │ glob │
│ 2 │ list<string> │ list<glob> │
│ 3 │ table │ table │
│ 4 │ record │ record │
╰───┴──────────────┴────────────╯
Examples:
convert string to glob
> '1234' | into glob
1234
convert glob to glob
> '1234' | into glob | 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 │ datetime │ 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<datetime> │ 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 │ datetime │ record │
│ 1 │ duration │ record │
│ 2 │ list<any> │ record │
│ 3 │ record │ record │
╰───┴───────────┴────────╯
Examples:
Convert from one row table to record
> [[value]; [false]] | into record
╭───────┬───────╮
│ value │ false │
╰───────┴───────╯
Convert from list of records to record
> [{foo: bar} {baz: quux}] | into record
╭─────┬──────╮
│ foo │ bar │
│ baz │ quux │
╰─────┴──────╯
Convert from list of pairs into record
> [[foo bar] [baz quux]] | into record
╭─────┬──────╮
│ foo │ bar │
│ baz │ quux │
╰─────┴──────╯
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 │
│ millisecond │ 0 │
│ microsecond │ 0 │
│ nanosecond │ 0 │
│ timezone │ +02:00 │
╰─────────────┴────────╯
convert date components to table columns
> 2020-04-12T22:10:57+02:00 | into record | transpose | transpose -r
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
Insert data that contains records, lists or tables, that will be stored as JSONB columns
These columns will be automatically turned back into nu objects when read directly via cell-path
> {a_record: {foo: bar, baz: quux}, a_list: [1 2 3], a_table: [[a b]; [0 1] [2 3]]} | into sqlite filename.db -t my_table
(open filename.db).my_table.0.a_list
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
╰───┴───╯
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
-g, --group-digits: group digits together by the locale specific thousands separator
-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 │ datetime │ string │
│ 8 │ duration │ string │
│ 9 │ cell-path │ string │
│ 10 │ range │ string │
│ 11 │ list<any> │ list<string> │
│ 12 │ table │ table │
│ 13 │ 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
> 1kB | into string
1.0 kB
convert duration to string
> 9day | into string
1wk 2day
convert cell-path to string
> $.name | into string
$.name
into value
Convert custom values into base values.
Custom values from plugins have a base value representation. This extracts that base value representation. For streams use collect.
Search terms: custom, base, convert, conversion
Usage:
> into value {flags}
Flags:
-h, --help: Display the help message for this command
-c, --columns <list<any>>: list of columns to update
-f, --prefer-filesizes: For ints display them as human-readable file sizes
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
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 │
╰───┴───────────────╯
job
Various commands for working with background jobs.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> job
Subcommands:
job flush - Clear this job's mailbox.
job id - Get id of current job.
job kill - Kill a background job.
job list - List background jobs.
job recv - Read a message from the mailbox.
job send - Send a message to the mailbox of a job.
job spawn - Spawn a background job and retrieve its ID.
job tag - Add a description tag to a background job.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
job flush
Clear this job's mailbox.
This command removes all messages in the mailbox of the current job.
If a message is received while this command is executing, it may also be discarded.
Usage:
> job flush
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Clear the mailbox of the current job.
> job flush
job id
Get id of current job.
This command returns the job id for the current background job.
The special id 0 indicates that this command was not called from a background job thread, and
was instead spawned by main nushell execution thread.
Search terms: self, this, my-id, this-id
Usage:
> job id
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ int │
╰───┴─────────┴────────╯
Examples:
Get id of current job
> job id
job kill
Kill a background job.
Search terms: halt, stop, end, close
Usage:
> job kill <id>
Flags:
-h, --help: Display the help message for this command
Parameters:
id <int>: The id of the job to kill.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Kill a newly spawned job
> let id = job spawn { sleep 10sec }; job kill $id
job list
List background jobs.
Search terms: background, jobs
Usage:
> job list
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
List all background jobs
> job list
job recv
Read a message from the mailbox.
When messages are sent to the current process, they get stored in what is called the "mailbox".
This commands reads and returns a message from the mailbox, in a first-in-first-out fashion.
Messages may have numeric flags attached to them. This commands supports filtering out messages that do not satisfy a given tag, by using the tag flag.
If no tag is specified, this command will accept any message.
If no message with the specified tag (if any) is available in the mailbox, this command will block the current thread until one arrives.
By default this command block indefinitely until a matching message arrives, but a timeout duration can be specified.
If a timeout duration of zero is specified, it will succeed only if there already is a message in the mailbox.
Note: When using par-each, only one thread at a time can utilize this command.
In the case of two or more threads running this command, they will wait until other threads are done using it,
in no particular order, regardless of the specified timeout parameter.
Search terms: receive
Usage:
> job recv {flags}
Flags:
-h, --help: Display the help message for this command
--tag <int>: A tag for the message
--timeout <duration>: The maximum time duration to wait for.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯
Examples:
Block the current thread while no message arrives
> job recv
Receive a message, wait for at most 10 seconds.
> job recv --timeout 10sec
Get a message or fail if no message is available immediately
> job recv --timeout 0sec
Receive a message from a newly-spawned job
> job spawn { sleep 1sec; 'hi' | job send 0 }; job recv
job send
Send a message to the mailbox of a job.
This command sends a message to a background job, which can then read sent messages
in a first-in-first-out fashion with job recv. When it does so, it may additionally specify a numeric filter tag,
in which case it will only read messages sent with the exact same filter tag.
In particular, the id 0 refers to the main/initial nushell thread.
A message can be any nushell value, and streams are always collected before being sent.
This command never blocks.
Usage:
> job send {flags} <id>
Flags:
-h, --help: Display the help message for this command
--tag <int>: A tag for the message
Parameters:
id <int>: The id of the job to send the message to.
Input/output types:
╭───┬───────┬─────────╮
│ # │ input │ output │
├───┼───────┼─────────┤
│ 0 │ any │ nothing │
╰───┴───────┴─────────╯
Examples:
Send a message from the main thread to a newly-spawned job
> let id = job spawn { job recv | save sent.txt }; 'hi' | job send $id
Send a message from a newly-spawned job to the main thread (which always has an ID of 0)
> job spawn { sleep 1sec; 'hi' | job send 0 }; job recv
job spawn
Spawn a background job and retrieve its ID.
Executes the provided closure in a background thread
and registers this task in the background job table, which can be retrieved with job list.
This command returns the job id of the newly created job.
Search terms: background, bg, &
Usage:
> job spawn {flags} <closure>
Flags:
-h, --help: Display the help message for this command
-t, --tag <string>: An optional description tag for this job
Parameters:
closure <closure(any)>: The closure to run in another thread.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ int │
╰───┴─────────┴────────╯
Examples:
Spawn a background job to do some time consuming work
> job spawn { sleep 5sec; rm evidence.pdf }
job tag
Add a description tag to a background job.
Search terms: describe, desc
Usage:
> job tag <id> <tag>
Flags:
-h, --help: Display the help message for this command
Parameters:
id <int>: The id of the job to tag.
tag <oneof<string, nothing>>: The tag to assign to the job.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Tag a newly spawned job
> let id = job spawn { sleep 10sec }; job tag $id abc
Remove the tag of a job
> let id = job spawn { sleep 10sec }; job tag $id abc; job tag $id null
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 <table>: 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)
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 ids of processes that are to be killed.
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
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 23 45 #E
Return the last item of a range
> 1..3 | last
3
length
Count the number of items in an input list, rows in a table, or bytes in binary data.
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 │
│ 1 │ binary │ int │
│ 2 │ nothing │ 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
Count the number of bytes in binary data
> 0x[01 02] | length
2
Count the length a null value
> null | length
0
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 │
│ 2 │ any │ 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.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> loop <block>
Flags:
-h, --help: Display the help message for this command
Parameters:
block <block>: Block to loop.
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)
-t, --threads: Use multiple threads to list contents. Output will be non-deterministic.
Parameters:
...pattern <oneof<glob, string>>: The glob pattern to use.
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 | where name !~ bar
List the full path of all dirs in your home directory
> ls -a ~ | where type == dir
List only the names (not paths) of all dirs in your home directory which have not been modified in 7 days
> ls -as ~ | where type == dir and modified < ((date now) - 7day)
Recursively list all files and subdirectories under the current directory using a glob pattern
> ls -a **/*
Recursively list *.rs and *.toml files using the glob command
> ls ...(glob **/*.{rs,toml})
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.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
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.
Examples:
Match on a value
> match 3 { 1 => 'one', 2 => 'two', 3 => 'three' }
three
Match against alternative values
> match 'three' { 1 | 'one' => '-', 2 | 'two' => '--', 3 | 'three' => '---' }
---
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 arccos - Returns the arccosine of the number.
math arccosh - Returns the inverse of the hyperbolic cosine function.
math arcsin - Returns the arcsine of the number.
math arcsinh - Returns the inverse of the hyperbolic sine function.
math arctan - Returns the arctangent of the number.
math arctanh - Returns the inverse of the hyperbolic tangent function.
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 cos - Returns the cosine of the number.
math cosh - Returns the hyperbolic cosine of the number.
math exp - Returns e raised to the power of x.
math floor - Returns the floor of a number (largest integer less than or equal to that number).
math ln - Returns the natural logarithm. Base: (math e).
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 sin - Returns the sine of the number.
math sinh - Returns the hyperbolic sine of the number.
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 tan - Returns the tangent of the number.
math tanh - Returns the hyperbolic tangent of the number.
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> │
│ 4 │ range │ list<number> │
╰───┴────────────────┴────────────────╯
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 arccos
Returns the arccosine of the number.
Search terms: trigonometry, inverse
Usage:
> math arccos {flags}
Flags:
-h, --help: Display the help message for this command
-d, --degrees: Return degrees instead of radians
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Get the arccosine of 1
> 1 | math arccos
0.0
Get the arccosine of -1 in degrees
> -1 | math arccos --degrees
180.0
math arccosh
Returns the inverse of the hyperbolic cosine function.
Search terms: trigonometry, inverse, hyperbolic
Usage:
> math arccosh
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Get the arccosh of 1
> 1 | math arccosh
0.0
math arcsin
Returns the arcsine of the number.
Search terms: trigonometry, inverse
Usage:
> math arcsin {flags}
Flags:
-h, --help: Display the help message for this command
-d, --degrees: Return degrees instead of radians
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Get the arcsine of 1
> 1 | math arcsin
1.5707963267948966
Get the arcsine of 1 in degrees
> 1 | math arcsin --degrees
90.0
math arcsinh
Returns the inverse of the hyperbolic sine function.
Search terms: trigonometry, inverse, hyperbolic
Usage:
> math arcsinh
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Get the arcsinh of 0
> 0 | math arcsinh
0.0
math arctan
Returns the arctangent of the number.
Search terms: trigonometry, inverse
Usage:
> math arctan {flags}
Flags:
-h, --help: Display the help message for this command
-d, --degrees: Return degrees instead of radians
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Get the arctangent of 1
> 1 | math arctan
0.7853981633974483
Get the arctangent of -1 in degrees
> -1 | math arctan --degrees
-45.0
math arctanh
Returns the inverse of the hyperbolic tangent function.
Search terms: trigonometry, inverse, hyperbolic
Usage:
> math arctanh
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Get the arctanh of 1
> 1 | math arctanh
inf
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.0
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> │
│ 2 │ range │ list<number> │
╰───┴──────────────┴──────────────╯
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 cos
Returns the cosine of the number.
Search terms: trigonometry
Usage:
> math cos {flags}
Flags:
-h, --help: Display the help message for this command
-d, --degrees: Use degrees instead of radians
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Apply the cosine to π
> 3.141592 | math cos | math round --precision 4
-1.0
Apply the cosine to a list of angles in degrees
> [0 90 180 270 360] | math cos --degrees
╭───┬───────╮
│ 0 │ 1.00 │
│ 1 │ 0.00 │
│ 2 │ -1.00 │
│ 3 │ 0.00 │
│ 4 │ 1.00 │
╰───┴───────╯
math cosh
Returns the hyperbolic cosine of the number.
Search terms: trigonometry, hyperbolic
Usage:
> math cosh
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Apply the hyperbolic cosine to 1
> 1 | math cosh
1.5430806348152435
math exp
Returns e raised to the power of x.
Search terms: exponential, exponentiation, euler
Usage:
> math exp
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Get e raised to the power of zero
> 0 | math exp
1.0
Get e (same as 'math e')
> 1 | math exp
2.718281828459045
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> │
│ 2 │ range │ list<number> │
╰───┴──────────────┴──────────────╯
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 ln
Returns the natural logarithm. Base: (math e).
Search terms: natural, logarithm, inverse, euler
Usage:
> math ln
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Get the natural logarithm of e
> 2.7182818 | math ln | math round --precision 4
1.0
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> │
│ 2 │ range │ list<number> │
╰───┴──────────────┴──────────────╯
Examples:
Get the logarithm of 100 to the base 10
> 100 | math log 10
2.0
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 (2 years 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 │ │ 0 │ 1 │ │
│ │ ╰───┴───╯ │
│ │ ╭───┬────╮ │
│ b │ │ 0 │ -1 │ │
│ │ │ 1 │ 3 │ │
│ │ │ 2 │ 5 │ │
│ │ ╰───┴────╯ │
╰───┴────────────╯
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> │
│ 2 │ range │ 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 sin
Returns the sine of the number.
Search terms: trigonometry
Usage:
> math sin {flags}
Flags:
-h, --help: Display the help message for this command
-d, --degrees: Use degrees instead of radians
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Apply the sine to π/2
> 3.141592 / 2 | math sin | math round --precision 4
1.0
Apply the sine to a list of angles in degrees
> [0 90 180 270 360] | math sin -d | math round --precision 4
╭───┬───────╮
│ 0 │ 0.00 │
│ 1 │ 1.00 │
│ 2 │ 0.00 │
│ 3 │ -1.00 │
│ 4 │ 0.00 │
╰───┴───────╯
math sinh
Returns the hyperbolic sine of the number.
Search terms: trigonometry, hyperbolic
Usage:
> math sinh
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Apply the hyperbolic sine to 1
> 1 | math sinh
1.1752011936438014
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> │
│ 2 │ range │ list<number> │
╰───┴──────────────┴──────────────╯
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 │ range │ number │
│ 2 │ table │ record │
│ 3 │ 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 tan
Returns the tangent of the number.
Search terms: trigonometry
Usage:
> math tan {flags}
Flags:
-h, --help: Display the help message for this command
-d, --degrees: Use degrees instead of radians
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Apply the tangent to π/4
> 3.141592 / 4 | math tan | math round --precision 4
1.0
Apply the tangent to a list of angles in degrees
> [-45 0 45] | math tan --degrees
╭───┬───────╮
│ 0 │ -1.00 │
│ 1 │ 0.00 │
│ 2 │ 1.00 │
╰───┴───────╯
math tanh
Returns the hyperbolic tangent of the number.
Search terms: trigonometry, hyperbolic
Usage:
> math tanh
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────┬─────────────╮
│ # │ input │ output │
├───┼──────────────┼─────────────┤
│ 0 │ number │ float │
│ 1 │ list<number> │ list<float> │
╰───┴──────────────┴─────────────╯
Examples:
Apply the hyperbolic tangent to 10*π
> 3.141592 * 10 | math tanh | math round --precision 4
1.0
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 │ range │ number │
│ 2 │ table │ record │
│ 3 │ record │ record │
╰───┴──────────────┴────────╯
Examples:
Get the variance of a list of numbers
> [1 2 3 4 5] | math variance
2.0
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>
Subcommands:
merge deep - Merge the input with a record or table, recursively merging values in matching columns.
Flags:
-h, --help: Display the help message for this command
Parameters:
value <oneof<record, table>>: The new value to merge with.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
╰───┴────────┴────────╯
Examples:
Add an 'id' column to the input table
> [a b c] | wrap name | merge ( [47 512 618] | wrap id )
╭───┬──────┬─────╮
│ # │ name │ id │
├───┼──────┼─────┤
│ 0 │ a │ 47 │
│ 1 │ b │ 512 │
│ 2 │ c │ 618 │
╰───┴──────┴─────╯
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 │
╰───┴─────────┴─────────╯
merge deep
Merge the input with a record or table, recursively merging values in matching columns.
The way that key-value pairs which exist in both the input and the argument are merged depends on their types.
Scalar values (like numbers and strings) in the input are overwritten by the corresponding value from the argument.
Records in the input are merged similarly to the merge command, but recursing rather than overwriting inner records.
The way lists and tables are merged is controlled by the --strategy flag:
- table: Merges tables element-wise, similarly to the merge command. Non-table lists are overwritten.
- overwrite: Lists and tables are overwritten with their corresponding value from the argument, similarly to scalars.
- append: Lists and tables in the input are appended with the corresponding list from the argument.
- prepend: Lists and tables in the input are prepended with the corresponding list from the argument.
Usage:
> merge deep {flags} <value>
Flags:
-h, --help: Display the help message for this command
-s, --strategy <string>: The list merging strategy to use. One of: table (default), overwrite, append, prepend
Parameters:
value <oneof<record, table, list<any>>>: The new value to merge with.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
╰───┴────────┴────────╯
Examples:
Merge two records recursively
> {a: 1, b: {c: 2, d: 3}} | merge deep {b: {d: 4, e: 5}}
╭───┬───────────╮
│ a │ 1 │
│ │ ╭───┬───╮ │
│ b │ │ c │ 2 │ │
│ │ │ d │ 4 │ │
│ │ │ e │ 5 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
Merge two tables
> [{columnA: 0, columnB: [{B1: 1}]}] | merge deep [{columnB: [{B2: 2}]}]
╭───┬─────────┬─────────────────╮
│ # │ columnA │ columnB │
├───┼─────────┼─────────────────┤
│ 0 │ 0 │ ╭───┬────┬────╮ │
│ │ │ │ # │ B1 │ B2 │ │
│ │ │ ├───┼────┼────┤ │
│ │ │ │ 0 │ 1 │ 2 │ │
│ │ │ ╰───┴────┴────╯ │
╰───┴─────────┴─────────────────╯
Merge two records and their inner tables
> {inner: [{a: 1}, {b: 2}]} | merge deep {inner: [{c: 3}]}
╭───────┬──────────────────────╮
│ │ ╭───┬────┬────┬────╮ │
│ inner │ │ # │ a │ c │ b │ │
│ │ ├───┼────┼────┼────┤ │
│ │ │ 0 │ 1 │ 3 │ ❎ │ │
│ │ │ 1 │ ❎ │ ❎ │ 2 │ │
│ │ ╰───┴────┴────┴────╯ │
╰───────┴──────────────────────╯
Merge two records, appending their inner tables
> {inner: [{a: 1}, {b: 2}]} | merge deep {inner: [{c: 3}]} --strategy=append
╭───────┬──────────────────────╮
│ │ ╭───┬────┬────┬────╮ │
│ inner │ │ # │ a │ b │ c │ │
│ │ ├───┼────┼────┼────┤ │
│ │ │ 0 │ 1 │ ❎ │ ❎ │ │
│ │ │ 1 │ ❎ │ 2 │ ❎ │ │
│ │ │ 2 │ ❎ │ ❎ │ 3 │ │
│ │ ╰───┴────┴────┴────╯ │
╰───────┴──────────────────────╯
metadata
Get the metadata for items in the stream.
Usage:
> metadata (expression)
Subcommands:
metadata access - Access the metadata for the input stream within a closure.
metadata set - Set the metadata for items in the stream.
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
metadata access
Access the metadata for the input stream within a closure.
Usage:
> metadata access <closure>
Flags:
-h, --help: Display the help message for this command
Parameters:
closure <closure(record)>: The closure to run with metadata access.
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Access metadata and data from a stream together
> {foo: bar} | to json --raw | metadata access {|meta| {in: $in, content: $meta.content_type}}
╭─────────┬──────────────────╮
│ in │ {"foo":"bar"} │
│ content │ application/json │
╰─────────┴──────────────────╯
metadata set
Set the metadata for items in the stream.
Usage:
> metadata set {flags}
Flags:
-h, --help: Display the help message for this command
-l, --datasource-ls: Assign the DataSource::Ls metadata to the input
-f, --datasource-filepath <path>: Assign the DataSource::FilePath metadata to the input
-c, --content-type <string>: Assign content type metadata to the input
-m, --merge <record>: Merge arbitrary metadata fields
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ any │
╰───┴───────┴────────╯
Examples:
Set the metadata of a table literal
> [[name color]; [Cargo.lock '#ff0000'] [Cargo.toml '#00ff00'] [README.md '#0000ff']] | metadata set --datasource-ls
Set the metadata of a file path
> 'crates' | metadata set --datasource-filepath $'(pwd)/crates'
Set the content type metadata
> 'crates' | metadata set --content-type text/plain | metadata | get content_type
text/plain
Set custom metadata
> "data" | metadata set --merge {custom_key: "value"} | metadata | get custom_key
value
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 <oneof<glob, 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: create, directory, file, folder, temporary, coreutils
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 <path>: 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
Moves columns relative to other columns or make them the first/last columns. Flags are mutually exclusive.
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
--first: makes the columns be the first ones
--last: makes the columns be the last ones
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, file, files, coreutils
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
-u, --update: move and overwrite only when the SOURCE file is newer than the destination file or when the destination file is missing
-n, --no-clobber: do not overwrite an existing file
Parameters:
...paths <oneof<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 only if source file is newer than target file
> mv -u new/test.txt old/
Move many files into a directory
> mv *.txt my/subdirectory
Move a file into the "my" directory two levels up in the directory tree
> mv test.txt .../my/
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
Parameters:
path <string>: File path to parse. (optional)
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ nothing │ bool │
│ 1 │ string │ bool │
│ 2 │ list<any> │ bool │
│ 3 │ 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 a byte 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
nu-highlight
Syntax highlight the input string.
Search terms: syntax, color, convert
Usage:
> nu-highlight {flags}
Flags:
-h, --help: Display the help message for this command
-r, --reject-garbage: Return an error if invalid syntax (garbage) was encountered
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, cat, get-content
Usage:
> open {flags} ...(files)
Flags:
-h, --help: Display the help message for this command
-r, --raw: open file as raw binary
Parameters:
...files <oneof<glob, string>>: The file(s) to open.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
│ 1 │ string │ any │
│ 2 │ any │ 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
Show the extensions for which the open command will automatically parse
> scope commands
| where name starts-with "from "
| insert extension { get name | str replace -r "^from " "" | $"*.($in)" }
| select extension name
| rename extension command
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 overlays with their active status.
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 overlays with their active status.
The overlays are listed in the order they were activated. Hidden overlays are listed first, followed by active overlays listed in the order that they were activated. last command will always give the top active overlay
Usage:
> overlay list
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬───────────────────────────────────╮
│ # │ input │ output │
├───┼─────────┼───────────────────────────────────┤
│ 0 │ nothing │ table<name: string, active: bool> │
╰───┴─────────┴───────────────────────────────────╯
Examples:
List all overlays with their active status
> module spam { export def foo [] { "foo" } }
overlay use spam
overlay list
╭───┬──────┬────────╮
│ # │ name │ active │
├───┼──────┼────────┤
│ 0 │ spam │ true │
╰───┴──────┴────────╯
Get overlay status after hiding
> module spam { export def foo [] { "foo" } }
overlay use spam
overlay hide spam
overlay list | where name == "spam"
╭───┬──────┬────────╮
│ # │ name │ active │
├───┼──────┼────────┤
│ 0 │ spam │ false │
╰───┴──────┴────────╯
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 {flags} <name>
Flags:
-h, --help: Display the help message for this command
-r, --reload: If the overlay already exists, reload its environment.
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 <oneof<string, nothing>>: Module name to use overlay for (null for no-op).
"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
Causes nushell to panic.
Search terms: crash, throw
Usage:
> panic (msg)
Flags:
-h, --help: Display the help message for this command
Parameters:
msg <string>: The custom message for the panic. (optional)
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Panic with a custom message
> panic 'This is a custom panic message'
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)>: 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 or a supplied regular expression.
The parse command always uses regular expressions even when you use a simple pattern. If a simple pattern is supplied, parse will transform that pattern into a regular expression.
Search terms: pattern, match, regex, str extract
Usage:
> parse {flags} <pattern>
Flags:
-h, --help: Display the help message for this command
-r, --regex: use full regex syntax for patterns
-b, --backtrack <int>: set the max backtrack limit for regex
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, ignoring a column with _
> "hello world" | parse "{foo} {_}"
╭───┬───────╮
│ # │ foo │
├───┼───────┤
│ 0 │ hello │
╰───┴───────╯
This is how the first example is interpreted in the source code
> "hi there" | parse --regex '(?s)\A(?P<foo>.*?) (?P<bar>.*?)\z'
╭───┬─────┬───────╮
│ # │ 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 │
╰───┴──────────╯
Parse a string with a manually set fancy-regex backtrack limit
> "hi there" | parse --backtrack 1500000 "{foo} {bar}"
╭───┬─────┬───────╮
│ # │ foo │ bar │
├───┼─────┼───────┤
│ 0 │ hi │ there │
╰───┴─────┴───────╯
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 self - Get the absolute path of the script or module containing this command at parse time.
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.
Also note that if you don't have a permission to a directory of a path, false will be returned
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 self
Get the absolute path of the script or module containing this command at parse time.
Usage:
> path self (path)
Flags:
-h, --help: Display the help message for this command
Parameters:
path <path>: Path to get instead of the current file. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Get the path of the current file
> const current_file = path self
Get the path of the directory containing the current file
> const current_file = path self .
Get the absolute form of a path relative to the current file
> const current_file = path self ..\foo
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 │ ╭───┬──────────╮ │
│ │ │ 0 │ C:\ │ │
│ │ │ 1 │ Users │ │
│ │ │ 2 │ viking │ │
│ │ │ 3 │ spam.txt │ │
│ │ ╰───┴──────────╯ │
│ 1 │ ╭───┬──────────╮ │
│ │ │ 0 │ C:\ │ │
│ │ │ 1 │ Users │ │
│ │ │ 2 │ viking │ │
│ │ │ 3 │ eggs.txt │ │
│ │ ╰───┴──────────╯ │
╰───┴──────────────────╯
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 the path does not exist, null 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
plugin
Commands for managing plugins.
Usage:
> plugin
Subcommands:
plugin add - Add a plugin to the plugin registry file.
plugin list - List loaded and installed plugins.
plugin rm - Remove a plugin from the plugin registry file.
plugin stop - Stop an installed plugin if it was running.
plugin use - Load a plugin from the plugin registry file into scope.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Run the nu_plugin_inc plugin from the current directory and install its signatures.
> plugin add nu_plugin_inc
Load (or reload) the inc plugin from the plugin registry file and put its
commands in scope. The plugin must already be in the registry file at parse
time.
> plugin use inc
List installed plugins
> plugin list
Stop the plugin named inc.
> plugin stop inc
Remove the installed signatures for the inc plugin.
> plugin rm inc
plugin add
Add a plugin to the plugin registry file.
This does not load the plugin commands into the scope - see plugin use for
that.
Instead, it runs the plugin to get its command signatures, and then edits the
plugin registry file (by default, $nu.plugin-path). The changes will be
apparent the next time nu is next launched with that plugin registry file.
Search terms: load, register, signature
Usage:
> plugin add {flags} <filename>
Flags:
-h, --help: Display the help message for this command
--plugin-config <path>: Use a plugin registry file other than the one set in $nu.plugin-path
-s, --shell <path>: Use an additional shell program (cmd, sh, python, etc.) to run the plugin
Parameters:
filename <string>: Path to the executable for the plugin.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Run the nu_plugin_inc plugin from the current directory or $env.NU_PLUGIN_DIRS and install its signatures.
> plugin add nu_plugin_inc
Run the nu_plugin_polars plugin from the current directory or $env.NU_PLUGIN_DIRS, and install its signatures to the "polars.msgpackz" plugin registry file.
> plugin add --plugin-config polars.msgpackz nu_plugin_polars
plugin list
List loaded and installed plugins.
The status column will contain one of the following values:
- added: The plugin is present in the plugin registry file, but not in
the engine.
- loaded: The plugin is present both in the plugin registry file and in
the engine, but is not running.
- running: The plugin is currently running, and the pid column should
contain its process ID.
- modified: The plugin state present in the plugin registry file is different
from the state in the engine.
- removed: The plugin is still loaded in the engine, but is not present in
the plugin registry file.
- invalid: The data in the plugin registry file couldn't be deserialized,
and the plugin most likely needs to be added again.
running takes priority over any other status. Unless --registry is used
or the plugin has not been loaded yet, the values of version, filename,
shell, and commands reflect the values in the engine and not the ones in
the plugin registry file.
See also: plugin use
Search terms: scope
Usage:
> plugin list {flags}
Flags:
-h, --help: Display the help message for this command
--plugin-config <path>: Use a plugin registry file other than the one set in $nu.plugin-path
-e, --engine: Show info for plugins that are loaded into the engine only.
-r, --registry: Show info for plugins from the registry file only.
Input/output types:
╭───┬─────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ # │ input │ output │
├───┼─────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 0 │ nothing │ table<name: string, version: string, status: string, pid: int, filename: string, shell: string, commands: list<string>> │
╰───┴─────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples:
List installed plugins.
> plugin list
╭───┬──────┬─────────┬─────────┬────────┬─────────────────────────────────┬───────┬─────────────╮
│ # │ name │ version │ status │ pid │ filename │ shell │ commands │
├───┼──────┼─────────┼─────────┼────────┼─────────────────────────────────┼───────┼─────────────┤
│ 0 │ inc │ 0.108.0 │ running │ 106480 │ C:\nu\plugins\nu_plugin_inc.exe │ │ ╭───┬─────╮ │
│ │ │ │ │ │ │ │ │ 0 │ inc │ │
│ │ │ │ │ │ │ │ ╰───┴─────╯ │
╰───┴──────┴─────────┴─────────┴────────┴─────────────────────────────────┴───────┴─────────────╯
Get process information for running plugins.
> ps | where pid in (plugin list).pid
plugin rm
Remove a plugin from the plugin registry file.
This does not remove the plugin commands from the current scope or from `plugin
list` in the current shell. It instead removes the plugin from the plugin
registry file (by default, $nu.plugin-path). The changes will be apparent the
next time nu is launched with that plugin registry file.
This can be useful for removing an invalid plugin signature, if it can't be
fixed with plugin add.
Search terms: remove, delete, signature
Usage:
> plugin rm {flags} <name>
Flags:
-h, --help: Display the help message for this command
--plugin-config <path>: Use a plugin registry file other than the one set in $nu.plugin-path
-f, --force: Don't cause an error if the plugin name wasn't found in the file
Parameters:
name <string>: The name, or filename, of the plugin to remove.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Remove the installed signatures for the inc plugin.
> plugin rm inc
Remove the installed signatures for the plugin with the filename ~/.cargo/bin/nu_plugin_inc.
> plugin rm ~/.cargo/bin/nu_plugin_inc
Remove the installed signatures for the polars plugin from the "polars.msgpackz" plugin registry file.
> plugin rm --plugin-config polars.msgpackz polars
plugin stop
Stop an installed plugin if it was running.
Usage:
> plugin stop <name>
Flags:
-h, --help: Display the help message for this command
Parameters:
name <string>: The name, or filename, of the plugin to stop.
Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯
Examples:
Stop the plugin named inc.
> plugin stop inc
Stop the plugin with the filename ~/.cargo/bin/nu_plugin_inc.
> plugin stop ~/.cargo/bin/nu_plugin_inc
Stop all plugins.
> plugin list | each { |p| plugin stop $p.name }
plugin use
Load a plugin from the plugin registry file into scope.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
The plugin definition must be available in the plugin registry file at parse
time. Run plugin add first in the REPL to do this, or from a script consider
preparing a plugin registry file and passing --plugin-config, or using the
--plugin option to nu instead.
If the plugin was already loaded, this will reload the latest definition from
the registry file into scope.
Note that even if the plugin filename is specified, it will only be loaded if
it was already previously registered with plugin add.
Search terms: add, register, scope
Usage:
> plugin use {flags} <name>
Flags:
-h, --help: Display the help message for this command
--plugin-config <path>: Use a plugin registry file other than the one set in $nu.plugin-path
Parameters:
name <string>: The name, or filename, of the plugin to load.
Examples:
Load the commands for the query plugin from $nu.plugin-path
> plugin use query
Load the commands for the plugin with the filename ~/.cargo/bin/nu_plugin_query from $nu.plugin-path
> plugin use ~/.cargo/bin/nu_plugin_query
Load the commands for the query plugin from a custom plugin registry file
> plugin use --plugin-config local-plugins.msgpackz query
polars
Operate with data in a dataframe format.
You must use one of the subcommands below. Using this command as-is will only produce this help message.
The following are the main datatypes (wrapped from Polars) that are used by these subcommands:
Lazy and Strict dataframes (called NuLazyFrame and NuDataFrame in error messages) are the main
data structure.
Expressions, representing various column operations (called NuExpression), are passed to many commands such as
polars filter or polars with-column. Most nushell operators are supported in these expressions, importantly
arithmetic, comparison and boolean logical.
Groupbys (NuLazyGroupBy), the output of a polars group-by, represent a grouped dataframe and are typically piped
to the polars agg command with some column expressions for aggregation which then returns a dataframe.
Usage:
> polars
Subcommands:
polars agg (plugin) - Performs a series of aggregations from a group-by.
polars agg-groups (plugin) - Creates an agg_groups expression.
polars all-false (plugin) - Returns true if all values are false.
polars all-true (plugin) - Returns true if all values are true.
polars append (plugin) - Appends a new dataframe.
polars arg-max (plugin) - Return index for max value in series.
polars arg-min (plugin) - Return index for min value in series.
polars arg-sort (plugin) - Returns indexes for a sorted series.
polars arg-true (plugin) - Returns indexes where values are true.
polars arg-unique (plugin) - Returns indexes for unique values.
polars arg-where (plugin) - Creates an expression that returns the arguments where expression is true.
polars as (plugin) - Creates an alias expression.
polars as-date (plugin) - Converts string to date.
polars as-datetime (plugin) - Converts string to datetime.
polars cache (plugin) - Caches operations in a new LazyFrame.
polars cast (plugin) - Cast a column to a different dtype.
polars col (plugin) - Creates a named column expression.
polars collect (plugin) - Collect lazy dataframe into eager dataframe.
polars columns (plugin) - Show dataframe columns.
polars concat (plugin) - Concatenate two or more dataframes.
polars concat-str (plugin) - Creates a concat string expression.
polars contains (plugin) - Checks if a pattern is contained in a string.
polars convert-time-zone (plugin) - Convert datetime to target timezone.
polars count (plugin) - Returns the number of non-null values in the column.
polars count-null (plugin) - Counts null values.
polars cumulative (plugin) - Cumulative calculation for a column or series.
polars cut (plugin) - Bin continuous values into discrete categories for a series.
polars datepart (plugin) - Creates an expression for capturing the specified datepart in a column.
polars decimal (plugin) - Converts a string column into a decimal column
polars drop (plugin) - Creates a new dataframe by dropping the selected columns.
polars drop-duplicates (plugin) - Drops duplicate values in dataframe.
polars drop-nulls (plugin) - Drops null values in dataframe.
polars dummies (plugin) - Creates a new dataframe with dummy variables.
polars explode (plugin) - Explodes a dataframe or creates a explode expression.
polars expr-not (plugin) - Creates a not expression.
polars fill-nan (plugin) - Replaces NaN values with the given expression.
polars fill-null (plugin) - Replaces NULL values with the given expression.
polars filter (plugin) - Filter dataframe based in expression.
polars filter-with (plugin) - Filters dataframe using a mask or expression as reference.
polars first (plugin) - Show only the first number of rows or create a first expression
polars flatten (plugin) - An alias for polars explode.
polars get (plugin) - Creates dataframe with the selected columns.
polars get-day (plugin) - Gets day from date.
polars get-hour (plugin) - Gets hour from datetime.
polars get-minute (plugin) - Gets minute from date.
polars get-month (plugin) - Gets month from date.
polars get-nanosecond (plugin) - Gets nanosecond from date.
polars get-ordinal (plugin) - Gets ordinal from date.
polars get-second (plugin) - Gets second from date.
polars get-week (plugin) - Gets week from date.
polars get-weekday (plugin) - Gets weekday from date.
polars get-year (plugin) - Gets year from date.
polars group-by (plugin) - Creates a group-by object that can be used for other aggregations.
polars horizontal (plugin) - Horizontal calculation across multiple columns.
polars implode (plugin) - Aggregates values into a list.
polars integer (plugin) - Converts a string column into a integer column
polars into-df (plugin) - Converts a list, table or record into a dataframe.
polars into-dtype (plugin) - Convert a string to a specific datatype.
polars into-lazy (plugin) - Converts a dataframe into a lazy dataframe.
polars into-nu (plugin) - Converts a dataframe or an expression into nushell value for access and exploration.
polars into-repr (plugin) - Display a dataframe in its repr format.
polars into-schema (plugin) - Convert a value to a polars schema object
polars is-duplicated (plugin) - Creates mask indicating duplicated values.
polars is-in (plugin) - Creates an is-in expression or checks to see if the elements are contained in the right series
polars is-not-null (plugin) - Creates mask where value is not null.
polars is-null (plugin) - Creates mask where value is null.
polars is-unique (plugin) - Creates mask indicating unique values.
polars join (plugin) - Joins a lazy frame with other lazy frame.
polars join-where (plugin) - Joins a lazy frame with other lazy frame based on conditions.
polars last (plugin) - Creates new dataframe with tail rows or creates a last expression.
polars len (plugin) - Return the number of rows in the context. This is similar to COUNT(*) in SQL.
polars list-contains (plugin) - Checks if an element is contained in a list.
polars lit (plugin) - Creates a literal expression.
polars lowercase (plugin) - Lowercase the strings in the column.
polars math (plugin) - Collection of math functions to be applied on one or more column expressions
polars max (plugin) - Creates a max expression or aggregates columns to their max value.
polars mean (plugin) - Creates a mean expression for an aggregation or aggregates columns to their mean value.
polars median (plugin) - Median value from columns in a dataframe or creates expression for an aggregation
polars min (plugin) - Creates a min expression or aggregates columns to their min value.
polars n-unique (plugin) - Counts unique values.
polars not (plugin) - Inverts boolean mask.
polars open (plugin) - Opens CSV, JSON, NDJSON/JSON lines, arrow, avro, or parquet file to create dataframe. A lazy dataframe will be created by default, if supported.
polars otherwise (plugin) - Completes a when expression.
polars over (plugin) - Compute expressions over a window group defined by partition expressions.
polars pivot (plugin) - Pivot a DataFrame from long to wide format.
polars profile (plugin) - Profile a lazy dataframe.
polars qcut (plugin) - Bin continuous values into discrete categories based on their quantiles for a series.
polars quantile (plugin) - Aggregates the columns to the selected quantile.
polars query (plugin) - Query dataframe using SQL. Note: The dataframe is always named 'df' in your query's from clause.
polars rename (plugin) - Rename a dataframe column.
polars replace (plugin) - Create an expression that replaces old values with new values
polars replace-time-zone (plugin) - Replace the timezone information in a datetime column.
polars reverse (plugin) - Reverses the LazyFrame
polars rolling (plugin) - Rolling calculation for a series.
polars sample (plugin) - Create sample dataframe.
polars save (plugin) - Saves a dataframe to disk. For lazy dataframes a sink operation will be used if the file type supports it (parquet, ipc/arrow, csv, and ndjson).
polars schema (plugin) - Show schema for a dataframe.
polars select (plugin) - Selects columns from lazyframe.
polars set (plugin) - Sets value where given mask is true.
polars set-with-idx (plugin) - Sets value in the given index.
polars shape (plugin) - Shows column and row size for a dataframe.
polars shift (plugin) - Shifts the values by a given period.
polars slice (plugin) - Creates new dataframe from a slice of rows.
polars sort-by (plugin) - Sorts a lazy dataframe based on expression(s).
polars std (plugin) - Creates a std expression for an aggregation of std value from columns in a dataframe.
polars store-get (plugin) - Gets a Dataframe or other object from the plugin cache.
polars store-ls (plugin) - Lists stored polars objects.
polars store-rm (plugin) - Removes a stored Dataframe or other object from the plugin cache.
polars str-join (plugin) - Concatenates strings within a column or dataframes
polars str-lengths (plugin) - Get lengths of all strings.
polars str-replace (plugin) - Replace the leftmost (sub)string by a regex pattern.
polars str-replace-all (plugin) - Replace all (sub)strings by a regex pattern.
polars str-slice (plugin) - Slices the string from the start position until the selected length.
polars str-split (plugin) - Split the string by a substring. The resulting dtype is list<str>.
polars str-strip-chars (plugin) - Strips specified characters from strings in a column
polars strftime (plugin) - Formats date based on string rule.
polars struct-json-encode (plugin) - Convert this struct to a string column with json values.
polars sum (plugin) - Creates a sum expression for an aggregation or aggregates columns to their sum value.
polars summary (plugin) - For a dataframe, produces descriptive statistics (summary statistics) for its numeric columns.
polars take (plugin) - Creates new dataframe using the given indices.
polars truncate (plugin) - Divide the date/datetime range into buckets.
polars unique (plugin) - Returns unique values from a dataframe.
polars unnest (plugin) - Decompose struct columns into separate columns for each of their fields. The new columns will be inserted into the dataframe at the location of the struct column.
polars unpivot (plugin) - Unpivot a DataFrame from wide to long format.
polars uppercase (plugin) - Uppercase the strings in the column.
polars value-counts (plugin) - Returns a dataframe with the counts for unique values in series.
polars var (plugin) - Create a var expression for an aggregation.
polars when (plugin) - Creates and modifies a when expression.
polars with-column (plugin) - Adds a series to the dataframe.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
polars agg
Performs a series of aggregations from a group-by.
Usage:
> polars agg ...(Group-by expressions)
Flags:
-h, --help: Display the help message for this command
Parameters:
...Group-by expressions <any>: Expression(s) that define the aggregations to be applied
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Group by and perform an aggregation
> [[a b]; [1 2] [1 4] [2 6] [2 4]]
| polars into-lazy
| polars group-by a
| polars agg [
(polars col b | polars min | polars as "b_min")
(polars col b | polars max | polars as "b_max")
(polars col b | polars sum | polars as "b_sum")
]
| polars collect
| polars sort-by a
╭───┬───┬───────┬───────┬───────╮
│ # │ a │ b_min │ b_max │ b_sum │
├───┼───┼───────┼───────┼───────┤
│ 0 │ 1 │ 2 │ 4 │ 6 │
│ 1 │ 2 │ 4 │ 6 │ 10 │
╰───┴───┴───────┴───────┴───────╯
Group by and perform an aggregation using a record
> [[a b]; [1 2] [1 4] [2 6] [2 4]]
| polars into-lazy
| polars group-by a
| polars agg {
b_min: (polars col b | polars min)
b_max: (polars col b | polars max)
b_sum: (polars col b | polars sum)
}
| polars collect
| polars sort-by a
╭───┬───┬───────┬───────┬───────╮
│ # │ a │ b_min │ b_max │ b_sum │
├───┼───┼───────┼───────┼───────┤
│ 0 │ 1 │ 2 │ 4 │ 6 │
│ 1 │ 2 │ 4 │ 6 │ 10 │
╰───┴───┴───────┴───────┴───────╯
polars agg-groups
Creates an agg_groups expression.
Usage:
> polars agg-groups
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Get the group index of the group by operations.
> [[group value]; [one 94] [one 95] [one 96] [two 97] [two 98] [two 99]]
| polars into-df
| polars group-by group
| polars agg (polars col value | polars agg-groups)
| polars collect
| polars sort-by group
╭───┬───────┬───────────╮
│ # │ group │ values │
├───┼───────┼───────────┤
│ 0 │ one │ ╭───┬───╮ │
│ │ │ │ 0 │ 0 │ │
│ │ │ │ 1 │ 1 │ │
│ │ │ │ 2 │ 2 │ │
│ │ │ ╰───┴───╯ │
│ 1 │ two │ ╭───┬───╮ │
│ │ │ │ 0 │ 3 │ │
│ │ │ │ 1 │ 4 │ │
│ │ │ │ 2 │ 5 │ │
│ │ │ ╰───┴───╯ │
╰───┴───────┴───────────╯
polars all-false
Returns true if all values are false.
Usage:
> polars all-false
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Returns true if all values are false
> [false false false] | polars into-df | polars all-false
╭───┬───────────╮
│ # │ all_false │
├───┼───────────┤
│ 0 │ true │
╰───┴───────────╯
Checks the result from a comparison
> let s = ([5 6 2 10] | polars into-df);
let res = ($s > 9);
$res | polars all-false
╭───┬───────────╮
│ # │ all_false │
├───┼───────────┤
│ 0 │ false │
╰───┴───────────╯
polars all-true
Returns true if all values are true.
Usage:
> polars all-true
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Returns true if all values are true
> [true true true] | polars into-df | polars all-true
╭───┬──────────╮
│ # │ all_true │
├───┼──────────┤
│ 0 │ true │
╰───┴──────────╯
Checks the result from a comparison
> let s = ([5 6 2 8] | polars into-df);
let res = ($s > 9);
$res | polars all-true
╭───┬──────────╮
│ # │ all_true │
├───┼──────────┤
│ 0 │ false │
╰───┴──────────╯
polars append
Appends a new dataframe.
Usage:
> polars append {flags} <other>
Flags:
-h, --help: Display the help message for this command
-c, --col: append as new columns instead of rows
Parameters:
other <any>: other dataframe to append
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Appends a dataframe as new columns
> let a = ([[a b]; [1 2] [3 4]] | polars into-df);
$a | polars append $a
╭───┬───┬───┬─────┬─────╮
│ # │ a │ b │ a_x │ b_x │
├───┼───┼───┼─────┼─────┤
│ 0 │ 1 │ 2 │ 1 │ 2 │
│ 1 │ 3 │ 4 │ 3 │ 4 │
╰───┴───┴───┴─────┴─────╯
Appends a dataframe merging at the end of columns
> let a = ([[a b]; [1 2] [3 4]] | polars into-df); $a | polars append $a --col
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
│ 2 │ 1 │ 2 │
│ 3 │ 3 │ 4 │
╰───┴───┴───╯
polars arg-max
Return index for max value in series.
Search terms: argmax, maximum, most, largest, greatest
Usage:
> polars arg-max
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Returns index for max value
> [1 3 2] | polars into-df | polars arg-max
╭───┬─────────╮
│ # │ arg_max │
├───┼─────────┤
│ 0 │ 1 │
╰───┴─────────╯
polars arg-min
Return index for min value in series.
Search terms: argmin, minimum, least, smallest, lowest
Usage:
> polars arg-min
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Returns index for min value
> [1 3 2] | polars into-df | polars arg-min
╭───┬─────────╮
│ # │ arg_min │
├───┼─────────┤
│ 0 │ 0 │
╰───┴─────────╯
polars arg-sort
Returns indexes for a sorted series.
Search terms: argsort, order, arrange
Usage:
> polars arg-sort {flags}
Flags:
-h, --help: Display the help message for this command
-r, --reverse: reverse order
-n, --nulls-last: nulls ordered last
-l, --limit <int>: Limit a sort output, this is for optimization purposes and might be ignored.
-m, --maintain-order: maintain order on sorted items
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Returns indexes for a sorted series
> [1 2 2 3 3] | polars into-df | polars arg-sort
╭───┬──────────╮
│ # │ arg_sort │
├───┼──────────┤
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 2 │
│ 3 │ 3 │
│ 4 │ 4 │
╰───┴──────────╯
Returns indexes for a sorted series
> [1 2 2 3 3] | polars into-df | polars arg-sort --reverse
╭───┬──────────╮
│ # │ arg_sort │
├───┼──────────┤
│ 0 │ 3 │
│ 1 │ 4 │
│ 2 │ 1 │
│ 3 │ 2 │
│ 4 │ 0 │
╰───┴──────────╯
Returns indexes for a sorted series and applying a limit
> [1 2 2 3 3] | polars into-df | polars arg-sort --limit 2
╭───┬──────────╮
│ # │ arg_sort │
├───┼──────────┤
│ 0 │ 0 │
│ 1 │ 1 │
╰───┴──────────╯
polars arg-true
Returns indexes where values are true.
Search terms: argtrue, truth, boolean-true
Usage:
> polars arg-true
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Returns indexes where values are true
> [false true false] | polars into-df | polars arg-true
╭───┬──────────╮
│ # │ arg_true │
├───┼──────────┤
│ 0 │ 1 │
╰───┴──────────╯
polars arg-unique
Returns indexes for unique values.
Search terms: argunique, distinct, noduplicate, unrepeated
Usage:
> polars arg-unique
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Returns indexes for unique values
> [1 2 2 3 3] | polars into-df | polars arg-unique
╭───┬────────────╮
│ # │ arg_unique │
├───┼────────────┤
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 3 │
╰───┴────────────╯
polars arg-where
Creates an expression that returns the arguments where expression is true.
Search terms: condition, match, if
Usage:
> polars arg-where <column name>
Flags:
-h, --help: Display the help message for this command
Parameters:
column name <any>: Expression to evaluate
Input/output types:
╭───┬───────┬───────────────────╮
│ # │ input │ output │
├───┼───────┼───────────────────┤
│ 0 │ any │ polars_expression │
╰───┴───────┴───────────────────╯
Examples:
Return a dataframe where the value match the expression
> let df = ([[a b]; [one 1] [two 2] [three 3]] | polars into-df);
$df | polars select (polars arg-where ((polars col b) >= 2) | polars as b_arg)
╭───┬───────╮
│ # │ b_arg │
├───┼───────┤
│ 0 │ 1 │
│ 1 │ 2 │
╰───┴───────╯
polars as
Creates an alias expression.
Search terms: aka, abbr, otherwise
Usage:
> polars as <Alias name>
Flags:
-h, --help: Display the help message for this command
Parameters:
Alias name <string>: Alias name for the expression
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Creates and alias expression
> polars col a | polars as new_a | polars into-nu
╭───────┬────────────────────╮
│ │ ╭───────┬────────╮ │
│ expr │ │ expr │ column │ │
│ │ │ value │ a │ │
│ │ ╰───────┴────────╯ │
│ alias │ new_a │
╰───────┴────────────────────╯
polars as-date
Converts string to date.
Format example:
"%Y-%m-%d" => 2021-12-31
"%d-%m-%Y" => 31-12-2021
"%Y%m%d" => 2021319 (2021-03-19)
Usage:
> polars as-date {flags} <format>
Flags:
-h, --help: Display the help message for this command
-n, --not-exact: the format string may be contained in the date (e.g. foo-2021-01-01-bar could match 2021-01-01)
Parameters:
format <string>: formatting date string
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Converts string to date
> ["2021-12-30" "2021-12-31"] | polars into-df | polars as-date "%Y-%m-%d"
╭───┬─────────────╮
│ # │ date │
├───┼─────────────┤
│ 0 │ 3 years ago │
│ 1 │ 3 years ago │
╰───┴─────────────╯
Converts string to date
> ["2021-12-30" "2021-12-31 21:00:00"] | polars into-df | polars as-date "%Y-%m-%d" --not-exact
╭───┬─────────────╮
│ # │ date │
├───┼─────────────┤
│ 0 │ 3 years ago │
│ 1 │ 3 years ago │
╰───┴─────────────╯
Converts string to date in an expression
> ["2021-12-30" "2021-12-31 21:00:00"] | polars into-lazy | polars select (polars col 0 | polars as-date "%Y-%m-%d" --not-exact)
╭───┬─────────────╮
│ # │ date │
├───┼─────────────┤
│ 0 │ 3 years ago │
│ 1 │ 3 years ago │
╰───┴─────────────╯
Output is of date type
> ["2021-12-30" "2021-12-31 21:00:00"] | polars into-df | polars as-date "%Y-%m-%d" --not-exact | polars schema
╭──────┬──────╮
│ date │ date │
╰──────┴──────╯
polars as-datetime
Converts string to datetime.
Format example:
"%y/%m/%d %H:%M:%S" => 21/12/31 12:54:98
"%y-%m-%d %H:%M:%S" => 2021-12-31 24:58:01
"%y/%m/%d %H:%M:%S" => 21/12/31 24:58:01
"%y%m%d %H:%M:%S" => 210319 23:58:50
"%Y/%m/%d %H:%M:%S" => 2021/12/31 12:54:98
"%Y-%m-%d %H:%M:%S" => 2021-12-31 24:58:01
"%Y/%m/%d %H:%M:%S" => 2021/12/31 24:58:01
"%Y%m%d %H:%M:%S" => 20210319 23:58:50
"%FT%H:%M:%S" => 2019-04-18T02:45:55
"%FT%H:%M:%S.%6f" => microseconds
"%FT%H:%M:%S.%9f" => nanoseconds
Usage:
> polars as-datetime {flags} <format>
Flags:
-h, --help: Display the help message for this command
-n, --not-exact: the format string may be contained in the date (e.g. foo-2021-01-01-bar could match 2021-01-01)
--naive: the input datetimes should be parsed as naive (i.e., not timezone-aware). Ignored if input is an expression.
-a, --ambiguous <oneof<string, nothing>>: Determine how to deal with ambiguous datetimes:
raise (default): raise error
earliest: use the earliest datetime
latest: use the latest datetime
null: set to null
Used only when input is a lazyframe or expression and ignored otherwise
--time-unit <string>: time unit for the output datetime. One of: ns, us, ms. Default is ns
--time-zone <string>: time zone for the output datetime. E.g. 'UTC', 'America/New_York'
Parameters:
format <string>: formatting date time string
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Converts string to datetime
> ["2021-12-30 00:00:00 -0400" "2021-12-31 00:00:00 -0400"] | polars into-df | polars as-datetime "%Y-%m-%d %H:%M:%S %z"
╭───┬─────────────╮
│ # │ datetime │
├───┼─────────────┤
│ 0 │ 3 years ago │
│ 1 │ 3 years ago │
╰───┴─────────────╯
Converts string to datetime with high resolutions
> ["2021-12-30 00:00:00.123456789" "2021-12-31 00:00:00.123456789"] | polars into-df | polars as-datetime "%Y-%m-%d %H:%M:%S.%9f" --naive
╭───┬─────────────╮
│ # │ datetime │
├───┼─────────────┤
│ 0 │ 3 years ago │
│ 1 │ 3 years ago │
╰───┴─────────────╯
Converts string to datetime using the --not-exact flag even with excessive symbols
> ["2021-12-30 00:00:00 GMT+4"] | polars into-df | polars as-datetime "%Y-%m-%d %H:%M:%S" --not-exact --naive
╭───┬─────────────╮
│ # │ datetime │
├───┼─────────────┤
│ 0 │ 3 years ago │
╰───┴─────────────╯
Converts string to datetime using the --not-exact flag even with excessive symbols in an expression
> ["2025-11-02 00:00:00", "2025-11-02 01:00:00", "2025-11-02 02:00:00", "2025-11-02 03:00:00"] | polars into-df | polars select (polars col 0 | polars as-datetime "%Y-%m-%d %H:%M:%S")
╭───┬─────────────╮
│ # │ datetime │
├───┼─────────────┤
│ 0 │ a month ago │
│ 1 │ a month ago │
│ 2 │ a month ago │
│ 3 │ a month ago │
╰───┴─────────────╯
polars cache
Caches operations in a new LazyFrame.
Usage:
> polars cache
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Caches the result into a new LazyFrame
> [[a b]; [6 2] [4 2] [2 2]] | polars into-df
| polars reverse
| polars cache
| polars sort-by a
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 2 │ 2 │
│ 1 │ 4 │ 2 │
│ 2 │ 6 │ 2 │
╰───┴───┴───╯
polars cast
Cast a column to a different dtype.
Usage:
> polars cast <dtype> (column)
Flags:
-h, --help: Display the help message for this command
Parameters:
dtype <string>: The dtype to cast the column to
column <string>: The column to cast. Required when used with a dataframe. (optional)
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Cast a column in a dataframe to a different dtype
> [[a b]; [1 2] [3 4]] | polars into-df | polars cast u8 a | polars schema
╭───┬─────╮
│ a │ u8 │
│ b │ i64 │
╰───┴─────╯
Cast a column in a lazy dataframe to a different dtype
> [[a b]; [1 2] [3 4]] | polars into-df | polars into-lazy | polars cast u8 a | polars schema
╭───┬─────╮
│ a │ u8 │
│ b │ i64 │
╰───┴─────╯
Cast a column in a expression to a different dtype
> [[a b]; [1 2] [1 4]] | polars into-df | polars group-by a | polars agg [ (polars col b | polars cast u8 | polars min | polars as "b_min") ] | polars schema
polars col
Creates a named column expression.
Search terms: create
Usage:
> polars col {flags} <column name> ...(more columns)
Flags:
-h, --help: Display the help message for this command
-t, --type: Treat column names as type names
Parameters:
column name <string>: Name of column to be used. '*' can be used for all columns. Accepts regular expression input; regular expressions should start with ^ and end with $.
...more columns <string>: Additional columns to be used. Cannot be '*'
Input/output types:
╭───┬───────┬───────────────────╮
│ # │ input │ output │
├───┼───────┼───────────────────┤
│ 0 │ any │ polars_expression │
╰───┴───────┴───────────────────╯
Examples:
Creates a named column expression and converts it to a nu object
> polars col a | polars into-nu
╭───────┬────────╮
│ expr │ column │
│ value │ a │
╰───────┴────────╯
Select all columns using the asterisk wildcard.
> [[a b]; [x 1] [y 2] [z 3]] | polars into-df | polars select (polars col '*') | polars collect
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ x │ 1 │
│ 1 │ y │ 2 │
│ 2 │ z │ 3 │
╰───┴───┴───╯
Select multiple columns (cannot be used with asterisk wildcard)
> [[a b c]; [x 1 1.1] [y 2 2.2] [z 3 3.3]] | polars into-df | polars select (polars col b c | polars sum) | polars collect
╭───┬───┬──────╮
│ # │ b │ c │
├───┼───┼──────┤
│ 0 │ 6 │ 6.60 │
╰───┴───┴──────╯
Select multiple columns by types (cannot be used with asterisk wildcard)
> [[a b c]; [x o 1.1] [y p 2.2] [z q 3.3]] | polars into-df | polars select (polars col str f64 --type | polars max) | polars collect
╭───┬───┬───┬──────╮
│ # │ a │ b │ c │
├───┼───┼───┼──────┤
│ 0 │ z │ q │ 3.30 │
╰───┴───┴───┴──────╯
Select columns using a regular expression
> [[ham hamburger foo bar]; [1 11 2 a] [2 22 1 b]] | polars into-df | polars select (polars col '^ham.*$') | polars collect
╭───┬─────┬───────────╮
│ # │ ham │ hamburger │
├───┼─────┼───────────┤
│ 0 │ 1 │ 11 │
│ 1 │ 2 │ 22 │
╰───┴─────┴───────────╯
polars collect
Collect lazy dataframe into eager dataframe.
Usage:
> polars collect
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_dataframe │
╰───┴──────────────────┴──────────────────╯
Examples:
drop duplicates
> [[a b]; [1 2] [3 4]] | polars into-lazy | polars collect
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
polars columns
Show dataframe columns.
Usage:
> polars columns
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Dataframe columns
> [[a b]; [1 2] [3 4]] | polars into-df | polars columns
╭───┬───╮
│ 0 │ a │
│ 1 │ b │
╰───┴───╯
polars concat
Concatenate two or more dataframes.
Usage:
> polars concat {flags} ...(dataframes)
Flags:
-h, --help: Display the help message for this command
--no-parallel: Disable parallel execution
--rechunk: Rechunk the resulting dataframe
--to-supertypes: Cast to supertypes
--diagonal: Concatenate dataframes diagonally
--no-maintain-order: Do not maintain order. The default behavior is to maintain order.
--from-partitioned-ds: Concatenate dataframes from a partitioned dataset
Parameters:
...dataframes <any>: The dataframes to concatenate
Input/output types:
╭───┬───────┬──────────────────╮
│ # │ input │ output │
├───┼───────┼──────────────────┤
│ 0 │ any │ polars_dataframe │
│ 1 │ any │ polars_lazyframe │
╰───┴───────┴──────────────────╯
Examples:
Concatenates two dataframes with the dataframe in the pipeline.
> [[a b]; [1 2]] | polars into-df
| polars concat ([[a b]; [3 4]] | polars into-df) ([[a b]; [5 6]] | polars into-df)
| polars collect
| polars sort-by [a b]
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
│ 2 │ 5 │ 6 │
╰───┴───┴───╯
Concatenates three dataframes together
> polars concat ([[a b]; [1 2]] | polars into-df) ([[a b]; [3 4]] | polars into-df) ([[a b]; [5 6]] | polars into-df)
| polars collect
| polars sort-by [a b]
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
│ 2 │ 5 │ 6 │
╰───┴───┴───╯
polars concat-str
Creates a concat string expression.
Search terms: join, connect, update
Usage:
> polars concat-str <separator> <concat expressions>
Flags:
-h, --help: Display the help message for this command
Parameters:
separator <string>: Separator used during the concatenation
concat expressions <list<any>>: Expression(s) that define the string concatenation
Input/output types:
╭───┬───────┬───────────────────╮
│ # │ input │ output │
├───┼───────┼───────────────────┤
│ 0 │ any │ polars_expression │
╰───┴───────┴───────────────────╯
Examples:
Creates a concat string expression
> let df = ([[a b c]; [one two 1] [three four 2]] | polars into-df);
$df | polars with-column ((polars concat-str "-" [(polars col a) (polars col b) ((polars col c) * 2)]) | polars as concat)
╭───┬───────┬──────┬───┬──────────────╮
│ # │ a │ b │ c │ concat │
├───┼───────┼──────┼───┼──────────────┤
│ 0 │ one │ two │ 1 │ one-two-2 │
│ 1 │ three │ four │ 2 │ three-four-4 │
╰───┴───────┴──────┴───┴──────────────╯
polars contains
Checks if a pattern is contained in a string.
Usage:
> polars contains <pattern>
Flags:
-h, --help: Display the help message for this command
Parameters:
pattern <string>: Regex pattern to be searched
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns boolean indicating if pattern was found in a column
> let df = [[a]; [abc] [acb] [acb]] | polars into-df;
let df2 = $df | polars with-column [(polars col a | polars contains ab | polars as b)] | polars collect;
$df2.b
╭───┬───────╮
│ # │ b │
├───┼───────┤
│ 0 │ true │
│ 1 │ false │
│ 2 │ false │
╰───┴───────╯
Returns boolean indicating if pattern was found
> [abc acb acb] | polars into-df | polars contains ab
╭───┬───────╮
│ # │ 0 │
├───┼───────┤
│ 0 │ true │
│ 1 │ false │
│ 2 │ false │
╰───┴───────╯
polars convert-time-zone
Convert datetime to target timezone.
Usage:
> polars convert-time-zone <time_zone>
Flags:
-h, --help: Display the help message for this command
Parameters:
time_zone <string>: Timezone for the Datetime Series. Pass null to unset time zone.
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Convert timezone for timezone-aware datetime
> ["2025-04-10 09:30:00 -0400" "2025-04-10 10:30:00 -0400"] | polars into-df
| polars as-datetime "%Y-%m-%d %H:%M:%S %z"
| polars select (polars col datetime | polars convert-time-zone "Europe/Lisbon")
╭───┬──────────────╮
│ # │ datetime │
├───┼──────────────┤
│ 0 │ 8 months ago │
│ 1 │ 8 months ago │
╰───┴──────────────╯
Timezone conversions for timezone-naive datetime will assume the original timezone is UTC
> ["2025-04-10 09:30:00" "2025-04-10 10:30:00"] | polars into-df
| polars as-datetime "%Y-%m-%d %H:%M:%S" --naive
| polars select (polars col datetime | polars convert-time-zone "America/New_York")
╭───┬──────────────╮
│ # │ datetime │
├───┼──────────────┤
│ 0 │ 8 months ago │
│ 1 │ 8 months ago │
╰───┴──────────────╯
polars count
Returns the number of non-null values in the column.
Usage:
> polars count
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Count the number of non-null values in a column
> [[a]; ["foo"] ["bar"] [null]] | polars into-df
| polars select (polars col a | polars count)
| polars collect
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 2 │
╰───┴───╯
polars count-null
Counts null values.
Usage:
> polars count-null
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Counts null values
> let s = ([1 1 0 0 3 3 4] | polars into-df);
($s / $s) | polars count-null
╭───┬────────────╮
│ # │ count_null │
├───┼────────────┤
│ 0 │ 2 │
╰───┴────────────╯
polars cumulative
Cumulative calculation for a column or series.
Usage:
> polars cumulative {flags} <type>
Flags:
-h, --help: Display the help message for this command
-r, --reverse: Reverse cumulative calculation
Parameters:
type <string>: rolling operation. Values of min, max, and sum are accepted.
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Cumulative sum for a column
> [[a]; [1] [2] [3] [4] [5]]
| polars into-df
| polars select (polars col a | polars cumulative sum | polars as cum_a)
| polars collect
╭───┬───────╮
│ # │ cum_a │
├───┼───────┤
│ 0 │ 1 │
│ 1 │ 3 │
│ 2 │ 6 │
│ 3 │ 10 │
│ 4 │ 15 │
╰───┴───────╯
Cumulative sum for a series
> [1 2 3 4 5] | polars into-df | polars cumulative sum
╭───┬──────────────────╮
│ # │ 0_cumulative_sum │
├───┼──────────────────┤
│ 0 │ 1 │
│ 1 │ 3 │
│ 2 │ 6 │
│ 3 │ 10 │
│ 4 │ 15 │
╰───┴──────────────────╯
Cumulative sum for a series in reverse order
> [1 2 3 4 5] | polars into-df | polars cumulative sum --reverse
╭───┬──────────────────╮
│ # │ 0_cumulative_sum │
├───┼──────────────────┤
│ 0 │ 15 │
│ 1 │ 14 │
│ 2 │ 12 │
│ 3 │ 9 │
│ 4 │ 5 │
╰───┴──────────────────╯
polars cut
Bin continuous values into discrete categories for a series.
Usage:
> polars cut {flags} <breaks>
Flags:
-h, --help: Display the help message for this command
-l, --labels <list<string>>: Names of the categories. The number of labels must be equal to the number of cut points plus one.
-c, --left_closed: Set the intervals to be left-closed instead of right-closed.
-b, --include_breaks: Include a column with the right endpoint of the bin each observation falls in. This will change the data type of the output from a Categorical to a Struct.
Parameters:
breaks <any>: Dataframe that contains a series of unique cut points.
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Divide the column into three categories.
> [-2, -1, 0, 1, 2] | polars into-df | polars cut [-1, 1] --labels ["a", "b", "c"]
polars datepart
Creates an expression for capturing the specified datepart in a column.
Search terms: year, month, week, weekday, quarter, day, hour, minute, second, millisecond, microsecond, nanosecond
Usage:
> polars datepart <Datepart name>
Flags:
-h, --help: Display the help message for this command
Parameters:
Datepart name <string>: Part of the date to capture. Possible values are year, quarter, month, week, weekday, day, hour, minute, second, millisecond, microsecond, nanosecond
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Creates an expression to capture the year date part
> [["2021-12-30T01:02:03.123456789"]] | polars into-df | polars as-datetime "%Y-%m-%dT%H:%M:%S.%9f" --naive | polars with-column [(polars col datetime | polars datepart year | polars as datetime_year )]
╭───┬─────────────┬───────────────╮
│ # │ datetime │ datetime_year │
├───┼─────────────┼───────────────┤
│ 0 │ 3 years ago │ 2021 │
╰───┴─────────────┴───────────────╯
Creates an expression to capture multiple date parts
> [["2021-12-30T01:02:03.123456789"]] | polars into-df | polars as-datetime "%Y-%m-%dT%H:%M:%S.%9f" --naive |
polars with-column [ (polars col datetime | polars datepart year | polars as datetime_year ),
(polars col datetime | polars datepart month | polars as datetime_month ),
(polars col datetime | polars datepart day | polars as datetime_day ),
(polars col datetime | polars datepart hour | polars as datetime_hour ),
(polars col datetime | polars datepart minute | polars as datetime_minute ),
(polars col datetime | polars datepart second | polars as datetime_second ),
(polars col datetime | polars datepart nanosecond | polars as datetime_ns ) ]
╭────┬──────────────┬────────────────┬─────────────────┬───────────────┬────────────────┬──────────────────┬──────────────────┬─────────────╮
│ # │ datetime │ datetime_year │ datetime_month │ datetime_day │ datetime_hour │ datetime_minute │ datetime_second │ datetime_ns │
├────┼──────────────┼────────────────┼─────────────────┼───────────────┼────────────────┼──────────────────┼──────────────────┼─────────────┤
│ 0 │ 3 years ago │ 2021 │ 12 │ 30 │ 1 │ 2 │ 3 │ 123456789 │
╰────┴──────────────┴────────────────┴─────────────────┴───────────────┴────────────────┴──────────────────┴──────────────────┴─────────────╯
polars drop
Creates a new dataframe by dropping the selected columns.
Usage:
> polars drop ...(rest)
Flags:
-h, --help: Display the help message for this command
Parameters:
...rest <any>: column names to be dropped
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
drop column a
> [[a b]; [1 2] [3 4]] | polars into-df | polars drop a
╭───┬───╮
│ # │ b │
├───┼───┤
│ 0 │ 2 │
│ 1 │ 4 │
╰───┴───╯
polars drop-duplicates
Drops duplicate values in dataframe.
Usage:
> polars drop-duplicates {flags} (subset)
Flags:
-h, --help: Display the help message for this command
-m, --maintain: maintain order
-l, --last: keeps last duplicate value (by default keeps first)
Parameters:
subset <table>: subset of columns to drop duplicates (optional)
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
drop duplicates
> [[a b]; [1 2] [3 4] [1 2]] | polars into-df
| polars drop-duplicates
| polars sort-by a
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
polars drop-nulls
Drops null values in dataframe.
Usage:
> polars drop-nulls (subset)
Flags:
-h, --help: Display the help message for this command
Parameters:
subset <table>: subset of columns to drop nulls (optional)
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
drop null values in dataframe
> let df = ([[a b]; [1 2] [3 0] [1 2]] | polars into-df);
let res = ($df.b / $df.b);
let a = ($df | polars with-column $res --name res);
$a | polars drop-nulls
╭───┬───┬───┬─────╮
│ # │ a │ b │ res │
├───┼───┼───┼─────┤
│ 0 │ 1 │ 2 │ 1 │
│ 1 │ 1 │ 2 │ 1 │
╰───┴───┴───┴─────╯
drop null values in dataframe
> let s = ([1 2 0 0 3 4] | polars into-df);
($s / $s) | polars drop-nulls
╭───┬─────────╮
│ # │ div_0_0 │
├───┼─────────┤
│ 0 │ 1 │
│ 1 │ 1 │
│ 2 │ 1 │
│ 3 │ 1 │
╰───┴─────────╯
polars dummies
Creates a new dataframe with dummy variables.
Usage:
> polars dummies {flags}
Flags:
-h, --help: Display the help message for this command
-d, --drop-first: Drop first row
-n, --drop-nulls: Drop nulls
-s, --separator: Optional separator
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Create new dataframe with dummy variables from a dataframe
> [[a b]; [1 2] [3 4]] | polars into-df | polars dummies
╭───┬─────┬─────┬─────┬─────╮
│ # │ a_1 │ a_3 │ b_2 │ b_4 │
├───┼─────┼─────┼─────┼─────┤
│ 0 │ 1 │ 0 │ 1 │ 0 │
│ 1 │ 0 │ 1 │ 0 │ 1 │
╰───┴─────┴─────┴─────┴─────╯
Create new dataframe with dummy variables from a series
> [1 2 2 3 3] | polars into-df | polars dummies
╭───┬─────┬─────┬─────╮
│ # │ 0_1 │ 0_2 │ 0_3 │
├───┼─────┼─────┼─────┤
│ 0 │ 1 │ 0 │ 0 │
│ 1 │ 0 │ 1 │ 0 │
│ 2 │ 0 │ 1 │ 0 │
│ 3 │ 0 │ 0 │ 1 │
│ 4 │ 0 │ 0 │ 1 │
╰───┴─────┴─────┴─────╯
polars explode
Explodes a dataframe or creates a explode expression.
Usage:
> polars explode ...(columns)
Flags:
-h, --help: Display the help message for this command
Parameters:
...columns <string>: columns to explode, only applicable for dataframes
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Explode the specified dataframe
> [[id name hobbies]; [1 Mercy [Cycling Knitting]] [2 Bob [Skiing Football]]]
| polars into-df
| polars explode hobbies
| polars collect
| polars sort-by [id, name]
╭───┬────┬───────┬──────────╮
│ # │ id │ name │ hobbies │
├───┼────┼───────┼──────────┤
│ 0 │ 1 │ Mercy │ Cycling │
│ 1 │ 1 │ Mercy │ Knitting │
│ 2 │ 2 │ Bob │ Skiing │
│ 3 │ 2 │ Bob │ Football │
╰───┴────┴───────┴──────────╯
Select a column and explode the values
> [[id name hobbies]; [1 Mercy [Cycling Knitting]] [2 Bob [Skiing Football]]] | polars into-df | polars select (polars col hobbies | polars explode)
╭───┬──────────╮
│ # │ hobbies │
├───┼──────────┤
│ 0 │ Cycling │
│ 1 │ Knitting │
│ 2 │ Skiing │
│ 3 │ Football │
╰───┴──────────╯
polars expr-not
Creates a not expression.
Usage:
> polars expr-not
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Creates a not expression
> (polars col a) > 2) | polars expr-not
Adds a column showing which values of col a are not greater than 2
> [[a]; [1] [2] [3] [4] [5]] | polars into-df
| polars with-column [(((polars col a) > 2)
| polars expr-not
| polars as a_expr_not)]
| polars collect
| polars sort-by a
╭───┬───┬───────╮
│ # │ a │ b │
├───┼───┼───────┤
│ 0 │ 1 │ true │
│ 1 │ 2 │ true │
│ 2 │ 3 │ false │
│ 3 │ 4 │ false │
│ 4 │ 5 │ false │
╰───┴───┴───────╯
polars fill-nan
Replaces NaN values with the given expression.
Usage:
> polars fill-nan <fill>
Flags:
-h, --help: Display the help message for this command
Parameters:
fill <any>: Expression to use to fill the NAN values
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Fills the NaN values with 0
> [1 2 NaN 3 NaN] | polars into-df | polars fill-nan 0
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 0 │
│ 3 │ 3 │
│ 4 │ 0 │
╰───┴───╯
Fills the NaN values of a whole dataframe
> [[a b]; [0.2 1] [0.1 NaN]] | polars into-df | polars fill-nan 0
╭───┬──────┬───╮
│ # │ a │ b │
├───┼──────┼───┤
│ 0 │ 0.20 │ 1 │
│ 1 │ 0.10 │ 0 │
╰───┴──────┴───╯
polars fill-null
Replaces NULL values with the given expression.
Usage:
> polars fill-null <fill>
Flags:
-h, --help: Display the help message for this command
Parameters:
fill <any>: Expression to use to fill the null values
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Fills the null values by 0
> [1 2 2 3 3] | polars into-df | polars shift 2 | polars fill-null 0
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 0 │
│ 1 │ 0 │
│ 2 │ 1 │
│ 3 │ 2 │
│ 4 │ 2 │
╰───┴───╯
Fills the null values in expression
> [[a]; [1] [2] [2] [3] [3]]
| polars into-df
| polars select (polars col a | polars shift 2 | polars fill-null 0)
| polars collect
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 0 │
│ 1 │ 0 │
│ 2 │ 1 │
│ 3 │ 2 │
│ 4 │ 2 │
╰───┴───╯
polars filter
Filter dataframe based in expression.
Usage:
> polars filter <filter expression>
Flags:
-h, --help: Display the help message for this command
Parameters:
filter expression <any>: Expression that define the column selection
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Filter dataframe using an expression
> [[a b]; [6 2] [4 2] [2 2]] | polars into-df | polars filter ((polars col a) >= 4)
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 6 │ 2 │
│ 1 │ 4 │ 2 │
╰───┴───┴───╯
Filter dataframe for rows where dt is within the last 2 days of the maximum dt value
> [[dt val]; [2025-04-01 1] [2025-04-02 2] [2025-04-03 3] [2025-04-04 4]] | polars into-df | polars filter ((polars col dt) > ((polars col dt | polars max | $in - 2day)))
╭───┬──────────────┬─────╮
│ # │ dt │ val │
├───┼──────────────┼─────┤
│ 0 │ 8 months ago │ 3 │
│ 1 │ 8 months ago │ 4 │
╰───┴──────────────┴─────╯
Filter a single column in a group-by context
> [[a b]; [foo 1] [foo 2] [foo 3] [bar 2] [bar 3] [bar 4]] | polars into-df
| polars group-by a --maintain-order
| polars agg {
lt: (polars col b | polars filter ((polars col b) < 2) | polars sum)
gte: (polars col b | polars filter ((polars col b) >= 3) | polars sum)
}
| polars collect
╭───┬─────┬────┬─────╮
│ # │ a │ lt │ gte │
├───┼─────┼────┼─────┤
│ 0 │ foo │ 1 │ 3 │
│ 1 │ bar │ 0 │ 7 │
╰───┴─────┴────┴─────╯
polars filter-with
Filters dataframe using a mask or expression as reference.
Usage:
> polars filter-with <mask or expression>
Flags:
-h, --help: Display the help message for this command
Parameters:
mask or expression <any>: boolean mask used to filter data
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Filter dataframe using a bool mask
> let mask = ([true false] | polars into-df);
[[a b]; [1 2] [3 4]] | polars into-df | polars filter-with $mask
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
╰───┴───┴───╯
Filter dataframe using an expression
> [[a b]; [1 2] [3 4]] | polars into-df | polars filter-with ((polars col a) > 1)
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 3 │ 4 │
╰───┴───┴───╯
polars flatten
An alias for polars explode.
Usage:
> polars flatten ...(columns)
Flags:
-h, --help: Display the help message for this command
Parameters:
...columns <string>: columns to flatten, only applicable for dataframes
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Flatten the specified dataframe
> [[id name hobbies]; [1 Mercy [Cycling Knitting]] [2 Bob [Skiing Football]]] | polars into-df | polars flatten hobbies | polars collect
╭───┬────┬───────┬──────────╮
│ # │ id │ name │ hobbies │
├───┼────┼───────┼──────────┤
│ 0 │ 1 │ Mercy │ Cycling │
│ 1 │ 1 │ Mercy │ Knitting │
│ 2 │ 2 │ Bob │ Skiing │
│ 3 │ 2 │ Bob │ Football │
╰───┴────┴───────┴──────────╯
Select a column and flatten the values
> [[id name hobbies]; [1 Mercy [Cycling Knitting]] [2 Bob [Skiing Football]]] | polars into-df | polars select (polars col hobbies | polars flatten)
╭───┬──────────╮
│ # │ hobbies │
├───┼──────────┤
│ 0 │ Cycling │
│ 1 │ Knitting │
│ 2 │ Skiing │
│ 3 │ Football │
╰───┴──────────╯
polars get
Creates dataframe with the selected columns.
Usage:
> polars get ...(rest)
Flags:
-h, --help: Display the help message for this command
Parameters:
...rest <any>: column names to sort dataframe
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Returns the selected column
> [[a b]; [1 2] [3 4]] | polars into-df | polars get a
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 1 │
│ 1 │ 3 │
╰───┴───╯
polars get-day
Gets day from date.
Usage:
> polars get-day
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns day from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-day
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 4 │
│ 1 │ 4 │
╰───┴───╯
Returns day from a date in an expression
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-day)
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 4 │
│ 1 │ 4 │
╰───┴───╯
polars get-hour
Gets hour from datetime.
Usage:
> polars get-hour
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns hour from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-hour
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ 16 │
│ 1 │ 16 │
╰───┴────╯
Returns hour from a date in a lazyframe
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-lazy);
$df | polars get-hour
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ 16 │
│ 1 │ 16 │
╰───┴────╯
Returns hour from a date in an expression
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-hour)
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ 16 │
│ 1 │ 16 │
╰───┴────╯
polars get-minute
Gets minute from date.
Usage:
> polars get-minute
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns minute from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-minute
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ 39 │
│ 1 │ 39 │
╰───┴────╯
Returns minute from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-minute)
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ 39 │
│ 1 │ 39 │
╰───┴────╯
polars get-month
Gets month from date.
Usage:
> polars get-month
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns month from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-month
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 8 │
│ 1 │ 8 │
╰───┴───╯
Returns month from a date in an expression
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-month)
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 8 │
│ 1 │ 8 │
╰───┴───╯
polars get-nanosecond
Gets nanosecond from date.
Usage:
> polars get-nanosecond
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns nanosecond from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-nanosecond
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 0 │
│ 1 │ 0 │
╰───┴───╯
Returns nanosecond from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-nanosecond)
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 0 │
│ 1 │ 0 │
╰───┴───╯
polars get-ordinal
Gets ordinal from date.
Usage:
> polars get-ordinal
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns ordinal from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-ordinal
╭───┬─────╮
│ # │ 0 │
├───┼─────┤
│ 0 │ 217 │
│ 1 │ 217 │
╰───┴─────╯
Returns ordinal from a date in an expression
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-ordinal)
╭───┬─────╮
│ # │ 0 │
├───┼─────┤
│ 0 │ 217 │
│ 1 │ 217 │
╰───┴─────╯
polars get-second
Gets second from date.
Usage:
> polars get-second
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns second from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-second
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ 18 │
│ 1 │ 18 │
╰───┴────╯
Returns second from a date in an expression
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-second)
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ 18 │
│ 1 │ 18 │
╰───┴────╯
polars get-week
Gets week from date.
Usage:
> polars get-week
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns week from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-week
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ 32 │
│ 1 │ 32 │
╰───┴────╯
Returns week from a date in an expression
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-week)
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ 32 │
│ 1 │ 32 │
╰───┴────╯
polars get-weekday
Gets weekday from date.
Usage:
> polars get-weekday
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns weekday from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-weekday
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 2 │
│ 1 │ 2 │
╰───┴───╯
Returns weekday from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-weekday)
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 2 │
│ 1 │ 2 │
╰───┴───╯
polars get-year
Gets year from date.
Usage:
> polars get-year
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns year from a date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars get-year
╭───┬──────╮
│ # │ 0 │
├───┼──────┤
│ 0 │ 2020 │
│ 1 │ 2020 │
╰───┴──────╯
Returns year from a date in an expression
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars select (polars col 0 | polars get-year)
╭───┬──────╮
│ # │ 0 │
├───┼──────┤
│ 0 │ 2020 │
│ 1 │ 2020 │
╰───┴──────╯
polars group-by
Creates a group-by object that can be used for other aggregations.
Usage:
> polars group-by {flags} ...(Group-by expressions)
Flags:
-h, --help: Display the help message for this command
-m, --maintain-order: Ensure that the order of the groups is consistent with the input data. This is slower than a default group by and cannot be run on the streaming engine.
Parameters:
...Group-by expressions <any>: Expression(s) that define the lazy group-by
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Group by and perform an aggregation
> [[a b]; [1 2] [1 4] [2 6] [2 4]]
| polars into-lazy
| polars group-by a
| polars agg [
(polars col b | polars min | polars as "b_min")
(polars col b | polars max | polars as "b_max")
(polars col b | polars sum | polars as "b_sum")
]
| polars collect
| polars sort-by a
╭───┬───┬───────┬───────┬───────╮
│ # │ a │ b_min │ b_max │ b_sum │
├───┼───┼───────┼───────┼───────┤
│ 0 │ 1 │ 2 │ 4 │ 6 │
│ 1 │ 2 │ 4 │ 6 │ 10 │
╰───┴───┴───────┴───────┴───────╯
Group by an expression and perform an aggregation
> [[a b]; [2025-04-01 1] [2025-04-02 2] [2025-04-03 3] [2025-04-04 4]]
| polars into-lazy
| polars group-by (polars col a | polars get-day | $in mod 2)
| polars agg [
(polars col b | polars min | polars as "b_min")
(polars col b | polars max | polars as "b_max")
(polars col b | polars sum | polars as "b_sum")
]
| polars collect
| polars sort-by a
╭───┬───┬───────┬───────┬───────╮
│ # │ a │ b_min │ b_max │ b_sum │
├───┼───┼───────┼───────┼───────┤
│ 0 │ 0 │ 2 │ 4 │ 6 │
│ 1 │ 1 │ 1 │ 3 │ 4 │
╰───┴───┴───────┴───────┴───────╯
polars horizontal
Horizontal calculation across multiple columns.
Usage:
> polars horizontal {flags} <type> ...(Group-by expressions)
Flags:
-h, --help: Display the help message for this command
-n, --nulls: If set, null value in the input will lead to null output
Parameters:
type <string>: horizontal operation. Values of all, any, min, max, sum, and mean are accepted.
...Group-by expressions <any>: Expression(s) that define the lazy group-by
Input/output types:
╭───┬───────┬───────────────────╮
│ # │ input │ output │
├───┼───────┼───────────────────┤
│ 0 │ any │ polars_expression │
╰───┴───────┴───────────────────╯
Examples:
Horizontal sum across two columns (ignore nulls by default)
> [[a b]; [1 2] [2 3] [3 4] [4 5] [5 null]]
| polars into-df
| polars select (polars horizontal sum a b)
| polars collect
╭───┬─────╮
│ # │ sum │
├───┼─────┤
│ 0 │ 3 │
│ 1 │ 5 │
│ 2 │ 7 │
│ 3 │ 9 │
│ 4 │ 5 │
╰───┴─────╯
Horizontal sum across two columns while accounting for nulls
> [[a b]; [1 2] [2 3] [3 4] [4 5] [5 null]]
| polars into-df
| polars select (polars horizontal sum a b --nulls)
| polars collect
╭───┬─────╮
│ # │ sum │
├───┼─────┤
│ 0 │ 3 │
│ 1 │ 5 │
│ 2 │ 7 │
│ 3 │ 9 │
│ 4 │ │
╰───┴─────╯
polars implode
Aggregates values into a list.
Usage:
> polars implode
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Create two lists for columns a and b with all the rows as values.
> [[a b]; [1 4] [2 5] [3 6]] | polars into-df | polars select (polars col '*' | polars implode) | polars collect
╭───┬───────────┬───────────╮
│ # │ a │ b │
├───┼───────────┼───────────┤
│ 0 │ ╭───┬───╮ │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │ │ 0 │ 4 │ │
│ │ │ 1 │ 2 │ │ │ 1 │ 5 │ │
│ │ │ 2 │ 3 │ │ │ 2 │ 6 │ │
│ │ ╰───┴───╯ │ ╰───┴───╯ │
╰───┴───────────┴───────────╯
polars into-df
Converts a list, table or record into a dataframe.
Usage:
> polars into-df {flags}
Flags:
-h, --help: Display the help message for this command
-s, --schema <any>: Polars Schema in format [{name: str}].
-c, --as-columns: When input shape is record of lists, treat each list as column values.
Input/output types:
╭───┬───────┬──────────────────╮
│ # │ input │ output │
├───┼───────┼──────────────────┤
│ 0 │ any │ polars_dataframe │
╰───┴───────┴──────────────────╯
Examples:
Takes a dictionary and creates a dataframe
> [[a b];[1 2] [3 4]] | polars into-df
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Takes a record of lists and creates a dataframe
> {a: [1 3], b: [2 4]} | polars into-df --as-columns
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Takes a list of tables and creates a dataframe
> [[1 2 a] [3 4 b] [5 6 c]] | polars into-df
╭───┬───┬───┬───╮
│ # │ 0 │ 1 │ 2 │
├───┼───┼───┼───┤
│ 0 │ 1 │ 2 │ a │
│ 1 │ 3 │ 4 │ b │
│ 2 │ 5 │ 6 │ c │
╰───┴───┴───┴───╯
Takes a list and creates a dataframe
> [a b c] | polars into-df
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ a │
│ 1 │ b │
│ 2 │ c │
╰───┴───╯
Takes a list of booleans and creates a dataframe
> [true true false] | polars into-df
╭───┬───────╮
│ # │ 0 │
├───┼───────┤
│ 0 │ true │
│ 1 │ true │
│ 2 │ false │
╰───┴───────╯
Convert to a dataframe and provide a schema
> [[a b c e]; [1 {d: [1 2 3]} [10 11 12] 1.618]]| polars into-df -s {a: u8, b: {d: list<u64>}, c: list<u8>, e: 'decimal<4,3>'}
╭───┬───┬───────────────────┬────────────┬──────╮
│ # │ a │ b │ c │ e │
├───┼───┼───────────────────┼────────────┼──────┤
│ 0 │ 1 │ ╭───┬───────────╮ │ ╭───┬────╮ │ 1.62 │
│ │ │ │ │ ╭───┬───╮ │ │ │ 0 │ 10 │ │ │
│ │ │ │ d │ │ 0 │ 1 │ │ │ │ 1 │ 11 │ │ │
│ │ │ │ │ │ 1 │ 2 │ │ │ │ 2 │ 12 │ │ │
│ │ │ │ │ │ 2 │ 3 │ │ │ ╰───┴────╯ │ │
│ │ │ │ │ ╰───┴───╯ │ │ │ │
│ │ │ ╰───┴───────────╯ │ │ │
╰───┴───┴───────────────────┴────────────┴──────╯
Convert to a dataframe and provide a schema that adds a new column
> [[a b]; [1 "foo"] [2 "bar"]] | polars into-df -s {a: u8, b:str, c:i64} | polars fill-null 3
╭───┬───┬─────┬───╮
│ # │ a │ b │ c │
├───┼───┼─────┼───┤
│ 0 │ 1 │ foo │ 3 │
│ 1 │ 2 │ bar │ 3 │
╰───┴───┴─────┴───╯
If a provided schema specifies a subset of columns, only those columns are selected
> [[a b]; [1 "foo"] [2 "bar"]] | polars into-df -s {a: str}
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 1 │
│ 1 │ 2 │
╰───┴───╯
Use a predefined schama
> let schema = {a: str, b: str}; [[a b]; [1 "foo"] [2 "bar"]] | polars into-df -s $schema
╭───┬───┬─────╮
│ # │ a │ b │
├───┼───┼─────┤
│ 0 │ 1 │ foo │
│ 1 │ 2 │ bar │
╰───┴───┴─────╯
polars into-dtype
Convert a string to a specific datatype.
Usage:
> polars into-dtype
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬────────┬──────────────────╮
│ # │ input │ output │
├───┼────────┼──────────────────┤
│ 0 │ string │ polars_dataframe │
╰───┴────────┴──────────────────╯
Examples:
Convert a string to a specific datatype and back to a nu object
> 'i64' | polars into-dtype | polars into-nu
i64
polars into-lazy
Converts a dataframe into a lazy dataframe.
Usage:
> polars into-lazy {flags}
Flags:
-h, --help: Display the help message for this command
-s, --schema <any>: Polars Schema in format [{name: str}].
Input/output types:
╭───┬───────┬──────────────────╮
│ # │ input │ output │
├───┼───────┼──────────────────┤
│ 0 │ any │ polars_lazyframe │
╰───┴───────┴──────────────────╯
Examples:
Takes a table and creates a lazyframe
> [[a b];[1 2] [3 4]] | polars into-lazy
Takes a table, creates a lazyframe, assigns column 'b' type str, displays the schema
> [[a b];[1 2] [3 4]] | polars into-lazy --schema {b: str} | polars schema
╭───┬─────╮
│ b │ str │
╰───┴─────╯
Use a predefined schama
> let schema = {a: str, b: str}; [[a b]; [1 "foo"] [2 "bar"]] | polars into-lazy -s $schema
╭───┬───┬─────╮
│ # │ a │ b │
├───┼───┼─────┤
│ 0 │ 1 │ foo │
│ 1 │ 2 │ bar │
╰───┴───┴─────╯
polars into-nu
Converts a dataframe or an expression into nushell value for access and exploration.
Usage:
> polars into-nu {flags}
Flags:
-h, --help: Display the help message for this command
-n, --rows <number>: number of rows to be shown
-t, --tail: shows tail rows
-i, --index: add an index column
Input/output types:
╭───┬───────────────────┬────────╮
│ # │ input │ output │
├───┼───────────────────┼────────┤
│ 0 │ polars_dataframe │ table │
│ 1 │ polars_lazyframe │ table │
│ 2 │ polars_expression │ any │
│ 3 │ polars_group_by │ any │
│ 4 │ polars_when │ any │
│ 5 │ polars_datatype │ any │
│ 6 │ polars_schema │ any │
╰───┴───────────────────┴────────╯
Examples:
Shows head rows from dataframe
> [[a b]; [1 2] [3 4]] | polars into-df | polars into-nu --index
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Shows tail rows from dataframe
> [[a b]; [1 2] [5 6] [3 4]] | polars into-df | polars into-nu --tail --rows 1 --index
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 2 │ 3 │ 4 │
╰───┴───┴───╯
Convert a col expression into a nushell value
> polars col a | polars into-nu --index
╭───────┬────────╮
│ expr │ column │
│ value │ a │
╰───────┴────────╯
polars into-repr
Display a dataframe in its repr format.
Usage:
> polars into-repr
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬────────╮
│ # │ input │ output │
├───┼──────────────────┼────────┤
│ 0 │ polars_dataframe │ string │
│ 1 │ polars_lazyframe │ string │
╰───┴──────────────────┴────────╯
Examples:
Shows dataframe in repr format
> [[a b]; [2025-01-01 2] [2025-01-02 4]] | polars into-df | polars into-repr
shape: (2, 2)
┌─────────────────────────┬─────┐
│ a ┆ b │
│ --- ┆ --- │
│ datetime[ns, UTC] ┆ i64 │
╞═════════════════════════╪═════╡
│ 2025-01-01 00:00:00 UTC ┆ 2 │
│ 2025-01-02 00:00:00 UTC ┆ 4 │
└─────────────────────────┴─────┘
Shows lazy dataframe in repr format
> [[a b]; [2025-01-01 2] [2025-01-02 4]] | polars into-lazy | polars into-repr
shape: (2, 2)
┌─────────────────────────┬─────┐
│ a ┆ b │
│ --- ┆ --- │
│ datetime[ns, UTC] ┆ i64 │
╞═════════════════════════╪═════╡
│ 2025-01-01 00:00:00 UTC ┆ 2 │
│ 2025-01-02 00:00:00 UTC ┆ 4 │
└─────────────────────────┴─────┘
polars is-duplicated
Creates mask indicating duplicated values.
Usage:
> polars is-duplicated
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Create mask indicating duplicated values
> [5 6 6 6 8 8 8] | polars into-df | polars is-duplicated
╭───┬───────────────╮
│ # │ is_duplicated │
├───┼───────────────┤
│ 0 │ false │
│ 1 │ true │
│ 2 │ true │
│ 3 │ true │
│ 4 │ true │
│ 5 │ true │
│ 6 │ true │
╰───┴───────────────╯
Create mask indicating duplicated rows in a dataframe
> [[a, b]; [1 2] [1 2] [3 3] [3 3] [1 1]] | polars into-df | polars is-duplicated
╭───┬───────────────╮
│ # │ is_duplicated │
├───┼───────────────┤
│ 0 │ true │
│ 1 │ true │
│ 2 │ true │
│ 3 │ true │
│ 4 │ false │
╰───┴───────────────╯
polars is-not-null
Creates mask where value is not null.
Usage:
> polars is-not-null
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Create mask where values are not null
> let s = ([5 6 0 8] | polars into-df);
let res = ($s / $s);
$res | polars is-not-null
╭───┬─────────────╮
│ # │ is_not_null │
├───┼─────────────┤
│ 0 │ true │
│ 1 │ true │
│ 2 │ false │
│ 3 │ true │
╰───┴─────────────╯
Creates a is not null expression from a column
> polars col a | polars is-not-null
polars is-null
Creates mask where value is null.
Usage:
> polars is-null
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Create mask where values are null
> let s = ([5 6 0 8] | polars into-df);
let res = ($s / $s);
$res | polars is-null
╭───┬─────────╮
│ # │ is_null │
├───┼─────────┤
│ 0 │ false │
│ 1 │ false │
│ 2 │ true │
│ 3 │ false │
╰───┴─────────╯
Creates a is null expression from a column
> polars col a | polars is-null
polars is-unique
Creates mask indicating unique values.
Usage:
> polars is-unique
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Create mask indicating unique values
> [5 6 6 6 8 8 8] | polars into-df | polars is-unique
╭───┬───────────╮
│ # │ is_unique │
├───┼───────────┤
│ 0 │ true │
│ 1 │ false │
│ 2 │ false │
│ 3 │ false │
│ 4 │ false │
│ 5 │ false │
│ 6 │ false │
╰───┴───────────╯
Create mask indicating duplicated rows in a dataframe
> [[a, b]; [1 2] [1 2] [3 3] [3 3] [1 1]] | polars into-df | polars is-unique
╭───┬───────────╮
│ # │ is_unique │
├───┼───────────┤
│ 0 │ false │
│ 1 │ false │
│ 2 │ false │
│ 3 │ false │
│ 4 │ true │
╰───┴───────────╯
polars join
Joins a lazy frame with other lazy frame.
Usage:
> polars join {flags} <other> (left_on) (right_on)
Flags:
-h, --help: Display the help message for this command
-i, --inner: inner joining between lazyframes (default)
-l, --left: left join between lazyframes
-f, --full: full join between lazyframes
-c, --cross: cross join between lazyframes
--coalesce-columns: Sets the join coalesce strategy to colesce columns. Most useful when used with --full, which will not otherwise coalesce.
-s, --suffix <string>: Suffix to use on columns with same name
Parameters:
other <any>: LazyFrame to join with
left_on <any>: Left column(s) to join on (optional)
right_on <any>: Right column(s) to join on (optional)
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Join two lazy dataframes
> let df_a = ([[a b c];[1 "a" 0] [2 "b" 1] [1 "c" 2] [1 "c" 3]] | polars into-lazy)
let df_b = ([["foo" "bar" "ham"];[1 "a" "let"] [2 "c" "var"] [3 "c" "const"]] | polars into-lazy)
$df_a | polars join $df_b a foo | polars collect
╭───┬───┬───┬───┬─────┬─────╮
│ # │ a │ b │ c │ bar │ ham │
├───┼───┼───┼───┼─────┼─────┤
│ 0 │ 1 │ a │ 0 │ a │ let │
│ 1 │ 2 │ b │ 1 │ c │ var │
│ 2 │ 1 │ c │ 2 │ a │ let │
│ 3 │ 1 │ c │ 3 │ a │ let │
╰───┴───┴───┴───┴─────┴─────╯
Join one eager dataframe with a lazy dataframe
> let df_a = ([[a b c];[1 "a" 0] [2 "b" 1] [1 "c" 2] [1 "c" 3]] | polars into-df)
let df_b = ([["foo" "bar" "ham"];[1 "a" "let"] [2 "c" "var"] [3 "c" "const"]] | polars into-lazy)
$df_a | polars join $df_b a foo
╭───┬───┬───┬───┬─────┬─────╮
│ # │ a │ b │ c │ bar │ ham │
├───┼───┼───┼───┼─────┼─────┤
│ 0 │ 1 │ a │ 0 │ a │ let │
│ 1 │ 2 │ b │ 1 │ c │ var │
│ 2 │ 1 │ c │ 2 │ a │ let │
│ 3 │ 1 │ c │ 3 │ a │ let │
╰───┴───┴───┴───┴─────┴─────╯
Perform a full join of two dataframes and coalesce columns
> let table1 = [[A B]; ["common" "common"] ["table1" "only"]] | polars into-df
let table2 = [[A C]; ["common" "common"] ["table2" "only"]] | polars into-df
$table1 | polars join -f $table2 --coalesce-columns A A
╭───┬────────┬────────┬────────╮
│ # │ A │ B │ C │
├───┼────────┼────────┼────────┤
│ 0 │ common │ common │ common │
│ 1 │ table2 │ │ only │
│ 2 │ table1 │ only │ │
╰───┴────────┴────────┴────────╯
Join one eager dataframe with another using a cross join
> let tokens = [[monopoly_token]; [hat] [shoe] [boat]] | polars into-df
let players = [[name, cash]; [Alice, 78] [Bob, 135]] | polars into-df
$players | polars select (polars col name) | polars join --cross $tokens | polars collect
╭───┬───────┬────────────────╮
│ # │ name │ monopoly_token │
├───┼───────┼────────────────┤
│ 0 │ Alice │ hat │
│ 1 │ Alice │ shoe │
│ 2 │ Alice │ boat │
│ 3 │ Bob │ hat │
│ 4 │ Bob │ shoe │
│ 5 │ Bob │ boat │
╰───┴───────┴────────────────╯
polars join-where
Joins a lazy frame with other lazy frame based on conditions.
Usage:
> polars join-where <other> <condition>
Flags:
-h, --help: Display the help message for this command
Parameters:
other <any>: LazyFrame to join with
condition <any>: Condition
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Join two lazy dataframes with a condition
> let df_a = ([[name cash];[Alice 5] [Bob 10]] | polars into-lazy)
let df_b = ([[item price];[A 3] [B 7] [C 12]] | polars into-lazy)
$df_a | polars join-where $df_b ((polars col cash) > (polars col price)) | polars collect
╭───┬───────┬──────┬──────┬───────╮
│ # │ name │ cash │ item │ price │
├───┼───────┼──────┼──────┼───────┤
│ 0 │ Bob │ 10 │ B │ 7 │
│ 1 │ Bob │ 10 │ A │ 3 │
│ 2 │ Alice │ 5 │ A │ 3 │
╰───┴───────┴──────┴──────┴───────╯
polars last
Creates new dataframe with tail rows or creates a last expression.
Usage:
> polars last (rows)
Flags:
-h, --help: Display the help message for this command
Parameters:
rows <int>: Number of rows for tail (optional)
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Create new dataframe with last rows
> [[a b]; [1 2] [3 4]] | polars into-df | polars last 1
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 3 │ 4 │
╰───┴───┴───╯
Creates a last expression from a column
> polars col a | polars last
Aggregate the last values in the group.
> [[a b c d]; [1 0.5 true Apple] [2 0.5 true Orange] [2 4 true Apple] [3 10 false Apple] [4 13 false Banana] [5 14 true Banana]] | polars into-df -s {a: u8, b: f32, c: bool, d: str} | polars group-by d | polars last | polars sort-by [a] | polars collect
╭───┬────────┬───┬───────┬───────╮
│ # │ d │ a │ b │ c │
├───┼────────┼───┼───────┼───────┤
│ 0 │ Orange │ 2 │ 0.50 │ true │
│ 1 │ Apple │ 3 │ 10.00 │ false │
│ 2 │ Banana │ 5 │ 14.00 │ true │
╰───┴────────┴───┴───────┴───────╯
polars len
Return the number of rows in the context. This is similar to COUNT(*) in SQL.
Usage:
> polars len
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────┬───────────────────╮
│ # │ input │ output │
├───┼───────┼───────────────────┤
│ 0 │ any │ polars_expression │
╰───┴───────┴───────────────────╯
Examples:
Count the number of rows in the the dataframe.
> [[a b]; [1 2] [3 4]] | polars into-df | polars select (polars len) | polars collect
╭───┬─────╮
│ # │ len │
├───┼─────┤
│ 0 │ 2 │
╰───┴─────╯
Creates a last expression from a column
> polars col a | polars last
polars list-contains
Checks if an element is contained in a list.
Usage:
> polars list-contains <element>
Flags:
-h, --help: Display the help message for this command
Parameters:
element <any>: Element to search for in the list
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns boolean indicating if a literal element was found in a list column
> let df = [[a]; [[a,b,c]] [[b,c,d]] [[c,d,f]]] | polars into-df -s {a: list<str>};
let df2 = $df | polars with-column [(polars col a | polars list-contains (polars lit a) | polars as b)] | polars collect;
$df2.b
╭───┬───────╮
│ # │ b │
├───┼───────┤
│ 0 │ true │
│ 1 │ false │
│ 2 │ false │
╰───┴───────╯
Returns boolean indicating if an element from another column was found in a list column
> let df = [[a, b]; [[a,b,c], a] [[b,c,d], f] [[c,d,f], f]] | polars into-df -s {a: list<str>, b: str};
let df2 = $df | polars with-column [(polars col a | polars list-contains b | polars as c)] | polars collect;
$df2.c
╭───┬───────╮
│ # │ b │
├───┼───────┤
│ 0 │ true │
│ 1 │ false │
│ 2 │ true │
╰───┴───────╯
Returns boolean indicating if an element from another expression was found in a list column
> let df = [[a, b]; [[1,2,3], 4] [[2,4,1], 2] [[2,1,6], 3]] | polars into-df -s {a: list<i64>, b: i64};
let df2 = $df | polars with-column [(polars col a | polars list-contains ((polars col b) * 2) | polars as c)] | polars collect;
$df2.c
╭───┬───────╮
│ # │ b │
├───┼───────┤
│ 0 │ false │
│ 1 │ true │
│ 2 │ true │
╰───┴───────╯
polars lit
Creates a literal expression.
Search terms: string, literal, expression
Usage:
> polars lit <literal>
Flags:
-h, --help: Display the help message for this command
Parameters:
literal <any>: literal to construct the expression
Input/output types:
╭───┬───────┬───────────────────╮
│ # │ input │ output │
├───┼───────┼───────────────────┤
│ 0 │ any │ polars_expression │
╰───┴───────┴───────────────────╯
Examples:
Created a literal expression and converts it to a nu object
> polars lit 2 | polars into-nu
╭───────┬────────────╮
│ expr │ literal │
│ value │ dyn int: 2 │
╰───────┴────────────╯
Create a literal expression from date
> polars lit 2025-04-13 | polars into-nu
╭──────────────┬──────────────────────────────────────────╮
│ │ ╭───────┬──────────────────────────────╮ │
│ expr │ │ expr │ literal │ │
│ │ │ value │ dyn int: 1744502400000000000 │ │
│ │ ╰───────┴──────────────────────────────╯ │
│ dtype │ Datetime('ns') │
│ cast_options │ STRICT │
╰──────────────┴──────────────────────────────────────────╯
Create a literal expression from duration
> polars lit 3hr | polars into-nu
╭──────────────┬─────────────────────────────────────╮
│ │ ╭───────┬─────────────────────────╮ │
│ expr │ │ expr │ literal │ │
│ │ │ value │ dyn int: 10800000000000 │ │
│ │ ╰───────┴─────────────────────────╯ │
│ dtype │ Duration('ns') │
│ cast_options │ STRICT │
╰──────────────┴─────────────────────────────────────╯
polars lowercase
Lowercase the strings in the column.
Usage:
> polars lowercase
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Modifies strings in a column to lowercase
> [[a]; [Abc]] | polars into-df | polars select (polars col a | polars lowercase) | polars collect
╭───┬─────╮
│ # │ a │
├───┼─────┤
│ 0 │ abc │
╰───┴─────╯
Modifies strings to lowercase
> [Abc aBc abC] | polars into-df | polars lowercase
╭───┬─────╮
│ # │ 0 │
├───┼─────┤
│ 0 │ abc │
│ 1 │ abc │
│ 2 │ abc │
╰───┴─────╯
polars max
Creates a max expression or aggregates columns to their max value.
Usage:
> polars max
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Max value from columns in a dataframe
> [[a b]; [6 2] [1 4] [4 1]] | polars into-df | polars max
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 6 │ 4 │
╰───┴───┴───╯
Max aggregation for a group-by
> [[a b]; [one 2] [one 4] [two 1]]
| polars into-df
| polars group-by a
| polars agg (polars col b | polars max)
| polars collect
| polars sort-by a
╭───┬─────┬───╮
│ # │ a │ b │
├───┼─────┼───┤
│ 0 │ one │ 4 │
│ 1 │ two │ 1 │
╰───┴─────┴───╯
polars mean
Creates a mean expression for an aggregation or aggregates columns to their mean value.
Usage:
> polars mean
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Mean value from columns in a dataframe
> [[a b]; [6 2] [4 2] [2 2]] | polars into-df | polars mean
╭───┬──────┬──────╮
│ # │ a │ b │
├───┼──────┼──────┤
│ 0 │ 4.00 │ 2.00 │
╰───┴──────┴──────╯
Mean aggregation for a group-by
> [[a b]; [one 2] [one 4] [two 1]]
| polars into-df
| polars group-by a
| polars agg (polars col b | polars mean)
| polars collect
| polars sort-by a
╭───┬─────┬──────╮
│ # │ a │ b │
├───┼─────┼──────┤
│ 0 │ one │ 3.00 │
│ 1 │ two │ 1.00 │
╰───┴─────┴──────╯
polars min
Creates a min expression or aggregates columns to their min value.
Usage:
> polars min
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Min value from columns in a dataframe
> [[a b]; [6 2] [1 4] [4 1]] | polars into-df | polars min
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 1 │
╰───┴───┴───╯
Min aggregation for a group-by
> [[a b]; [one 2] [one 4] [two 1]]
| polars into-df
| polars group-by a
| polars agg (polars col b | polars min)
| polars collect
| polars sort-by a
╭───┬─────┬───╮
│ # │ a │ b │
├───┼─────┼───┤
│ 0 │ one │ 2 │
│ 1 │ two │ 1 │
╰───┴─────┴───╯
polars n-unique
Counts unique values.
Usage:
> polars n-unique
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Counts unique values
> [1 1 2 2 3 3 4] | polars into-df | polars n-unique
╭───┬──────────────╮
│ # │ count_unique │
├───┼──────────────┤
│ 0 │ 4 │
╰───┴──────────────╯
Creates a is n-unique expression from a column
> polars col a | polars n-unique
polars not
Inverts boolean mask.
Usage:
> polars not
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Inverts boolean mask
> [true false true] | polars into-df | polars not
╭───┬───────╮
│ # │ 0 │
├───┼───────┤
│ 0 │ false │
│ 1 │ true │
│ 2 │ false │
╰───┴───────╯
polars open
Opens CSV, JSON, NDJSON/JSON lines, arrow, avro, or parquet file to create dataframe. A lazy dataframe will be created by default, if supported.
Usage:
> polars open {flags} <file>
Flags:
-h, --help: Display the help message for this command
--eager: Open dataframe as an eager dataframe
-t, --type <string>: File type: csv, tsv, json, parquet, arrow, avro. If omitted, derive from file extension
-d, --delimiter <string>: file delimiter character. CSV file
--no-header: Indicates if file doesn't have header. CSV file
--infer-schema <number>: Number of rows to infer the schema of the file. CSV file
--skip-rows <number>: Number of rows to skip from file. CSV file
--columns <list<string>>: Columns to be selected from csv file. CSV and Parquet file
-s, --schema <any>: Polars Schema in format [{name: str}]. CSV, JSON, and JSONL files
--hive-enabled: Enable hive support. Parquet and Arrow files
--hive-start-idx <number>: Start index of hive partitioning. Parquet and Arrow files
--hive-schema <any>: Hive schema in format [{name: str}]. Parquet and Arrow files
--hive-try-parse-dates: Try to parse dates in hive partitioning. Parquet and Arrow files
--truncate-ragged-lines: Truncate lines that are longer than the schema. CSV file
Parameters:
file <string>: file path or cloud url to load values from
Input/output types:
╭───┬───────┬──────────────────╮
│ # │ input │ output │
├───┼───────┼──────────────────┤
│ 0 │ any │ polars_dataframe │
│ 1 │ any │ polars_lazyframe │
╰───┴───────┴──────────────────╯
Examples:
Takes a file name and creates a dataframe
> polars open test.csv
polars otherwise
Completes a when expression.
Search terms: condition, else
Usage:
> polars otherwise <otherwise expression>
Flags:
-h, --help: Display the help message for this command
Parameters:
otherwise expression <any>: expression to apply when no when predicate matches
Input/output types:
╭───┬───────┬───────────────────╮
│ # │ input │ output │
├───┼───────┼───────────────────┤
│ 0 │ any │ polars_expression │
╰───┴───────┴───────────────────╯
Examples:
Create a when conditions
> polars when ((polars col a) > 2) 4 | polars otherwise 5
Create a when conditions
> polars when ((polars col a) > 2) 4 | polars when ((polars col a) < 0) 6 | polars otherwise 0
Create a new column for the dataframe
> [[a b]; [6 2] [1 4] [4 1]]
| polars into-lazy
| polars with-column (
polars when ((polars col a) > 2) 4 | polars otherwise 5 | polars as c
)
| polars with-column (
polars when ((polars col a) > 5) 10 | polars when ((polars col a) < 2) 6 | polars otherwise 0 | polars as d
)
| polars collect
╭───┬───┬───┬───┬────╮
│ # │ a │ b │ c │ d │
├───┼───┼───┼───┼────┤
│ 0 │ 6 │ 2 │ 4 │ 10 │
│ 1 │ 1 │ 4 │ 5 │ 6 │
│ 2 │ 4 │ 1 │ 4 │ 0 │
╰───┴───┴───┴───┴────╯
polars over
Compute expressions over a window group defined by partition expressions.
Usage:
> polars over ...(partition by expressions)
Flags:
-h, --help: Display the help message for this command
Parameters:
...partition by expressions <any>: Expression(s) that define the partition window
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Compute expression over an aggregation window
> [[a b]; [x 2] [x 4] [y 6] [y 4]]
| polars into-lazy
| polars select a (polars col b | polars cumulative sum | polars over a | polars as cum_b)
| polars collect
╭───┬───┬───────╮
│ # │ a │ cum_b │
├───┼───┼───────┤
│ 0 │ x │ 2 │
│ 1 │ x │ 6 │
│ 2 │ y │ 6 │
│ 3 │ y │ 10 │
╰───┴───┴───────╯
Compute expression over an aggregation window where partitions are defined by expressions
> [[a b]; [x 2] [X 4] [Y 6] [y 4]]
| polars into-lazy
| polars select a (polars col b | polars cumulative sum | polars over (polars col a | polars lowercase) | polars as cum_b)
| polars collect
╭───┬───┬───────╮
│ # │ a │ cum_b │
├───┼───┼───────┤
│ 0 │ x │ 2 │
│ 1 │ X │ 6 │
│ 2 │ Y │ 6 │
│ 3 │ y │ 10 │
╰───┴───┴───────╯
polars pivot
Pivot a DataFrame from long to wide format.
Usage:
> polars pivot {flags}
Flags:
-o, --on (required parameter) <list<string>>: column names for pivoting
-i, --index (required parameter) <list<string>>: column names for indexes
-v, --values (required parameter) <list<string>>: column names used as value columns
-h, --help: Display the help message for this command
-a, --aggregate <any>: Aggregation to apply when pivoting. The following are supported: first, sum, min, max, mean, median, count, last, or a custom expression
-p, --separator <string>: Delimiter in generated column names in case of multiple values columns (default '_')
-s, --sort: Sort columns
-t, --streamable: Whether or not to use the polars streaming engine. Only valid for lazy dataframes
--stable: Perform a stable pivot.
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Perform a pivot in order to show individuals test score by subject
> [[name subject date test_1 test_2]; [Cady maths 2025-04-01 98 100] [Cady physics 2025-04-01 99 100] [Karen maths 2025-04-02 61 60] [Karen physics 2025-04-02 58 60]] | polars into-df | polars pivot --on [subject] --index [name date] --values [test_1]
╭───┬───────┬──────────────┬───────┬─────────╮
│ # │ name │ date │ maths │ physics │
├───┼───────┼──────────────┼───────┼─────────┤
│ 0 │ Cady │ 8 months ago │ 98 │ 99 │
│ 1 │ Karen │ 8 months ago │ 61 │ 58 │
╰───┴───────┴──────────────┴───────┴─────────╯
Perform a pivot with multiple values columns with a separator
> [[name subject date test_1 test_2 grade_1 grade_2]; [Cady maths 2025-04-01 98 100 A A] [Cady physics 2025-04-01 99 100 A A] [Karen maths 2025-04-02 61 60 D D] [Karen physics 2025-04-02 58 60 D D]] | polars into-df | polars pivot --on [subject] --index [name] --values [test_1 grade_1] --separator /
╭───┬───────┬──────────────┬────────────────┬───────────────┬─────────────────╮
│ # │ name │ test_1/maths │ test_1/physics │ grade_1/maths │ grade_1/physics │
├───┼───────┼──────────────┼────────────────┼───────────────┼─────────────────┤
│ 0 │ Cady │ 98 │ 99 │ A │ A │
│ 1 │ Karen │ 61 │ 58 │ D │ D │
╰───┴───────┴──────────────┴────────────────┴───────────────┴─────────────────╯
polars profile
Profile a lazy dataframe.
This will run the query and return a record containing the materialized DataFrame and a DataFrame that contains profiling information of each node that is executed.
The units of the timings are microseconds.
Usage:
> polars profile
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Profile a lazy dataframe
> [[a b]; [1 2] [1 4] [2 6] [2 4]]
| polars into-lazy
| polars group-by a
| polars agg [
(polars col b | polars min | polars as "b_min")
(polars col b | polars max | polars as "b_max")
(polars col b | polars sum | polars as "b_sum")
]
| polars profile
polars qcut
Bin continuous values into discrete categories based on their quantiles for a series.
Usage:
> polars qcut {flags} <quantiles>
Flags:
-h, --help: Display the help message for this command
-l, --labels <list<string>>: Names of the categories. The number of labels must be equal to the number of cut points plus one.
-c, --left_closed: Set the intervals to be left-closed instead of right-closed.
-b, --include_breaks: Include a column with the right endpoint of the bin each observation falls in. This will change the data type of the output from a Categorical to a Struct.
-d, --allow_duplicates: If set, duplicates in the resulting quantiles are dropped, rather than raising an error. This can happen even with unique probabilities, depending on the data.
Parameters:
quantiles <any>: Either a list of quantile probabilities between 0 and 1 or a positive integer determining the number of bins with uniform probability.
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Divide a column into three categories according to pre-defined quantile probabilities.
> [-2, -1, 0, 1, 2] | polars into-df | polars qcut [0.25, 0.75] --labels ["a", "b", "c"]
polars quantile
Aggregates the columns to the selected quantile.
Usage:
> polars quantile <quantile>
Flags:
-h, --help: Display the help message for this command
Parameters:
quantile <number>: quantile value for quantile operation
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
quantile value from columns in a dataframe
> [[a b]; [6 2] [1 4] [4 1]] | polars into-df | polars quantile 0.5
╭───┬──────┬──────╮
│ # │ a │ b │
├───┼──────┼──────┤
│ 0 │ 4.00 │ 2.00 │
╰───┴──────┴──────╯
Quantile aggregation for a group-by
> [[a b]; [one 2] [one 4] [two 1]]
| polars into-df
| polars group-by a
| polars agg (polars col b | polars quantile 0.5)
| polars collect
| polars sort-by a
╭───┬─────┬──────╮
│ # │ a │ b │
├───┼─────┼──────┤
│ 0 │ one │ 4.00 │
│ 1 │ two │ 1.00 │
╰───┴─────┴──────╯
polars query
Query dataframe using SQL. Note: The dataframe is always named 'df' in your query's from clause.
Search terms: dataframe, sql, search
Usage:
> polars query <sql>
Flags:
-h, --help: Display the help message for this command
Parameters:
sql <string>: sql query
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Query dataframe using SQL
> [[a b]; [1 2] [3 4]] | polars into-df | polars query 'select a from df'
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 1 │
│ 1 │ 3 │
╰───┴───╯
polars rename
Rename a dataframe column.
Usage:
> polars rename <columns> <new names>
Flags:
-h, --help: Display the help message for this command
Parameters:
columns <any>: Column(s) to be renamed. A string or list of strings
new names <any>: New names for the selected column(s). A string or list of strings
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Renames a series
> [5 6 7 8] | polars into-df | polars rename '0' new_name
╭───┬──────────╮
│ # │ new_name │
├───┼──────────┤
│ 0 │ 5 │
│ 1 │ 6 │
│ 2 │ 7 │
│ 3 │ 8 │
╰───┴──────────╯
Renames a dataframe column
> [[a b]; [1 2] [3 4]] | polars into-df | polars rename a a_new
╭───┬───────┬───╮
│ # │ a_new │ b │
├───┼───────┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───────┴───╯
Renames two dataframe columns
> [[a b]; [1 2] [3 4]] | polars into-df | polars rename [a b] [a_new b_new]
╭───┬───────┬───────╮
│ # │ a_new │ b_new │
├───┼───────┼───────┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───────┴───────╯
polars replace-time-zone
Replace the timezone information in a datetime column.
Usage:
> polars replace-time-zone {flags} <time_zone>
Flags:
-h, --help: Display the help message for this command
-a, --ambiguous <oneof<string, nothing>>: Determine how to deal with ambiguous datetimes:
raise (default): raise error
earliest: use the earliest datetime
latest: use the latest datetime
null: set to null
-n, --nonexistent <oneof<string, nothing>>: Determine how to deal with non-existent datetimes: raise (default) or null.
Parameters:
time_zone <string>: Timezone for the Datetime Series. Pass null to unset time zone.
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Apply timezone to a naive datetime
> ["2021-12-30 00:00:00" "2021-12-31 00:00:00"] | polars into-df
| polars as-datetime "%Y-%m-%d %H:%M:%S" --naive
| polars select (polars col datetime | polars replace-time-zone "America/New_York")
╭───┬─────────────╮
│ # │ datetime │
├───┼─────────────┤
│ 0 │ 3 years ago │
│ 1 │ 3 years ago │
╰───┴─────────────╯
Apply timezone with ambiguous datetime
> ["2025-11-02 00:00:00", "2025-11-02 01:00:00", "2025-11-02 02:00:00", "2025-11-02 03:00:00"]
| polars into-df
| polars as-datetime "%Y-%m-%d %H:%M:%S" --naive
| polars select (polars col datetime | polars replace-time-zone "America/New_York" --ambiguous null)
╭───┬─────────────╮
│ # │ datetime │
├───┼─────────────┤
│ 0 │ a month ago │
│ 1 │ │
│ 2 │ a month ago │
│ 3 │ a month ago │
╰───┴─────────────╯
Apply timezone with nonexistent datetime
> ["2025-03-09 01:00:00", "2025-03-09 02:00:00", "2025-03-09 03:00:00", "2025-03-09 04:00:00"]
| polars into-df
| polars as-datetime "%Y-%m-%d %H:%M:%S" --naive
| polars select (polars col datetime | polars replace-time-zone "America/New_York" --nonexistent null)
╭───┬──────────────╮
│ # │ datetime │
├───┼──────────────┤
│ 0 │ 9 months ago │
│ 1 │ │
│ 2 │ 9 months ago │
│ 3 │ 9 months ago │
╰───┴──────────────╯
polars rolling
Rolling calculation for a series.
Usage:
> polars rolling <type> <window>
Flags:
-h, --help: Display the help message for this command
Parameters:
type <string>: rolling operation
window <int>: Window size for rolling
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Rolling sum for a series
> [1 2 3 4 5] | polars into-df | polars rolling sum 2 | polars drop-nulls
╭───┬───────────────╮
│ # │ 0_rolling_sum │
├───┼───────────────┤
│ 0 │ 3 │
│ 1 │ 5 │
│ 2 │ 7 │
│ 3 │ 9 │
╰───┴───────────────╯
Rolling max for a series
> [1 2 3 4 5] | polars into-df | polars rolling max 2 | polars drop-nulls
╭───┬───────────────╮
│ # │ 0_rolling_max │
├───┼───────────────┤
│ 0 │ 2 │
│ 1 │ 3 │
│ 2 │ 4 │
│ 3 │ 5 │
╰───┴───────────────╯
polars sample
Create sample dataframe.
Usage:
> polars sample {flags}
Flags:
-h, --help: Display the help message for this command
-n, --n-rows <int>: number of rows to be taken from dataframe
-f, --fraction <number>: fraction of dataframe to be taken
-s, --seed <number>: seed for the selection
-e, --replace: sample with replace
-u, --shuffle: shuffle sample
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Sample rows from dataframe
> [[a b]; [1 2] [3 4]] | polars into-df | polars sample --n-rows 1
Shows sample row using fraction and replace
> [[a b]; [1 2] [3 4] [5 6]] | polars into-df | polars sample --fraction 0.5 --replace
Shows sample row using using predefined seed 1
> [[a b]; [1 2] [3 4] [5 6]] | polars into-df | polars sample --seed 1 --n-rows 1
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 5 │ 6 │
╰───┴───┴───╯
polars save
Saves a dataframe to disk. For lazy dataframes a sink operation will be used if the file type supports it (parquet, ipc/arrow, csv, and ndjson).
Usage:
> polars save {flags} <path>
Flags:
-h, --help: Display the help message for this command
-t, --type <string>: File type: csv, json, parquet, arrow/ipc. If omitted, derive from file extension
--avro-compression <string>: Compression for avro supports deflate or snappy
--csv-delimiter <string>: file delimiter character
--csv-no-header: Indicates to exclude a header row for CSV files.
Parameters:
path <string>: Path or cloud url to write to
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ string │
╰───┴───────┴────────╯
Examples:
Performs a streaming collect and save the output to the specified file
> [[a b];[1 2] [3 4]] | polars into-lazy | polars save test.parquet
Saves dataframe to parquet file
> [[a b]; [1 2] [3 4]] | polars into-df | polars save test.parquet
Saves dataframe to arrow file
> [[a b]; [1 2] [3 4]] | polars into-df | polars save test.arrow
Saves dataframe to NDJSON file
> [[a b]; [1 2] [3 4]] | polars into-df | polars save test.ndjson
Saves dataframe to avro file
> [[a b]; [1 2] [3 4]] | polars into-df | polars save test.avro
Saves dataframe to CSV file
> [[a b]; [1 2] [3 4]] | polars into-df | polars save test.csv
Saves dataframe to CSV file using other delimiter
> [[a b]; [1 2] [3 4]] | polars into-df | polars save test.csv --csv-delimiter '|'
polars schema
Show schema for a dataframe.
Usage:
> polars schema {flags}
Flags:
-h, --help: Display the help message for this command
-l, --datatype-list: creates a lazy dataframe
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ record │
╰───┴───────┴────────╯
Examples:
Dataframe schema
> [[a b]; [1 "foo"] [3 "bar"]] | polars into-df | polars schema
╭───┬─────╮
│ a │ i64 │
│ b │ str │
╰───┴─────╯
polars select
Selects columns from lazyframe.
Usage:
> polars select ...(select expressions)
Flags:
-h, --help: Display the help message for this command
Parameters:
...select expressions <any>: Expression(s) that define the column selection
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Select a column from the dataframe
> [[a b]; [6 2] [4 2] [2 2]] | polars into-df | polars select a
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 6 │
│ 1 │ 4 │
│ 2 │ 2 │
╰───┴───╯
Select a column from a dataframe using a record
> [[a b]; [6 2] [4 2] [2 2]] | polars into-df | polars select {c: ((polars col a) * 2)}
╭───┬────╮
│ # │ c │
├───┼────┤
│ 0 │ 12 │
│ 1 │ 8 │
│ 2 │ 4 │
╰───┴────╯
Select a column from a dataframe using a mix of expressions and record of expressions
> [[a b]; [6 2] [4 2] [2 2]] | polars into-df | polars select a b {c: ((polars col a) ** 2)}
╭───┬───┬───┬────╮
│ # │ a │ b │ c │
├───┼───┼───┼────┤
│ 0 │ 6 │ 2 │ 36 │
│ 1 │ 4 │ 2 │ 16 │
│ 2 │ 2 │ 2 │ 4 │
╰───┴───┴───┴────╯
polars set
Sets value where given mask is true.
Usage:
> polars set {flags} <value>
Flags:
-m, --mask (required parameter) <any>: mask indicating insertions
-h, --help: Display the help message for this command
Parameters:
value <any>: value to be inserted in series
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Shifts the values by a given period
> let s = ([1 2 2 3 3] | polars into-df | polars shift 2);
let mask = ($s | polars is-null);
$s | polars set 0 --mask $mask
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 0 │
│ 1 │ 0 │
│ 2 │ 1 │
│ 3 │ 2 │
│ 4 │ 2 │
╰───┴───╯
polars set-with-idx
Sets value in the given index.
Usage:
> polars set-with-idx {flags} <value>
Flags:
-i, --indices (required parameter) <any>: list of indices indicating where to set the value
-h, --help: Display the help message for this command
Parameters:
value <any>: value to be inserted in series
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Set value in selected rows from series
> let series = ([4 1 5 2 4 3] | polars into-df);
let indices = ([0 2] | polars into-df);
$series | polars set-with-idx 6 --indices $indices
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 6 │
│ 1 │ 1 │
│ 2 │ 6 │
│ 3 │ 2 │
│ 4 │ 4 │
│ 5 │ 3 │
╰───┴───╯
polars shape
Shows column and row size for a dataframe.
Usage:
> polars shape
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Shows row and column shape
> [[a b]; [1 2] [3 4]] | polars into-df | polars shape
╭───┬──────┬─────────╮
│ # │ rows │ columns │
├───┼──────┼─────────┤
│ 0 │ 2 │ 2 │
╰───┴──────┴─────────╯
polars shift
Shifts the values by a given period.
Usage:
> polars shift {flags} <period>
Flags:
-h, --help: Display the help message for this command
-f, --fill <any>: Expression used to fill the null values (lazy df)
Parameters:
period <int>: shift period
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Shifts the values by a given period
> [1 2 2 3 3] | polars into-df | polars shift 2 | polars drop-nulls
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 2 │
╰───┴───╯
Shifts the values by a given period, fill absent values with 0
> [1 2 2 3 3] | polars into-lazy | polars shift 2 --fill 0 | polars collect
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 0 │
│ 1 │ 0 │
│ 2 │ 1 │
│ 3 │ 2 │
│ 4 │ 2 │
╰───┴───╯
Shift values of a column, fill absent values with 0
> [[a]; [1] [2] [2] [3] [3]]
| polars into-lazy
| polars with-column {b: (polars col a | polars shift 2 --fill 0)}
| polars collect
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 0 │
│ 1 │ 2 │ 0 │
│ 2 │ 2 │ 1 │
│ 3 │ 3 │ 2 │
│ 4 │ 3 │ 2 │
╰───┴───┴───╯
polars slice
Creates new dataframe from a slice of rows.
Usage:
> polars slice <offset> <size>
Flags:
-h, --help: Display the help message for this command
Parameters:
offset <int>: start of slice
size <int>: size of slice
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Create new dataframe from a slice of the rows
> [[a b]; [1 2] [3 4]] | polars into-df | polars slice 0 1
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
╰───┴───┴───╯
polars sort-by
Sorts a lazy dataframe based on expression(s).
Usage:
> polars sort-by {flags} ...(sort expression)
Flags:
-h, --help: Display the help message for this command
-r, --reverse <list<bool>>: Reverse sorting. Default is false
-n, --nulls-last: nulls are shown last in the dataframe
-m, --maintain-order: Maintains order during sort
Parameters:
...sort expression <any>: sort expression for the dataframe
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Sort dataframe by one column
> [[a b]; [6 2] [1 4] [4 1]] | polars into-df | polars sort-by a
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 4 │
│ 1 │ 4 │ 1 │
│ 2 │ 6 │ 2 │
╰───┴───┴───╯
Sort column using two columns
> [[a b]; [6 2] [1 1] [1 4] [2 4]] | polars into-df | polars sort-by [a b] -r [false true]
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 4 │
│ 1 │ 1 │ 1 │
│ 2 │ 2 │ 4 │
│ 3 │ 6 │ 2 │
╰───┴───┴───╯
polars std
Creates a std expression for an aggregation of std value from columns in a dataframe.
Usage:
> polars std
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Std value from columns in a dataframe
> [[a b]; [6 2] [4 2] [2 2]] | polars into-df | polars std | polars collect
╭───┬──────┬──────╮
│ # │ a │ b │
├───┼──────┼──────┤
│ 0 │ 2.00 │ 0.00 │
╰───┴──────┴──────╯
Std aggregation for a group-by
> [[a b]; [one 2] [one 2] [two 1] [two 1]]
| polars into-df
| polars group-by a
| polars agg (polars col b | polars std)
| polars collect
| polars sort-by a
╭───┬─────┬──────╮
│ # │ a │ b │
├───┼─────┼──────┤
│ 0 │ one │ 0.00 │
│ 1 │ two │ 0.00 │
╰───┴─────┴──────╯
polars store-get
Gets a Dataframe or other object from the plugin cache.
Usage:
> polars store-get <key>
Flags:
-h, --help: Display the help message for this command
Parameters:
key <string>: Key of objects to get
Input/output types:
╭───┬───────┬───────────────────╮
│ # │ input │ output │
├───┼───────┼───────────────────┤
│ 0 │ any │ polars_dataframe │
│ 1 │ any │ polars_lazyframe │
│ 2 │ any │ polars_expression │
│ 3 │ any │ polars_group_by │
│ 4 │ any │ polars_when │
│ 5 │ any │ polars_datatype │
│ 6 │ any │ polars_schema │
╰───┴───────┴───────────────────╯
Examples:
Get a stored object
> let df = ([[a b];[1 2] [3 4]] | polars into-df);
polars store-ls | get key | first | polars store-get $in
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
polars store-ls
Lists stored polars objects.
Usage:
> polars store-ls
Flags:
-h, --help: Display the help message for this command
Examples:
Creates a new dataframe and shows it in the dataframe list
> let test = ([[a b];[1 2] [3 4]] | polars into-df);
polars store-ls
polars store-rm
Removes a stored Dataframe or other object from the plugin cache.
Usage:
> polars store-rm ...(keys)
Flags:
-h, --help: Display the help message for this command
Parameters:
...keys <string>: Keys of objects to remove
Input/output types:
╭───┬───────┬──────────────╮
│ # │ input │ output │
├───┼───────┼──────────────┤
│ 0 │ any │ list<string> │
╰───┴───────┴──────────────╯
Examples:
Removes a stored
> let df = ([[a b];[1 2] [3 4]] | polars into-df);
polars store-ls | get key | first | polars store-rm $in
polars str-lengths
Get lengths of all strings.
Usage:
> polars str-lengths {flags}
Flags:
-h, --help: Display the help message for this command
-b, --bytes: Get the length in bytes instead of chars.
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns string lengths for a column
> [[a]; [a] [ab] [abc]] | polars into-df | polars select (polars col a | polars str-lengths) | polars collect
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
╰───┴───╯
Returns string lengths
> [a ab abc] | polars into-df | polars str-lengths
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 1 │
│ 1 │ 2 │
│ 2 │ 3 │
╰───┴───╯
polars str-replace
Replace the leftmost (sub)string by a regex pattern.
Usage:
> polars str-replace {flags}
Flags:
-p, --pattern (required parameter) <string>: Regex pattern to be matched
-r, --replace (required parameter) <string>: replacing string
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Replaces string in column
> [[a]; [abc] [abcabc]] | polars into-df | polars select (polars col a | polars str-replace --pattern ab --replace AB) | polars collect
╭───┬────────╮
│ # │ a │
├───┼────────┤
│ 0 │ ABc │
│ 1 │ ABcabc │
╰───┴────────╯
Replaces string
> [abc abc abc] | polars into-df | polars str-replace --pattern ab --replace AB
╭───┬─────╮
│ # │ 0 │
├───┼─────┤
│ 0 │ ABc │
│ 1 │ ABc │
│ 2 │ ABc │
╰───┴─────╯
polars str-replace-all
Replace all (sub)strings by a regex pattern.
Usage:
> polars str-replace-all {flags}
Flags:
-p, --pattern (required parameter) <string>: Regex pattern to be matched
-r, --replace (required parameter) <string>: replacing string
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Replaces string in a column
> [[a]; [abac] [abac] [abac]] | polars into-df | polars select (polars col a | polars str-replace-all --pattern a --replace A) | polars collect
╭───┬──────╮
│ # │ a │
├───┼──────┤
│ 0 │ AbAc │
│ 1 │ AbAc │
│ 2 │ AbAc │
╰───┴──────╯
Replaces string
> [abac abac abac] | polars into-df | polars str-replace-all --pattern a --replace A
╭───┬──────╮
│ # │ 0 │
├───┼──────┤
│ 0 │ AbAc │
│ 1 │ AbAc │
│ 2 │ AbAc │
╰───┴──────╯
polars str-slice
Slices the string from the start position until the selected length.
Usage:
> polars str-slice {flags} <start>
Flags:
-h, --help: Display the help message for this command
-l, --length <int>: optional length
Parameters:
start <int>: start of slice
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Creates slices from the strings in a specified column
> [[a]; [abcded] [abc321] [abc123]] | polars into-df | polars select (polars col a | polars str-slice 1 --length 2) | polars collect
╭───┬────╮
│ # │ a │
├───┼────┤
│ 0 │ bc │
│ 1 │ bc │
│ 2 │ bc │
╰───┴────╯
Creates slices from the strings
> [abcded abc321 abc123] | polars into-df | polars str-slice 1 --length 2
╭───┬────╮
│ # │ 0 │
├───┼────┤
│ 0 │ bc │
│ 1 │ bc │
│ 2 │ bc │
╰───┴────╯
Creates slices from the strings without length
> [abcded abc321 abc123] | polars into-df | polars str-slice 1
╭───┬───────╮
│ # │ 0 │
├───┼───────┤
│ 0 │ bcded │
│ 1 │ bc321 │
│ 2 │ bc123 │
╰───┴───────╯
polars str-split
Split the string by a substring. The resulting dtype is list<str>.
Usage:
> polars str-split <expr>
Flags:
-h, --help: Display the help message for this command
Parameters:
expr <any>: Separator expression
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Split the string by comma, then create a new row for each string
> [[a]; ["one,two,three"]] | polars into-df
| polars select (polars col a | polars str-split "," | polars explode)
| polars collect
╭───┬───────╮
│ # │ a │
├───┼───────┤
│ 0 │ one │
│ 1 │ two │
│ 2 │ three │
╰───┴───────╯
polars strftime
Formats date based on string rule.
Usage:
> polars strftime <fmt>
Flags:
-h, --help: Display the help message for this command
Parameters:
fmt <string>: Format rule
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Formats date column as a string
> let date = '2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC';
let df = ([[a]; [$date]] | polars into-df);
let df2 = $df | polars with-column [(polars col a | polars strftime "%Y/%m/%d" | polars as b)] | polars collect;
$df2.b
╭───┬────────────╮
│ # │ b │
├───┼────────────┤
│ 0 │ 2020/08/04 │
╰───┴────────────╯
Formats date
> let dt = ('2020-08-04T16:39:18+00:00' | into datetime --timezone 'UTC');
let df = ([$dt $dt] | polars into-df);
$df | polars strftime "%Y/%m/%d"
╭───┬────────────╮
│ # │ 0 │
├───┼────────────┤
│ 0 │ 2020/08/04 │
│ 1 │ 2020/08/04 │
╰───┴────────────╯
polars struct-json-encode
Convert this struct to a string column with json values.
Usage:
> polars struct-json-encode
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬────────────┬────────────╮
│ # │ input │ output │
├───┼────────────┼────────────┤
│ 0 │ expression │ expression │
╰───┴────────────┴────────────╯
Examples:
Encode a struct as JSON
> [[id person]; [1 {name: "Bob", age: 36}] [2 {name: "Betty", age: 63}]]
| polars into-df -s {id: i32, person: {name: str, age: u8}}
| polars select id (polars col person | polars struct-json-encode | polars as encoded)
| polars sort-by id
| polars collect
╭───┬────┬───────────────────────────╮
│ # │ id │ encoded │
├───┼────┼───────────────────────────┤
│ 0 │ 1 │ {"name":"Bob","age":36} │
│ 1 │ 2 │ {"name":"Betty","age":63} │
╰───┴────┴───────────────────────────╯
polars sum
Creates a sum expression for an aggregation or aggregates columns to their sum value.
Usage:
> polars sum
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Sums all columns in a dataframe
> [[a b]; [6 2] [1 4] [4 1]] | polars into-df | polars sum | polars collect
╭───┬────┬───╮
│ # │ a │ b │
├───┼────┼───┤
│ 0 │ 11 │ 7 │
╰───┴────┴───╯
Sum aggregation for a group-by
> [[a b]; [one 2] [one 4] [two 1]]
| polars into-df
| polars group-by a
| polars agg (polars col b | polars sum)
| polars collect
| polars sort-by a
╭───┬─────┬───╮
│ # │ a │ b │
├───┼─────┼───┤
│ 0 │ one │ 6 │
│ 1 │ two │ 1 │
╰───┴─────┴───╯
polars summary
For a dataframe, produces descriptive statistics (summary statistics) for its numeric columns.
Usage:
> polars summary {flags}
Flags:
-h, --help: Display the help message for this command
-q, --quantiles <list<float>>: provide optional quantiles
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
list dataframe descriptives
> [[a b]; [1 1] [1 1]] | polars into-df | polars summary
╭───┬────────────┬─────────┬─────────╮
│ # │ descriptor │ a (i64) │ b (i64) │
├───┼────────────┼─────────┼─────────┤
│ 0 │ count │ 2.00 │ 2.00 │
│ 1 │ sum │ 2.00 │ 2.00 │
│ 2 │ mean │ 1.00 │ 1.00 │
│ 3 │ median │ 1.00 │ 1.00 │
│ 4 │ std │ 0.00 │ 0.00 │
│ 5 │ min │ 1.00 │ 1.00 │
│ 6 │ 25% │ 1.00 │ 1.00 │
│ 7 │ 50% │ 1.00 │ 1.00 │
│ 8 │ 75% │ 1.00 │ 1.00 │
│ 9 │ max │ 1.00 │ 1.00 │
╰───┴────────────┴─────────┴─────────╯
polars take
Creates new dataframe using the given indices.
Usage:
> polars take <indices>
Flags:
-h, --help: Display the help message for this command
Parameters:
indices <any>: list of indices used to take data
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Takes selected rows from dataframe
> let df = ([[a b]; [4 1] [5 2] [4 3]] | polars into-df);
let indices = ([0 2] | polars into-df);
$df | polars take $indices
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 4 │ 1 │
│ 1 │ 4 │ 3 │
╰───┴───┴───╯
Takes selected rows from series
> let series = ([4 1 5 2 4 3] | polars into-df);
let indices = ([0 2] | polars into-df);
$series | polars take $indices
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 4 │
│ 1 │ 5 │
╰───┴───╯
polars truncate
Divide the date/datetime range into buckets.
Each date/datetime is mapped to the start of its bucket using the corresponding local datetime. Note that weekly buckets start on Monday. Ambiguous results are localised using the DST offset of the original timestamp - for example, truncating '2022-11-06 01:30:00 CST' by '1h' results in '2022-11-06 01:00:00 CST', whereas truncating '2022-11-06 01:30:00 CDT' by '1h' results in '2022-11-06 01:00:00 CDT'.
See Notes in documentation for full list of compatible string values for every: https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.dt.truncate.html
Usage:
> polars truncate <every>
Flags:
-h, --help: Display the help message for this command
Parameters:
every <oneof<duration, string>>: Period length for every interval (can be duration or str)
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Truncate a series of dates by period length
> seq date -b 2025-01-01 --periods 4 --increment 6wk -o "%Y-%m-%d %H:%M:%S" | polars into-df | polars as-datetime "%F %H:%M:%S" --naive | polars select datetime (polars col datetime | polars truncate 5d37m | polars as truncated)
╭───┬───────────────┬───────────────╮
│ # │ datetime │ truncated │
├───┼───────────────┼───────────────┤
│ 0 │ 11 months ago │ a year ago │
│ 1 │ 10 months ago │ 10 months ago │
│ 2 │ 8 months ago │ 8 months ago │
│ 3 │ 7 months ago │ 7 months ago │
╰───┴───────────────┴───────────────╯
polars unique
Returns unique values from a dataframe.
Usage:
> polars unique {flags}
Flags:
-h, --help: Display the help message for this command
-s, --subset <any>: Subset of column(s) to use to maintain rows (lazy df)
-l, --last: Keeps last unique value. Default keeps first value (lazy df)
-k, --maintain-order: Keep the same order as the original DataFrame (lazy df)
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Returns unique values from a series
> [2 2 2 2 2] | polars into-df | polars unique
╭───┬───╮
│ # │ 0 │
├───┼───┤
│ 0 │ 2 │
╰───┴───╯
Returns unique values in a subset of lazyframe columns
> [[a b c]; [1 2 1] [2 2 2] [3 2 1]] | polars into-lazy | polars unique --subset [b c] | polars collect
╭───┬───┬───┬───╮
│ # │ a │ b │ c │
├───┼───┼───┼───┤
│ 0 │ 1 │ 2 │ 1 │
│ 1 │ 2 │ 2 │ 2 │
╰───┴───┴───┴───╯
Returns unique values in a subset of lazyframe columns
> [[a b c]; [1 2 1] [2 2 2] [3 2 1]]
| polars into-lazy
| polars unique --subset [b c] --last
| polars collect
╭───┬───┬───┬───╮
│ # │ a │ b │ c │
├───┼───┼───┼───┤
│ 0 │ 2 │ 2 │ 2 │
│ 1 │ 3 │ 2 │ 1 │
╰───┴───┴───┴───╯
Returns unique values in a subset of lazyframe columns
> [[a]; [2] [1] [2]]
| polars into-lazy
| polars select (polars col a | polars unique)
| polars collect
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 1 │
│ 1 │ 2 │
╰───┴───╯
Returns unique values in a subset of lazyframe columns
> [[a]; [2] [1] [2]]
| polars into-lazy
| polars select (polars col a | polars unique --maintain-order)
| polars collect
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 2 │
│ 1 │ 1 │
╰───┴───╯
polars unnest
Decompose struct columns into separate columns for each of their fields. The new columns will be inserted into the dataframe at the location of the struct column.
Usage:
> polars unnest ...(cols)
Flags:
-h, --help: Display the help message for this command
Parameters:
...cols <string>: columns to unnest
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Unnest a dataframe
> [[id person]; [1 {name: "Bob", age: 36}] [2 {name: "Betty", age: 63}]]
| polars into-df -s {id: i64, person: {name: str, age: u8}}
| polars unnest person
| polars get id name age
| polars sort-by id
╭───┬────┬───────┬─────╮
│ # │ id │ name │ age │
├───┼────┼───────┼─────┤
│ 0 │ 1 │ Bob │ 36 │
│ 1 │ 2 │ Betty │ 63 │
╰───┴────┴───────┴─────╯
Unnest a lazy dataframe
> [[id person]; [1 {name: "Bob", age: 36}] [2 {name: "Betty", age: 63}]]
| polars into-df -s {id: i64, person: {name: str, age: u8}}
| polars into-lazy
| polars unnest person
| polars select (polars col id) (polars col name) (polars col age)
| polars collect
| polars sort-by id
╭───┬────┬───────┬─────╮
│ # │ id │ name │ age │
├───┼────┼───────┼─────┤
│ 0 │ 1 │ Bob │ 36 │
│ 1 │ 2 │ Betty │ 63 │
╰───┴────┴───────┴─────╯
polars unpivot
Unpivot a DataFrame from wide to long format.
Usage:
> polars unpivot {flags}
Flags:
-i, --index (required parameter) <list<any>>: column names for unpivoting
-o, --on (required parameter) <list<any>>: column names used as value columns
-h, --help: Display the help message for this command
-r, --variable-name <string>: optional name for variable column
-l, --value-name <string>: optional name for value column
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
unpivot on an eager dataframe
> [[a b c d]; [x 1 4 a] [y 2 5 b] [z 3 6 c]] | polars into-df | polars unpivot -i [b c] -o [a d]
╭───┬───┬───┬──────────┬───────╮
│ # │ b │ c │ variable │ value │
├───┼───┼───┼──────────┼───────┤
│ 0 │ 1 │ 4 │ a │ x │
│ 1 │ 2 │ 5 │ a │ y │
│ 2 │ 3 │ 6 │ a │ z │
│ 3 │ 1 │ 4 │ d │ a │
│ 4 │ 2 │ 5 │ d │ b │
│ 5 │ 3 │ 6 │ d │ c │
╰───┴───┴───┴──────────┴───────╯
unpivot on a lazy dataframe
> [[a b c d]; [x 1 4 a] [y 2 5 b] [z 3 6 c]] | polars into-lazy | polars unpivot -i [b c] -o [a d] | polars collect
╭───┬───┬───┬──────────┬───────╮
│ # │ b │ c │ variable │ value │
├───┼───┼───┼──────────┼───────┤
│ 0 │ 1 │ 4 │ a │ x │
│ 1 │ 2 │ 5 │ a │ y │
│ 2 │ 3 │ 6 │ a │ z │
│ 3 │ 1 │ 4 │ d │ a │
│ 4 │ 2 │ 5 │ d │ b │
│ 5 │ 3 │ 6 │ d │ c │
╰───┴───┴───┴──────────┴───────╯
polars uppercase
Uppercase the strings in the column.
Search terms: capitalize, caps, capital
Usage:
> polars uppercase
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
│ 2 │ polars_expression │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Modifies strings in a column to uppercase
> [[a]; [Abc]] | polars into-df | polars select (polars col a | polars uppercase) | polars collect
╭───┬─────╮
│ # │ a │
├───┼─────┤
│ 0 │ ABC │
╰───┴─────╯
Modifies strings to uppercase
> [Abc aBc abC] | polars into-df | polars uppercase
╭───┬─────╮
│ # │ 0 │
├───┼─────┤
│ 0 │ ABC │
│ 1 │ ABC │
│ 2 │ ABC │
╰───┴─────╯
polars value-counts
Returns a dataframe with the counts for unique values in series.
Usage:
> polars value-counts {flags}
Flags:
-h, --help: Display the help message for this command
-c, --column <string>: Provide a custom name for the count column
-s, --sort: Whether or not values should be sorted
-p, --parallel: Use multiple threads when processing
-n, --normalize <string>: Normalize the counts
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Calculates value counts
> [5 5 5 5 6 6] | polars into-df | polars value-counts | polars sort-by count
╭───┬───┬───────╮
│ # │ 0 │ count │
├───┼───┼───────┤
│ 0 │ 6 │ 2 │
│ 1 │ 5 │ 4 │
╰───┴───┴───────╯
polars var
Create a var expression for an aggregation.
Usage:
> polars var
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ polars_expression │ polars_expression │
│ 1 │ polars_dataframe │ polars_dataframe │
│ 2 │ polars_lazyframe │ polars_lazyframe │
╰───┴───────────────────┴───────────────────╯
Examples:
Var value from columns in a dataframe or aggregates columns to their var value
> [[a b]; [6 2] [4 2] [2 2]] | polars into-df | polars var | polars collect
╭───┬──────┬──────╮
│ # │ a │ b │
├───┼──────┼──────┤
│ 0 │ 4.00 │ 0.00 │
╰───┴──────┴──────╯
Var aggregation for a group-by
> [[a b]; [one 2] [one 2] [two 1] [two 1]]
| polars into-df
| polars group-by a
| polars agg (polars col b | polars var)
| polars collect
| polars sort-by a
╭───┬─────┬──────╮
│ # │ a │ b │
├───┼─────┼──────┤
│ 0 │ one │ 0.00 │
│ 1 │ two │ 0.00 │
╰───┴─────┴──────╯
polars when
Creates and modifies a when expression.
Search terms: condition, match, if, else
Usage:
> polars when <when expression> <then expression>
Flags:
-h, --help: Display the help message for this command
Parameters:
when expression <any>: when expression used for matching
then expression <any>: expression that will be applied when predicate is true
Input/output types:
╭───┬───────────────────┬───────────────────╮
│ # │ input │ output │
├───┼───────────────────┼───────────────────┤
│ 0 │ nothing │ polars_expression │
│ 1 │ polars_expression │ polars_expression │
│ 2 │ any │ polars_expression │
╰───┴───────────────────┴───────────────────╯
Examples:
Create a when conditions
> polars when ((polars col a) > 2) 4
Create a when conditions
> polars when ((polars col a) > 2) 4 | polars when ((polars col a) < 0) 6
Create a new column for the dataframe
> [[a b]; [6 2] [1 4] [4 1]]
| polars into-lazy
| polars with-column (
polars when ((polars col a) > 2) 4 | polars otherwise 5 | polars as c
)
| polars with-column (
polars when ((polars col a) > 5) 10 | polars when ((polars col a) < 2) 6 | polars otherwise 0 | polars as d
)
| polars collect
╭───┬───┬───┬───┬────╮
│ # │ a │ b │ c │ d │
├───┼───┼───┼───┼────┤
│ 0 │ 6 │ 2 │ 4 │ 10 │
│ 1 │ 1 │ 4 │ 5 │ 6 │
│ 2 │ 4 │ 1 │ 4 │ 0 │
╰───┴───┴───┴───┴────╯
polars with-column
Adds a series to the dataframe.
Usage:
> polars with-column {flags} ...(series or expressions)
Flags:
-h, --help: Display the help message for this command
-n, --name <string>: New column name. For lazy dataframes and expressions syntax, use a polars as expression to name a column.
Parameters:
...series or expressions <any>: series to be added or expressions used to define the new columns
Input/output types:
╭───┬──────────────────┬──────────────────╮
│ # │ input │ output │
├───┼──────────────────┼──────────────────┤
│ 0 │ polars_dataframe │ polars_dataframe │
│ 1 │ polars_lazyframe │ polars_lazyframe │
╰───┴──────────────────┴──────────────────╯
Examples:
Adds a series to the dataframe
> [[a b]; [1 2] [3 4]]
| polars into-df
| polars with-column ([5 6] | polars into-df) --name c
╭───┬───┬───┬───╮
│ # │ a │ b │ c │
├───┼───┼───┼───┤
│ 0 │ 1 │ 2 │ 5 │
│ 1 │ 3 │ 4 │ 6 │
╰───┴───┴───┴───╯
Adds a series to the dataframe
> [[a b]; [1 2] [3 4]]
| polars into-lazy
| polars with-column [
((polars col a) * 2 | polars as "c")
((polars col a) * 3 | polars as "d")
]
| polars collect
╭───┬───┬───┬───┬───╮
│ # │ a │ b │ c │ d │
├───┼───┼───┼───┼───┤
│ 0 │ 1 │ 2 │ 2 │ 3 │
│ 1 │ 3 │ 4 │ 6 │ 9 │
╰───┴───┴───┴───┴───╯
Add series to a lazyframe using a record
> [[a b]; [1 2] [3 4]]
| polars into-lazy
| polars with-column {
c: ((polars col a) * 2)
d: ((polars col a) * 3)
}
| polars collect
╭───┬───┬───┬───┬───╮
│ # │ a │ b │ c │ d │
├───┼───┼───┼───┼───┤
│ 0 │ 1 │ 2 │ 2 │ 3 │
│ 1 │ 3 │ 4 │ 6 │ 9 │
╰───┴───┴───┴───┴───╯
Add series to a dataframe using a record
> [[a b]; [1 2] [3 4]]
| polars into-df
| polars with-column {
c: ((polars col a) * 2)
d: ((polars col a) * 3)
}
| polars collect
╭───┬───┬───┬───┬───╮
│ # │ a │ b │ c │ d │
├───┼───┼───┼───┼───┤
│ 0 │ 1 │ 2 │ 2 │ 3 │
│ 1 │ 3 │ 4 │ 6 │ 9 │
╰───┴───┴───┴───┴───╯
port
Get a free TCP 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
-r, --raw: print without formatting (including binary data)
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)
Print 'ABC' from binary data
> 0x[41 42 43] | print --raw
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 SQLite database with SQL statements.
This command is only supported for local or in-memory SQLite databases.
Search terms: database, SQLite
Usage:
> query db {flags} <SQL>
Flags:
-h, --help: Display the help message for this command
-p, --params <any>: List of parameters for the SQL statement
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"
Execute a SQL statement with parameters
> stor create -t my_table -c { first: str, second: int }
stor open | query db "INSERT INTO my_table VALUES (?, ?)" -p [hello 123]
Execute a SQL statement with named parameters
> stor create -t my_table -c { first: str, second: int }
stor insert -t my_table -d { first: 'hello', second: '123' }
stor open | query db "SELECT * FROM my_table WHERE second = :search_second" -p { search_second: 123 }
╭───┬───────┬────────╮
│ # │ first │ second │
├───┼───────┼────────┤
│ 0 │ hello │ 123 │
╰───┴───────┴────────╯
Execute a SQL query, selecting a declared JSON(B) column that will automatically be parsed
> stor create -t my_table -c {data: jsonb}
[{data: {name: Albert, age: 40}} {data: {name: Barnaby, age: 54}}] | stor insert -t my_table
stor open | query db "SELECT data FROM my_table WHERE data->>'age' < 45"
╭───┬───────────────────╮
│ # │ data │
├───┼───────────────────┤
│ 0 │ ╭──────┬────────╮ │
│ │ │ name │ Albert │ │
│ │ │ age │ 40 │ │
│ │ ╰──────┴────────╯ │
╰───┴───────────────────╯
Execute a SQL query selecting a sub-field of a JSON(B) column.
In this case, results must be parsed afterwards because SQLite does not
return declaration types when a JSON(B) column is not directly selected
> stor create -t my_table -c {data: jsonb}
stor insert -t my_table -d {data: {foo: foo, bar: 12, baz: [0 1 2]}}
stor open | query db "SELECT data->'baz' AS baz FROM my_table" | update baz {from json}
╭───┬───────────╮
│ # │ baz │
├───┼───────────┤
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 0 │ │
│ │ │ 1 │ 1 │ │
│ │ │ 2 │ 2 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
query webpage-info
uses the webpage crate to extract info from html: title, description, language, links, RSS feeds, Opengraph, Schema.org, and more
Usage:
> query webpage-info
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ record │
╰───┴────────┴────────╯
Examples:
extract detailed info from phoronix.com website
> http get https://phoronix.com | query webpage-info
query xml
Execute XPath 1.0 query on XML input
Scalar results (Number, String, Boolean) are returned as nu scalars.
Output of the nodeset results depends on the flags used:
- No flags: returns a table with string_value column.
- You have to specify --output-string-value to include string_value in the output when using any other --output-* flags.
- --output-type includes type column with node type.
- --output-names includes local_name, prefixed_name, and namespace columns.
Usage:
> query xml {flags} <query>
Flags:
-h, --help: Display the help message for this command
-n, --namespaces <record>: map of prefixes to namespace URIs
--output-string-value: Include string_value in the nodeset output. On by default.
--output-type: Include type in the nodeset output. Off by default.
--output-names: Include local_name, prefixed_name, and namespace in the nodeset output. Off by default.
Parameters:
query <string>: xpath query
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ any │
╰───┴────────┴────────╯
Examples:
Query namespaces on the root element of an SVG file
> http get --raw https://www.w3.org/TR/SVG/images/conform/smiley.svg
| query xml '/svg:svg/namespace::*' --output-string-value --output-names --output-type --namespaces {svg: "http://www.w3.org/2000/svg"}
Query the language of Nushell blog (xml: prefix is always available)
> http get --raw https://www.nushell.sh/atom.xml
| query xml 'string(/*/@xml:lang)'
Query all XLink targets in SVG document
> http get --raw https://www.w3.org/TR/SVG/images/conform/smiley.svg
| query xml '//*/@xlink:href' --namespaces {xlink: "http://www.w3.org/1999/xlink"}
Get recent Nushell news
> http get --raw https://www.nushell.sh/atom.xml
| query xml '//atom:entry/atom:title|//atom:entry/atom:link/@href' --namespaces {atom: "http://www.w3.org/2005/Atom"}
| window 2 --stride 2
| each { {title: $in.0.string_value, link: $in.1.string_value} }
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 binary - Generate random bytes.
random bool - Generate a random boolean value.
random chars - Generate random chars uniformly distributed over ASCII letters and numbers: a-z, A-Z and 0-9.
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 uuid string of the specified version.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
random binary
Generate random bytes.
Search terms: generate, bytes
Usage:
> random binary <length>
Flags:
-h, --help: Display the help message for this command
Parameters:
length <oneof<int, filesize>>: Length of the output binary.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ binary │
╰───┴─────────┴────────╯
Examples:
Generate 16 random bytes
> random binary 16
Generate 1 random kilobyte
> random binary 1kb
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 uniformly distributed over ASCII letters and numbers: a-z, A-Z and 0-9.
Search terms: generate, character, symbol, alphanumeric
Usage:
> random chars {flags}
Flags:
-h, --help: Display the help message for this command
-l, --length <oneof<int, filesize>>: Number of chars (default 25)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Generate a string with 25 random chars
> random chars
Generate random chars with specified length
> random chars --length 20
Generate one kilobyte of random chars
> random chars --length 1kb
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<int> │
╰───┴─────────┴───────────╯
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 potential values, inclusive of both start and end values. (optional)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ int │
╰───┴─────────┴────────╯
Examples:
Generate a non-negative random integer
> random int
Generate a random integer between 0 (inclusive) and 500 (inclusive)
> random int ..500
Generate a random integer greater than or equal to 100000
> random int 100000..
Generate a random integer between -10 (inclusive) and 10 (inclusive)
> random int (-10)..10
random uuid
Generate a random uuid string of the specified version.
Search terms: generate, uuid4, uuid1, uuid3, uuid5, uuid7
Usage:
> random uuid {flags}
Flags:
-h, --help: Display the help message for this command
-v, --version <int>: The UUID version to generate (1, 3, 4, 5, 7). Defaults to 4 if not specified.
-n, --namespace <string>: The namespace for v3 and v5 UUIDs (dns, url, oid, x500). Required for v3 and v5.
-s, --name <string>: The name string for v3 and v5 UUIDs. Required for v3 and v5.
-m, --mac <string>: The MAC address (node ID) used to generate v1 UUIDs. Required for v1.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Generate a random uuid v4 string (default)
> random uuid
Generate a uuid v1 string (timestamp-based)
> random uuid -v 1 -m 00:11:22:33:44:55
Generate a uuid v3 string (namespace with MD5)
> random uuid -v 3 -n dns -s example.com
Generate a uuid v4 string (random).
> random uuid -v 4
Generate a uuid v5 string (namespace with SHA1)
> random uuid -v 5 -n dns -s example.com
Generate a uuid v7 string (timestamp + random)
> random uuid -v 7
reduce
Aggregate a list (starting from the left) 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)>: 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
reduce accumulates value from left to right, equivalent to (((1 - 2) - 3) - 4).
> [ 1 2 3 4 ] | reduce {|it, acc| $acc - $it }
-8
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
Iteratively perform string replace (from left to right): 'foobar' -> 'bazbar' -> 'quuxbar'
> [[foo baz] [baz quux]] | reduce --fold "foobar" {|it, acc| $acc | str replace $it.0 $it.1}
quuxbar
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
Merge multiple records together, making use of the fact that the accumulated value is also supplied as pipeline input to the closure.
> [{a: 1} {b: 2} {c: 3}] | reduce {|it| merge $it}
╭───┬───╮
│ a │ 1 │
│ b │ 2 │
│ c │ 3 │
╰───┴───╯
regex
Parse input with a regular expression and display the results.
Usage:
> regex <pattern>
Flags:
-h, --help: Display the help message for this command
Parameters:
pattern <string>: the regular expression to use
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ string │ table │
╰───┴────────┴────────╯
Examples:
Parse a string with a regular expression
> "hello world" | regex '(?P<first>\w+) (?P<second>\w+)'
registry
Various commands for interacting with the system registry (Windows only).
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> registry
Subcommands:
registry query - Query the Windows registry.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
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
-o, --optional: make all cell path members optional
--ignore-case: make all cell path members case insensitive
-i, --ignore-errors: ignore missing data (make all cell path members optional) (deprecated)
Parameters:
...rest <cell-path>: The names of columns to remove from the table.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
│ 2 │ list<any> │ list<any> │
╰───┴───────────┴───────────╯
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 │ │ c │ 5 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
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 │
╰───┴────────────╯
Reject item in list
> [1 2 3] | reject 1
╭───┬───╮
│ 0 │ 1 │
│ 1 │ 3 │
╰───┴───╯
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(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 custom command.
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 <oneof<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
roll
Rolling commands for tables.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Search terms: rotate, shift, move
Usage:
> roll
Subcommands:
roll down - Roll table rows down.
roll left - Roll record or table columns left.
roll right - Roll table columns right.
roll up - Roll table rows up.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
roll down
Roll table rows down.
Search terms: rotate, shift, move, row
Usage:
> roll down {flags}
Flags:
-h, --help: Display the help message for this command
-b, --by <int>: Number of rows to roll
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ table │ table │
╰───┴───────┴────────╯
Examples:
Rolls rows down of a table
> [[a b]; [1 2] [3 4] [5 6]] | roll down
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 5 │ 6 │
│ 1 │ 1 │ 2 │
│ 2 │ 3 │ 4 │
╰───┴───┴───╯
roll left
Roll record or table columns left.
Search terms: rotate, shift, move, column
Usage:
> roll left {flags}
Flags:
-h, --help: Display the help message for this command
-b, --by <int>: Number of columns to roll
-c, --cells-only: rotates columns leaving headers fixed
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
╰───┴────────┴────────╯
Examples:
Rolls columns of a record to the left
> {a:1 b:2 c:3} | roll left
╭───┬───╮
│ b │ 2 │
│ c │ 3 │
│ a │ 1 │
╰───┴───╯
Rolls columns of a table to the left
> [[a b c]; [1 2 3] [4 5 6]] | roll left
╭───┬───┬───┬───╮
│ # │ b │ c │ a │
├───┼───┼───┼───┤
│ 0 │ 2 │ 3 │ 1 │
│ 1 │ 5 │ 6 │ 4 │
╰───┴───┴───┴───╯
Rolls columns to the left without changing column names
> [[a b c]; [1 2 3] [4 5 6]] | roll left --cells-only
╭───┬───┬───┬───╮
│ # │ a │ b │ c │
├───┼───┼───┼───┤
│ 0 │ 2 │ 3 │ 1 │
│ 1 │ 5 │ 6 │ 4 │
╰───┴───┴───┴───╯
roll right
Roll table columns right.
Search terms: rotate, shift, move, column
Usage:
> roll right {flags}
Flags:
-h, --help: Display the help message for this command
-b, --by <int>: Number of columns to roll
-c, --cells-only: rotates columns leaving headers fixed
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ record │
│ 1 │ table │ table │
╰───┴────────┴────────╯
Examples:
Rolls columns of a record to the right
> {a:1 b:2 c:3} | roll right
╭───┬───╮
│ c │ 3 │
│ a │ 1 │
│ b │ 2 │
╰───┴───╯
Rolls columns to the right
> [[a b c]; [1 2 3] [4 5 6]] | roll right
╭───┬───┬───┬───╮
│ # │ c │ a │ b │
├───┼───┼───┼───┤
│ 0 │ 3 │ 1 │ 2 │
│ 1 │ 6 │ 4 │ 5 │
╰───┴───┴───┴───╯
Rolls columns to the right with fixed headers
> [[a b c]; [1 2 3] [4 5 6]] | roll right --cells-only
╭───┬───┬───┬───╮
│ # │ a │ b │ c │
├───┼───┼───┼───┤
│ 0 │ 3 │ 1 │ 2 │
│ 1 │ 6 │ 4 │ 5 │
╰───┴───┴───┴───╯
roll up
Roll table rows up.
Search terms: rotate, shift, move, row
Usage:
> roll up {flags}
Flags:
-h, --help: Display the help message for this command
-b, --by <int>: Number of rows to roll
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ table │ table │
╰───┴───────┴────────╯
Examples:
Rolls rows up
> [[a b]; [1 2] [3 4] [5 6]] | roll up
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 3 │ 4 │
│ 1 │ 5 │ 6 │
│ 2 │ 1 │ 2 │
╰───┴───┴───╯
rotate
Rotates a table or record clockwise (default) or counter-clockwise (use --ccw flag).
Usage:
> rotate {flags} ...(rest)
Flags:
-h, --help: Display the help message for this command
--ccw: rotate counter clockwise
Parameters:
...rest <string>: The names to give columns once rotated.
Input/output types:
╭───┬───────────┬────────╮
│ # │ input │ output │
├───┼───────────┼────────┤
│ 0 │ record │ table │
│ 1 │ table │ table │
│ 2 │ list<any> │ table │
│ 3 │ string │ table │
╰───┴───────────┴────────╯
Examples:
Rotate a record clockwise, producing a table (like transpose but with column order reversed)
> {a:1, b:2} | rotate
╭───┬─────────┬─────────╮
│ # │ column0 │ column1 │
├───┼─────────┼─────────┤
│ 0 │ 1 │ a │
│ 1 │ 2 │ b │
╰───┴─────────┴─────────╯
Rotate 2x3 table clockwise
> [[a b]; [1 2] [3 4] [5 6]] | rotate
╭───┬─────────┬─────────┬─────────┬─────────╮
│ # │ column0 │ column1 │ column2 │ column3 │
├───┼─────────┼─────────┼─────────┼─────────┤
│ 0 │ 5 │ 3 │ 1 │ a │
│ 1 │ 6 │ 4 │ 2 │ b │
╰───┴─────────┴─────────┴─────────┴─────────╯
Rotate table clockwise and change columns names
> [[a b]; [1 2]] | rotate col_a col_b
╭───┬───────┬───────╮
│ # │ col_a │ col_b │
├───┼───────┼───────┤
│ 0 │ 1 │ a │
│ 1 │ 2 │ b │
╰───┴───────┴───────╯
Rotate table counter clockwise
> [[a b]; [1 2]] | rotate --ccw
╭───┬─────────┬─────────╮
│ # │ column0 │ column1 │
├───┼─────────┼─────────┤
│ 0 │ b │ 2 │
│ 1 │ a │ 1 │
╰───┴─────────┴─────────╯
Rotate table counter-clockwise
> [[a b]; [1 2] [3 4] [5 6]] | rotate --ccw
╭───┬─────────┬─────────┬─────────┬─────────╮
│ # │ column0 │ column1 │ column2 │ column3 │
├───┼─────────┼─────────┼─────────┼─────────┤
│ 0 │ b │ 2 │ 4 │ 6 │
│ 1 │ a │ 1 │ 3 │ 5 │
╰───┴─────────┴─────────┴─────────┴─────────╯
Rotate table counter-clockwise and change columns names
> [[a b]; [1 2]] | rotate --ccw col_a col_b
╭───┬───────┬───────╮
│ # │ col_a │ col_b │
├───┼───────┼───────┤
│ 0 │ b │ 2 │
│ 1 │ a │ 1 │
╰───┴───────┴───────╯
run-external
Runs external command.
All externals are run with this command, whether you call it directly with run-external external or use external or ^external.
If you create a custom command with this name, that will be used instead.
Usage:
> run-external ...(command)
Flags:
-h, --help: Display the help message for this command
Parameters:
...command <oneof<glob, any>>: External command to run, with arguments.
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 "echo" "-n" "hello" | split chars
Redirect stderr from an external command into the pipeline
> run-external "nu" "-c" "print -e hello" e>| 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 <path>: 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
Show the extensions for which the save command will automatically serialize
> scope commands
| where name starts-with "to "
| insert extension { get name | str replace -r "^to " "" | $"*.($in)" }
| select extension name
| rename extension command
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
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
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 │ list<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
-o, --optional: make all cell path members optional (returns null for missing values)
--ignore-case: make all cell path members case insensitive
-i, --ignore-errors: ignore missing data (make all cell path members optional) (deprecated)
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 column even if some rows are missing that column
> [{a: a0 b: b0} {b: b1}] | select -o a
╭───┬────╮
│ # │ a │
├───┼────┤
│ 0 │ a0 │
│ 1 │ │
╰───┴────╯
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 join the characters with a pipe
> 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 <oneof<duration, int>>: increment dates by this duration (defaults to days if integer)
-d, --days <int>: number of days to print (ignored if periods is used)
-p, --periods <int>: number of periods to print
-r, --reverse: print dates in reverse
Input/output types:
╭───┬─────────┬──────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────┤
│ 0 │ nothing │ list<string> │
╰───┴─────────┴──────────────╯
Examples:
Return a list of the next 10 days in the YYYY-MM-DD format
> seq date --days 10
Return the previous 10 days in the YYYY-MM-DD format
> seq date --days 10 --reverse
Return the previous 10 days, starting today, in the MM/DD/YYYY format
> seq date --days 10 -o '%m/%d/%Y' --reverse
Return the first 10 days in January, 2020
> seq date --begin-date '2020-01-01' --end-date '2020-01-10' --increment 1day
╭───┬────────────╮
│ 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 │
╰───┴────────────╯
Return the first 10 days in January, 2020 using --days flag
> seq date --begin-date '2020-01-01' --days 10 --increment 1day
╭───┬────────────╮
│ 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 │
╰───┴────────────╯
Return the first five 5-minute periods starting January 1, 2020
> seq date --begin-date '2020-01-01' --periods 5 --increment 5min --output-format '%Y-%m-%d %H:%M:%S'
╭───┬─────────────────────╮
│ 0 │ 2020-01-01 00:00:00 │
│ 1 │ 2020-01-01 00:05:00 │
│ 2 │ 2020-01-01 00:10:00 │
│ 3 │ 2020-01-01 00:15:00 │
│ 4 │ 2020-01-01 00:20:00 │
╰───┴─────────────────────╯
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 5day
╭───┬────────────╮
│ 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 │
╰───┴────────────╯
increment defaults to days if no duration is supplied
> 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 │
╰───┴────────────╯
print every six hours starting January 1st, 2020 until January 3rd, 2020
> seq date --begin-date '2020-01-01' --end-date '2020-01-03' --increment 6hr --output-format '%Y-%m-%d %H:%M:%S'
╭───┬─────────────────────╮
│ 0 │ 2020-01-01 00:00:00 │
│ 1 │ 2020-01-01 06:00:00 │
│ 2 │ 2020-01-01 12:00:00 │
│ 3 │ 2020-01-01 18:00:00 │
│ 4 │ 2020-01-02 00:00:00 │
│ 5 │ 2020-01-02 06:00:00 │
│ 6 │ 2020-01-02 12:00:00 │
│ 7 │ 2020-01-02 18:00:00 │
│ 8 │ 2020-01-03 00:00:00 │
╰───┴─────────────────────╯
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 │ binary │ binary │
│ 2 │ 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 2 bytes of a binary value
> 0x[01 23 45 67] | skip 2
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 45 67 Eg
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)>: 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)>: 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
Use multiple arguments to write a duration with multiple units, which is unsupported by duration literals
> sleep 1min 30sec
Send output after 1sec
> sleep 1sec; echo done
slice
Return only the selected rows.
Search terms: filter, head, tail, range
Usage:
> slice <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] | slice 4..5
╭───┬───╮
│ 0 │ 4 │
│ 1 │ 5 │
╰───┴───╯
Get the last 2 items
> [0,1,2,3,4,5] | slice (-2)..
╭───┬───╮
│ 0 │ 4 │
│ 1 │ 5 │
╰───┴───╯
Get the next to last 2 items
> [0,1,2,3,4,5] | slice (-3)..-2
╭───┬───╮
│ 0 │ 3 │
│ 1 │ 4 │
╰───┴───╯
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 alphanumeric strings in natural order
> [foo1 foo10 foo9] | sort -n
╭───┬───────╮
│ 0 │ foo1 │
│ 1 │ foo9 │
│ 2 │ foo10 │
╰───┴───────╯
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 cell path or closure.
Usage:
> sort-by {flags} ...(comparator)
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
-n, --natural: Sort alphanumeric string-based data naturally (1, 9, 10, 99, 100, ...)
-c, --custom: Use closures to specify a custom sort order, rather than to compute a comparison key
Parameters:
...comparator <oneof<cell-path, closure(any), closure(any, any)>>: The cell path(s) or closure(s) to compare elements 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 │
╰───┴────────┴───────╯
Sort by a nested value
> [[name info]; [Cairo {founded: 969}] [Kyoto {founded: 794}]] | sort-by info.founded
╭───┬───────┬───────────────────╮
│ # │ name │ info │
├───┼───────┼───────────────────┤
│ 0 │ Kyoto │ ╭─────────┬─────╮ │
│ │ │ │ founded │ 794 │ │
│ │ │ ╰─────────┴─────╯ │
│ 1 │ Cairo │ ╭─────────┬─────╮ │
│ │ │ │ founded │ 969 │ │
│ │ │ ╰─────────┴─────╯ │
╰───┴───────┴───────────────────╯
Sort by the last value in a list
> [[2 50] [10 1]] | sort-by { last }
╭───┬────────────╮
│ 0 │ ╭───┬────╮ │
│ │ │ 0 │ 10 │ │
│ │ │ 1 │ 1 │ │
│ │ ╰───┴────╯ │
│ 1 │ ╭───┬────╮ │
│ │ │ 0 │ 2 │ │
│ │ │ 1 │ 50 │ │
│ │ ╰───┴────╯ │
╰───┴────────────╯
Sort in a custom order
> [7 3 2 8 4] | sort-by -c {|a, b| $a < $b}
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 3 │
│ 2 │ 4 │
│ 3 │ 7 │
│ 4 │ 8 │
╰───┴───╯
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 <oneof<path, nothing>>: The filepath to the script file to source (null for no-op).
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
Sourcing null is a no-op.
> source null
Source can be used with const variables.
> const file = if $nu.is-interactive { "interactive.nu" } else { null }; source $file
source-env
Source the environment from a source file into the current environment.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> source-env <filename>
Flags:
-h, --help: Display the help message for this command
Parameters:
filename <oneof<string, nothing>>: The filepath to the script file to source the environment from (null for no-op).
Examples:
Sources the environment from foo.nu in the current context
> source-env foo.nu
Sourcing null is a no-op.
> source-env null
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 cell-path - Split a cell-path into its components.
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 cell-path
Split a cell-path into its components.
Search terms: convert
Usage:
> split cell-path
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬───────────┬─────────────────────────────────────────────────────────────╮
│ # │ input │ output │
├───┼───────────┼─────────────────────────────────────────────────────────────┤
│ 0 │ cell-path │ list<any> │
│ 1 │ cell-path │ list<record<value: any, optional: bool, insensitive: bool>> │
╰───┴───────────┴─────────────────────────────────────────────────────────────╯
Examples:
Split a cell-path into its components
> $.5?.c | split cell-path
╭───┬───────┬──────────┬─────────────╮
│ # │ value │ optional │ insensitive │
├───┼───────┼──────────┼─────────────┤
│ 0 │ 5 │ true │ false │
│ 1 │ c │ false │ false │
╰───┴───────┴──────────┴─────────────╯
Split a complex cell-path
> $.a!.b?.1."2"."c.d" | split cell-path
╭───┬───────┬──────────┬─────────────╮
│ # │ value │ optional │ insensitive │
├───┼───────┼──────────┼─────────────┤
│ 0 │ a │ false │ true │
│ 1 │ b │ true │ false │
│ 2 │ 1 │ false │ false │
│ 3 │ 2 │ false │ false │
│ 4 │ c.d │ false │ false │
╰───┴───────┴──────────┴─────────────╯
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 │ ╭───┬───╮ │
│ │ │ 0 │ h │ │
│ │ │ 1 │ e │ │
│ │ │ 2 │ l │ │
│ │ │ 3 │ l │ │
│ │ │ 4 │ o │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ w │ │
│ │ │ 1 │ o │ │
│ │ │ 2 │ r │ │
│ │ │ 3 │ l │ │
│ │ │ 4 │ d │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
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
-n, --number <int>: Split into maximum number of items
-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 into columns, last column may contain the delimiter
> ['author: Salina Yoon' r#'title: Where's Ellie?: A Hide-and-Seek Book'#] | split column --number 2 ': ' key value
╭───┬────────┬──────────────────────────────────────╮
│ # │ key │ value │
├───┼────────┼──────────────────────────────────────┤
│ 0 │ author │ Salina Yoon │
│ 1 │ title │ Where's Ellie?: A Hide-and-Seek Book │
╰───┴────────┴──────────────────────────────────────╯
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
--split <string>: Whether to split lists before, after, or on (default) the separator
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 │ ╭───┬───╮ │
│ │ │ 0 │ a │ │
│ │ │ 1 │ b │ │
│ │ │ 2 │ c │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ e │ │
│ │ │ 1 │ f │ │
│ │ │ 2 │ g │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
Split a list of lists into two lists of lists
> [[1,2], [2,3], [3,4]] | split list [2,3]
╭───┬───────────────────╮
│ 0 │ ╭───┬───────────╮ │
│ │ │ 0 │ ╭───┬───╮ │ │
│ │ │ │ │ 0 │ 1 │ │ │
│ │ │ │ │ 1 │ 2 │ │ │
│ │ │ │ ╰───┴───╯ │ │
│ │ ╰───┴───────────╯ │
│ 1 │ ╭───┬───────────╮ │
│ │ │ 0 │ ╭───┬───╮ │ │
│ │ │ │ │ 0 │ 3 │ │ │
│ │ │ │ │ 1 │ 4 │ │ │
│ │ │ │ ╰───┴───╯ │ │
│ │ ╰───┴───────────╯ │
╰───┴───────────────────╯
Split a list of chars into two lists
> [a, b, c, d, a, e, f, g] | split list a
╭───┬────────────────╮
│ 0 │ [list 0 items] │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ b │ │
│ │ │ 1 │ c │ │
│ │ │ 2 │ d │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ e │ │
│ │ │ 1 │ f │ │
│ │ │ 2 │ g │ │
│ │ ╰───┴───╯ │
╰───┴────────────────╯
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 │ ╭───┬───╮ │
│ │ │ 0 │ a │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ c │ │
│ │ │ 1 │ d │ │
│ │ │ 2 │ a │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ f │ │
│ │ │ 1 │ g │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
Split a list of numbers on multiples of 3
> [1 2 3 4 5 6 7 8 9 10] | split list {|e| $e mod 3 == 0 }
╭───┬────────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 4 │ │
│ │ │ 1 │ 5 │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ 7 │ │
│ │ │ 1 │ 8 │ │
│ │ ╰───┴───╯ │
│ 3 │ ╭───┬────╮ │
│ │ │ 0 │ 10 │ │
│ │ ╰───┴────╯ │
╰───┴────────────╯
Split a list of numbers into lists ending with 0
> [1 2 0 3 4 5 0 6 0 0 7] | split list --split after 0
╭───┬───────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ │ 2 │ 0 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 3 │ │
│ │ │ 1 │ 4 │ │
│ │ │ 2 │ 5 │ │
│ │ │ 3 │ 0 │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ 6 │ │
│ │ │ 1 │ 0 │ │
│ │ ╰───┴───╯ │
│ 3 │ ╭───┬───╮ │
│ │ │ 0 │ 0 │ │
│ │ ╰───┴───╯ │
│ 4 │ ╭───┬───╮ │
│ │ │ 0 │ 7 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
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
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 or URL to open.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ 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 the default browser
> start https://www.nushell.sh
Open an application-registered protocol URL
> start obsidian://open?vault=Test
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:
-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
-h, --help: Display the help message for this command
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}
Create an in-memory sqlite database with a json column
> stor create --table-name files_with_md --columns {file: str, metadata: jsonb}
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:
-t, --table-name (required parameter) <string>: name of the table you want to delete or delete from
-h, --help: Display the help message for this command
-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:
-f, --file-name (required parameter) <string>: file name to export the sqlite in-memory database to
-h, --help: Display the help message for this command
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:
-f, --file-name (required parameter) <string>: file name to import the sqlite in-memory database from
-h, --help: Display the help message for this command
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:
-t, --table-name (required parameter) <string>: name of the table you want to insert into
-h, --help: Display the help message for this command
-d, --data-record <record>: a record of column names and column values to insert into the specified table
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
│ 1 │ record │ table │
│ 2 │ table │ table │
│ 3 │ any │ table │
╰───┴─────────┴────────╯
Examples:
Insert data in 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}
Insert data through pipeline input as a record of column-name and column-value pairs
> {bool1: true, int1: 5, float1: 1.1, str1: fdncred, datetime1: 2023-04-17} | stor insert --table-name nudb
Insert data through pipeline input as a table literal
> [[bool1 int1 float1]; [true 5 1.1], [false 8 3.14]] | stor insert --table-name nudb
Insert ls entries
> ls | stor insert --table-name files
Insert nu records as json data
> ls -l | each {{file: $in.name, metadata: ($in | reject name)}} | stor insert --table-name files_with_md
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:
-t, --table-name (required parameter) <string>: name of the table you want to insert into
-h, --help: Display the help message for this command
-u, --update-record <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 │
│ 1 │ record │ table │
│ 2 │ any │ 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"
Update the in-memory sqlite database through pipeline input
> {str1: nushell datetime1: 2020-04-17} | stor update --table-name nudb
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 camel-case - Convert a string to camelCase.
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 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 kebab-case - Convert a string to kebab-case.
str length - Output the length of any strings in the pipeline.
str pascal-case - Convert a string to PascalCase.
str replace - Find and replace text.
str reverse - Reverse every string in the pipeline.
str screaming-snake-case - Convert a string to SCREAMING_SNAKE_CASE.
str snake-case - Convert a string to snake_case.
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 first character of a string is index 0.
str title-case - Convert a string to Title Case.
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 camel-case
Convert a string to camelCase.
Search terms: convert, style, caps, convention
Usage:
> str camel-case ...(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:
convert a string to camelCase
> 'NuShell' | str camel-case
nuShell
convert a string to camelCase
> 'this-is-the-first-case' | str camel-case
thisIsTheFirstCase
convert a string to camelCase
> 'this_is_the_second_case' | str camel-case
thisIsTheSecondCase
convert a column from a table to camelCase
> [[lang, gems]; [nu_test, 100]] | str camel-case lang
╭───┬────────┬──────╮
│ # │ lang │ gems │
├───┼────────┼──────┤
│ 0 │ nuTest │ 100 │
╰───┴────────┴──────╯
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
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 │
╰───┴───────╯
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 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 │
╰───┴──────╯
Supports zero padding in numeric ranges.
> "A{08..10}B{11..013}C" | str expand
╭───┬──────────╮
│ 0 │ A08B011C │
│ 1 │ A08B012C │
│ 2 │ A08B013C │
│ 3 │ A09B011C │
│ 4 │ A09B012C │
│ 5 │ A09B013C │
│ 6 │ A10B011C │
│ 7 │ A10B012C │
│ 8 │ A10B013C │
╰───┴──────────╯
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 kebab-case
Convert a string to kebab-case.
Search terms: convert, style, hyphens, convention
Usage:
> str kebab-case ...(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 │ table │ table │
│ 2 │ record │ record │
│ 3 │ list<string> │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
convert a string to kebab-case
> 'NuShell' | str kebab-case
nu-shell
convert a string to kebab-case
> 'thisIsTheFirstCase' | str kebab-case
this-is-the-first-case
convert a string to kebab-case
> 'THIS_IS_THE_SECOND_CASE' | str kebab-case
this-is-the-second-case
convert a column from a table to kebab-case
> [[lang, gems]; [nuTest, 100]] | str kebab-case lang
╭───┬─────────┬──────╮
│ # │ lang │ gems │
├───┼─────────┼──────┤
│ 0 │ nu-test │ 100 │
╰───┴─────────┴──────╯
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 in grapheme clusters (all visible chars have length 1)
-b, --utf-8-bytes: count length in UTF-8 bytes (default; all non-ASCII chars have length 2+)
-c, --chars: count length in chars
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 in bytes
> 'hello' | str length
5
Count length of a string in grapheme clusters
> '🇯🇵ほげ ふが ぴよ' | str length --grapheme-clusters
9
Return the lengths of multiple strings in bytes
> ['hi' 'there'] | str length
╭───┬───╮
│ 0 │ 2 │
│ 1 │ 5 │
╰───┴───╯
Return the lengths of a string in chars
> 'hällo' | str length --chars
5
str pascal-case
Convert a string to PascalCase.
Search terms: convert, style, caps, upper, convention
Usage:
> str pascal-case ...(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 │ table │ table │
│ 2 │ record │ record │
│ 3 │ list<string> │ list<string> │
╰───┴──────────────┴──────────────╯
Examples:
convert a string to PascalCase
> 'nu-shell' | str pascal-case
NuShell
convert a string to PascalCase
> 'this-is-the-first-case' | str pascal-case
ThisIsTheFirstCase
convert a string to PascalCase
> 'this_is_the_second_case' | str pascal-case
ThisIsTheSecondCase
convert a column from a table to PascalCase
> [[lang, gems]; [nu_test, 100]] | str pascal-case lang
╭───┬────────┬──────╮
│ # │ lang │ gems │
├───┼────────┼──────┤
│ 0 │ NuTest │ 100 │
╰───┴────────┴──────╯
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 contents with capture group using regular expression, with escapes
> 'hello=world' | str replace -r '\$?(?<varname>.*)=(?<value>.*)' '$$$varname = $value'
$hello = world
Find and replace all occurrences of found string using regular expression
> 'abc abc abc' | str replace --all --regex 'b' 'z'
azc azc azc
Find and replace all occurrences of found 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 found 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 screaming-snake-case
Convert a string to SCREAMING_SNAKE_CASE.
Search terms: convert, style, underscore, convention
Usage:
> str screaming-snake-case ...(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:
convert a string to SCREAMING_SNAKE_CASE
> "NuShell" | str screaming-snake-case
NU_SHELL
convert a string to SCREAMING_SNAKE_CASE
> "this_is_the_second_case" | str screaming-snake-case
THIS_IS_THE_SECOND_CASE
convert a string to SCREAMING_SNAKE_CASE
> "this-is-the-first-case" | str screaming-snake-case
THIS_IS_THE_FIRST_CASE
convert a column from a table to SCREAMING_SNAKE_CASE
> [[lang, gems]; [nu_test, 100]] | str screaming-snake-case lang
╭───┬─────────┬──────╮
│ # │ lang │ gems │
├───┼─────────┼──────┤
│ 0 │ NU_TEST │ 100 │
╰───┴─────────┴──────╯
str snake-case
Convert a string to snake_case.
Search terms: convert, style, underscore, lower, convention
Usage:
> str snake-case ...(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:
convert a string to snake_case
> "NuShell" | str snake-case
nu_shell
convert a string to snake_case
> "this_is_the_second_case" | str snake-case
this_is_the_second_case
convert a string to snake_case
> "this-is-the-first-case" | str snake-case
this_is_the_first_case
convert a column from a table to snake_case
> [[lang, gems]; [nuTest, 100]] | str snake-case lang
╭───┬─────────┬──────╮
│ # │ lang │ gems │
├───┼─────────┼──────┤
│ 0 │ nu_test │ 100 │
╰───┴─────────┴──────╯
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 │
│ unicode-width │ 38 │
╰───────────────┴────╯
Counts unicode characters
> '今天天气真好' | str stats
╭───────────────┬────╮
│ lines │ 1 │
│ words │ 6 │
│ bytes │ 18 │
│ chars │ 6 │
│ graphemes │ 6 │
│ unicode-width │ 12 │
╰───────────────┴────╯
Counts Unicode characters correctly in a string
> "Amélie Amelie" | str stats
╭───────────────┬────╮
│ lines │ 1 │
│ words │ 2 │
│ bytes │ 15 │
│ chars │ 14 │
│ graphemes │ 13 │
│ unicode-width │ 13 │
╰───────────────┴────╯
str substring
Get part of a string. Note 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..11
nushell
Count indexes and split using grapheme clusters
> '🇯🇵ほげ ふが ぴよ' | str substring --grapheme-clusters 4..5
ふが
sub string by negative index
> 'good nushell' | str substring 5..-2
nushel
str title-case
Convert a string to Title Case.
Search terms: convert, style, convention
Usage:
> str title-case ...(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:
convert a string to Title Case
> 'nu-shell' | str title-case
Nu Shell
convert a string to Title Case
> 'this is a test case' | str title-case
This Is A Test Case
convert a column from a table to Title Case
> [[title, count]; ['nu test', 100]] | str title-case title
╭───┬─────────┬───────╮
│ # │ title │ count │
├───┼─────────┼───────┤
│ 0 │ Nu Test │ 100 │
╰───┴─────────┴───────╯
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.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> sys
Subcommands:
sys cpu - View information about the system CPUs.
sys disks - View information about the system disks.
sys host - View information about the system host.
sys mem - View information about the system memory.
sys net - View information about the system network interfaces.
sys temp - View the temperatures of system components.
sys users - View information about the users on the system.
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
sys cpu
View information about the system CPUs.
Usage:
> sys cpu {flags}
Flags:
-h, --help: Display the help message for this command
-l, --long: Get all available columns (slower, needs to sample CPU over time)
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Show info about the system CPUs
> sys cpu
sys disks
View information about the system disks.
Usage:
> sys disks
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Show info about the system disks
> sys disks
sys host
View information about the system host.
Usage:
> sys host
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
Show info about the system host
> sys host
sys mem
View information about the system memory.
Usage:
> sys mem
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
Show info about the system memory
> sys mem
sys net
View information about the system network interfaces.
Usage:
> sys net
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Show info about the system network
> sys net
sys temp
View the temperatures of system components.
Some system components do not support temperature readings, so this command may return an empty list if no components support temperature.
Usage:
> sys temp
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Show the system temperatures
> sys temp
sys users
View information about the users on the system.
Usage:
> sys users
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Show info about the system users
> sys users
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] [3 [4 4]]] | table --expand
╭───┬───┬───────────╮
│ # │ a │ b │
├───┼───┼───────────┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ ╭───┬───╮ │
│ │ │ │ 0 │ 4 │ │
│ │ │ │ 1 │ 4 │ │
│ │ │ ╰───┴───╯ │
╰───┴───┴───────────╯
Render data in table view (collapsed)
> [[a b]; [1 2] [3 [4 4]]] | table --collapse
╭───┬───╮
│ a │ b │
├───┼───┤
│ 1 │ 2 │
├───┼───┤
│ 3 │ 4 │
│ ├───┤
│ │ 4 │
╰───┴───╯
Change the table theme to the specified theme for a single run
> [[a b]; [1 2] [3 [4 4]]] | table --theme basic
Force showing of the #/index column for a single run
> [[a b]; [1 2] [3 [4 4]]] | table -i true
Set the starting number of the #/index column to 100 for a single run
> [[a b]; [1 2] [3 [4 4]]] | table -i 100
Force hiding of the #/index column for a single run
> [[a b]; [1 2] [3 [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
Length: 2 (0x2) bytes | printable whitespace ascii_other non_ascii
00000000: 01 23 •#
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)>: The predicate that element(s) must not match.
Input/output types:
╭───┬───────────┬───────────╮
│ # │ input │ output │
├───┼───────────┼───────────┤
│ 0 │ 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)>: 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
> nu -c '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
Do something with a value on another thread, while also passing through the value
> 10000 | tee { 1..$in | print } | $in * 5
50000
term
Commands for querying information about the terminal.
You must use one of the following subcommands. Using this command as-is will only produce this help message.
Usage:
> term
Subcommands:
term query - Query the terminal for information.
term size - Returns a record containing the number of columns (width) and rows (height) of the terminal.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
term query
Query the terminal for information.
Print the given query, and read the immediate result from stdin.
The standard input will be read right after query is printed, and consumed until the terminator
sequence is encountered. The terminator is not included in the output.
If terminator is not supplied, input will be read until Ctrl-C is pressed.
If prefix is supplied, input's initial bytes will be validated against it.
The prefix is not included in the output.
Usage:
> term query {flags} <query>
Flags:
-h, --help: Display the help message for this command
-p, --prefix <oneof<binary, string>>: Prefix sequence for the expected reply.
-t, --terminator <oneof<binary, string>>: Terminator sequence for the expected reply.
-k, --keep: Include prefix and terminator in the output.
Parameters:
query <oneof<binary, string>>: The query that will be printed to stdout.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ binary │
╰───┴─────────┴────────╯
Examples:
Get cursor position.
> term query (ansi cursor_position) --prefix (ansi csi) --terminator 'R'
Get terminal background color.
> term query $'(ansi osc)10;?(ansi st)' --prefix $'(ansi osc)10;' --terminator (ansi st)
Get terminal background color. (some terminals prefer char bel rather than ansi st as string terminator)
> term query $'(ansi osc)10;?(char bel)' --prefix $'(ansi osc)10;' --terminator (char bel)
Read clipboard content on terminals supporting OSC-52.
> term query $'(ansi osc)52;c;?(ansi st)' --prefix $'(ansi osc)52;c;' --terminator (ansi st)
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 how long it takes a closure to run.
Any pipeline input given to this command is passed to the closure. Note that streaming inputs may affect timing results, and it is recommended to add a collect command before this if the input is a stream.
This command will bubble up any errors encountered when running the closure. The return pipeline of the closure is collected into a value and then discarded.
Search terms: timing, timer, benchmark, measure
Usage:
> timeit <command>
Flags:
-h, --help: Display the help message for this command
Parameters:
command <closure()>: The closure to run.
Input/output types:
╭───┬─────────┬──────────╮
│ # │ input │ output │
├───┼─────────┼──────────┤
│ 0 │ any │ duration │
│ 1 │ nothing │ duration │
╰───┴─────────┴──────────╯
Examples:
Time a closure containing one command
> timeit { sleep 500ms }
Time a closure with an input value
> 'A really long string' | timeit { split chars }
Time a closure with an input stream
> open some_file.txt | collect | timeit { split chars }
Time a closure containing a pipeline
> timeit { open some_file.txt | split chars }
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 html - Convert table into simple HTML.
to json - Converts table data into JSON text.
to md - Convert table into simple Markdown.
to msgpack - Convert Nu values into MessagePack.
to msgpackz - Convert Nu values into brotli-compressed MessagePack.
to nuon - Converts table data into Nuon (Nushell Object Notation) text.
to plist (plugin) - Convert Nu values into plist
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.
to yml - 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
--columns <list<string>>: the names (in order) of the columns to use
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ string │
│ 1 │ table │ string │
╰───┴────────┴────────╯
Examples:
Outputs a CSV string representing the contents of this table
> [[foo bar]; [1 2]] | to csv
foo,bar
1,2
Outputs a CSV string representing the contents of this table
> [[foo bar]; [1 2]] | to csv --separator ';'
foo;bar
1;2
Outputs a CSV string representing the contents of this record
> {a: 1 b: 2} | to csv
a,b
1,2
Outputs a CSV stream with column names pre-determined
> [[foo bar baz]; [1 2 3]] | to csv --columns [baz foo]
baz,foo
3,1
to html
Convert table into simple HTML.
Screenshots of the themes can be browsed here: https://github.com/mbadolato/iTerm2-Color-Schemes.
Usage:
> to html {flags}
Flags:
-h, --help: Display the help message for this command
-c, --html-color: change ansi colors to html colors
-n, --no-color: remove all ansi colors in output
-d, --dark: indicate your background color is a darker color
-p, --partial: only output the html for the content itself
-t, --theme <string>: the name of the theme to use (github, blulocolight, ...); case-insensitive
-l, --list: produce a color table of all available themes
-r, --raw: do not escape html tags
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
│ 1 │ any │ string │
╰───┴─────────┴────────╯
Examples:
Outputs an HTML string representing the contents of this table
> [[foo bar]; [1 2]] | to html
<html><style>body { background-color:white;color:black; }</style><body><table><thead><tr><th>foo</th><th>bar</th></tr></thead><tbody><tr><td>1</td><td>2</td></tr></tbody></table></body></html>
Outputs an HTML string using a record of xml data
> {tag: a attributes: { style: "color: red" } content: ["hello!"] } | to xml | to html --raw
<html><style>body { background-color:white;color:black; }</style><body><a style="color: red">hello!</a></body></html>
Optionally, only output the html for the content itself
> [[foo bar]; [1 2]] | to html --partial
<div style="background-color:white;color:black;"><table><thead><tr><th>foo</th><th>bar</th></tr></thead><tbody><tr><td>1</td><td>2</td></tr></tbody></table></div>
Optionally, output the string with a dark background
> [[foo bar]; [1 2]] | to html --dark
<html><style>body { background-color:black;color:white; }</style><body><table><thead><tr><th>foo</th><th>bar</th></tr></thead><tbody><tr><td>1</td><td>2</td></tr></tbody></table></body></html>
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 and trailing line ending
-i, --indent <number>: specify indentation width
-t, --tabs <number>: specify indentation tab quantity
-s, --serialize: serialize nushell types that cannot be deserialized
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
-c, --center <list<cell-path>>: Formats the Markdown table to center given columns
-m, --escape-md: Escapes Markdown special characters
-t, --escape-html: Escapes HTML special characters
-a, --escape-all: Escapes both Markdown and HTML special characters
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
Separate list into markdown tables
> [ {foo: 1, bar: 2} {foo: 3, bar: 4} {foo: 5}] | to md --per-element
| foo | bar |
| --- | --- |
| 1 | 2 |
| 3 | 4 |
| foo |
| --- |
| 5 |
Center a column of a markdown table
> [ {foo: 1, bar: 2} {foo: 3, bar: 4}] | to md --pretty --center [bar]
| foo | bar |
| --- |:---:|
| 1 | 2 |
| 3 | 4 |
Escape markdown special characters
> [ {foo: "_1_", bar: "\# 2"} {foo: "[3]", bar: "4|5"}] | to md --escape-md
| foo | bar |
| --- | --- |
| \_1\_ | \# 2 |
| \[3\] | 4\|5 |
Escape html special characters
> [ {a: p, b: "<p>Welcome to nushell</p>"}] | to md --escape-html
| a | b |
| --- | --- |
| p | <p>Welcome to nushell</p> |
to msgpack
Convert Nu values into MessagePack.
Not all values are representable as MessagePack.
The datetime extension type is used for dates. Binaries are represented with
the native MessagePack binary type. Most other types are represented in an
analogous way to to json, and may not convert to the exact same type when
deserialized with from msgpack.
MessagePack: https://msgpack.org/
Usage:
> to msgpack {flags}
Flags:
-h, --help: Display the help message for this command
-s, --serialize: serialize nushell types that cannot be deserialized
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ binary │
╰───┴───────┴────────╯
Examples:
Convert a list of values to MessagePack
> [foo, 42, false] | to msgpack
Length: 7 (0x7) bytes | printable whitespace ascii_other non_ascii
00000000: 93 a3 66 6f 6f 2a c2 ××foo*×
Convert a range to a MessagePack array
> 1..10 | to msgpack
Length: 11 (0xb) bytes | printable whitespace ascii_other non_ascii
00000000: 9a 01 02 03 04 05 06 07 08 09 0a ו•••••••__
Convert a table to MessagePack
> [
[event_name time];
['Apollo 11 Landing' 1969-07-24T16:50:35]
['Nushell first commit' 2019-05-10T09:59:12-07:00]
] | to msgpack
Length: 95 (0x5f) bytes | printable whitespace ascii_other non_ascii
00000000: 92 82 aa 65 76 65 6e 74 5f 6e 61 6d 65 b1 41 70 ×××event_name×Ap
00000010: 6f 6c 6c 6f 20 31 31 20 4c 61 6e 64 69 6e 67 a4 ollo 11 Landing×
00000020: 74 69 6d 65 c7 0c ff 00 00 00 00 ff ff ff ff ff time×_×0000×××××
00000030: 2c ab 5b 82 aa 65 76 65 6e 74 5f 6e 61 6d 65 b4 ,×[××event_name×
00000040: 4e 75 73 68 65 6c 6c 20 66 69 72 73 74 20 63 6f Nushell first co
00000050: 6d 6d 69 74 a4 74 69 6d 65 d6 ff 5c d5 ad e0 mmit×time××\×××
to msgpackz
Convert Nu values into brotli-compressed MessagePack.
This is the format used by the plugin registry file ($nu.plugin-path).
Usage:
> to msgpackz {flags}
Flags:
-h, --help: Display the help message for this command
-q, --quality <int>: Quality of brotli compression (default 3)
-w, --window-size <int>: Window size for brotli compression (default 20)
-s, --serialize: serialize nushell types that cannot be deserialized
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ binary │
╰───┴───────┴────────╯
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 (overwrites -i and -t)
-i, --indent <number>: specify indentation width
-t, --tabs <number>: specify indentation tab quantity
-s, --serialize: serialize nushell types that cannot be deserialized
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
]
}
A more complex record with --raw
> {date: 2000-01-01, data: [1 [2 3] 4.56]} | to nuon --raw
{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}
Flags:
-h, --help: Display the help message for this command
-n, --no-newline: Do not append a newline to the end of the text
-s, --serialize: serialize nushell types that cannot be deserialized
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ string │
╰───┴───────┴────────╯
Examples:
Outputs data as simple text with a trailing newline
> [1] | to text
1
Outputs data as simple text without a trailing newline
> [1] | to text --no-newline
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}
Flags:
-h, --help: Display the help message for this command
-s, --serialize: serialize nushell types that cannot be deserialized
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
foo = 1
bar = "qwe"
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
--columns <list<string>>: the names (in order) of the columns to use
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ record │ string │
│ 1 │ table │ string │
╰───┴────────┴────────╯
Examples:
Outputs a TSV string representing the contents of this table
> [[foo bar]; [1 2]] | to tsv
foobar
12
Outputs a TSV string representing the contents of this record
> {a: 1 b: 2} | to tsv
ab
12
Outputs a TSV stream with column names pre-determined
> [[foo bar baz]; [1 2 3]] | to tsv --columns [baz foo]
bazfoo
31
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}
Flags:
-h, --help: Display the help message for this command
-s, --serialize: serialize nushell types that cannot be deserialized
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ string │
╰───┴───────┴────────╯
Examples:
Outputs a YAML string representing the contents of this table
> [[foo bar]; ["1" "2"]] | to yaml
- foo: '1'
bar: '2'
to yml
Convert table into .yaml/.yml text.
Usage:
> to yml {flags}
Flags:
-h, --help: Display the help message for this command
-s, --serialize: serialize nushell types that cannot be deserialized
Input/output types:
╭───┬───────┬────────╮
│ # │ input │ output │
├───┼───────┼────────┤
│ 0 │ any │ string │
╰───┴───────┴────────╯
Examples:
Outputs a YAML string representing the contents of this table
> [[foo bar]; ["1" "2"]] | to yml
- foo: '1'
bar: '2'
touch
Creates one or more files.
Search terms: create, file, coreutils
Usage:
> touch {flags} ...(files)
Flags:
-h, --help: Display the help message for this command
-r, --reference <path>: Use the access and modification times of the reference file/directory instead of the current time
-t, --timestamp <datetime>: Use the given timestamp instead of the current time
-d, --date <string>: Use the given time instead of the current time. This can be a full timestamp or it can be relative to either the current time or reference file time (if given). For more information, see https://www.gnu.org/software/coreutils/manual/html_node/touch-invocation.html
-m, --modified: Change only the modification time (if used with -a, access time is changed too)
-a, --access: Change only the access time (if used with -m, modification time is changed too)
-c, --no-create: Don't create the file if it doesn't exist
-s, --no-deref: Affect each symbolic link instead of any referenced file (only for systems that can change the timestamps of a symlink). Ignored if touching stdout
Parameters:
...files <oneof<glob, path>>: The file(s) to create. '-' is used to represent stdout.
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 and accessed time of all files with the .json extension to today's date
> touch *.json
Changes the last accessed and modified times of files a, b and c to the current time but yesterday
> touch -d "yesterday" a b c
Changes the last modified time of files 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 datetime
> touch -a -t 2019-08-24T12:30:30 fixture.json
Change the last accessed and modified times of stdout
> touch -
Changes the last accessed and modified times of file a to 1 month before "fixture.json"'s last modified time
> touch -r fixture.json -d "-1 month" a
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: use the first input column as the table header-row (or keynames when combined with --as-record)
-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 closure.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
Usage:
> try <try_block> (catch <catch_closure>)
Flags:
-h, --help: Display the help message for this command
Parameters:
try_block <block>: Block to run.
"catch" + <oneof<closure(), closure(any)>>: Closure to run if try block fails. (optional)
Examples:
Try to run a division by zero
> try { 1 / 0 }
Try to run a division by zero and return a string instead
> try { 1 / 0 } catch { 'divided by zero' }
divided by zero
Try to run a division by zero and report the message
> try { 1 / 0 } catch { |err| $err.msg }
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"
uname
Print certain system information using uutils/coreutils uname.
Search terms: system, coreutils
Usage:
> uname
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Print all information
> uname
uniq
Return the distinct values in the input.
Search terms: distinct, deduplicate, count
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.
When updating a column, the closure will be run for each row, and the current row will be passed as the first argument. Referencing $in inside the closure will provide the value at the column for the current row.
When updating a specific index, the closure will instead be run once. The first argument to the closure and the $in value will both be the current value at the index.
Usage:
> update <field> <replacement value>
Subcommands:
update cells - Update the table cells.
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 │
╰───┴─────────┴──────────────────╯
Implicitly use the $in value in a closure to update 'authors'
> [[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 │
╰───┴───╯
update cells
Update the table cells.
Usage:
> update cells {flags} <closure>
Flags:
-h, --help: Display the help message for this command
-c, --columns <list<any>>: list of columns to update
Parameters:
closure <closure(any)>: The closure to run an update for each cell.
Input/output types:
╭───┬────────┬────────╮
│ # │ input │ output │
├───┼────────┼────────┤
│ 0 │ table │ table │
│ 1 │ record │ record │
╰───┴────────┴────────╯
Examples:
Update the zero value cells to empty strings.
> [
["2021-04-16", "2021-06-10", "2021-09-18", "2021-10-15", "2021-11-16", "2021-11-17", "2021-11-18"];
[ 37, 0, 0, 0, 37, 0, 0]
] | update cells { |value|
if $value == 0 {
""
} else {
$value
}
}
╭───┬────────────┬────────────┬────────────┬────────────┬────────────┬────────────┬────────────╮
│ # │ 2021-04-16 │ 2021-06-10 │ 2021-09-18 │ 2021-10-15 │ 2021-11-16 │ 2021-11-17 │ 2021-11-18 │
├───┼────────────┼────────────┼────────────┼────────────┼────────────┼────────────┼────────────┤
│ 0 │ 37 │ │ │ │ 37 │ │ │
╰───┴────────────┴────────────┴────────────┴────────────┴────────────┴────────────┴────────────╯
Update the zero value cells to empty strings in 2 last columns.
> [
["2021-04-16", "2021-06-10", "2021-09-18", "2021-10-15", "2021-11-16", "2021-11-17", "2021-11-18"];
[ 37, 0, 0, 0, 37, 0, 0]
] | update cells -c ["2021-11-18", "2021-11-17"] { |value|
if $value == 0 {
""
} else {
$value
}
}
╭───┬────────────┬────────────┬────────────┬────────────┬────────────┬────────────┬────────────╮
│ # │ 2021-04-16 │ 2021-06-10 │ 2021-09-18 │ 2021-10-15 │ 2021-11-16 │ 2021-11-17 │ 2021-11-18 │
├───┼────────────┼────────────┼────────────┼────────────┼────────────┼────────────┼────────────┤
│ 0 │ 37 │ 0 │ 0 │ 0 │ 37 │ │ │
╰───┴────────────┴────────────┴────────────┴────────────┴────────────┴────────────┴────────────╯
Update each value in a record.
> {a: 1, b: 2, c: 3} | update cells { $in + 10 }
╭───┬────╮
│ a │ 11 │
│ b │ 12 │
│ c │ 13 │
╰───┴────╯
upsert
Update an existing column to have a new value, or insert a new column.
When updating or inserting a column, the closure will be run for each row, and the current row will be passed as the first argument. Referencing $in inside the closure will provide the value at the column for the current row or null if the column does not exist.
When updating a specific index, the closure will instead be run once. The first argument to the closure and the $in value will both be the current value at the index. If the command is inserting at the end of a list or table, then both of these values will be null.
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 │
╰───┴───╯
Upsert into a nested path, creating new values as needed
> [{} {a: [{}]}] | upsert a.0.b "value"
╭───┬───────────────╮
│ # │ a │
├───┼───────────────┤
│ 0 │ ╭───┬───────╮ │
│ │ │ # │ b │ │
│ │ ├───┼───────┤ │
│ │ │ 0 │ value │ │
│ │ ╰───┴───────╯ │
│ 1 │ ╭───┬───────╮ │
│ │ │ # │ b │ │
│ │ ├───┼───────┤ │
│ │ │ 0 │ value │ │
│ │ ╰───┴───────╯ │
╰───┴───────────────╯
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.
url split-query - Converts query string into table applying percent-decoding.
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<key: any, value: any> │ 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 record, with a value that needs to be url-encoded
> {a:"AT&T", b: "AT T"} | url build-query
a=AT%26T&b=AT+T
Outputs a query string representing the contents of this record, "exploding" the list into multiple parameters
> {a: ["one", "two"], b: "three"} | url build-query
a=one&a=two&b=three
Outputs a query string representing the contents of this table containing key-value pairs
> [[key, value]; [a, one], [a, two], [b, three], [a, four]] | url build-query
a=one&a=two&b=three&a=four
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, params and query fields must be equivalent
> {
"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, "exploding" the list in params into multiple parameters
> {
"scheme": "http",
"username": "user",
"password": "pwd",
"host": "www.pixiv.net",
"port": "1234",
"params": {a: ["one", "two"], b: "three"},
"fragment": ""
} | url join
http://user:pwd@www.pixiv.net:1234?a=one&a=two&b=three
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:pwd@www.pixiv.net: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:pass567@www.example.com:8081/foo/bar?param1=section&p2=&f[name]=vldc&f[no]=42#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&f[no]=42 │
│ fragment │ hello │
│ │ ╭───┬─────────┬─────────╮ │
│ params │ │ # │ key │ value │ │
│ │ ├───┼─────────┼─────────┤ │
│ │ │ 0 │ param1 │ section │ │
│ │ │ 1 │ p2 │ │ │
│ │ │ 2 │ f[name] │ vldc │ │
│ │ │ 3 │ f[no] │ 42 │ │
│ │ ╰───┴─────────┴─────────╯ │
╰──────────┴──────────────────────────────────────────╯
url split-query
Converts query string into table applying percent-decoding.
Search terms: convert, record, table
Usage:
> url split-query
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬────────┬───────────────────────────────────╮
│ # │ input │ output │
├───┼────────┼───────────────────────────────────┤
│ 0 │ string │ table<key: string, value: string> │
╰───┴────────┴───────────────────────────────────╯
Examples:
Outputs a table representing the contents of this query string
> "mode=normal&userid=31415" | url split-query
╭───┬────────┬────────╮
│ # │ key │ value │
├───┼────────┼────────┤
│ 0 │ mode │ normal │
│ 1 │ userid │ 31415 │
╰───┴────────┴────────╯
Outputs a table representing the contents of this query string, url-decoding the values
> "a=AT%26T&b=AT+T" | url split-query
╭───┬─────┬───────╮
│ # │ key │ value │
├───┼─────┼───────┤
│ 0 │ a │ AT&T │
│ 1 │ b │ AT T │
╰───┴─────┴───────╯
Outputs a table representing the contents of this query string
> "a=one&a=two&b=three" | url split-query
╭───┬─────┬───────╮
│ # │ key │ value │
├───┼─────┼───────┤
│ 0 │ a │ one │
│ 1 │ a │ two │
│ 2 │ b │ three │
╰───┴─────┴───────╯
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 <oneof<string, nothing>>: Module or module file (null for no-op).
...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 │ ╭───┬────╮ │
│ │ │ 0 │ ls │ │
│ │ │ 1 │ mv │ │
│ │ │ 2 │ cd │ │
│ │ ╰───┴────╯ │
│ 1 │ ╭───┬──────────────────╮ │
│ │ │ 0 │ list │ │
│ │ │ 1 │ move │ │
│ │ │ 2 │ change directory │ │
│ │ ╰───┴──────────────────╯ │
╰───┴──────────────────────────╯
version
Display Nu version, and its build configuration.
Usage:
> version
Subcommands:
version check - Checks to see if you have the latest version of nushell.
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯
Examples:
Display Nu version
> version
version check
Checks to see if you have the latest version of nushell.
If you're running nushell nightly, version check will check to see if you are running the latest nightly version. If you are running the nushell release, version check will check to see if you're running the latest release version.
Usage:
> version check
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
Examples:
Check if you have the latest version of nushell
> version check
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 blocks - View the blocks registered in nushell's EngineState memory.
view files - View the files registered in nushell's EngineState memory.
view ir - View the compiled IR code for a block of code.
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 blocks
View the blocks registered in nushell's EngineState memory.
These are blocks parsed and loaded at runtime as well as any blocks that accumulate in the repl.
Usage:
> view blocks
Flags:
-h, --help: Display the help message for this command
Input/output types:
╭───┬─────────┬─────────────────────────────────────────────────────────────╮
│ # │ input │ output │
├───┼─────────┼─────────────────────────────────────────────────────────────┤
│ 0 │ nothing │ table<block_id: int, content: string, start: int, end: int> │
╰───┴─────────┴─────────────────────────────────────────────────────────────╯
Examples:
View the blocks registered in Nushell's EngineState memory
> view blocks
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 ir
View the compiled IR code for a block of code.
The target can be a closure, the name of a custom command, or an internal block
ID. Closure literals within IR dumps often reference the block by ID (e.g.
closure(3231)), so this provides an easy way to read the IR of any embedded
closures.
The --decl-id option is provided to use a declaration ID instead, which can be
found on call instructions. This is sometimes better than using the name, as
the declaration may not be in scope.
Usage:
> view ir {flags} <target>
Flags:
-h, --help: Display the help message for this command
-j, --json: Dump the raw block data as JSON (unstable).
-d, --decl-id: Integer is a declaration ID rather than a block ID.
Parameters:
target <any>: The name or block to view compiled code for.
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ string │
╰───┴─────────┴────────╯
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.
When run without a closure, watch returns a stream of events instead.
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 (deprecated)
--debounce <duration>: Debounce changes for this duration (default: 100ms). 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 <bool>: Watch all directories under <path> recursively. Will be ignored if <path> is a file (default: true)
-q, --quiet: Hide the initial status message (default: false)
-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. (optional)
Input/output types:
╭───┬─────────┬──────────────────────────────────────────────────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────────────────────────────────────────────────┤
│ 0 │ nothing │ nothing │
│ 1 │ nothing │ table<operation: string, path: string, new_path: string> │
╰───┴─────────┴──────────────────────────────────────────────────────────╯
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)"}
watch (when run without a closure) can also emit a stream of events it detects.
> watch /foo/bar
| where operation == Create
| first 5
| each {|e| $"New file!: ($e.path)" }
| to text
| save --append changes_in_bar.log
Print file changes with a debounce time of 5 minutes
> watch /foo/bar --debounce 5min { |op, path| $"Registered ($op) on ($path)" | print }
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 of an input list based on a condition.
A condition is evaluated for each element of the input, and only elements which meet the condition are included in the output.
A condition can be either a "row condition" or a closure. A row condition is a special short-hand syntax to makes accessing fields easier.
Each element of the input can be accessed through the $it variable.
On the left hand side of a row condition, any field name is automatically expanded to use $it.
For example, where type == dir is equivalent to where $it.type == dir. This expansion does not happen when passing a subexpression or closure to where.
When using a closure, the element is passed as an argument and as pipeline input ($in) to the closure. Unlike row conditions, the $it variable isn't available inside closures.
Row conditions cannot be stored in a variable. To pass a condition with a variable, use a closure instead.
Search terms: filter, find, search, condition
Usage:
> where <condition>
Flags:
-h, --help: Display the help message for this command
Parameters:
condition <oneof<condition, closure(any)>>: Filter row condition or closure.
Examples:
Filter rows of a table according to a condition
> [{a: 1} {a: 2}] | where a > 1
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 2 │
╰───┴───╯
List only the files in the current directory
> ls | where type == file
List all files in the current directory with sizes greater than 2kb
> ls | where size > 2kb
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
Filter items of a list with a row condition
> [1 2 3 4 5] | where $it > 2
╭───┬───╮
│ 0 │ 3 │
│ 1 │ 4 │
│ 2 │ 5 │
╰───┴───╯
Filter items of a list with a closure
> [1 2 3 4 5] | where {|x| $x > 2 }
╭───┬───╮
│ 0 │ 3 │
│ 1 │ 4 │
│ 2 │ 5 │
╰───┴───╯
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)' } | get item
Find case-insensitively files called "readme", with a subexpression inside the row condition
> ls | where ($it.name | str downcase) =~ readme
Find case-insensitively files called "readme", with regex only
> ls | where name =~ '(?i)readme'
Filter rows of a table according to a stored condition
> let cond = {|x| $x.a > 1}; [{a: 1} {a: 2}] | where $cond
╭───┬───╮
│ # │ a │
├───┼───┤
│ 0 │ 2 │
╰───┴───╯
List all numbers above 3, using an existing closure condition
> let a = {$in > 3}; [1, 2, 5, 6] | where $a
╭───┬───╮
│ 0 │ 5 │
│ 1 │ 6 │
╰───┴───╯
which
Finds a program file, alias or custom command. If application is not provided, all deduplicated commands will be returned.
Search terms: find, path, location, command, whereis, get-command
Usage:
> which {flags} ...(applications)
Flags:
-h, --help: Display the help message for this command
-a, --all: list all executables
Parameters:
...applications <string>: Application(s).
Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ table │
╰───┴─────────┴────────╯
Examples:
Find if the 'myapp' application is available
> which myapp
Find all executables across all paths without deduplication
> which -a
while
Conditionally run a block in a loop.
This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html
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.
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.
This command will error if window_size or stride are negative or zero.
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 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 2 │ │
│ │ │ 1 │ 3 │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ 3 │ │
│ │ │ 1 │ 4 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
A sliding window of two elements, with a stride of 3
> [1, 2, 3, 4, 5, 6, 7, 8] | window 2 --stride 3
╭───┬───────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 4 │ │
│ │ │ 1 │ 5 │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ 7 │ │
│ │ │ 1 │ 8 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
A sliding window of equal stride that includes remainder. Equivalent to chunking
> [1, 2, 3, 4, 5] | window 3 --stride 3 --remainder
╭───┬───────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 2 │ │
│ │ │ 2 │ 3 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 4 │ │
│ │ │ 1 │ 5 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
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 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
> [ Pachisi Mahjong Catan Carcassonne ] | wrap game
╭───┬─────────────╮
│ # │ game │
├───┼─────────────┤
│ 0 │ Pachisi │
│ 1 │ Mahjong │
│ 2 │ Catan │
│ 3 │ Carcassonne │
╰───┴─────────────╯
Wrap a range into a table with a given column name
> 4..6 | wrap num
╭───┬─────╮
│ # │ num │
├───┼─────┤
│ 0 │ 4 │
│ 1 │ 5 │
│ 2 │ 6 │
╰───┴─────╯
zip
Combine a stream with the input.
Usage:
> zip <other>
Flags:
-h, --help: Display the help message for this command
Parameters:
other <oneof<any, closure()>>: The other input, or closure returning a stream.
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 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 3 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 2 │ │
│ │ │ 1 │ 4 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
Zip two ranges
> 1..3 | zip 4..6
╭───┬───────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 4 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 2 │ │
│ │ │ 1 │ 5 │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ 3 │ │
│ │ │ 1 │ 6 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
Zip two streams
> seq 1 3 | zip { seq 4 600000000 }
╭───┬───────────╮
│ 0 │ ╭───┬───╮ │
│ │ │ 0 │ 1 │ │
│ │ │ 1 │ 4 │ │
│ │ ╰───┴───╯ │
│ 1 │ ╭───┬───╮ │
│ │ │ 0 │ 2 │ │
│ │ │ 1 │ 5 │ │
│ │ ╰───┴───╯ │
│ 2 │ ╭───┬───╮ │
│ │ │ 0 │ 3 │ │
│ │ │ 1 │ 6 │ │
│ │ ╰───┴───╯ │
╰───┴───────────╯
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 }