Recipe index

Choose the example closest to your task, then adapt its inputs, step IDs, and outputs. Each linked TypeScript example uses public package imports and is compiled and checked against the packaged library.

For an existing script or workflow, use tubeless-make-pipeline from the agent skill pack to choose step boundaries before adapting one of these recipes.

The model-agent recipe explicitly requests high reasoning; omit that option when selecting a model that does not support it. The recipe loads guidance from the physical workspace path and uses that same cwd for all tool calls. The prompt requires nested guidance before file operations or task commands in its scope. The Claude recipe uses the same factory with anthropicModel(); both adapters accept baseUrl for compatible APIs. Custom OpenAI tools need inline strict schemas; oversized result batches use explicit previews while the harness keeps complete outcomes. See the model-agent contract. Record the delegation recipe with --trace or --store, then use tubeless history <run-id> for typed agent/turn/call history and child-agent links; add --json for the same structured projection.

For ownership and governance discovery, adapt graph-metadata.ts. Use metadata, querySteps, and toMermaid({ query }); read graph metadata for bounds, trace identity, and document compatibility.

Static step families

Use parameterized-steps.ts when several statically known steps share an implementation. Its defineRangeChecks helper accepts a readonly tuple of specifications and returns an ordered tuple of ordinary steps. Each specification names a stable ID, description, source step, and bounds. The example checks positive quantities, fulfillment limits, and catalog prices.

The helper expands the whole family synchronously at module load. Spread it into steps and, when each check should be selectable, targets. Pass the tuple to dependsOn to join all checks, or use an individual tuple member to depend on one. Plans, traces, Mermaid diagrams, and Studio show each check as an ordinary step. definePipeline still validates duplicate IDs and missing dependencies.

This is a recipe-local pattern, not a new package export. Adapt the concrete factory and specification type to your domain. Every check in this example returns a number; sources must publish numeric arrays. The mapped tuple type preserves each position’s literal ID. Its one assertion accounts for Array.map losing tuple positions, and is justified by the factory always using the supplied ID and returning the same output type. Do not reuse that assertion for a factory whose output type varies by specification. Prefer explicit declarations for heterogeneous steps unless you can prove their mapping separately.

Pass an inline tuple as shown, or retain literal IDs with as const on a separate specification list. An already widened array cannot recover exact positions or literal IDs. The tuple is enough for ordered expansion and destructuring; no second ID-keyed container is needed. Use forEachPipeline for items discovered during execution. Step families only describe a graph known before a run starts.

The example has no side effects, so its checks also execute during dry runs. If you adapt the factory to write data, declare its ordinary dryRun policy there.

Run the registered recipe:

bun run tubeless -- run --project examples/project/tubeless.project.ts order-checks -- --quantities 2 --quantities 3 --prices 10 --prices 5
bun run tubeless -- plan --project examples/project/tubeless.project.ts order-checks --target valid-prices

Node helpers

tubeless/node provides optional helpers for pipelines that use the local filesystem, environment, and worker threads. It uses Node built-ins and adds no runtime package dependencies. Importing core does not load these helpers.

writeJson throws when the value has no JSON representation, including top-level undefined, functions, symbols, and values whose toJSON returns undefined. Serialization failures leave existing files and directories untouched. Each write uses its own temporary file, including across worker threads. Concurrent writes replace complete files; the last rename wins. This does not merge checkpoint updates or provide a lock for read-modify-write operations.

Filesystem helpers do not know whether a pipeline is in dry-run mode. Put writes and directory resets in steps marked dryRun: "skip", as in node-artifacts.ts. Validate untrusted JSON at the boundary with a schema; readJson<T> alone is not validation. Read required environment values during execution so importing, inspecting and planning a pipeline does not require credentials.

Choose a pattern

1. Use an ordinary step for one unit of domain work.

2. Set dryRun: "skip" or provide a side-effect-free dryRun handler before exposing side-effecting work through CLI dry-run support.

3. Add skip only for a successful policy decision, never to hide an error.

4. Use a child pipeline when the child has value independently; use a normal helper function when it does not.

5. Use forEachPipeline when every item needs child-pipeline lifecycle and reporting. Add skip to forEachPipeline when policy may omit the whole fan-out and a skip should appear in reports. Use runConcurrent for lightweight worker functions that should throw on the first failure. Use runConcurrentPartial when the caller needs completed results plus that failure without throwing. Both stop admitting work after the first observed failure or cancellation, then drain active workers without cancelling siblings. runConcurrentPartial returns ConcurrentPartialResult<R>: branch on ok, never on failure. Success has dense input-order readonly R[] results; failure has sparse results and the first rejection or observed abort error. completedIndexes identifies successful outputs, including undefined; a rejection can also be undefined. Invalid concurrency still throws, including for empty input. runBatched and runBatchedPartial apply that same throw-or-partial split to fixed-size batches instead of individual items.

