Workflow Commands - DBOS Transact

Overview

The dbos workflow command group provides tools for managing workflow execution, including listing, inspecting, canceling, resuming, and forking workflows.

dbos workflow list

List workflows for your application with filtering and pagination.

dbos workflow list [OPTIONS]

Options

--limit

int

default:"10"

Maximum number of workflows to return.

--offset

int

Offset for pagination. Skip this many workflows.

--sort-desc

boolean

default:"false"

Sort results in descending order (older workflows first).

--user

string

Filter by authenticated user ID.

--start-time

string

Retrieve workflows starting after this timestamp (ISO 8601 format).Example: 2024-03-15T10:00:00Z

--end-time

string

Retrieve workflows starting before this timestamp (ISO 8601 format).

--status

string

Filter by workflow status:

PENDING - Currently executing
SUCCESS - Completed successfully
ERROR - Failed with an error
ENQUEUED - Queued for execution
CANCELLED - Cancelled by user
MAX_RECOVERY_ATTEMPTS_EXCEEDED - Exceeded retry limit

--application-version

string

Filter by application version.

--name

string

Filter by workflow function name.

--db-url

string

Application database URL.

--sys-db-url

string

System database URL.

--schema

string

default:"dbos"

Schema name for DBOS system tables.

Examples

List recent workflows:

dbos workflow list --limit 5

[
  {
    "workflow_id": "wf_abc123",
    "name": "process_order",
    "status": "SUCCESS",
    "authenticated_user": "[email protected]",
    "created_at": "2024-03-15T10:30:00.000Z",
    "updated_at": "2024-03-15T10:30:05.123Z",
    "application_version": "1.0.0"
  },
  {
    "workflow_id": "wf_def456",
    "name": "send_notification",
    "status": "PENDING",
    "authenticated_user": null,
    "created_at": "2024-03-15T10:29:55.000Z",
    "updated_at": "2024-03-15T10:29:55.000Z",
    "application_version": "1.0.0"
  }
]

Filter by status:

dbos workflow list --status ERROR --limit 10

Filter by time range:

dbos workflow list --start-time 2024-03-15T00:00:00Z --end-time 2024-03-15T23:59:59Z

Filter by workflow name:

dbos workflow list --name process_order --limit 20

Pagination:

# First page
dbos workflow list --limit 10 --offset 0

# Second page
dbos workflow list --limit 10 --offset 10

dbos workflow get

Retrieve detailed status of a specific workflow.

dbos workflow get <workflow_id> [OPTIONS]

Arguments

workflow_id

string

required

The workflow ID to retrieve.

Options

--db-url

string

Application database URL.

--sys-db-url

string

System database URL.

--schema

string

default:"dbos"

Schema name for DBOS system tables.

Example

dbos workflow get wf_abc123

{
  "workflow_id": "wf_abc123",
  "name": "process_order",
  "status": "SUCCESS",
  "authenticated_user": "[email protected]",
  "created_at": "2024-03-15T10:30:00.000Z",
  "updated_at": "2024-03-15T10:30:05.123Z",
  "application_version": "1.0.0",
  "executor_id": "executor-1",
  "serialization": "py_pickle",
  "input": {"args": ["order-123"], "kwargs": {}},
  "output": {"status": "processed"},
  "error": null
}

dbos workflow steps

List all steps executed by a workflow.

dbos workflow steps <workflow_id> [OPTIONS]

Arguments

workflow_id

string

required

The workflow ID whose steps to list.

Options

--db-url

string

Application database URL.

--sys-db-url

string

System database URL.

--schema

string

default:"dbos"

Schema name for DBOS system tables.

Example

dbos workflow steps wf_abc123

