Configuration

OpenWorkflow uses a configuration file to connect to your database, locate your workflow files, and set worker options. The CLI reads this file automatically for all commands. If you ran npx @openworkflow/cli init, this file was created for you. This page covers all available options. If you’re using the PostgreSQL backend, install the Postgres driver:

npm i openworkflow postgres

pnpm add openworkflow postgres

bun add openworkflow postgres

Config File

Create openworkflow.config.ts (or .js) in your project root:

import { defineConfig } from "@openworkflow/cli";
import { BackendPostgres } from "openworkflow/postgres";

export default defineConfig({
  backend: await BackendPostgres.connect(
    process.env.OPENWORKFLOW_POSTGRES_URL!,
  ),
  dirs: ["./openworkflow"],
});

The CLI automatically finds this file by searching up from the current directory. If your config lives somewhere else, pass an explicit path:

npx @openworkflow/cli worker start --config src/openworkflow.config.ts

Verify Configuration

After creating or updating the config, run:

npx @openworkflow/cli doctor

pnpx @openworkflow/cli doctor

bunx @openworkflow/cli doctor

This confirms that your config can be loaded, the backend can be reached, and your workflows can be found.

Configuration Options

`backend` (required)

The storage backend for workflow state. See PostgreSQL or SQLite.

import { BackendPostgres } from "openworkflow/postgres";
import { BackendSqlite } from "openworkflow/sqlite";

// PostgreSQL (production)
backend: await BackendPostgres.connect(process.env.OPENWORKFLOW_POSTGRES_URL!),

// SQLite (development)
backend: BackendSqlite.connect("./openworkflow/backend.db"),

`dirs`

Directory or directories to scan for workflow files. Defaults to ["./openworkflow"].

// Single directory
dirs: "./openworkflow",

// Multiple directories
dirs: ["./openworkflow", "./src/workflows"],

The CLI recursively scans these directories for files with extensions: .ts, .mts, .cts, .js, .mjs, .cjs.

`ignorePatterns`

Glob patterns to exclude when discovering workflow files:

ignorePatterns: [
  "**/*.test.*",      // Ignore test files
  "**/*.run.*",       // Ignore runner scripts
  "**/__fixtures__/**", // Ignore fixtures
],

The pattern **/*.run.* is ignored by default to exclude runner scripts.

`worker`

Worker configuration options:

worker: {
  // Number of concurrent workflow executions (default: 1)
  concurrency: 4,
},

Full Example

import { defineConfig } from "@openworkflow/cli";
import { BackendPostgres } from "openworkflow/postgres";

export default defineConfig({
  // PostgreSQL for production, with namespace
  backend: await BackendPostgres.connect(
    process.env.OPENWORKFLOW_POSTGRES_URL!,
    {
      namespaceId: process.env.OPENWORKFLOW_NAMESPACE_ID || "default",
    },
  ),

  // Scan multiple directories
  dirs: ["./openworkflow", "./src/workflows"],

  // Ignore test files
  ignorePatterns: ["**/*.test.*", "**/*.spec.*"],

  // Worker configuration
  worker: {
    concurrency: 8,
  },
});

Environment-Based Configuration

Use environment variables for different environments:

import { defineConfig } from "@openworkflow/cli";
import { BackendPostgres } from "openworkflow/postgres";
import { BackendSqlite } from "openworkflow/sqlite";

const isDev = process.env.NODE_ENV !== "production";

export default defineConfig({
  backend: isDev
    ? BackendSqlite.connect("./openworkflow/backend.db")
    : await BackendPostgres.connect(process.env.OPENWORKFLOW_POSTGRES_URL!),

  dirs: ["./openworkflow"],

  worker: {
    concurrency: isDev ? 1 : 8,
  },
});

Loading Environment Variables

The CLI loads .env files automatically. Add your database URL and other secrets there:

# .env
OPENWORKFLOW_POSTGRES_URL=postgresql://user:pass@localhost:5432/openworkflow
OPENWORKFLOW_NAMESPACE_ID=development

Supported Extensions

Config files can use these extensions:

openworkflow.config.ts
openworkflow.config.mts
openworkflow.config.cts
openworkflow.config.js
openworkflow.config.mjs
openworkflow.config.cjs

Get Started

Core Concepts

Guides

Backends

Reference

Integrations

Comparisons

Resources

Config File

Verify Configuration

Configuration Options

`backend` (required)

`dirs`

`ignorePatterns`

`worker`

Full Example

Environment-Based Configuration

Loading Environment Variables

Supported Extensions

​Config File

​Verify Configuration

​Configuration Options

​backend (required)

​dirs

​ignorePatterns

​worker

​Full Example

​Environment-Based Configuration

​Loading Environment Variables

​Supported Extensions

Config File

Verify Configuration

Configuration Options

`backend` (required)

`dirs`

`ignorePatterns`

`worker`

Full Example

Environment-Based Configuration

Loading Environment Variables

Supported Extensions