Running Pipelines

Pipelines can be executed either through the CLI or programmatically with @ucdjs/pipeline-executor.

# List discovered pipelines
./packages/cli/bin/ucd.js pipelines list --cwd packages/pipelines/pipeline-playground

# Run one pipeline by ID
./packages/cli/bin/ucd.js pipelines run source-and-route --cwd packages/pipelines/pipeline-playground

# Launch the Pipeline Server
./packages/cli/bin/ucd.js pipelines run --ui --cwd packages/pipelines/pipeline-playground

import { createPipelineExecutor } from "@ucdjs/pipeline-executor";

const executor = createPipelineExecutor({
  onLog(entry) {
    console.log(entry.level, entry.message);
  },
});

const results = await executor.run([myPipeline], {
  cache: true,
  versions: ["1.0.0"],
});

The executor orders pipelines that depend on published outputs, resolves source files, evaluates route filters, respects the route DAG, materializes outputs, and emits logs and traces to the host.

Hooks during execution

Pipeline definitions can include hooks for side effects during execution. Hooks run inside the executor lifecycle and receive ctx.phase as either "start" or "end".

const pipeline = definePipeline({
  id: "with-hooks",
  name: "With Hooks",
  versions: ["1.0.0"],
  inputs: [source],
  routes: [route],
  hooks: {
    route(ctx) {
      ctx.logger.info("Route lifecycle", {
        phase: ctx.phase,
        routeId: ctx.routeId,
      });
    },
  },
});

Use hooks when the pipeline itself owns the side effect, such as custom metrics, notifications, or extra bookkeeping. Use executor-level onLog when the host application wants to collect logs from many pipelines in one place.

Useful CLI flags

• --cwd <path> to change the discovery root
• --path <path> to narrow discovery within a directory or repository
• --github <owner/repo> and --gitlab <owner/repo> to load remote pipeline definitions
• --ref <ref> to target a branch, tag, or commit
• --ui and --port <number> to launch the Pipeline Server