> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# orca workflows

> List, start, tail, cancel, and repair workflow runs, and manage workflow definitions and schedules.

> **Last updated: 2026-09-06**

`orca workflows` works with [workflows](/concepts/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](/cli/reference/overview#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

```bash theme={"dark"}
orca workflows list [--limit <n>] [--offset <n>] [--all]
```

Lists the workflow definitions in the current tenant.

| Flag           | Type    | Default | Description                                                        |
| -------------- | ------- | ------- | ------------------------------------------------------------------ |
| `--limit <n>`  | integer | `10`    | Page size                                                          |
| `--offset <n>` | integer | `0`     | Page offset                                                        |
| `--all`        | boolean | `false` | Fetch every page (cannot be combined with `--limit` or `--offset`) |

```bash theme={"dark"}
orca workflows list --all --json | jq -r '.[] | "\(.id)\t\(.name)"'
```

Plain (piped) output is one tab-separated row per definition: `name`, `id`, step count, `updated`.

## orca workflows get

```bash theme={"dark"}
orca workflows get <id>
```

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.

```bash theme={"dark"}
orca workflows get wfdef-nightly --json | jq '.nodes[] | {id, profile, dependsOn}'
```

## orca workflows delete

```bash theme={"dark"}
orca workflows delete <id> [--yes]
```

Deletes a workflow definition. Existing runs are not affected.

| Flag    | Type    | Default | Description                  |
| ------- | ------- | ------- | ---------------------------- |
| `--yes` | boolean | `false` | Skip the confirmation prompt |

```bash theme={"dark"}
orca workflows delete wfdef-nightly --yes --json
```

```json theme={"dark"}
{ "id": "wfdef-nightly", "deleted": true }
```

## orca workflows runs

```bash theme={"dark"}
orca workflows runs [--status <status>] [--orchestrator <runId>] [--limit <n>] [--offset <n>] [--all]
```

Lists workflow runs, newest first. The group itself is the list action; there is no separate `runs list`.

| Flag                     | Type    | Default | Description                                                                                                                    |
| ------------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--status <status>`      | string  | none    | Filter by status: one of `pending`, `running`, `paused`, `completed`, `failed`, `cancelled` (forwarded to the server as given) |
| `--orchestrator <runId>` | string  | none    | Only runs spawned by this orchestrator run                                                                                     |
| `--limit <n>`            | integer | `10`    | Page size                                                                                                                      |
| `--offset <n>`           | integer | `0`     | Page offset                                                                                                                    |
| `--all`                  | boolean | `false` | Fetch every page (cannot be combined with `--limit` or `--offset`)                                                             |

```bash theme={"dark"}
orca workflows runs --status failed --all --json | jq -r '.[].id'
```

Plain output is one tab-separated row per run: `id`, `status`, step count, `created`, `duration`.

### orca workflows runs get

```bash theme={"dark"}
orca workflows runs get <id>
```

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.

```bash theme={"dark"}
orca workflows runs get workflow-3f9a1c --json | jq '.nodes[] | select(.status == 4) | {id, error}'
```

## orca workflows start

```bash theme={"dark"}
orca workflows start <id> [--prompt <text>] [--no-autostart]
```

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.

| Flag              | Type    | Default                       | Description                                                                                   |
| ----------------- | ------- | ----------------------------- | --------------------------------------------------------------------------------------------- |
| `--prompt <text>` | string  | the definition's `userPrompt` | User prompt for the new run; overrides the definition's default. Definition ids only          |
| `--no-autostart`  | boolean | autostart on                  | Create the run in `pending` instead of handing it straight to the engine. Definition ids only |

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.

```bash theme={"dark"}
RUN=$(orca workflows start wfdef-nightly --prompt "Summarize yesterday's incidents")
orca workflows tail "$RUN"
```

## orca workflows tail

```bash theme={"dark"}
orca workflows tail <run-id>
```

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.

```bash theme={"dark"}
orca workflows tail workflow-3f9a1c --json | jq -c '{type, status: .workflowRun.status}'
```

## orca workflows cancel

```bash theme={"dark"}
orca workflows cancel <run-id> [--yes]
```

Cancels an in-flight workflow run.

| Flag    | Type    | Default | Description                  |
| ------- | ------- | ------- | ---------------------------- |
| `--yes` | boolean | `false` | Skip the confirmation prompt |

With `--json` the server's accepted-action envelope is printed: `workflowRunId`, plus `status` or `ok` when the server sets them.

```bash theme={"dark"}
orca workflows cancel workflow-3f9a1c --yes
```

## orca workflows repair

```bash theme={"dark"}
orca workflows repair <run-id> --type <type> [--node <id>]
```

Repairs a paused run: abort it outright, or retry one failed step so the engine can continue.

| Flag            | Type   | Default  | Description                                         |
| --------------- | ------ | -------- | --------------------------------------------------- |
| `--type <type>` | string | required | `abort` or `retry-node`                             |
| `--node <id>`   | string | none     | Step id to retry; required with `--type retry-node` |

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.

```bash theme={"dark"}
orca workflows repair workflow-3f9a1c --type retry-node --node summarize
```

## orca workflows schedules

```bash theme={"dark"}
orca workflows schedules [--limit <n>] [--offset <n>] [--all]
```

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).

| Flag           | Type    | Default | Description                                                        |
| -------------- | ------- | ------- | ------------------------------------------------------------------ |
| `--limit <n>`  | integer | `10`    | Page size                                                          |
| `--offset <n>` | integer | `0`     | Page offset                                                        |
| `--all`        | boolean | `false` | Fetch every page (cannot be combined with `--limit` or `--offset`) |

```bash theme={"dark"}
orca workflows schedules --all --json | jq -r '.[] | select(.status == "paused") | .id'
```

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

```bash theme={"dark"}
orca workflows schedules get <id>
```

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.

```bash theme={"dark"}
orca workflows schedules get sched-01J... --json
```

### orca workflows schedules pause

```bash theme={"dark"}
orca workflows schedules pause <id>
```

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

```bash theme={"dark"}
orca workflows schedules pause sched-01J...
```

### orca workflows schedules resume

```bash theme={"dark"}
orca workflows schedules resume <id>
```

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

```bash theme={"dark"}
orca workflows schedules resume sched-01J...
```

### orca workflows schedules delete

```bash theme={"dark"}
orca workflows schedules delete <id> [--yes]
```

Deletes a schedule.

| Flag    | Type    | Default | Description                  |
| ------- | ------- | ------- | ---------------------------- |
| `--yes` | boolean | `false` | Skip the confirmation prompt |

```bash theme={"dark"}
orca workflows schedules delete sched-01J... --yes --json
```

```json theme={"dark"}
{ "id": "sched-01J...", "deleted": true }
```

<Note>
  Verified against orca-cli `cli-v0.5.0`.
</Note>