Workflows
Durable orchestration over tables, columns, tools, transforms, approvals, and external sync.
A workflow is a repeatable GTM process. It can chain columns, provider tool calls, transforms, approvals, table writes, and external sync. It fires from an API call, schedule, webhook, or event. Each fire produces a run.
Shape
| Field | Notes |
|---|---|
id | Stable workflow identifier |
name | Human-readable |
kind | Applied template, blueprint, durable recipe, or chained-column automation |
trigger | API, cron, webhook, or event; see Triggers |
mode_default | Default execution mode; see Modes |
enabled | Boolean. Disabled workflows ignore triggers |
steps | Ordered |
approval_policy | When approval is required |
cost_posture | Predicted credit consumption per fire |
Three ways to define a workflow
| Source | Use when |
|---|---|
| Blueprints or workflow templates | A reusable pattern exists in the catalog |
| Durable recipes | Custom TypeScript logic with conditionals |
| Chained columns | Single-table, sequential, no branching |
All three compile to the same internal representation.
Working with workflows
oxygen workflows list --json
oxygen workflows list --include-archived --json # archived workflows are hidden by default
oxygen workflows get <workflow-id> --json
oxygen workflows schema --json # full JSON schema for a workflow spec
oxygen workflows lint --file workflow.ts --json # validate without applying
oxygen workflows apply --file workflow.ts --json # create or update
oxygen workflows duplicate <workflow-id> --json
oxygen workflows rename <workflow-id> "New name" --json
oxygen workflows enable <workflow-id> --json
oxygen workflows disable <workflow-id> --json
oxygen workflows delete <workflow-id> --json # archive (reversible); add --purge to remove permanentlyenable and disable accept several workflow ids at once and report per-item results.
Deleting, archiving, and restoring
delete archives by default: the workflow disappears from workflows list, its trigger is disarmed so it can never fire, and its run history stays inspectable. Restore it anytime with workflows enable (back and armed) or workflows disable (back but paused); find archived workflows with workflows list --include-archived. Only delete --purge removes a workflow permanently — that cannot be undone. Pass --reason "<why>" on any of these to record the reason for your workspace.
Cron-triggered workflows show a human-readable schedule ("Every 5 minutes", "Daily at 10:00") in list/get output, and schedules that fire more often than every 15 minutes come back with a non-blocking warning on apply/enable — confirm the cadence is intentional before arming them.
Running a workflow
oxygen workflows call <workflow-id> --input-json '{"key":"value"}' --mode smoke_test --json
oxygen workflows call <workflow-id> --input-json '{"key":"value"}' --mode dry_run --json
oxygen workflows call <workflow-id> --input-json '{"key":"value"}' --mode live --json
oxygen workflows tail <workflow-run-id> --json
oxygen workflows run <workflow-run-id> --json # inspect one run
oxygen workflows cancel <run-id> --jsoncall enqueues a workflow run through the workflow's trigger shape. run inspects an existing workflow run by run id.
Inspecting fires
oxygen workflows runs --workflow <workflow-id> --json
oxygen workflows failures --jsonBoth return run records.
Events
A workflow can emit events that other workflows subscribe to. See Triggers for the event model.
oxygen workflows events emit --source tenant --event lead.qualified --payload-json '{"id":"lead_123","score":87}' --mode dry_run --json