@outputai/cli - Output Framework

The output CLI is how you create projects, start development services, run workflows, and debug executions. It’s the main way you interact with Output during development.

Quick Start

# Create a new project
npx @outputai/cli init
cd <project-name>

# Start development services (Temporal, API, worker)
npx output dev

# Run a workflow with a test scenario
npx output workflow run lead_enrichment acme

Command Reference

Command	Description
`output init`	Create a new project
`output dev`	Start development services
`output update`	Update CLI and agent configuration
`output workflow plan`	Generate a workflow plan from a description
`output workflow generate`	Generate workflow code from a plan
`output workflow list`	List available workflows
`output workflow runs list`	List recent workflow runs
`output workflow run`	Run a workflow and wait for the result
`output workflow start`	Start a workflow without waiting
`output workflow status`	Check workflow execution status
`output workflow monitor`	Attach to a run and stream status updates until it ends
`output workflow result`	Get a completed workflow’s result
`output workflow stop`	Stop a workflow gracefully
`output workflow terminate`	Force-stop a workflow
`output workflow reset`	Rerun a workflow from after a completed step
`output workflow debug`	Show the execution trace
`output workflow cost`	Calculate execution cost from a trace
`output workflow test`	Run evaluations against a workflow
`output workflow dataset list`	List datasets for a workflow
`output workflow dataset generate`	Generate a dataset from a scenario or trace

Project Commands

output init

Create a new Output project with the standard file structure:

output init [folder-name]

folder-name

string

Name of the project folder to create

Flag	Default	Description
`--skip-env`	false	Skip interactive environment variable setup

output dev

Start all development services via Docker Compose:

output dev

This starts:

Service	URL	Description
Temporal UI	http://localhost:8080	Monitor and debug workflows
API Server	http://localhost:3001	REST API for running workflows
Worker	—	Processes workflows with auto-reload
PostgreSQL	—	Temporal persistence (container-internal)
Redis	—	Caching layer (container-internal)
Temporal Server	—	gRPC endpoint (container-internal)

Flag	Default	Description
`--compose-file, -f`	—	Path to custom docker-compose file
`--no-watch`	false	Disable file watching

Running multiple dev stacks

You can run multiple isolated Output stacks on the same machine — useful when working across several projects simultaneously or testing against different versions. Each stack needs a unique project name and non-conflicting host ports. Set these in the project’s .env:

# Project A (.env) — defaults, no changes needed
DOCKER_SERVICE_NAME=project-a

# Project B (.env)
DOCKER_SERVICE_NAME=project-b
OUTPUT_CATALOG_ID=project-b
OUTPUT_API_HOST_PORT=3002
OUTPUT_TEMPORAL_UI_HOST_PORT=8081
OUTPUT_TEMPORAL_HOST_PORT=7234

DOCKER_SERVICE_NAME isolates Docker networks, volumes, and container names so the stacks don’t interfere with each other. OUTPUT_CATALOG_ID keeps each stack’s workflow catalog separate. The three OUTPUT_*_HOST_PORT vars control which ports are exposed on your machine — the container-internal ports are unchanged, so workers in either stack still reach Temporal at temporal:7233. Run npx output dev in each project directory. Project A’s API is at http://localhost:3001 and Project B’s at http://localhost:3002. If a port is already in use, output dev names the conflicting port and the env var to override.

output dev eject

Export the Docker Compose configuration so you can customize it:

output dev eject

Flag	Default	Description
`--output, -o`	docker-compose.yml	Output path
`--force, -f`	false	Overwrite existing file

output update

Update the Output CLI and agent configuration:

output update

With no flags, updates everything. Use flags to update specific components:

Flag	Description
`--cli`	Update CLI packages only
`--agents`	Update Claude Code agent configuration only

Workflow Commands

output workflow plan

Generate a workflow plan from a natural language description. The command prompts for a description, generates a plan using AI, and lets you iterate on it interactively. Type ACCEPT to save.

output workflow plan
output workflow plan --description "Enrich leads by looking up company data and generating a summary"

Flag	Default	Description
`--description, -d`	—	Workflow description (prompts if not provided)
`--force-agent-file-write`	false	Force overwrite agent templates

output workflow generate

Generate workflow code from a plan or description:

output workflow generate <name>

name

string

required

Name of the workflow to generate

Flag	Default	Description
`--skeleton, -s`	false	Generate minimal skeleton without examples
`--description, -d`	—	Workflow description
`--output-dir, -o`	workflows/	Output directory
`--force, -f`	false	Overwrite existing directory
`--plan-file, -p`	—	Path to plan file for AI-assisted implementation