6. Group application pipelines with defineProject(id, [pipelineA, pipelineB]) from tubeless/project. Use project.get(id) to retain the selected pipeline’s exact option and result types; call its existing methods directly. Let definePipeline infer its generics to preserve literal IDs; annotate the finalizer’s return type when an explicit result contract is needed. Use PipelineInput<typeof pipeline> and PipelineResult<typeof pipeline> for wrapper contracts instead of restating the pipeline generics. The input type is the value accepted by run before schema transformation. Pipeline commands retain the exact wrapped pipeline as command.pipeline. Put optional name and description on a pipeline when CLI and Studio need friendlier presentation. definePipelineCommand inherits both; command-level values override them without changing the pipeline ID. Add optional { name, description } as the third argument for presentation; the project name defaults to its ID. Compile parsed documents with compilePipelineDocument(document, registry), then register selected pipelines. Reuse compiled.metadata through ordinary object construction, adding explicit name/description overrides as needed. A child need not be a project entry to run. A checked-in defineProject exposes its pipelines to the CLI and Studio directly; they infer flags from the options schema’s Standard JSON Schema input metadata. Without that metadata, supply explicit command params using adapters in the project’s entry list, even for pipelines with no domain inputs. Register each pipeline exactly once, directly or through its command. Mixed lists preserve exact lookup types; duplicate pipeline IDs fail regardless of entry form. Default-export the project to select it for CLI and Studio; without a default, multiple distinct projects are rejected. Run a uniquely exported schema-backed pipeline file directly when inferred flags are sufficient. Start customized scripts with definePipelineCommand(pipeline); an explicit command wins when both it and its pipeline are exported. Use --export to resolve multiple commands or pipelines. Use overrides for presentation only; explicit params and mapOptions are advanced options for type-only pipelines or custom input shapes. Non-string enum/const constraints and $ref siblings with validation constraints also require explicit parameters; see CLI inference. Use defineCommand from the same entrypoint for standalone scripts. Projects share their explicit adapters between terminal commands and Studio. Preview selection with command.plan() or tubeless plan; do not simulate planning with --plan. --step and --target are argv flags; mapOptions and hooks read stepIds and targets. Commands expose --resume only when an explicit adapter configures managed checkpoint support or sets resume: true and handles the value itself. Automatic project commands omit the flag.

7. Declare public goals with targets: [step] on the pipeline, select their IDs for goal-oriented execution, and use stepIds only for an exact filter. The control type rejects using both selections together. Without run selection controls, every step is selected. Omitted definition targets exposes the last step in execution order as a selectable goal; targets: [] exposes none. These declarations do not select work for a run. Omitted finalize returns that step’s output or undefined if absent. Use requireOutputs when the final domain result is not meaningful without specific step outputs. Read plan selectionReasons instead of recreating target-closure logic in a CLI or application.

8. Use the file layout and export conventions in the project with custom adapters only when custom adapters are needed. Do not infer executable modules from run history or the filesystem. Cancel only a live launch owned by the current studio process; it is not crash-resume and does not abort sibling launches. Studio pages top-level history; search includes nested runs across all pages, and run links open recorded details directly. Run details can switch to a live step graph that expands nested runs, agent turns, and tool calls. See the Studio controls.

Use fromRemote when a step calls another execution system. If a dry run contacts that system, both the adapter and remote worker must honor context.dryRun. A worker or durable host can invoke the whole pipeline when it needs to own job delivery and retries; see remote steps.

For dependency, failure, and selection behavior, read core concepts. For workbench commands, read the CLI. For hosted execution, follow Cloud authentication and deployed runs; list loaded pipelines, then run one by exact name or listed slug with JSON input. For the local run UI, read the studio. To connect historical runs to a compiled graph and handler release, set implementationVersion as shown in tracing. Studio’s definition history groups runs by definition and compares observed versions. Definition metadata remains visible while its run pages refresh. Complete recorded snapshots must match their hashes, including recorded child implementation identities, to be accepted by NDJSON or SQLite history.

Host Studio privately

Use the Studio gateway recipe to mount a long-lived CLI process beneath an application’s admin URL. Tubeless supplies prefix-aware pages/APIs and backend authentication; your application checks login and admin permission for every request and owns deployment/storage. Use an explicit deployed catalog, keep the backend token server-only, and never retry an uncertain launch. No framework adapter or server-internal imports are needed.