Cmd

Create a new command with the given program name. Execute it with [exec!], [capture!], [run!] or [spawn!].

cmd = Cmd.new("ls")

The program is an OsStr. A string literal can be passed directly, and so can a literal that interpolates: Cmd.new("${tool}").

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

For a List(Str) use cmd.args(names.map(OsStr.from_str)).

Add a single environment variable to the command.

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

Add multiple environment variables to the command.

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

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

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.

Choose the child's standard input; see StdinMode.

When this is not called, [run!] gives the child Null, and [exec!], [capture!] and [spawn!] let it inherit the parent's standard input.

Choose where the child's standard output goes; see StdoutMode.

When this is not called, [run!] and [capture!] capture it, and [exec!] and [spawn!] let it go to the parent's standard output.

Choose where the child's standard error goes; see StderrMode.

When this is not called, [run!] captures it, and [exec!], [capture!] and [spawn!] let it go to the parent's standard error.

Let the child use the parent's standard input, output and error, however the command is run. With [run!] this gives the exit status of a command that prints to the terminal:

status = Cmd.new("roc").args(["check", "main.roc"]).inherit_stdio().run!()?.status

Stop the command when it has run for longer than duration. The deadline covers the whole run, including reading the rest of its output.

A command that reaches its deadline is killed, and the result is Err(CmdErr(TimedOut(partial))) with the output captured so far. That is also what [Child.wait!] and [Child.poll!] return for a child started with [spawn!]. When timeout is not called there is no deadline; Duration.zero expires immediately.

Limit how many bytes of standard output and standard error are captured, counted together. The default is MaxBytes(16777216), 16 MiB.

A command that prints more is killed, and the result is Err(CmdErr(OutputLimitExceeded(partial))) with the output captured up to the limit. NoLimit captures whatever the command prints.

Limit how many bytes of Pipe output may wait to be read with [Child.read!], counted over both streams (default 1 MiB). A child that gets further ahead of its reader is killed, and [Child.wait!] returns Err(CmdErr(OutputLimitExceeded(partial))).

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

Run the command on the parent's terminal and require it to succeed.

Standard input, output and error are inherited unless the command sets them. Any status other than exit code 0 is Err(BadExitStatus(output)).

Cmd.new("cargo").args(["build", "--release"]).exec!()?

Run the command, require it to succeed, and return its standard output as text.

Standard output is captured unless the command sets it. Standard input and standard error are inherited unless the command sets them, so warnings still reach the terminal, as with a shell's $(..). Any status other than exit code 0 is Err(BadExitStatus(output)), and output that is not UTF-8 is Err(BadUtf8(..)).

The text is returned as printed, including a final newline:

sha = Cmd.new("git").args(["rev-parse", "${branch}"]).capture!()?.trim()

Run the command and return its exit status and output as data. A non-zero exit code or a signal is not an error here: match on output.status, or call Output.require_success.

Standard output and standard error are captured, and standard input is Null, unless the command sets them. The result is returned once the command has exited and all of its output has been read.

output = Cmd.new("roc").args(["check", "main.roc"]).run!()?

Start the command and return a Child without waiting for it.

Standard input, output and error are inherited unless the command sets them. Set a stream to Pipe to exchange data with the child while it runs.

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.

The program and its arguments, separated by spaces, for messages and logs. An argument that is empty or contains a space or a quote is written as a quoted, escaped string. The environment, the working directory and the other settings are not included.

expect Cmd.new("git").args(["commit", "-m", "first draft"]).to_str() == "git commit -m \"first draft\""

Customize command output for Str.inspect: the full configuration, with the names of the environment variables it sets but never their values, and the length of Bytes input but not its content.