[
  {
    "step_id": 1,
    "name": "validate_order",
    "type": "transaction",
    "status": "SUCCESS",
    "created_at": "2024-03-15T10:30:00.100Z",
    "updated_at": "2024-03-15T10:30:00.250Z",
    "output": {"valid": true}
  },
  {
    "step_id": 2,
    "name": "charge_payment",
    "type": "step",
    "status": "SUCCESS",
    "created_at": "2024-03-15T10:30:00.300Z",
    "updated_at": "2024-03-15T10:30:02.100Z",
    "output": {"transaction_id": "txn_789"}
  },
  {
    "step_id": 3,
    "name": "send_confirmation",
    "type": "step",
    "status": "SUCCESS",
    "created_at": "2024-03-15T10:30:02.150Z",
    "updated_at": "2024-03-15T10:30:05.000Z",
    "output": {"email_sent": true}
  }
]

dbos workflow cancel

Cancel a workflow to prevent automatic retries and restarts.

dbos workflow cancel <workflow_id> [OPTIONS]

Arguments

workflow_id

string

required

The workflow ID to cancel.

Options

--db-url

string

Application database URL.

--sys-db-url

string

System database URL.

--schema

string

default:"dbos"

Schema name for DBOS system tables.

Behavior

Sets the workflow status to CANCELLED
Prevents automatic retries on failure
Prevents recovery on application restart
Does not immediately stop a running workflow (it will complete its current step)

Example

dbos workflow cancel wf_abc123

Cancelled workflows can be resumed using dbos workflow resume.

dbos workflow resume

Resume a previously cancelled workflow.

dbos workflow resume <workflow_id> [OPTIONS]

Arguments

workflow_id

string

required

The workflow ID to resume.

Options

--db-url

string

Application database URL.

--sys-db-url

string

System database URL.

--schema

string

default:"dbos"

Schema name for DBOS system tables.

Behavior

Changes workflow status from CANCELLED back to PENDING
Allows the workflow to be recovered on next application start
Re-enables automatic retries

Example

dbos workflow resume wf_abc123

dbos workflow fork

Create a new workflow instance by forking an existing workflow, optionally starting from a specific step.

dbos workflow fork <workflow_id> [OPTIONS]

Arguments

workflow_id

string

required

The workflow ID to fork from.

Options

--step

int

default:"1"

Step number to restart from (1-indexed).

--forked-workflow-id

string

Custom ID for the forked workflow. If not provided, a new UUID is generated.

--application-version

string

Custom application version for the forked workflow.

--db-url

string

Application database URL.

--sys-db-url

string

System database URL.

--schema

string

default:"dbos"

Schema name for DBOS system tables.

Behavior

Creates a new workflow with the same inputs as the original
Optionally starts from a specific step (useful for retrying after a failure)
The original workflow is unchanged
Returns the status of the newly forked workflow

Examples

Fork from the beginning:

dbos workflow fork wf_abc123

{
  "workflow_id": "wf_xyz789",
  "name": "process_order",
  "status": "PENDING",
  "created_at": "2024-03-15T11:00:00.000Z"
}

Fork from step 3:

dbos workflow fork wf_abc123 --step 3

Fork with custom ID:

dbos workflow fork wf_abc123 --forked-workflow-id wf_retry_001

Fork with new version:

dbos workflow fork wf_abc123 --application-version 2.0.0

Use dbos workflow steps to identify which step failed, then fork from that step to retry.

Queue Commands

Manage enqueued workflows with the dbos workflow queue subcommand.

dbos workflow queue list

List enqueued workflows.

dbos workflow queue list [OPTIONS]

Options

--limit

int

Maximum number of results to return.

--offset

int

Offset for pagination.

--sort-desc

boolean

default:"false"

Sort in descending order (older first).

--start-time

string

Filter by creation time (after this timestamp).

--end-time

string

Filter by creation time (before this timestamp).

--status

string

Filter by status (PENDING, SUCCESS, ERROR, ENQUEUED, CANCELLED).

--queue-name

string

Filter by queue name.

--name

string

Filter by workflow function name.

--db-url

string

Application database URL.

--sys-db-url

