Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openworkflow.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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
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