Running System (External) Commands

Nu provides a set of commands that you can use across different operating systems ("internal" commands) and having this consistency is helpful when creating cross-platform code. Sometimes, though, you want to run an external command that has the same name as an internal Nu command. To run the external ls or date command, for example, preface it with the caret (^) sigil. Prefacing with the caret calls the external command found in the user's PATH (e.g. /bin/ls) instead of Nu's internal ls command).

Nu internal command:

ls

External command (typically /usr/bin/ls):

^ls

Running a Built-in Command with %

The percent (%) sigil does the opposite of the caret: it always runs the Nushell built-in command, even when a custom command or alias with the same name shadows it:

def echo [...args] { "custom echo" }
echo hello
# => custom echo
%echo hello
# => hello

A % call only resolves to built-in commands. It still finds a built-in that has been hidden with hide, and it never falls back to an external command or a custom command. If no built-in has that name, Nushell reports an error:

%lss
# => Error: nu::parser::error
# =>
# =>   × percent sigil requires a built-in command
# =>    ╭─[repl_entry #1:1:2]
# =>  1 │ %lss
# =>    ·  ─┬─
# =>    ·   ╰── unknown built-in command
# =>    ╰────
# =>   help: remove `%` to use normal resolution, or use `^` to run an external command explicitly

Like ^, the % sigil also accepts a command name stored in a variable, such as %$cmd.

Passing Arguments

External arguments are separated by Nushell syntax, not by spaces inside a quoted string. Quote a string to keep its spaces inside one argument:

git commit -m "Update external command documentation"

Nushell does not automatically convert a list into external arguments, and passing a list directly produces an error. Use the spread operator (...) to pass each list item as its own argument:

let paths = ["file one.txt" "file two.txt"]
git add ...$paths

Here, git receives two path arguments, and the space in each path remains part of that argument. See the spread operator in command calls for more examples and the complete spreading rules.

The caret can also run an executable whose name or path is stored in a variable:

let program = "git"
^$program status

See Strings as external commands for the supported string forms. An extern declaration can add type checking and completions for a known external command, and its @structured attribute can turn the command's output into data. Calling it follows the same argument rules described here.

Additional Windows Notes

When running an external command on Windows, Nushell forwards some CMD.EXE internal commands to cmd instead of attempting to run external commands. Coming from CMD.EXE contains a list of these commands and describes the behavior in more detail.