# Generate a skeleton workflow
output workflow generate lead_enrichment --skeleton

# Generate from a saved plan
output workflow generate lead_enrichment --plan-file .outputai/plans/2025_01_15_lead_enrichment/PLAN.md

output workflow list

List available workflows from the catalog:

output workflow list
output workflow list --format json --detailed

Flag	Default	Description
`--format, -f`	list	Output format: list, table, json
`--detailed, -d`	false	Show schemas and descriptions
`--filter`	—	Filter by name

output workflow runs list

List recent workflow runs, optionally filtered by workflow name:

output workflow runs list
output workflow runs list lead_enrichment --limit 10
output workflow runs list lead_enrichment --format json

workflowName

string

Filter by workflow name (optional)

Flag	Default	Description
`--limit, -l`	100	Maximum runs to return
`--format, -f`	table	Output format: table, json, text

output workflow run

Run a workflow synchronously and wait for the result:

output workflow run <workflowName> [scenario]

workflowName

string

required

Name of the workflow to execute

scenario

string

Scenario name — resolved from the workflow’s scenarios/ directory

Flag	Default	Description
`--input, -i`	—	JSON input or file path (overrides scenario)
`--catalog, -c`	`OUTPUT_CATALOG_ID`	Catalog name (the deprecated `--task-queue, -q` aliases still work)
`--format, -f`	text	Output format: json, text

# Using a scenario file (recommended for repeatable tests)
output workflow run lead_enrichment acme

# Using inline JSON
output workflow run lead_enrichment --input '{"companyDomain": "acme.com"}'

# Using a file path
output workflow run lead_enrichment --input ./test_input.json

output workflow start

Start a workflow asynchronously — returns the workflow ID immediately without waiting:

output workflow start <workflowName> [scenario]

workflowName

string

required

Name of the workflow to start

scenario

string

Scenario name — resolved from the workflow’s scenarios/ directory

Flag	Default	Description
`--input, -i`	—	JSON input or file path (overrides scenario)
`--catalog, -c`	`OUTPUT_CATALOG_ID`	Catalog name (the deprecated `--task-queue, -q` aliases still work)

output workflow status

Check whether a workflow is still running, completed, or failed:

output workflow status <workflowId>

workflowId

string

required

The workflow execution ID

Flag	Default	Description
`--format, -f`	text	Output format: json, text

output workflow monitor

Attach to a workflow run and stream status updates until it ends — a step starts, completes, or fails is printed as it happens, so you don’t have to re-run workflow status in a loop to watch a long-running workflow:

output workflow monitor <workflowId>

workflowId

string

required

The workflow execution ID

Flag	Default	Description
`--run-id, -r`	latest run	Monitor a specific run (continue-as-new chains are followed regardless of this flag)
`--format, -f`	text	Output format: json, text
`--include-payloads`	false	Include decoded step input/output payloads
`--interval`	2500	Poll interval in milliseconds. Also bounds the resumed long-poll’s server-side wait, so an idle workflow’s update cadence is roughly twice this value, not a longer separate server default.
`--color`	true	Colorize status output (`--no-color` to disable)

Exits 0 when the workflow completes, 1 when it fails, is canceled, terminated, or times out, and 130 if you detach with Ctrl+C — detaching never stops the workflow itself. monitor also exits 1 after 5 consecutive transient poll failures (network errors, 5xx/408/429 responses), printing a warning before each retry — this is API/network trouble, not a workflow outcome, but shares the same exit code.

output workflow monitor wf-12345
output workflow monitor wf-12345 --run-id 2fe0b36b-...
output workflow monitor wf-12345 --format json

--format json here is not the same thing as the native --json flag used by workflow run, workflow status, and other commands migrated in OUT-419 (see the changelog). Native --json suppresses all in-progress log output and prints a single JSON object once the command finishes. monitor has no single final result to print — it’s a long-running command that emits a stream of discrete events (a step starting or finishing, a continue-as-new notice, a final summary) while the workflow is still running. --format json prints each event as its own line of newline-delimited JSON as it happens, so the output can be piped into jq or read incrementally by another process — often another automated or agent process rather than a person, which is the primary reason this command keeps its own JSON mode instead of adopting --json.

output workflow result

Get the output of a completed workflow:

output workflow result <workflowId>

workflowId

string

required

The workflow execution ID

Flag	Default	Description
`--format, -f`	text	Output format: json, text

