Cmd

:= [
    Cmd(
        {
            args : List(OsStr),
            clear_envs : Bool,
            envs : List({ name : OsStr, value : OsStr }),
            program : OsStr,
            timeout_ms : U64,
            stdout_limit_bytes : U64,
            stderr_limit_bytes : U64,
        },
    ),
]

Build and run finite child processes with native-safe programs, arguments, and environment values. Programs execute directly without a shell. Commands inherit the host working directory and, unless clear_envs is used, the host environment. exec!/exec_cmd! inherit standard streams; exec_output! captures both streams with finite limits.

output = Cmd.new_str("git")
    .args_str(["status", "--short"])
    .with_timeout_millis(5_000)
    .with_output_limits({ stdout_bytes: 256 * 1024, stderr_bytes: 64 * 1024 })
    .exec_output!()?
exec! : OsStr, List(OsStr) => Try({  }, [ExecFailed({ command : Str, exit_code : I32 }), FailedToGetExitCode({ command : Str, err : IOErr }), CommandTimedOut({ command : Str, timeout_ms : U64 }), CommandSaturated({ command : Str }), ..])

Execute a program with native arguments, inheriting standard streams.

exec_str! : Str, List(Str) => Try({  }, [ExecFailed({ command : Str, exit_code : I32 }), FailedToGetExitCode({ command : Str, err : IOErr }), CommandTimedOut({ command : Str, timeout_ms : U64 }), CommandSaturated({ command : Str }), ..])

Execute a UTF-8 program with UTF-8 arguments.

exec_cmd! : Cmd => Try({  }, [ExecCmdFailed({ command : Str, exit_code : I32 }), FailedToGetExitCode({ command : Str, err : IOErr }), CommandTimedOut({ command : Str, timeout_ms : U64 }), CommandSaturated({ command : Str }), ..])

Execute a configured command, inheriting standard streams.

exec_output! : Cmd => Try({ stdout_utf8 : Str, stderr_utf8_lossy : Str }, [StdoutContainsInvalidUtf8({ cmd_str : Str, err : [BadUtf8({ problem : _, index : U64 })] }), NonZeroExitCode({ command : Str, exit_code : I32, stdout_utf8_lossy : Str, stderr_utf8_lossy : Str }), FailedToGetExitCode({ command : Str, err : IOErr }), CommandTimedOut({ command : Str, timeout_ms : U64 }), CommandSaturated({ command : Str }), StdoutLimitExceeded({ command : Str, limit_bytes : U64, received_at_least : U64 }), StderrLimitExceeded({ command : Str, limit_bytes : U64, received_at_least : U64 }), ..])

Execute a command and capture stdout as UTF-8 and stderr lossily. Use [exec_output_bytes!] when either stream must be preserved exactly.

exec_output_bytes! : Cmd => Try({ stderr_bytes : List(U8), stdout_bytes : List(U8) }, [NonZeroExitCodeB({ exit_code : I32, stdout_bytes : List(U8), stderr_bytes : List(U8) }), FailedToGetExitCodeB(IOErr), CommandTimedOutB(U64), CommandSaturatedB, StdoutLimitExceededB({ limit_bytes : U64, received_at_least : U64 }), StderrLimitExceededB({ limit_bytes : U64, received_at_least : U64 }), ..])

Execute a command and capture stdout and stderr without text conversion.

exec_exit_code! : Cmd => Try(I32, [FailedToGetExitCode({ command : Str, err : IOErr }), CommandTimedOut({ command : Str, timeout_ms : U64 }), CommandSaturated({ command : Str }), ..])

Execute a command and return its exit code.

new : OsStr -> Cmd

Create a command whose program is an exact native OS string.

with_timeout_millis : Cmd, U64 -> Cmd

Set the total deadline, including bounded admission wait. Zero is normalized to one millisecond.

with_output_limits : Cmd, { stdout_bytes : U64, stderr_bytes : U64 } -> Cmd

Set independent finite limits for captured stdout and stderr.

new_str : Str -> Cmd

Create a command whose program is UTF-8 text.

arg : Cmd, OsStr -> Cmd

Add an exact native argument. Shell expansion is not performed.

arg_str : Cmd, Str -> Cmd

Add a UTF-8 argument. Shell expansion is not performed.

args : Cmd, List(OsStr) -> Cmd

Add exact native arguments. Shell expansion is not performed.

args_str : Cmd, List(Str) -> Cmd

Add UTF-8 arguments. Shell expansion is not performed.

env : Cmd, OsStr, OsStr -> Cmd

Add an exact native environment name and value.

env_str : Cmd, Str, Str -> Cmd

Add a UTF-8 environment name and value.

envs : Cmd, List({ name : OsStr, value : OsStr }) -> Cmd

Add exact native environment variables. Named fields keep same-typed names and values unambiguous at call sites.

envs_str : Cmd, List({ name : Str, value : Str }) -> Cmd

Add UTF-8 environment variables using { name, value } records.

clear_envs : Cmd -> Cmd

Remove the inherited environment before applying configured pairs.

to_str : Cmd -> Str

Render an escaped, diagnostic representation of this command. Native values are never round-tripped through this lossy string.