Struct StreamingRunner 

pub struct StreamingRunner { /* private fields */ }

A streaming process runner that allows async iteration over output

Implementations

impl StreamingRunner

pub fn new(command: impl Into<String>) -> Self

Create a streaming runner for a command string interpreted by the platform shell.

pub fn from_argv<P, I, S>(program: P, args: I) -> Self

where P: Into<OsString>, I: IntoIterator<Item = S>, S: Into<OsString>,

Create a streaming runner for an executable and exact argument vector.

Unlike StreamingRunner::new, this constructor bypasses the platform shell. Argument boundaries are therefore preserved on every platform, including Windows, without requiring shell-specific quoting.

pub fn cwd(self, path: impl Into<PathBuf>) -> Self

Set the working directory

pub fn env(self, env: HashMap<String, String>) -> Self

Set environment variables

pub fn prefer_local(self, preference: PreferLocal) -> Self

Prefer executables from the command’s working directory or explicit directories.

pub fn stdin(self, content: impl Into<String>) -> Self

Set stdin content

pub fn stdin_bytes(self, content: impl Into<Vec<u8>>) -> Self

Set binary stdin without UTF-8 conversion.

pub fn clear_env(self, clear: bool) -> Self

Clear inherited environment variables before applying env.

pub fn env_remove(self, name: impl Into<String>) -> Self

Remove one variable from the child’s environment, the equivalent of env -u NAME or std::process::Command::env_remove.

Removals are applied after env and clear_env, so a removed variable is absent even when the env map also sets it.

use command_stream::StreamingRunner;

let result = StreamingRunner::from_argv("printenv", ["CLAUDECODE"])
    .env_remove("CLAUDECODE")
    .collect()
    .await?;
assert_eq!(result.code, 1); // printenv reports the variable as missing

pub fn env_remove_all<I, S>(self, names: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Remove several variables from the child’s environment. See env_remove.

pub fn stdin_pipe(self) -> Self

Keep the child’s stdin open for the lifetime of the stream, so that OutputStream::write_stdin can send input in reaction to output.

Without it stdin is the null device (or, with stdin, a fixed buffer that is closed once written). Content set with stdin or stdin_bytes is still written first. Finish with OutputStream::close_stdin so the child reads end-of-file; dropping the stream closes stdin as well.

use command_stream::{OutputChunk, StreamingRunner};

let mut stream = StreamingRunner::from_argv("cat", Vec::<String>::new())
    .stdin_pipe()
    .stream();
stream.write_stdin(b"ping\n").await?;
while let Some(chunk) = stream.next().await {
    if let OutputChunk::Stdout(data) = chunk {
        assert_eq!(data, b"ping\n");
        stream.close_stdin().await?;
    }
}

pub fn timeout(self, limit: Duration) -> Self

Bound the run: once limit has passed since the spawn, the child is stopped with the kill_signal (then SIGKILL after the grace period), exactly as OutputStream::kill would.

Mirrors the JavaScript timeout option. The Exit chunk carries the 128 + signal code (143 for the default SIGTERM) and OutputStream::timed_out reports true.

pub fn kill_signal(self, signal: impl Into<String>) -> Self

Configure the signal used to stop the process when it is killed without an explicit signal — i.e. OutputStream::kill or abandoning the stream. Mirrors the JavaScript killSignal option (default SIGTERM).

The reported exit code follows the conventional 128 + signal mapping (e.g. SIGTERM => 143, SIGINT => 130, SIGKILL => 137).

pub fn kill_grace_ms(self, ms: u64) -> Self

Configure how long (in milliseconds) the child is given to handle the kill signal before SIGKILL is sent. Mirrors the JavaScript killGrace option (default 100ms).

This is the window in which a child running its own SIGTERM handler can shut down on its own terms. Set it to 0 to escalate immediately.

pub fn exit_pump_grace_ms(self, ms: u64) -> Self

Configure the grace period (in milliseconds) to keep draining the stdio pipes after the process exits before aborting lingering readers. Mirrors the JavaScript exitPumpGrace option (default 100ms).

pub fn detach(self) -> Result<Option<u32>>

Start the command detached from the caller and return its pid, without waiting for it (issue #232).

The child gets null stdio, leads a process group of its own on Unix (CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS on Windows) and is not killed when anything is dropped, so it keeps running after the caller returns or exits. cwd, env, clear_env, env_remove and prefer_local apply as usual; stdin content, stdin_pipe, timeout and the kill settings do not, since nothing supervises the child. A background thread reaps it when it exits. No Tokio runtime is needed.

use command_stream::StreamingRunner;

let pid = StreamingRunner::from_argv("sleep", ["60"]).cwd("/tmp").detach()?;
println!("started in the background as pid {pid:?}");

pub fn stream(self) -> OutputStream

Start the process and return a stream of output chunks

pub async fn collect(self) -> Result<CommandResult>

Run to completion and collect all output

pub fn collect_blocking(self) -> Result<CommandResult>

Run an exact-argument command to completion from synchronous code.

Build the command with Self::from_argv and configure it with the same cwd, env, and stdin methods used by Self::collect. Call this outside a Tokio runtime; async callers should use collect().await.