Workflow result JSON format

Use --format json with output workflow run or output workflow result to print the full structured workflow result:

{
  "workflowId": "lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "runId": "b5c6d7e8-9012-3456-7890-abcdef123456",
  "status": "completed",
  "input": { "companyDomain": "acme.com" },
  "output": {
    "company": "Acme Corp",
    "summary": "Enterprise software company focused on..."
  },
  "trace": { "destinations": {} },
  "error": null
}

Field	Description
`workflowId`	Workflow execution ID.
`runId`	Specific Temporal run ID.
`status`	Current or final execution status.
`input`	Original workflow input.
`output`	Value returned by the workflow on success, or `null` on failure.
`trace`	Trace metadata for the run, or `null` when unavailable.
`error`	Error message on failure, otherwise `null`.

output workflow stop

Stop a running workflow gracefully:

output workflow stop <workflowId>

workflowId

string

required

The workflow execution ID

output workflow terminate

Force-stop a workflow immediately. Use this for stuck workflows or cleaning up after branch switches:

output workflow terminate <workflowId>
output workflow terminate wf-12345 --reason "Cleaning up old workflows"

workflowId

string

required

The workflow execution ID

Flag	Default	Description
`--reason, -r`	—	Reason for termination

Unlike stop (which cancels gracefully), terminate kills the workflow immediately.

output workflow reset

Rerun a workflow from after a specific completed step. The current run is terminated and a new run is created that replays up to the given step (reusing its output), then re-executes every step after it. Useful when iterating on a late step without re-paying the cost of earlier LLM or API calls:

output workflow reset <workflowId> --step <stepName>
output workflow reset lead_enrichment-a1b2c3d4 --step consolidateCompetitors --reason "Retry with updated prompt"

workflowId

string

required

The workflow execution ID

Flag	Default	Description
`--step, -s`	—	Required. Name of the completed step to reset after. The step itself is not re-executed; every step after it is.
`--reason, -r`	—	Free-text reason, recorded in Temporal history for auditability

The command prints the original workflowId and a new runId for the fresh execution. Use output workflow status <workflowId> and output workflow result <workflowId> to track it.

Find valid step names with output workflow debug <workflowId> --format json — the step name you pass to --step is the one shown on completed step entries.

output workflow debug

Show the execution trace for a workflow — what steps ran, what they received and returned, and where failures happened. See Tracing for details on trace format.

output workflow debug <workflowId>
output workflow debug wf-12345 --format json

workflowId

string

required

The workflow execution ID

Flag	Default	Description
`--format, -f`	text	Output format: json, text

Use --format json to get the full untruncated trace. The text format truncates long values for readability, but the JSON format preserves everything.

output workflow cost

Calculate the estimated dollar cost of a workflow execution from its trace. Covers LLM token costs and API service costs. See Cost Estimation for details on pricing configuration and the config/costs.yml override file.

output workflow cost <workflowId> [tracePath]

workflowId

string

required

Workflow ID to calculate cost for

tracePath

string

Path to a local trace JSON file. If omitted, fetches the latest trace for the workflow.

Flag	Default	Description
`--format, -f`	text	Output format: json, text
`--verbose`	false	Show per-call breakdown with token counts and individual step costs

# Cost from latest trace
output workflow cost lead_enrichment_QlcADmOM

# Cost from a specific trace file
output workflow cost lead_enrichment_QlcADmOM logs/runs/lead_enrichment/2026-03-01_trace.json

# Detailed per-call breakdown
output workflow cost lead_enrichment_QlcADmOM --verbose

# Machine-readable output
output workflow cost lead_enrichment_QlcADmOM --format json

If the report shows “Unknown models”, add them to config/costs.yml in your project root. See Cost Estimation — Pricing Configuration for the format.

Evaluation Commands

These commands run offline evaluations against your workflows using the @outputai/evals package. You define evaluators, write dataset YAML files, and use these commands to execute and manage them.

output workflow test

Run evaluations against a workflow using its datasets:

output workflow test <workflowName>

workflowName

string

required

Name of the workflow to test

Flag	Default	Description
`--cached`	false	Use cached output from dataset files (skip workflow execution). Exclusive with `--save`
`--save`	false	Run workflow and save output back to dataset files. Exclusive with `--cached`
`--dataset, -d`	—	Comma-separated list of dataset names to run
`--format, -f`	text	Output format: text, json

# Run evals using cached output (fast — no workflow execution)
output workflow test simple --cached

