CLI

The ductor binary is a single executable with subcommands. With no arguments, it defaults to serve; a flag-only invocation (ductor --http-addr :9000) is also treated as serve.

ductor <command> [flags]

Global behavior

• --config <path> — path to a config file. Accepted by every subcommand; also parsed from raw args (--config path or --config=path).
• Config precedence: env vars > inline YAML in DUCTOR_CONFIG > config file > defaults. See the Configuration reference.
• -h / --help / help prints usage; -v / --version prints the version.
• A ./.env file is auto-loaded only when DUCTOR_ENVIRONMENT=development or DUCTOR_LOAD_DOTENV=true; otherwise it is ignored. Don't rely on it in production — set env vars directly.

Command overview

serve

Boots every subsystem through the fx composition root, honoring server.role (all/api/worker/executor). If database.auto_migrate is true it migrates first; regardless, it logs a warning at startup if pending migrations exist. Shuts down gracefully on SIGINT/SIGTERM.

ductor serve --http-addr :8080 --metrics-addr :9090

Every serve flag binds to a config key, so a flag is just an inline override of the corresponding DUCTOR_* variable. The most useful:

Additional flag groups: archival (--archival-enabled, --archival-backend, --archival-s3-bucket, …), tracing (--tracing-enabled, --tracing-endpoint, --tracing-grpc, --tracing-insecure, --tracing-sample-rate), rules/events (--hot-reload, --events-enabled, --rule-cache-size, --rule-cache-ttl), and the executor plane (--exec-addr, --exec-target, --exec-shared-secret, --exec-runner-kind, --exec-isolation-required, --exec-task-timeout).

dev

Boots a development instance with an in-process Redis (miniredis) so you only need Postgres. It forces development defaults: auth.enabled=false, auth.allow_anonymous=true, archival.enabled=false, tracing.enabled=false, database.auto_migrate=true, environment=development.

export DUCTOR_DATABASE_URL="postgres://ductor:ductor@localhost:5432/ductor?sslmode=disable"
ductor dev

Flags: --log-level (default debug), --log-format, --http-addr, --metrics-addr, --database-url, --api-addr.

migrate

Runs goose migrations. Positional subcommand, no flags:

ductor migrate up       # apply all pending (default)
ductor migrate status   # show applied/pending
ductor migrate down     # roll back one

Uses database.url / DUCTOR_DATABASE_URL. See Database migrations.

schema status

Verifies the database schema is ready (all migrations applied) and prints schema=ready. Useful as a readiness gate in CI/CD before rolling a new version.

ductor schema status --database-url "$DUCTOR_DATABASE_URL" --timeout 15s

health

Performs an HTTP GET /health against a running server and prints OK (or the error). Defaults the address to :8080.

ductor health --http-addr :8080

validate-config

Validates the fully-resolved configuration and prints a table of each key, its resolved value, and its source ([env: …], [config: …], or [default]), with DSNs redacted.

ductor validate-config

workflow

Offline and management operations on workflow definitions:

ductor workflow validate ./definition.yaml      # offline lint; non-zero on any issue
ductor workflow export <family-slug>             # write latest published YAML to stdout
ductor workflow bootstrap-routing [--verify] [--repair]

validate resolves every action, strategy, hook, and interface reference without touching the database. bootstrap-routing defaults to --verify when neither flag is given.

Operational subcommands

Exit codes

Subcommands exit non-zero on failure — workflow validate on any validation issue, schema status when the schema isn't ready, audit-shadow --fail-on-drift when drift is detected, and serve when a required dependency is unreachable. This makes them safe to wire into CI/CD gates.