Durable Workflow CLI
dw is the command-line interface for Durable Workflow Cloud and self-hosted
Durable Workflow Server. Use it to start and inspect workflows, send signals
and updates, manage schedules and namespaces, diagnose workers and task queues,
and automate operations with stable JSON output.
Install
The standalone binary does not require PHP.
# Linux and macOS
curl -fsSL https://durable-workflow.com/install.sh | sh
# Windows
irm https://durable-workflow.com/install.ps1 | iex
The installers verify the downloaded binary against the release
SHA256SUMS manifest. Releases also include GitHub artifact attestations,
native binaries, installer scripts, and a Homebrew formula. From 2.5.0 dw
is a native Rust binary and releases no longer include dw.phar; see the
2.5.0 notes to move off a PHAR install. The
2.3.x PHAR line receives security fixes only until 2027-02-28 and is
unsupported after that date.
See the distribution guide for exact-version installs,
direct downloads, checksum and attestation verification, Homebrew, and
reproducible builds.
Start a local Server
The native CLI includes a development Server and SQLite. Installing dw is
all you need to start the runtime:
It listens on 127.0.0.1:8080, initializes the database and default namespace,
and runs timers and maintenance. In another terminal, connect the CLI:
dw env:set local --server=http://127.0.0.1:8080 --token=dev-token --make-default
dw doctor
Data persists in dev-server under the CLI config directory. Use
--data-dir=./workflow-data to choose a directory or --port=9000 to choose a
port. Ctrl+C stops the runtime and preserves its data. When a newer dw
finds data written by an earlier one, it upgrades that development database
in place and prints the schema versions; an older dw refuses data written by
a newer one. Application workers still run your workflow and activity code
through an SDK.
Connect
Named profiles keep a runtime URL, namespace, token source, TLS policy, and
output preference together.
# Self-hosted Server
dw env:set local \
--server=http://localhost:8080 \
--namespace=default \
--make-default
# Durable Workflow Cloud namespace
dw env:set cloud \
--server="$DURABLE_WORKFLOW_RUNTIME_URL" \
--namespace="$DURABLE_WORKFLOW_NAMESPACE" \
--token-env=DURABLE_WORKFLOW_CLIENT_TOKEN
dw doctor --env=local
dw server:info --env=cloud
An unknown profile fails instead of silently falling back to another runtime.
Literal tokens are redacted from normal profile output; prefer --token-env
so credentials remain outside the config file.
Run a Workflow
Start a worker for the same namespace and task queue, then run:
dw workflow:start \
--type=orders.checkout \
--task-queue=orders \
--workflow-id="order-$(date +%s)" \
--input='{"order_id":"123"}' \
--wait \
--json
Common operations:
dw workflow:list --status=running
dw workflow:describe <workflow-id> --json
dw workflow:signal <workflow-id> payment-received --input='{"amount":99.99}'
dw workflow:query <workflow-id> current-status --json
dw workflow:update <workflow-id> approve --input='{"approver":"operator"}'
dw workflow:update-outcome <workflow-id> <update-id> --wait=completed
dw workflow:cancel <workflow-id> --reason="Customer request"
dw workflow:history <workflow-id> <run-id>
dw service-call:describe <endpoint> <service> <operation> <call-id> --json
Version branch usage
Before retiring a version branch, inspect the open runs for its workflow type
and change ID:
dw workflow:version-usage shipment carrier-api --min-version=2 --namespace=orders
dw workflow:version-usage shipment carrier-api --min-version=2 --state=unknown --json
This requires a Server advertising workflow_version_usage. Counts include all
legacy, current and unknown runs before filtering and paging. A missing marker
or unavailable history stays unknown. The command reads one live page; pass its
opaque next_cursor with the same query to continue. JSON and JSONL preserve the
whole page, including counts. Drain or fence admissions and restart the query
before making a branch-removal decision.
Automation Contract
All read and mutating commands support machine-readable output. Use
--output=json for one response or --output=jsonl for line-oriented records.
dw workflow:list --output=json | jq '.workflows[].workflow_id'
dw schedule:list --output=jsonl
dw schema:list
dw schema:show workflow:list > workflow-list.schema.json
Exit codes distinguish usage, network, authentication, not-found, server,
timeout, and compatibility failures. Published JSON Schema manifests define
the patch-stable response envelopes.
Reference
Development
The released CLI is the Rust crate in rust/: build and
test it with cargo, and compare it with 2.x through its parity harness.
The PHP implementation below remains for the 2.3.x maintenance line, which
receives security fixes only until 2027-02-28.
composer install
composer test
make phar
Run make help for the complete local development surface.
The PHP maintenance standalone builder acquires SPC through the fixed upstream
release identities in spc-artifact.py. It verifies
the compressed archive and extracted binary for all four recorded platforms,
and publishes caches atomically without replacing an existing file. Linux
execution requires Python 3, sealed memory descriptors and bubblewrap at
/usr/bin/bwrap with working unprivileged user namespaces. One sealed copy
supplies every download, build and combine call through a private read-only
mount, including the embedded PHP loader's self-reads. These controls run in
the existing Python parity test lane. The namespace helper must be owned by
root without setuid, setgid or file capabilities. The SPC process receives
only PATH, HOME, TMPDIR, SOURCE_DATE_EPOCH and fixed LC_ALL=C.
The legacy macOS standalone builder refuses execution. Use the supported native
Rust CLI or a qualified Linux legacy build. Native Rust CLI macOS releases are
unaffected. This binds the SPC component only. PHP, downloaded libraries, build
caches and each host platform still require their applicable toolchain
qualification.
The PHAR smoke caller has a separate runtime profile
and launcher. Its host controls and Box
artifact stay read-only. Only dependencies, build output, generated build
metadata and private runtime data are writable. The setup reuses the accepted
PHP image build source, then independently probes the PHAR settings and runs
the TLS and replacement controls. Source preparation alone does not qualify
the hosted caller or the separate reproducibility and legacy release paths.
Standalone release builds use the reviewed dependency source policy.
The workflow verifies the OpenSSL archive before compilation and checks the
produced runtime after both cold builds and cache restores. Each release includes
per-platform .dependencies.json inventories in the normal checksum and
attestation set, recording PHP, OpenSSL, libcurl and available library versions.
License
MIT