# Run evals with fresh execution and save results back to datasets
output workflow test simple --save

# Run specific datasets only
output workflow test simple --dataset basic_input,edge_case

# Get JSON output for CI integration
output workflow test simple --cached --format json

Dataset Commands

output workflow dataset list

List datasets for a workflow:

output workflow dataset list <workflowName>

workflowName

string

required

Workflow name to list datasets for

Flag	Default	Description
`--format, -f`	table	Output format: table, json, text

output workflow dataset list simple
output workflow dataset list simple --format json

output workflow dataset generate

Generate a dataset for a workflow from a scenario, inline JSON, a local trace file, or recent runs:

output workflow dataset generate <workflowName> [scenario]

workflowName

string

required

Name of the workflow

scenario

string

Scenario name — resolved from the workflow’s scenarios/ directory

Flag	Default	Description
`--input, -i`	—	Workflow input as JSON string or file path (overrides scenario)
`--name, -n`	—	Dataset name (defaults to scenario name or trace filename)
`--trace, -t`	—	Path to a local trace file to extract dataset from. Exclusive with `--download`
`--download, -d`	false	Generate datasets from recent workflow runs, fetched via the Output API. Exclusive with `--trace`
`--limit, -l`	5	Maximum number of recent runs to fetch
`--catalog, -c`	`OUTPUT_CATALOG_ID`	Catalog to scope runs to (used with `--download`)

# Generate from a scenario
output workflow dataset generate simple basic_input

# Generate with inline JSON input
output workflow dataset generate simple --input '{"values": [1, 2, 3]}' --name custom_case

# Generate from a local trace file
output workflow dataset generate simple --trace logs/runs/simple/trace.json --name from_trace

# Generate datasets from the most recent runs (traces fetched via the API)
output workflow dataset generate simple --download --limit 10

Environment Configuration

By default, the CLI loads environment variables from .env in the current directory. To use a different env file:

# Use production environment
OUTPUT_CLI_ENV=.env.prod output workflow list

# Use staging environment
OUTPUT_CLI_ENV=.env.staging output workflow run lead_enrichment acme

Variable	Default	Description
`OUTPUT_CLI_ENV`	`.env`	Path to custom env file (relative or absolute)
`OUTPUT_API_URL`	`http://localhost:3001`	Output API server URL used by workflow commands
`OUTPUT_API_AUTH_TOKEN`	—	API auth token for requests (required in production)
`OUTPUT_DEBUG`	—	Set to `true` to enable CLI debug mode
`DOCKER_SERVICE_NAME`	`output-sdk`	Docker Compose project name for `output dev` — isolates containers, networks, and volumes
`OUTPUT_API_HOST_PORT`	`3001`	Host port for the Output API server
`OUTPUT_TEMPORAL_UI_HOST_PORT`	`8080`	Host port for the Temporal UI
`OUTPUT_TEMPORAL_HOST_PORT`	`7233`	Host port for the Temporal gRPC endpoint. Override to run multiple dev stacks side-by-side
`OUTPUT_API_VERSION`	`1.9`	API Docker image tag. Set to `dev` for local builds
`OUTPUT_WORKFLOWS_DIR`	`.`	Workflows subdirectory relative to project root. Set to `test_workflows` for monorepo dev
`ANTHROPIC_API_KEY`	—	Anthropic API key for AI-assisted workflow generation (`workflow plan`, `workflow generate`)

​Quick Start

​Command Reference

​Project Commands

​output init

​output dev

​Running multiple dev stacks

​output dev eject

​output update

​Workflow Commands

​output workflow plan

​output workflow generate

​output workflow list

​output workflow runs list

​output workflow run

​output workflow start

​output workflow status

​output workflow monitor

​output workflow result

​Workflow result JSON format

​output workflow stop

​output workflow terminate

​output workflow reset

​output workflow debug

​output workflow cost

​Evaluation Commands

​output workflow test

​Dataset Commands

​output workflow dataset list

​output workflow dataset generate

​Environment Configuration

Quick Start

Command Reference

Project Commands

output init

output dev

Running multiple dev stacks

output dev eject

output update

Workflow Commands

output workflow plan

output workflow generate

output workflow list

output workflow runs list

output workflow run

output workflow start

output workflow status

output workflow monitor

output workflow result

Workflow result JSON format

output workflow stop

output workflow terminate

output workflow reset

output workflow debug

output workflow cost

Evaluation Commands

output workflow test

Dataset Commands

output workflow dataset list

output workflow dataset generate

Environment Configuration