string

System database URL.

--schema

string

default:"dbos"

Schema name for DBOS system tables.

Examples

List all enqueued workflows:

dbos workflow queue list --limit 10

[
  {
    "workflow_id": "wf_queued_001",
    "name": "background_job",
    "status": "ENQUEUED",
    "queue_name": "default",
    "created_at": "2024-03-15T10:00:00.000Z",
    "queue_position": 1
  },
  {
    "workflow_id": "wf_queued_002",
    "name": "batch_process",
    "status": "ENQUEUED",
    "queue_name": "batch",
    "created_at": "2024-03-15T10:01:00.000Z",
    "queue_position": 1
  }
]

Filter by queue:

dbos workflow queue list --queue-name batch --limit 20

Check queue status:

dbos workflow queue list --status PENDING

Common Workflows

Debugging a Failed Workflow

# 1. Find the failed workflow
dbos workflow list --status ERROR --limit 5

# 2. Get details
dbos workflow get wf_abc123

# 3. Check which step failed
dbos workflow steps wf_abc123

# 4. Fix the issue in code, then retry
dbos workflow fork wf_abc123 --step 3

Monitoring Workflow Execution

# Check recent workflows
dbos workflow list --limit 10

# Filter by time range
dbos workflow list \
  --start-time 2024-03-15T00:00:00Z \
  --end-time 2024-03-15T23:59:59Z

# Count by status
dbos workflow list --limit 1000 | \
  jq 'group_by(.status) | map({status: .[0].status, count: length})'

Managing Long-Running Workflows

# Find long-running workflows
dbos workflow list --status PENDING

# Cancel if needed
dbos workflow cancel wf_abc123

# Later, resume if canceled by mistake
dbos workflow resume wf_abc123

Working with Queues

# Check queue backlog
dbos workflow queue list --queue-name processing --status ENQUEUED

# Monitor queue progress
dbos workflow queue list --queue-name processing --limit 100 | \
  jq 'group_by(.status) | map({status: .[0].status, count: length})'

Output Format

All commands output JSON for easy parsing and scripting. Common fields:

Field	Type	Description
`workflow_id`	string	Unique workflow identifier
`name`	string	Workflow function name
`status`	string	Current status (PENDING, SUCCESS, ERROR, etc.)
`authenticated_user`	string \| null	User who triggered the workflow
`created_at`	string	ISO 8601 timestamp when workflow was created
`updated_at`	string	ISO 8601 timestamp of last update
`application_version`	string	Application version that created the workflow
`input`	object	Workflow input arguments
`output`	any	Workflow output (if completed)
`error`	string \| null	Error message (if failed)

Core API

Configuration

CLI

​Overview

​dbos workflow list

​Options

​Examples

​dbos workflow get

​Arguments

​Options

​Example

​dbos workflow steps

​Arguments

​Options

​Example

​dbos workflow cancel

​Arguments

​Options

​Behavior

​Example

​dbos workflow resume

​Arguments

​Options

​Behavior

​Example

​dbos workflow fork

​Arguments

​Options

​Behavior

​Examples

​Queue Commands

​dbos workflow queue list

​Options

​Examples

​Common Workflows

​Debugging a Failed Workflow

​Monitoring Workflow Execution

​Managing Long-Running Workflows

​Working with Queues

​Output Format

​See Also

Build docs developers (and LLMs) love

Overview

dbos workflow list

Options

Examples

dbos workflow get

Arguments

Options

Example

dbos workflow steps

Arguments

Options

Example

dbos workflow cancel

Arguments

Options

Behavior

Example

dbos workflow resume

Arguments

Options

Behavior

Example

dbos workflow fork

Arguments

Options

Behavior

Examples

Queue Commands

dbos workflow queue list

Options

Examples

Common Workflows

Debugging a Failed Workflow

Monitoring Workflow Execution

Managing Long-Running Workflows

Working with Queues

Output Format

See Also