Skip to main content
Last updated: 2026-09-06
orca workflows works with workflows: reusable definitions (a graph of steps, each bound to an agent profile), the runs instantiated from them, and the cron schedules that launch them. A definition id looks like wfdef-...; a run id looks like workflow-.... Every subcommand accepts the global flags. All positionals on this page are required; there is no interactive picker. Destructive subcommands prompt for confirmation in a terminal; in a script --yes is required or the command refuses (exit code 2). Terminal and plain output print statuses as labels; --json output carries the API’s integer enums. A run is pending (0), running (1), paused (2), completed (3), failed (4), or cancelled (5). A step is pending (0), ready (1), running (2), ok (3), error (4), skipped (5), or cancelled (6).

​
orca workflows list

Lists the workflow definitions in the current tenant.
Plain (piped) output is one tab-separated row per definition: name, id, step count, updated.

​
orca workflows get

Shows one workflow definition and its steps. With --json the full definition object is printed. The plain view prints one row per step in dependency order: step name, profile, and the comma-separated ids it depends on.

​
orca workflows delete

Deletes a workflow definition. Existing runs are not affected.

​
orca workflows runs

Lists workflow runs, newest first. The group itself is the list action; there is no separate runs list.
Plain output is one tab-separated row per run: id, status, step count, created, duration.

​
orca workflows runs get

Shows one workflow run with per-step status. With --json the full run object is printed, including every step’s status, attempt, runId, output, and error. The plain view prints one row per step in dependency order: step name, profile, status, attempt number, duration.

​
orca workflows start

Starts a run. What happens depends on the id you pass:
  • A definition id (anything that does not start with workflow-) launches a new run. The CLI fetches the definition, takes its steps, and resolves the user prompt from --prompt or the definition’s own userPrompt; a definition with no prompt and no --prompt, or with no steps, exits 2. By default the new run is handed straight to the engine; with --no-autostart it is created in pending so you can start it later.
  • A run id (starts with workflow-) hands an existing pending run to the engine. --prompt and --no-autostart are ignored on this path. A run that is already past pending is left as is.
Without --json, stdout carries only the new run id and a status line goes to stderr, so the id can be captured directly. With --json the server’s accepted-action envelope is printed: workflowRunId, plus status or ok when the server sets them.

​
orca workflows tail

Streams a run until it reaches a terminal status (completed, failed, or cancelled). In a terminal the step tree updates live. When stdout is a pipe, each step status change is printed as one line: the step name, its previous status label, and its new status label; a workflow <id> finished: <status> line goes to stderr at the end. With --json the output is NDJSON: one { "type": ..., "workflowRun": ... } frame per line, where type is snapshot for the initial state and plan_status for each later change, and workflowRun is the full run object at that moment. The exit code is 0 when the run completes and 1 when it fails or is cancelled. Ctrl-C detaches the tail only (exit code 130): the run keeps going server-side and can be reattached with the same command or stopped with orca workflows cancel. A dropped connection is reconnected automatically with backoff.

​
orca workflows cancel

Cancels an in-flight workflow run. With --json the server’s accepted-action envelope is printed: workflowRunId, plus status or ok when the server sets them.

​
orca workflows repair

Repairs a paused run: abort it outright, or retry one failed step so the engine can continue. The other repair actions (replace_node, add_dependency) need a full step body and are only available through the API. With --json the server’s accepted-action envelope is printed.

​
orca workflows schedules

Lists workflow schedules. The group itself is the list action; there is no separate schedules list, and there is no create subcommand (schedules are created outside the CLI).
Plain output is one tab-separated row per schedule: id, definition id, cron, timezone, status (active or paused), last run time.

​
orca workflows schedules get

Shows one schedule. With --json the full schedule object is printed (workflowDefinitionId, cron, timezone, status, lastRunAt, lastError, and so on). The plain view prints the same single row as the listing.

​
orca workflows schedules pause

Pauses a schedule so it stops launching runs. With --json the updated schedule object is printed.

​
orca workflows schedules resume

Resumes a paused schedule. With --json the updated schedule object is printed.

​
orca workflows schedules delete

Deletes a schedule.
Verified against orca-cli cli-v0.5.0.