Crate execra 

DO NOT DEPEND ON THIS CRATE

Execra is currently in heavy testing inside the author’s own rScoop project as the load-bearing case for whether it works as a general-purpose public crate. External consumers are not supported at this time: the API, the wire format, and the persistence schema will change without notice, and the crate may end up being narrowed back into an rScoop-only implementation detail rather than a published library. Read it, fork it, learn from it — do not cargo add it in production until a 1.0 release sets a stability contract.

---

Execra is a typed job runtime for external processes. You hand it a Command, it gives you back a JobHandle that you can either .await for the final Outcome or subscribe to as an event stream. Each job gets phases, progress, findings, persistence, and process-group cancellation, behind a single Execra::spawn entry point.

Interpretation of a CLI’s output into structured events is decoupled from the runtime via the Interpreter trait; see the INTERPRETER.md file in the repository for the contract.

Quick example

use execra::{Command, Config, Execra, Outcome};

let rt = Execra::open(Config::default()).await?;
let outcome = rt
    .spawn(Command::new("echo").arg("hello").label("greet"))
    .await?
    .await;
assert!(matches!(outcome, Outcome::Succeeded { .. }));

Feature flags

• bundled-sqlite (default) — Bundle SQLite with rusqlite. Disable to link against the system libsqlite3 instead.
• gzip (default) — Enable RawOutputPolicy::PersistGzipOnFinalize and pull in flate2. Without this feature raw logs can still be persisted uncompressed via RawOutputPolicy::Persist.

See SCHEMA.md, RUNTIME.md, and INTERPRETER.md in the repository for the full design contract.

Re-exports

pub use command::Command;

pub use command::StdinMode;

pub use event::Event;

pub use event::Stream;

pub use finding::Action;

pub use finding::Finding;

pub use finding::RelatedEntity;

pub use finding::Severity;

pub use interpreter::Context;

pub use interpreter::Interpreter;

pub use interpreter::InterpreterEvent;

pub use interpreter::Line;

pub use job::Job;

pub use job::JobId;

pub use job::JobState;

pub use outcome::ExitCode;

pub use outcome::FailureReason;

pub use outcome::Outcome;

pub use phase::Phase;

pub use phase::PhaseId;

pub use progress::Progress;

pub use progress::ProgressMetric;

pub use runtime::Config;

pub use runtime::Execra;

pub use runtime::JobHandle;

pub use runtime::JobsQuery;

pub use runtime::RawOutputPolicy;

pub use runtime::RetentionPolicy;

Modules

command

event

finding

interpreter

The Interpreter contract. See INTERPRETER.md.

job

outcome

phase

progress

Progress is the single most load-bearing type. See SCHEMA.md.

runtime

Runtime surface and per-job driver.

store

SQLite persistence. Stores jobs (one row), events (JSON blob per row), and findings (denormalized for queryability). Raw OutputAppended events are intentionally not persisted to SQLite , they belong in flat files (next pass). High-volume CLIs would balloon the database otherwise.