Tubeless

Tubeless is a TypeScript toolkit for work that unfolds in steps. It fits data pipelines, multi-step application workflows, and AI workloads—anywhere you want explicit dependencies, typed handoffs, and inspectable execution. The name is the cycling kind of tubeless: no inner tube, and no extra runtime to keep the work rolling.

Pipelines run in your process with no runtime dependencies. You can preview execution, select a target and its dependencies, compose child pipelines, and track progress. The optional CLI and Studio run locally or behind your authenticated admin gateway. For scheduling or crash recovery, pair it with a queue or workflow engine.

Installation

npm install tubeless

The ESM library requires Node.js 22.6+. The CLI requires Bun 1.3.14+. Linux and macOS are supported; Windows is untested. See installation and runtime support.

Tubeless is pre-1.0, so the public API may change between releases.

Quick start

This pipeline loads and normalizes strings. step creates a step; dependencies give typed inputs.

import { createSteps, definePipeline } from "tubeless";

interface ImportOptions {
  lines: readonly string[];
}

const { step } = createSteps<ImportOptions>();

const load = step("load", {
  run: (_inputs, context) => context.options.lines,
});

const normalize = step("normalize", {
  dependsOn: [load],
  run: ({ load: rows }) => rows.map((row) => row.trim().toLowerCase()).filter(Boolean),
});

export const ImportPipeline = definePipeline({
  id: "import",
  steps: [load, normalize],
});

const rows = await ImportPipeline.runOrThrow({ lines: [" Alpha ", "", "Beta"] });
// ["alpha", "beta"]

Omitted targets and finalize use the last step in execution order: normalize. Missing output returns undefined; use requireOutputs when absence should fail.

runOrThrow returns the result or throws on failure. Use run for reports, plan for previews, and toMermaid for diagrams. See getting started.

Use the CLI

Projects made with defineProject(id, [pipeline, command]) register each pipeline once and are directly usable by the CLI; schema-backed pipelines get inferred flags automatically. See the CLI guide for direct project usage and advanced custom command adapters. From this repository:

bunx tubeless list --project examples/tubeless.project.ts
bunx tubeless inspect --project examples/tubeless.project.ts validated-import
bunx tubeless run --project examples/tubeless.project.ts validated-import -- --source rows.txt

In your app, add tubeless.project.ts and omit --project. Pass application flags after --. Record runs with --store or --trace, then inspect them with tubeless history or the local studio.

Use tubeless auth login and tubeless cloud list to select a Cloud pipeline by name or slug; see Cloud CLI usage. To host Studio in your own Cloudflare account, see Deploy to Cloudflare.

Find your route

• Start with a typed import or add dry runs and write gates to a publishing job.
• Build workflows with child pipelines and fan-out.
• Run tubeless agent --model gpt-5.4-mini for a conversation loop with live pipeline reporting, or build agents with custom tools, subagents, and durable checkpoints.
• Optional: the peloton example is a cycling-themed kitchen sink for the live TUI.

The recipe index covers validation, retries, tracing, testing, and more. For help authoring pipelines with a coding agent, install the agent skill pack with npx skills add chetmancini/tubeless.

Documentation

Website · Getting started · CLI · Studio · Concepts · Comparison · API · Agent authoring guide

Contributing

Open an issue before a large change or public API change. See CONTRIBUTING.md for checks and SECURITY.md to report vulnerabilities.

License

MIT