Crate command_stream 

command-stream

Modern shell command execution library with streaming, async iteration, and event support.

This library provides a Rust equivalent to the JavaScript command-stream library, offering powerful shell command execution with streaming capabilities.

Features

• Async command execution with tokio
• Streaming output via async iterators
• Event-based output handling (on, once, emit)
• Virtual commands for common operations (cat, ls, mkdir, etc.)
• Shell operator support (&&, ||, ;, |)
• Pipeline support with .pipe() method and Pipeline builder
• Global state management for shell settings
• cmd! macro for ergonomic command creation (similar to JS $ tagged template literals)
• Cross-platform support

Module Organization

The codebase follows a modular architecture similar to the JavaScript implementation:

• ansi - ANSI escape code handling utilities
• commands - Virtual command implementations
• events - Event emitter for stream events
• macros - The cmd! macro for ergonomic command creation
• pipeline - Pipeline execution support
• quote - Shell quoting utilities
• shell_parser - Shell command parsing
• state - Global state management
• stream - Async streaming and iteration support
• trace - Logging and tracing utilities
• utils - Command results and virtual command helpers

Quick Start

use command_stream::{run, cmd};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Execute a simple command
    let result = run("echo hello world").await?;
    println!("{}", result.stdout);

    // Using the cmd! macro (similar to JS $ tagged template)
    let name = "world";
    let result = cmd!("echo hello {}", name).await?;
    println!("{}", result.stdout);

    // Using pipelines
    use command_stream::Pipeline;
    let result = Pipeline::new()
        .add("echo hello world")
        .add("grep world")
        .run()
        .await?;

    Ok(())
}

Re-exports

pub use commands::CommandContext;

pub use commands::StreamChunk;

pub use shell_parser::needs_real_shell;

pub use shell_parser::parse_shell_command;

pub use shell_parser::ParsedCommand;

pub use utils::CommandResult;

pub use utils::VirtualUtils;

pub use ansi::AnsiConfig;

pub use ansi::AnsiUtils;

pub use events::EventData;

pub use events::EventType;

pub use events::StreamEmitter;

pub use local_bin::PreferLocal;

pub use pipeline::Pipeline;

pub use pipeline::PipelineBuilder;

pub use pipeline::PipelineExt;

pub use quote::escape_for_double_quotes;

pub use quote::escape_for_single_quotes;

pub use quote::has_shell_escapes;

pub use quote::is_pre_quoted_passthrough_enabled;

pub use quote::is_quote_context_enabled;

pub use quote::quote;

pub use quote::quote_for_context;

pub use quote::scan_quote_context;

pub use quote::QuoteContext;

pub use signal::signal_exit_code;

pub use signal::signal_number;

pub use signal::DEFAULT_KILL_GRACE_MS;

pub use signal::DEFAULT_KILL_SIGNAL;

pub use state::get_shell_settings;

pub use state::global_state;

pub use state::reset_global_state;

pub use state::set_shell_option;

pub use state::unset_shell_option;

pub use state::GlobalState;

pub use state::ShellSettings;

pub use stream::AsyncIterator;

pub use stream::IntoStream;

pub use stream::OutputChunk;

pub use stream::OutputStream;

pub use stream::StreamingRunner;

pub use trace::trace;

pub use run as execute;

Modules

ansi

ANSI control character utilities for command-stream

bun_shell

A portable implementation of Bun Shell (Bun.$), ported from Bun’s src/runtime/shell and src/shell_parser and kept behaviour-identical with the JavaScript port in js/src/bun-shell/.

commands

Virtual command implementations

events

Event emitter for stream events

local_bin

Project-local executable resolution shared by the default, zx, and Bun runners.

pipeline

Pipeline execution support

quote

Shell quoting utilities for command-stream

result_streams

Re-readable snapshots of completed command output and a writable stdin record.

shell_parser

Enhanced shell command parser that handles &&, ||, ;, and () operators This allows virtual commands to work properly with shell operators

signal

Signal delivery and the signal exit-code convention.

state

Global state management for command-stream

stream

Streaming and async iteration support

terminal

trace

Trace/logging utilities for command-stream

utils

Utility functions and types for command-stream

zx

A zx-compatible API (modelled on google/zx 8.x) for writing shell scripts in Rust.

Macros

cmd

The cmd! macro for ergonomic shell command execution

cs

The cs! macro - alias for cmd!

s

The s! macro - short alias for cmd!

sh

The sh! macro - alias for cmd!

zx

Build a ProcessPromise from a format string whose {} placeholders are replaced by quoted arguments ({{}} is a literal {}).

Structs

ProcessChild

Borrowed access to the operating-system child owned by a ProcessRunner.

ProcessRunner

A running or completed process

RunOptions

Options for command execution

Enums

Error

Error type for command-stream operations

StdinOption

Standard input options

Functions

create

Create a new process runner without starting it

exec

Execute a command with custom options

run

Execute a command and return the result

run_sync

Execute a command synchronously (blocking)

Type Aliases

Result

Result type for command-stream operations