Skip to content

run-command.md

Latest commit

 

History

History
237 lines (172 loc) · 7.1 KB

run-command.md

File metadata and controls

237 lines (172 loc) · 7.1 KB
Raw

workflow run Command

Execute a workflow via the Temporal runtime from the CLI.

Usage

workflow run <identifier> [--input JSON|@file] [--stream] [--interactive] [--no-follow] [--verbose] [--no-color]

Arguments

Argument Description
identifier Workflow UUID or name to execute

Options

Option Short Description
--input Initial input data as JSON string or @filepath
--stream Use SSE streaming instead of polling
--interactive -i Enable interactive HITL mode for inline input/review prompts. Requires --stream
--no-follow Start the workflow and exit immediately
--verbose Show detailed multi-line SSE output with payload excerpts
--no-color Disable colored output (also respects NO_COLOR env var)

Execution Modes

Polling (default)

Polls GET /v2/workflows/{id}/status every 2 seconds and displays node progress. Exits when the workflow reaches a terminal state or HITL gate.

workflow run 939843a8-6257-4475-bfc0-f7d6500d9f00

SSE Streaming (--stream)

Connects to POST /v2/workflows/{id}/run/temporal with Accept: text/event-stream and displays events as they arrive in real-time.

workflow run "Invoice Processing" --stream

Fire-and-Forget (--no-follow)

Starts the workflow, prints the run ID, and exits immediately. Useful for CI/CD pipelines or when monitoring separately.

workflow run my-workflow --no-follow

Input Data

Provide initial input data with --input:

# Inline JSON
workflow run my-workflow --input '{"question": "What is AI?"}'

# From file
workflow run my-workflow --input @input.json

Identifier Resolution

The <identifier> argument is resolved in this order:

  1. UUID passthrough — if it matches UUID format, use directly
  2. Lockfile lookup — scan *.workflow.lock files in the current directory for a matching workflow name
  3. API name search — list workflows via API and filter by name (case-insensitive)

HITL Gate Behavior

When the workflow reaches a human-in-the-loop gate (INPUT or REVIEW node), the command prints a hint and exits with code 0:

⏸  Workflow paused — waiting for human review
   Use: workflow review <run-id> --approve

⏸  Workflow paused — waiting for input
   Use: workflow input <run-id> --data '{...}'

File Upload

When a workflow contains file_upload nodes, the CLI handles file uploads during interactive execution.

Interactive Mode

In --stream --interactive mode, the CLI prompts for file paths when the workflow reaches a file_upload node:

$ workflow run <id> --stream --interactive
...
File upload required
Node: upload-doc (FILE_UPLOAD)
Accepted formats: pdf, docx
Max file size: 10.0 MB
File path: /path/to/report.pdf
Added: report.pdf
Add another file? [y/N]: n
Uploading report.pdf... done
Files submitted.

.workflow.last_run Context File

After starting a workflow, a .workflow.last_run file is written to the current directory. This file stores the run context for use by subsequent commands (workflow status, workflow input, workflow review).

# Auto-generated by workflow CLI. Do not edit manually.
workflow_id: 939843a8-6257-4475-bfc0-f7d6500d9f00
run_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
instance: https://api.sb.allogy.com
started_at: '2026-02-25T10:30:00+00:00'

Node Outputs

When a workflow completes successfully, the CLI automatically fetches and displays all node outputs. This shows the data produced by each node during execution:

Node Outputs
  upload-invoice:
    {
      "files": ["invoice.pdf"]
    }
  extract-data:
    {
      "vendor": "Acme Corp",
      "total": 1250.00
    }

Node outputs are displayed using node slugs when available, falling back to truncated UUIDs. This feature works in both streaming and polling modes.

To view node outputs for a previously completed run, use:

workflow status --show-outputs

Retry Behavior

In streaming mode (--stream), the CLI automatically retries on transient server errors:

  • 502/503 errors — retried up to 2 attempts with a 1.5-second delay between attempts. These indicate the server is temporarily unavailable or overloaded.
  • Network errors — connection failures and timeouts are retried under the same policy (2 attempts, 1.5s delay).
  • Non-retryable errors — 400 (bad request) and 404 (not found) fail immediately without retrying, as these indicate a client-side error that will not resolve on retry.

SSE Events

Streaming mode processes AG-UI SSE events from the Temporal runtime and renders them with color coding by event type.

Key Event Types

Event Behavior
STATE_DELTA Extracts and displays node output text in real time
CUSTOM with SSE_PAUSING Detected as a HITL pause signal — exits cleanly without hanging
RUN_STARTED Displays run ID and confirms execution has begun
RUN_FINISHED Triggers node output fetch and final status display
STEP_STARTED / STEP_FINISHED Shows node progress with step name
TEXT_MESSAGE_* Streams assistant message content as it arrives
TOOL_CALL_* Shows tool invocations during node execution

Use --verbose to see full event payloads with field excerpts for all event types.

Workflow Statuses

The following workflow statuses may be encountered during or after execution:

Status Description
RUNNING Workflow is actively executing
COMPLETED Workflow finished successfully
FAILED Workflow encountered an unrecoverable error
PAUSED Workflow is paused (manual pause or HITL gate)
TIMED_OUT Workflow exceeded its execution time limit
WAITING_FOR_INPUT Workflow paused at an INPUT node awaiting user data
WAITING_FOR_REVIEW Workflow paused at a REVIEW node awaiting human decision

Exit Codes

Code Meaning
0 Workflow completed or paused at HITL gate
1 Runtime error (network, server, timeout)
2 User error (bad input, not found, invalid JSON)

Examples

# Run by UUID
workflow run 939843a8-6257-4475-bfc0-f7d6500d9f00

# Run by name with input
workflow run "Invoice Processing" --input '{"question": "What is AI?"}'

# Stream events in real-time
workflow run my-workflow --input @input.json --stream

# Stream with verbose output
workflow run my-workflow --stream --verbose

# Interactive HITL mode (inline prompts for input/review)
workflow run my-workflow --stream --interactive
workflow run my-workflow --stream -i

# Fire-and-forget
workflow run my-workflow --no-follow

# Disable color for CI pipelines
workflow run my-workflow --stream --no-color

See Also