CLI Overview

Introduction

The DBOS CLI (dbos) provides command-line tools for managing your DBOS applications, workflows, and databases.

Installation

The DBOS CLI is automatically installed with the dbos Python package:

pip install dbos

Verify installation:

dbos version

DBOS CLI version: 1.0.0

Command Structure

The CLI uses the following structure:

dbos [COMMAND] [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Main Commands

Command	Description
`dbos version`	Show DBOS CLI version
`dbos init`	Initialize a new DBOS application
`dbos start`	Start your DBOS application
`dbos migrate`	Run database migrations
`dbos reset`	Reset the system database
`dbos workflow`	Manage workflows
`dbos postgres`	Manage local PostgreSQL with Docker

Common Options

Many commands accept database connection options:

--db-url

string

Application database URL. Overrides configuration file.

--sys-db-url

string

System database URL. Overrides configuration file.

--schema

string

default:"dbos"

Schema name for DBOS system tables.

Database URL Resolution

The CLI resolves database URLs in the following order:

DBOS Cloud environment variables (if DBOS__CLOUD=true):
- DBOS_SYSTEM_DATABASE_URL
- DBOS_DATABASE_URL
Command-line options:
- --sys-db-url
- --db-url
Configuration file (dbos-config.yaml):
- system_database_url
- application_database_url or database_url
Default SQLite database:
- sqlite:///{app_name}.sqlite

Application Commands

dbos version

Display the DBOS CLI version.

dbos version

dbos init

Initialize a new DBOS application from a template.

dbos init [PROJECT_NAME] [OPTIONS]

Options:

PROJECT_NAME

string

Application name. If not provided, you’ll be prompted to select a template and enter a name.

--template

string

Template to use. Available templates:

dbos-toolbox - Full-featured starter with examples
dbos-app-starter - Basic application template
dbos-cron-starter - Scheduled workflow template

--config

boolean

Only add dbos-config.yaml to an existing project.

Examples:

# Interactive template selection
dbos init

# Create from specific template
dbos init my-app --template dbos-app-starter

# Add config to existing project
dbos init --config

dbos start

Start your DBOS application using commands defined in dbos-config.yaml.

dbos start

Executes the commands listed in runtimeConfig.start:

dbos-config.yaml

runtimeConfig:
  start:
    - uvicorn main:app --host 0.0.0.0 --port 8000
    - python worker.py

Behavior:

Executes each command sequentially
Forwards signals (SIGINT, SIGTERM) to child processes
Exits when any command fails or is terminated

On Windows, signal forwarding is limited. Use Ctrl+C to stop the process.

Database Management

dbos migrate

Create DBOS system tables and run application migrations.

dbos migrate [OPTIONS]

Options:

--db-url

string

Application database URL.

--sys-db-url

string

System database URL.

--app-role

string

PostgreSQL role to grant permissions to (PostgreSQL only).

--schema

string

default:"dbos"

Schema name for DBOS system tables.

Example:

dbos migrate --sys-db-url postgresql://localhost/myapp_dbos

Starting DBOS migrations
System database: postgresql://localhost/myapp_dbos
DBOS system schema: dbos
Executing migration commands from 'dbos-config.yaml'
Executing migration command: alembic upgrade head

See Database Commands for details.

dbos reset

Reset the DBOS system database, deleting all workflow history and metadata.

dbos reset [OPTIONS]

Options:

--yes

boolean

Skip confirmation prompt.

--db-url

string

Application database URL.

--sys-db-url

string

System database URL.

This command permanently deletes all workflow execution history, queued workflows, and system metadata. Use with caution.

Example:

dbos reset --yes

PostgreSQL Docker Management

Manage a local PostgreSQL instance using Docker.

dbos postgres start

Start a local PostgreSQL database in Docker.

dbos postgres start

Behavior:

Starts PostgreSQL 16 in a Docker container
Exposes port 5432
Uses persistent volume dbos_postgres_data
Default credentials: postgres:dbos

dbos postgres stop

Stop the local PostgreSQL database.

dbos postgres stop

Workflow Management

Workflow commands are documented in detail on the Workflow Commands page. Quick reference:

# List workflows
dbos workflow list --limit 10

# Get workflow status
dbos workflow get <workflow_id>

# List workflow steps
dbos workflow steps <workflow_id>

# Cancel a workflow
dbos workflow cancel <workflow_id>

# Resume a workflow
dbos workflow resume <workflow_id>

# Fork a workflow
dbos workflow fork <workflow_id> --step 5

Queue Commands

Manage enqueued workflows:

# List enqueued workflows
dbos workflow queue list --limit 10 --queue-name my-queue

Output Formats

Most commands output JSON for easy parsing:

dbos workflow list --limit 1

[{
  "workflow_id": "wf_abc123",
  "name": "process_order",
  "status": "SUCCESS",
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:05Z"
}]

Parsing JSON Output

Use jq for JSON processing:

# Get workflow IDs
dbos workflow list | jq -r '.[].workflow_id'

# Filter by status
dbos workflow list | jq '.[] | select(.status == "ERROR")'

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

Configuration File

The CLI uses dbos-config.yaml by default. This file must be in your current directory or a parent directory. Example:

name: my-app
system_database_url: postgresql://localhost/myapp_dbos

runtimeConfig:
  start:
    - python main.py

database:
  migrate:
    - alembic upgrade head

See Configuration for all available options.

Environment Variables

The CLI respects these environment variables:

Variable	Description
`DBOS__CLOUD`	Set to `true` when running in DBOS Cloud
`DBOS_SYSTEM_DATABASE_URL`	System database URL (DBOS Cloud)
`DBOS_DATABASE_URL`	Application database URL (DBOS Cloud)

Error Handling

The CLI exits with non-zero status codes on errors:

Exit Code	Meaning
0	Success
1	General error (configuration, database connection, etc.)

Example error:

dbos migrate

Error: Missing database URL: please set it using CLI flags or your dbos-config.yaml file.

Getting Help

Get help for any command:

dbos --help
dbos workflow --help
dbos workflow list --help

Common Patterns

Development Workflow

# 1. Initialize project
dbos init my-app --template dbos-app-starter
cd my-app

# 2. Start local database
dbos postgres start

# 3. Run migrations
dbos migrate

# 4. Start application
dbos start

Production Deployment

# 1. Run migrations (with production database URLs)
dbos migrate \
  --sys-db-url postgresql://prod-db/app_dbos \
  --db-url postgresql://prod-db/app

# 2. Start with production config
DBOS_DATABASE_URL=postgresql://prod-db/app \
DBOS_SYSTEM_DATABASE_URL=postgresql://prod-db/app_dbos \
dbos start

Debugging Failed Workflows

# 1. Find failed workflows
dbos workflow list --status ERROR --limit 10

# 2. Get details
dbos workflow get <workflow_id>

# 3. View steps
dbos workflow steps <workflow_id>

# 4. Fork and retry
dbos workflow fork <workflow_id>

Core API

Configuration

CLI

Introduction

Installation

Command Structure

Main Commands

Common Options

Database URL Resolution

Application Commands

dbos version

dbos init

dbos start

Database Management

dbos migrate

dbos reset

PostgreSQL Docker Management

dbos postgres start

dbos postgres stop

Workflow Management

Queue Commands

Output Formats

Parsing JSON Output

Configuration File

Environment Variables

Error Handling

Getting Help

Common Patterns

Development Workflow

Production Deployment

Debugging Failed Workflows

See Also

Build docs developers (and LLMs) love

Core API

Configuration

CLI

​Introduction

​Installation

​Command Structure

​Main Commands

​Common Options

​Database URL Resolution

​Application Commands

​dbos version

​dbos init

​dbos start

​Database Management

​dbos migrate

​dbos reset

​PostgreSQL Docker Management

​dbos postgres start

​dbos postgres stop

​Workflow Management

​Queue Commands

​Output Formats

​Parsing JSON Output

​Configuration File

​Environment Variables

​Error Handling

​Getting Help

​Common Patterns

​Development Workflow

​Production Deployment

​Debugging Failed Workflows

​See Also

Build docs developers (and LLMs) love

Introduction

Installation

Command Structure

Main Commands

Common Options

Database URL Resolution

Application Commands

dbos version

dbos init

dbos start

Database Management

dbos migrate

dbos reset

PostgreSQL Docker Management

dbos postgres start

dbos postgres stop

Workflow Management

Queue Commands

Output Formats

Parsing JSON Output

Configuration File

Environment Variables

Error Handling

Getting Help

Common Patterns

Development Workflow

Production Deployment

Debugging Failed Workflows

See Also