Pipelines

The pipeline special variable $in

Best practices for pipeline commands

Interaction with Unix pipes

Handling stdout and stderr

You can handle stderr in multiple ways:

1. Do nothing, stderr will be printed directly
2. Pipe stderr to the next command, using e>| or e+o>|
3. Redirect stderr to a file, using e> file_path, or e+o> file_path
4. Use do -i { cmd } | complete to capture both stdout and stderr as structured data

For the next examples, let's assume this file:

# demo.nu
print "foo"
print -e "barbar"

It prints foo to stdout and barbar to stderr. The following table illustrates the differences between the different redirection styles:

Redirection to a pipeline:

Redirection to a file:

complete command:

Note that e>| and o+e>| only work with external command, if you pipe internal commands' output through e>| and o+e>|, you will get an error:

❯ ls e>| str length
Error:   × `e>|` only works with external streams
   ╭─[entry #1:1:1]
 1 │ ls e>| str length
   ·    ─┬─
   ·     ╰── `e>|` only works on external streams
   ╰────

❯ ls e+o>| str length
Error:   × `o+e>|` only works with external streams
   ╭─[entry #2:1:1]
 1 │ ls e+o>| str length
   ·    ──┬──
   ·      ╰── `o+e>|` only works on external streams
   ╰────

You can also redirect stdout to a file, and pipe stderr to next command:

nu demo.nu o> file.txt e>| str upcase
nu demo.nu e> file.txt | str upcase

But you can't use redirection along with o+e>|, because it's ambiguous:

nu demo.nu o> file.txt o+e>| str upcase

Also note that complete is special, it doesn't work with e>|, o+e>|.

Stdio and redirection behavior examples

Pipeline and redirection behavior can be hard to follow when they are used with subexpressions, or custom commands. Here are some examples that show intended stdio behavior.

Examples for subexpression

• (^cmd1 | ^cmd2; ^cmd3 | ^cmd4)

• (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) | ^cmd5

It runs (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) first, then pipes stdout to ^cmd5, where both stdout and stderr are directed to the Terminal.

• (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) e>| ^cmd5

It runs (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) first, then pipes stderr to ^cmd5, where both stdout and stderr are directed to the Terminal.

• (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) o+e>| ^cmd5

It runs (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) first, then pipes stdout and stderr to ^cmd5, where both stdout and stderr are directed to the Terminal.

• (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) o> test.out

• (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) e> test.out

• (^cmd1 | ^cmd2; ^cmd3 | ^cmd4) o+e> test.out

Examples for custom command

Given the following custom commands

def custom-cmd [] {
    ^cmd1 | ^cmd2
    ^cmd3 | ^cmd4
}

The custom command stdio behavior is the same as the previous section.

In the examples below the body of custom-cmd is (^cmd1 | ^cmd2; ^cmd3 | ^cmd4).

• custom-cmd

• custom-cmd | ^cmd5

It runs custom-cmd first, then pipes stdout to ^cmd5, where both stdout and stderr are directed to the Terminal.

• custom-cmd e>| ^cmd5

It runs custom-cmd first, then pipes stderr to ^cmd5, where both stdout and stderr are directed to the Terminal.

• custom-cmd o+e>| ^cmd5

It runs custom-cmd first, then pipes stdout and stderr to ^cmd5, where both stdout and stderr are directed to the Terminal.

• custom-cmd o> test.out

• custom-cmd e> test.out

• custom-cmd o+e> test.out