Run a command
Declare a program, build its argument vector, run it, and read the result; meet the three ways a run can fail; and hold a running child when the caller must decide when it stops.
Work order 004 · Documentation
Documentation
Guides walk through a task end to end. The API reference lists every name Cuprum 0.2.0-beta2 exports, read from the source, with each signature, parameter, and failure.
Guides
Guide 01 Guide 02 Control output
Capture, echo, per-line callbacks, lines streamed as they arrive, a heartbeat for a quiet child, a sink that goes away, a stream sent to a file or the parent, and byte-exact capture.
Guide 03 Input, environment, and deadlines
Feed standard input from memory or a streaming producer, overlay or replace the environment, set a deadline that tears the child down cleanly, and reclaim the descendants it leaves behind.
Guide 04 Pipelines and concurrency
Join commands stage to stage, find the stage that failed, and run independent commands side by side.
Guide 05 Catalogues and builders
Name the programs an application may run, and wrap argument construction in small, validated builders.
Guide 06 Scopes, policy, and hooks
Narrow what a block of code may run, bind a program to the executable it should run, and run code around every command.
Guide 07 Observe production runs
Structured logs, metrics, and traces from every run, the settled outcome, redaction for secrets, control operations, and output framed for GitHub Actions.
Guide 08 Troubleshoot a run
The first thing to check for each common outcome, from an unknown program to a missing speed-up.
Guide 09 Migrate to 0.2.0
The changes an application using Cuprum 0.1 meets on upgrade, each with its fix, then what 0.2.0 adds and how to adopt each part.
API reference
21 names Commands and results
Building a typed command from a catalogued program, running it, and reading what it returns.
16 names Programs and catalogues
The programs Cuprum may build commands for, the projects that group them, and the defaults it ships.
7 names Pipelines and concurrency
Joining commands stage to stage, and running independent commands side by side.
21 names Scopes, policy, and hooks
Narrowing what a block of code may run, composing its environment, binding programs to executables, and running code around each command.
26 names Events and observation
The structured events a run emits, and the hooks that receive them.
10 names Rust pump and backends
Whether the optional native pump is present, and what it reports when a pipeline hop uses it or falls back.
10 names Adapters and sinks
Ready-made observe hooks for logging, metrics, and tracing; metrics for stream operations, line events, echo, control operations, and the Rust pump; the redaction policy that keeps secrets out of what they export; and the output sink that frames a run for GitHub Actions.
6 names Errors
The exceptions Cuprum raises when a program is unknown, forbidden, or too slow, when a stdin producer fails, or when a signal cannot reach a child.