Command Line Interface

The deepzero CLI is the primary interaction point for executing and managing pipelines.

# Standard execution
deepzero run ./targets -p pipelines/loldrivers/pipeline.yaml

# Execute with state cleanup (fresh run)
deepzero run ./targets -p pipelines/loldrivers/pipeline.yaml --clean

# Check execution status
deepzero status -p loldrivers

# Launch interactive analysis REPL
deepzero interactive -w work/loldrivers

# Start the Starlette REST API
deepzero serve -w work/loldrivers --port 8420

# Scaffold a new custom pipeline
deepzero init my_custom_pipeline

# Validate schema without execution
deepzero validate loldrivers

# Inspect system registry
deepzero list-processors

Core Commands

Command Description
run Execute a pipeline against a target. Resumes automatically if state exists.
status Show current pipeline run status, verdicts, and stage metrics.
interactive Interactive analysis REPL with LLM-backed conversation over pipeline results.
serve Start the REST API server to expose pipeline state externally.
init Scaffold a new pipeline directory with a boilerplate pipeline.yaml.
validate Perform dry-run validation of a pipeline’s schema and processor imports.
list-processors List all built-in and dynamically registered processor types.

Execution Flags (run)

| ——— | ———– | | TARGET | Positional argument. Path to the analysis corpus (file or directory). | | -p, --pipeline | Identifier, directory name, or discrete YAML file path. | | --clean | Purge existing state directory prior to execution. |

REST API (serve)

[!WARNING] WIP / Experimental Feature The REST API server is currently incomplete, highly unstable, and should not be used. It is provided strictly for experimental local development.

Starts a read-only FastAPI/Starlette REST API for querying run state and sample data.

Endpoint Method Description
/api/health GET Health check
/api/runs GET List available pipeline runs in the work directory
/api/run GET Fetch global state and metrics for the current run
/api/samples GET List samples (filterable by ?verdict=, ?stage=, ?status=)
/api/samples/{sample_id} GET Full sample state with historical pipeline data
/api/samples/{sample_id}/artifacts/{name} GET Read a specific file artifact generated by a processor

Retrying what ran out of time

A stage that hits its timeout records the sample as having run out of time rather than as having failed. That is a statement about the budget, not about the sample: the ones that hit it are the largest, which in most corpora are the ones worth looking at, and filing them with genuine errors quietly biases a run away from them.

A resumed run does not retry them on its own, because the budget that was too short still is. Ask for it:

deepzero run <target> -p <pipeline> --retry-timeouts

This forgets only the stages that ran out of time and gives them --timeout-multiplier (default 2x) longer. Every other result the run produced is kept, so a retry costs the time those stages need and nothing else. The report groups them separately and shows the budget each one exceeded.