plumb - run a plumbing pipeline

SYNOPSIS

plumb [--docroot dir] [--provider name] [--model name] spec.plumb

DESCRIPTION

plumb loads a pipeline specification from spec.plumb, finds the main binding, creates channels, spawns processes, wires boundary ports, and forwards standard input through the pipeline to standard output.

Structural morphisms (id, copy, merge, discard, map, filter, barrier) execute inline as forwarding threads within the plumb process. Agents and nested plumbs spawn as isolated subprocesses.

Input and output forwarding run on separate threads, handling arbitrary n:m message ratios (copy, merge, fan-in/fan-out).

OPTIONS

--docroot dir

Set the document root directory for builtin tools. When set, file-access tools are restricted to paths under dir.

--provider name

Set the default LLM provider for agents that do not specify one in their config. Sets the PLUMB_PROVIDER environment variable. See plumb-agent(1) for supported providers.

--model name

Set the default model for agents that do not specify one in their config. Sets the PLUMB_MODEL environment variable.

ENVIRONMENT

PLUMB_PATH

Colon-separated list of directories to search when resolving bare use declarations (e.g. use fs). Searched before the installed standard library directories.

PLUMB_RESOURCES

Colon-separated list of directories to search when resolving bare prompt file names in agent configs. Searched before the installed resource directories. Propagates to agent subprocesses.

PIPELINE_DEBUG

Set to 1 to enable debug logging. Conversation transcripts and API metadata are written as JSON Lines to stderr. Propagates to all subprocesses in the pipeline.

PLUMB_PROVIDER

Default LLM provider for agents without an explicit provider in config. Overridden by the --provider flag. See plumb-agent(1).

PLUMB_MODEL

Default model for agents without an explicit model in config. Overridden by the --model flag. See plumb-agent(1).

ANTHROPIC_API_KEY

API key for the Anthropic Messages API. Required when any agent in the pipeline uses provider "anthropic".

OPENAI_API_KEY

API key for the OpenAI Chat Completions API. Required when any agent uses provider "openai".

EXIT STATUS

0

Success.

1

Data or runtime error.

2

Configuration error (missing spec file, bad arguments).

EXAMPLES

Run a pipeline, sending a single JSON message:

echo '{"text":"hello"}' | plumb my-pipeline.plumb

Pipe a file of JSON Lines through a pipeline:

plumb my-pipeline.plumb < messages.jsonl > results.jsonl

SEE ALSO

plumb-chat(1), plumb-agent(1), plumbing(5)