Cmd

Spawn a child process with stdio pipes for bidirectional communication.

child = Cmd.new_str("node").arg_str("repl.js").spawn!()?
child.write_stdin!(Str.to_utf8("1+1\n"))?
response = child.read_stdout!(100)?
child.kill!()?

Spawn a child process that gets cleaned up when the parent exits.

Use this for test servers, subprocesses, or anything that shouldn't outlive your program.

**Linux and Windows**: children are guaranteed to die with the parent, even on SIGKILL (via PR_SET_PDEATHSIG / Job Objects). **macOS**: children die on normal exit, Ctrl+C, and crashes, but may survive kill -9 of the parent (kernel limitation).

Kill all processes spawned via [Cmd.spawn_grouped!] and their children.

This is called automatically on normal program exit, but you can call it explicitly for immediate cleanup.

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_bytes)}")? # {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 Roc string.

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

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

Add a single string argument to the command.

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

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

Add multiple string arguments to the command.

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 single string environment variable to the command.

Add multiple environment variables to the command.

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

Add multiple string environment variables to the command.

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")

Render a command configuration as a stable, escaped string.

Customize command output for Str.inspect.