Cmd

Simplest way to execute a command by name with arguments. Stdin, stdout, and stderr are inherited from the parent process.

If you want to capture the output, use [exec_output!] instead.

Cmd.exec!("echo", ["hello world"])?

Execute a Cmd (using the builder pattern). Stdin, stdout, and stderr are inherited from the parent process.

You should prefer using [exec!] instead, only use this if you want to use env, envs or clear_envs. If you want to capture the output, use [exec_output!] instead.

Cmd.new("cargo")
    .arg("build")
    .env("RUST_BACKTRACE", "1")
    .exec_cmd!()?

Execute command and capture stdout and stderr as UTF-8 strings. Invalid UTF-8 sequences are replaced with the Unicode replacement character.

Use [exec_output_bytes!] instead if you want to capture the output in the original form as bytes. [exec_output_bytes!] may also be used for maximum performance, because you may be able to avoid unnecessary UTF-8 conversions.

cmd_output =
    Cmd.new("echo")
        .args(["Hi"])
        .exec_output!()?

Stdout.line!("Echo output: ${cmd_output.stdout_utf8}")?

Execute command and capture stdout and stderr in the original form as bytes.

Use [exec_output!] instead if you want to get the output as UTF-8 strings.

cmd_output =
    Cmd.new("echo")
        .args(["Hi"])
        .exec_output_bytes!()?

Stdout.line!("${Str.inspect(cmd_output)}")? # {stderr_bytes: [], stdout_bytes: [72, 105, 10]}

Execute a command and return its exit code. Stdin, stdout, and stderr are inherited from the parent process.

You should prefer using [exec!] or [exec_cmd!] instead, only use this if you want to take a specific action based on a specific non-zero exit code. For example, roc check returns exit code 1 if there are errors, and exit code 2 if there are only warnings. So, you could use exec_exit_code! to ignore warnings on roc check.

exit_code = Cmd.new("cat").arg("non_existent.txt").exec_exit_code!()?

Create a new command with the given program name. Use a function that starts with exec_ to execute it.

cmd = Cmd.new("ls")

Create a new command from a dynamic Str. String literals can be passed directly to new.

Set the child working directory without changing the parent directory. Use an absolute executable path or a bare PATH name: resolving a relative executable against cwd is platform-specific.

Bytes supplies and closes stdin automatically. Pipe supports Child.write!. Default is Null for run!/exec_output!, Inherit for spawn!/exec_cmd!.

Capture retains bytes; Pipe queues tagged Child.read! events; Tee captures and forwards to the parent. Default captures for run!/exec_output!, and inherits for spawn!/exec_cmd!. Tee exposes a pipe, not a terminal, to the child.

Configure stderr independently, with the same modes and defaults as stdout.

Zero disables the execution deadline. It covers output draining too.

Combined capture budget in bytes (default 16 MiB). Exceeding it cancels the command and returns OutputLimit with the retained partial output.

Combined unread Pipe event budget (default 1 MiB). Consume events with Child.read! while running; exceeding this budget cancels the child.

Also terminate descendants on cancellation, using a Unix process group or Windows Job Object. Disabled by default; descendants must not escape it.

Send both child streams into one OS pipe using stdout's mode and budget. This preserves kernel write order; separate streams have no total ordering.

Nonzero exits and signal termination are returned as status data. Defaults to null stdin and captured stdout/stderr. Successful completion waits for output EOF; deadlines include draining and tee forwarding.

Start a managed child immediately. Default streams are inherited.

Add a single argument to the command. ❗ Shell features like variable substitution (e.g. $FOO), glob patterns (e.g. *.txt), ... are not available.

cmd = Cmd.new("ls").arg("-l")

Add a dynamic Str argument. String literals can be passed directly to arg.

Add multiple arguments to the command. ❗ Shell features like variable substitution (e.g. $FOO), glob patterns (e.g. *.txt), ... are not available.

cmd = Cmd.new("ls").args(["-l", "-a"])

Add multiple dynamic Str arguments. Lists of string literals can be passed directly to args.

Add a single environment variable to the command.

cmd = Cmd.new("env").env("FOO", "bar") # add the environment variable "FOO" with value "bar"

Add a dynamic Str environment variable. String literals can be passed directly to env.

Add multiple environment variables to the command.

cmd = Cmd.new("env").envs([("FOO", "bar"), ("BAZ", "qux")])

Add multiple dynamic Str environment variables. Lists of literal pairs can be passed directly to envs.

Clear all environment variables before running the command. Only environment variables added via env or envs will be available. Useful if you want a clean command run that does not behave unexpectedly if the user has some env var set.

cmd =
    Cmd.new("env")
        .clear_envs()
        .env("ONLY_THIS", "visible")

Report whether command can be found on the system as something runnable.

A bare name (like "git") is looked up across the PATH entries; a name containing a path separator is checked as-is. On Windows the candidate extensions come from %PATHEXT%.

On Unix this checks for an executable bit; a directory is not reported even though it carries one, though a symbolic link to a directory is a rare exception.

Render a command configuration as a stable, escaped string.

Customize command output for Str.inspect.