wfctl — Workflow Engine CLI Reference

wfctl is the command-line tool for the workflow engine. It handles offline config validation, project scaffolding, API spec generation, plugin management, deployment, and AI assistant integration — all without requiring a running server.

Installation

GitHub Releases (recommended)

# macOS (Apple Silicon)
curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-darwin-arm64 -o wfctl && chmod +x wfctl && sudo mv wfctl /usr/local/bin/

# macOS (Intel)
curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-darwin-amd64 -o wfctl && chmod +x wfctl && sudo mv wfctl /usr/local/bin/

# Linux (x86_64)
curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-linux-amd64 -o wfctl && chmod +x wfctl && sudo mv wfctl /usr/local/bin/

# Linux (ARM64)
curl -sL https://github.com/GoCodeAlone/workflow/releases/latest/download/wfctl-linux-arm64 -o wfctl && chmod +x wfctl && sudo mv wfctl /usr/local/bin/

From Source

go install github.com/GoCodeAlone/workflow/cmd/wfctl@latest

Self-Update

wfctl update          # install latest release
wfctl update --check  # check for updates without installing

Command Tree

graph TD
    wfctl --> init
    wfctl --> validate
    wfctl --> inspect
    wfctl --> run
    wfctl --> plugin
    wfctl --> pipeline
    wfctl --> schema
    wfctl --> snippets
    wfctl --> manifest
    wfctl --> migrate
    wfctl --> build-ui["build-ui"]
    wfctl --> ui
    wfctl --> publish
    wfctl --> deploy
    wfctl --> infra
    wfctl --> api
    wfctl --> diff
    wfctl --> template
    wfctl --> contract
    wfctl --> compat
    wfctl --> generate
    wfctl --> ci
    wfctl --> git
    wfctl --> registry
    wfctl --> update
    wfctl --> mcp
    wfctl --> editor-schemas["editor-schemas"]
    wfctl --> dsl-reference["dsl-reference"]
    wfctl --> ports
    wfctl --> security
    wfctl --> dev
    wfctl --> wizard

    dev --> dev-up["up"]
    dev --> dev-down["down"]
    dev --> dev-logs["logs"]
    dev --> dev-status["status"]
    dev --> dev-restart["restart"]

    ports --> ports-list["list"]

    security --> security-audit["audit"]
    security --> security-gennetpol["generate-network-policies"]

    infra --> infra-plan["plan"]
    infra --> infra-apply["apply"]
    infra --> infra-destroy["destroy"]
    infra --> infra-status["status"]
    infra --> infra-drift["drift"]
    infra --> infra-import["import"]
    infra --> infra-state["state"]

    infra-state --> infra-state-list["list"]
    infra-state --> infra-state-export["export"]
    infra-state --> infra-state-import["import"]

    ci --> ci-generate["generate"]

    plugin --> plugin-init["init"]
    plugin --> plugin-docs["docs"]
    plugin --> plugin-test["test"]
    plugin --> plugin-search["search"]
    plugin --> plugin-install["install"]
    plugin --> plugin-list["list"]
    plugin --> plugin-update["update"]
    plugin --> plugin-remove["remove"]
    plugin --> plugin-validate["validate"]
    plugin --> plugin-info["info"]

    pipeline --> pipeline-list["list"]
    pipeline --> pipeline-run["run"]

    migrate --> migrate-status["status"]
    migrate --> migrate-diff["diff"]
    migrate --> migrate-apply["apply"]

    ui --> ui-scaffold["scaffold"]
    ui --> ui-build["build"]

    deploy --> deploy-docker["docker"]
    deploy --> deploy-k8s["kubernetes / k8s"]
    deploy --> deploy-helm["helm"]
    deploy --> deploy-cloud["cloud"]

    deploy-k8s --> k8s-generate["generate"]
    deploy-k8s --> k8s-apply["apply"]
    deploy-k8s --> k8s-destroy["destroy"]
    deploy-k8s --> k8s-status["status"]
    deploy-k8s --> k8s-logs["logs"]
    deploy-k8s --> k8s-diff["diff"]

    api --> api-extract["extract"]
    template --> template-validate["validate"]
    contract --> contract-test["test / compare"]
    compat --> compat-check["check"]
    generate --> gen-github["github-actions"]
    git --> git-connect["connect"]
    git --> git-push["push"]
    registry --> registry-list["list"]
    registry --> registry-add["add"]
    registry --> registry-remove["remove"]

Commands by Category

Category	Commands
Project Setup	`init`, `run`, `wizard`
Local Development	`dev up/down/logs/status/restart` (--local, --k8s, --expose)
Validation & Inspection	`validate`, `inspect`, `schema`, `compat check`, `template validate`, `editor-schemas`, `dsl-reference`
API & Contract	`api extract`, `contract test`, `diff`
Deployment	`deploy docker/kubernetes/helm/cloud`, `build-ui`, `generate github-actions`
Infrastructure	`infra plan/apply/destroy/status/drift/import`, `infra state list/export/import`
CI/CD	`ci generate`, `generate github-actions`
Documentation	`docs generate`
Plugin Management	`plugin`, `registry`, `publish`
UI Generation	`ui scaffold`, `build-ui`
Database Migrations	`migrate status/diff/apply`
Git Integration	`git connect`, `git push`
Platform Inspection	`ports list`, `security audit`, `security generate-network-policies`
Utilities	`snippets`, `manifest`, `pipeline`, `update`, `mcp`

Command Reference

`init`

Scaffold a new workflow application project from a built-in template.

wfctl init [options] <project-name>

Flag	Default	Description
`-template`	`api-service`	Project template to use
`-author`	`your-org`	GitHub username or org (used in go.mod module path)
`-description`	(from template)	Project description
`-output`	(project name)	Output directory
`-list`	`false`	List available templates and exit

Available templates:

Template	Description
`api-service`	HTTP API service with health check and metrics
`event-processor`	Event-driven processor with state machine and messaging
`full-stack`	API service + React UI (Vite + TypeScript)
`plugin`	External workflow engine plugin (gRPC, go-plugin)
`ui-plugin`	External plugin with embedded React UI

Examples:

wfctl init my-api
wfctl init --template full-stack --author myorg my-app
wfctl init --list

`validate`

Validate one or more workflow configuration files offline.

wfctl validate [options] <config.yaml> [config2.yaml ...]

Flag	Default	Description
`-strict`	`false`	Enable strict validation (no empty modules allowed)
`-skip-unknown-types`	`false`	Skip unknown module/workflow/trigger type checks
`-allow-no-entry-points`	`false`	Allow configs with no triggers, routes, subscriptions, or jobs
`-dir`	(none)	Validate all `.yaml`/`.yml` files in a directory (recursive)
`-plugin-dir`	(none)	Directory of installed external plugins; their types are loaded before validation

Examples:

wfctl validate config.yaml
wfctl validate example/*.yaml
wfctl validate --dir ./example/
wfctl validate --strict admin/config.yaml
wfctl validate --skip-unknown-types example/*.yaml
wfctl validate --plugin-dir data/plugins config.yaml

When validating multiple files, a summary is printed:

  PASS example/api-server-config.yaml (5 modules, 3 workflows, 2 triggers)
  FAIL example/broken.yaml
       module "db" uses unknown type "postgres.v2"

--- Validation Summary ---
  2/3 configs passed

`inspect`

Inspect modules, workflows, triggers, and the dependency graph of a config.

wfctl inspect [options] <config.yaml>

Flag	Default	Description
`-deps`	`false`	Show module dependency graph

Example:

wfctl inspect config.yaml
wfctl inspect --deps config.yaml

`run`

Run a workflow engine from a config file. Blocks until Ctrl+C or SIGTERM.

wfctl run [options] <config.yaml>

Flag	Default	Description
`-log-level`	`info`	Log level: `debug`, `info`, `warn`, `error`
`-env`	(none)	Environment name (sets `WORKFLOW_ENV`)

Example:

wfctl run workflow.yaml
wfctl run --log-level debug --env staging workflow.yaml

`plugin`

Plugin management subcommands.

wfctl plugin <subcommand> [options]

`plugin init`

Scaffold a new plugin project.

wfctl plugin init [options] <name>

Flag	Default	Description
`-author`	(required)	Plugin author
`-version`	`0.1.0`	Plugin version
`-description`	(none)	Plugin description
`-license`	(none)	Plugin license
`-output`	(plugin name)	Output directory
`-contract`	`false`	Include a contract skeleton

wfctl plugin init --author myorg my-plugin

`plugin docs`

Generate markdown documentation for an existing plugin from its plugin.json.

wfctl plugin docs <plugin-dir>

wfctl plugin docs ./my-plugin/

`plugin test`

Run a plugin through its full lifecycle in a test harness.

wfctl plugin test [options]

`plugin search`

Search the plugin registry by name, description, or keyword.

wfctl plugin search [options] [<query>]

Flag	Default	Description
`-config`	(default registry)	Registry config file path

wfctl plugin search auth
wfctl plugin search

`plugin install`

Download and install a plugin from the registry.

wfctl plugin install [options] <name>[@<version>]

Flag	Default	Description
`-data-dir`	`data/plugins`	Plugin data directory
`-config`	(default registry)	Registry config file path
`-registry`	(all registries)	Use a specific registry by name

wfctl plugin install my-plugin
wfctl plugin install my-plugin@1.2.0
wfctl plugin install --data-dir /opt/plugins my-plugin

`plugin list`

List installed plugins.

wfctl plugin list [options]

Flag	Default	Description
`-data-dir`	`data/plugins`	Plugin data directory

`plugin update`

Update an installed plugin to its latest version.

wfctl plugin update [options] <name>

Flag	Default	Description
`-data-dir`	`data/plugins`	Plugin data directory

`plugin remove`

Uninstall a plugin.

wfctl plugin remove [options] <name>

Flag	Default	Description
`-data-dir`	`data/plugins`	Plugin data directory

`plugin validate`

Validate a plugin manifest from the registry or a local file.

wfctl plugin validate [options]

`plugin info`

Show details about an installed plugin.

wfctl plugin info [options] <name>

Flag	Default	Description
`-data-dir`	`data/plugins`	Plugin data directory

`pipeline`

Pipeline management subcommands.

wfctl pipeline <subcommand> [options]

`pipeline list`

List available pipelines in a config file.

wfctl pipeline list -c <config.yaml>

Flag	Default	Description
`-c`	(required)	Path to workflow config YAML file

`pipeline run`

Execute a pipeline locally from a config file (without starting an HTTP server).

wfctl pipeline run -c <config.yaml> -p <pipeline-name> [options]

Flag	Default	Description
`-c`	(required)	Path to workflow config YAML file
`-p`	(required)	Name of the pipeline to run
`-input`	(none)	Input data as a JSON object
`-verbose`	`false`	Show detailed step output
`-var`	(none)	Variable in `key=value` format (repeatable)

Examples:

wfctl pipeline run -c app.yaml -p build-and-deploy
wfctl pipeline run -c app.yaml -p deploy --var env=staging --var version=1.2.3
wfctl pipeline run -c app.yaml -p process-data --input '{"items":[1,2,3]}'

`schema`

Generate the JSON Schema for workflow configuration files.

wfctl schema [options]

Flag	Default	Description
`-output`	(stdout)	Write schema to file instead of stdout

Example:

wfctl schema
wfctl schema --output workflow-schema.json

`editor-schemas`

Export module and step type schemas for the visual editor. Outputs JSON with moduleSchemas, stepSchemas, and coercionRules. This is the source of truth consumed by @gocodealone/workflow-editor and IDE plugins.

wfctl editor-schemas

Output format:

{
  "moduleSchemas": {
    "http.server": {
      "type": "http.server",
      "label": "HTTP Server",
      "category": "http",
      "configFields": [
        {"key": "address", "type": "string", "label": "Listen Address", "required": true, "defaultValue": ":8080"}
      ],
      "inputs": [...],
      "outputs": [...]
    }
  },
  "stepSchemas": {
    "step.db_query": {
      "type": "step.db_query",
      "configFields": [...],
      "outputs": [...]
    }
  },
  "coercionRules": {
    "http.Request": ["any", "PipelineContext"]
  }
}

Example:

wfctl editor-schemas > engine-schemas.json
wfctl editor-schemas | jq '.moduleSchemas | keys | length'  # 279 types
wfctl editor-schemas | jq '.stepSchemas | keys | length'    # 182 types

`dsl-reference`

Export the workflow YAML DSL reference as structured JSON. Parses docs/dsl-reference.md (embedded in the binary) into sections with field documentation, examples, and relationship descriptions. Consumed by the visual editor's DSL Reference pane and IDE plugins for hover/completion.

wfctl dsl-reference

Output format:

{
  "sections": [
    {
      "id": "modules",
      "title": "Modules",
      "description": "Modules are the building blocks...",
      "requiredFields": [
        {"name": "name", "type": "string", "description": "unique identifier"}
      ],
      "optionalFields": [...],
      "example": "modules:\n  - name: db\n    type: database.workflow\n    ...",
      "relationships": ["Referenced by workflows.http.routes[].handler"],
      "parent": ""
    }
  ]
}

Example:

wfctl dsl-reference > dsl-reference.json
wfctl dsl-reference | jq '.sections | length'              # 12 sections
wfctl dsl-reference | jq '.sections[].id'                  # list section IDs

`expr-migrate`

Auto-convert Go template expressions ({{ }}) to expr syntax (${ }) in a workflow config file. Simple patterns are converted automatically; complex templates that cannot be safely rewritten receive a # TODO: migrate comment.

wfctl expr-migrate [options]

Flag	Default	Description
`--config`	(required)	Path to workflow YAML config file
`--output`	(stdout)	Write converted output to this file
`--inplace`	`false`	Rewrite the input file in-place (overrides `--output`)
`--dry-run`	`false`	Print conversion stats and preview without writing

Conversions applied:

Input (Go template)	Output (expr)
`{{ .field }}`	`${ field }`
`{{ .body.name }}`	`${ body.name }`
`{{ .steps.name.field }}`	`${ steps["name"]["field"] }`
`{{ eq .status "active" }}`	`${ status == "active" }`
`{{ ne .x "val" }}`	`${ x != "val" }`
`{{ gt .x 5 }}`	`${ x > 5 }`
`{{ index .steps "n" "k" }}`	`${ steps["n"]["k"] }`
`{{ upper .name }}`	`${ upper(name) }`
`{{ and (eq .x "a") ... }}`	`${ x == "a" && ... }`

Examples:

wfctl expr-migrate --config app.yaml --dry-run
wfctl expr-migrate --config app.yaml --output app-new.yaml
wfctl expr-migrate --config app.yaml --inplace

`snippets`

Export workflow configuration snippets for IDE support.

wfctl snippets [options]

Flag	Default	Description
`-format`	`json`	Output format: `json`, `vscode`, `jetbrains`
`-output`	(stdout)	Write output to file instead of stdout

Examples:

wfctl snippets --format vscode --output workflow.code-snippets
wfctl snippets --format jetbrains --output workflow.xml

`manifest`

Analyze a workflow configuration and report its infrastructure requirements (databases, services, event buses, ports, resource estimates, etc.).

wfctl manifest [options] <config.yaml>

Flag	Default	Description
`-format`	`json`	Output format: `json` or `yaml`
`-name`	(from config)	Override the workflow name in the manifest

Examples:

wfctl manifest config.yaml
wfctl manifest -format yaml config.yaml
wfctl manifest -name my-service config.yaml

`migrate`

Manage database schema migrations.

wfctl migrate <subcommand> [options]

Flag	Default	Description
`--db`	`workflow.db`	Path to SQLite database file

Subcommands

Subcommand	Description
`status`	Show applied and pending migrations
`diff`	Show pending migration SQL without applying
`apply`	Apply all pending migrations

Examples:

wfctl migrate status --db workflow.db
wfctl migrate diff --db workflow.db
wfctl migrate apply --db workflow.db

`build-ui`

Build the application UI using the detected package manager and framework. Runs npm install (or npm ci), npm run build, and validates the output.

wfctl build-ui [options]

Flag	Default	Description
`--ui-dir`	`ui`	Path to the UI source directory
`--output`	(none)	Copy `dist/` contents to this directory after build
`--validate`	`false`	Validate the build output without running the build
`--config-snippet`	`false`	Print the `static.fileserver` YAML config snippet

Examples:

wfctl build-ui
wfctl build-ui --ui-dir ./ui
wfctl build-ui --output ./module/ui_dist
wfctl build-ui --validate
wfctl build-ui --config-snippet

`ui`

UI tooling subcommands.

wfctl ui <subcommand> [options]

`ui scaffold`

Generate a complete Vite + React + TypeScript SPA from an OpenAPI 3.0 spec. Reads spec from a file or stdin.

wfctl ui scaffold [options]

Flag	Default	Description
`-spec`	(stdin)	Path to OpenAPI spec file (JSON or YAML)
`-output`	`ui`	Output directory for the scaffolded UI
`-title`	(from spec)	Application title
`-auth`	`false`	Include login/register pages
`-theme`	`auto`	Color theme: `light`, `dark`, `auto`

Examples:

wfctl ui scaffold -spec openapi.yaml -output ui
cat openapi.json | wfctl ui scaffold -output ./frontend
wfctl ui scaffold -spec api.yaml -title "My App" -auth -theme dark

`ui build`

Alias for build-ui.

`publish`

Prepare and publish a plugin manifest to the workflow-registry. Auto-detects manifest from manifest.json, plugin.json, or Go source (EngineManifest() function).

wfctl publish [options]

Flag	Default	Description
`--dir`	`.`	Plugin project directory
`--registry`	`GoCodeAlone/workflow-registry`	Registry repo (`owner/repo`)
`--dry-run`	`false`	Validate and print manifest without submitting
`--output`	(none)	Write manifest to file instead of submitting
`--build`	`false`	Build plugin binary for current platform
`--type`	`external`	Plugin type: `builtin`, `external`, or `ui`
`--tier`	`community`	Plugin tier: `core`, `community`, or `premium`

Examples:

wfctl publish --dry-run
wfctl publish --output manifest.json
wfctl publish --build --dry-run
wfctl publish --dir ./my-plugin --type external --tier community

`deploy`

Deploy the workflow application to a target environment.

wfctl deploy <target> [options]

`deploy docker`

Build a Docker image and run the application locally via docker compose. Generates Dockerfile and docker-compose.yml if not present.

wfctl deploy docker [options]

Flag	Default	Description
`-config`	`workflow.yaml`	Workflow config file to deploy
`-image`	`workflow-app:local`	Docker image name:tag to build
`-no-compose`	`false`	Build image only, skip `docker compose up`

wfctl deploy docker -config workflow.yaml

`deploy kubernetes` / `deploy k8s`

Deploy to Kubernetes via client-go (server-side apply).

wfctl deploy kubernetes <subcommand> [options]
wfctl deploy k8s <subcommand> [options]

Common flags (shared across all k8s subcommands):

Flag	Default	Description
`-config`	`app.yaml`	Workflow config file
`-image`	(required)	Container image name:tag
`-namespace`	`default`	Kubernetes namespace
`-app`	(from config)	Application name
`-replicas`	`1`	Number of replicas
`-secret`	(none)	Secret name for environment variables
`-command`	(none)	Container command (comma-separated)
`-args`	(none)	Container args (comma-separated)
`-image-pull-policy`	(auto)	`Never`, `Always`, or `IfNotPresent`
`-strategy`	(none)	Deployment strategy: `Recreate` or `RollingUpdate`
`-service-account`	(none)	Pod service account name
`-health-path`	`/healthz`	Health check path
`-configmap-name`	(auto)	Override configmap name

k8s generate — produce manifests to a directory:

Flag	Default	Description
`-output`	`./k8s-generated/`	Output directory for generated manifests

k8s apply — build and apply manifests to cluster:

Flag	Default	Description
`--dry-run`	`false`	Server-side dry run without applying
`--wait`	`false`	Wait for rollout to complete
`--force`	`false`	Force take ownership of fields from other managers
`--build`	`false`	Build Docker image and load into cluster before deploying
`--dockerfile`	`Dockerfile`	Path to Dockerfile
`--build-context`	`.`	Docker build context directory
`--build-arg`	(none)	Docker build args (comma-separated `KEY=VALUE`)
`--runtime`	(auto)	Override cluster runtime: `minikube`, `kind`, `docker-desktop`, `k3d`, `remote`
`--registry`	(none)	Registry for remote clusters (e.g. `ghcr.io/org`)

k8s destroy — delete all resources for an app:

Flag	Default	Description
`-app`	(required)	Application name
`-namespace`	`default`	Kubernetes namespace

k8s status — show deployment status and pod health:

Flag	Default	Description
`-app`	(required)	Application name
`-namespace`	`default`	Kubernetes namespace

k8s logs — stream logs from the deployed app:

Flag	Default	Description
`-app`	(required)	Application name
`-namespace`	`default`	Kubernetes namespace
`-container`	(app name)	Container name
`--follow`	`false`	Follow log output
`--tail`	`100`	Number of lines to show from end of logs

k8s diff — compare generated manifests against live cluster state (uses common flags, -image required).

Examples:

# One command: build, load into cluster, apply, wait
wfctl deploy k8s apply --build -config app.yaml --force --wait

# Preview manifests without applying
wfctl deploy k8s generate -config app.yaml -image myapp:v1

# Check status
wfctl deploy k8s status -app myapp

# Stream logs
wfctl deploy k8s logs -app myapp --follow

# Remote cluster
wfctl deploy k8s apply --build -config app.yaml --registry ghcr.io/org --wait

`deploy helm`

Deploy to Kubernetes using Helm. Requires helm in PATH.

wfctl deploy helm [options]

Flag	Default	Description
`-namespace`	`default`	Kubernetes namespace
`-release`	`workflow`	Helm release name
`-chart`	(auto-detected)	Path to Helm chart directory
`-values`	(none)	Additional Helm values file
`-set`	(none)	Comma-separated `key=value` pairs to override
`--dry-run`	`false`	Pass `--dry-run` to helm

wfctl deploy helm -namespace prod -values custom.yaml

`deploy cloud`

Deploy infrastructure defined in a workflow config to a cloud environment. Discovers cloud.account and platform.* modules, validates credentials, and applies changes.

wfctl deploy cloud [options]

Flag	Default	Description
`-target`	(none)	Deployment target: `staging` or `production`
`-config`	(auto-detected)	Workflow config file
`--dry-run`	`false`	Show plan without applying changes
`--yes`	`false`	Skip confirmation prompt

wfctl deploy cloud --target staging --dry-run
wfctl deploy cloud --target production --yes

`infra`

Manage infrastructure lifecycle defined in a workflow config. Discovers cloud.account, iac.state, iac.provider, and platform.* modules, then executes the corresponding IaC pipeline.

wfctl infra <action> [options] [config.yaml]

Action	Description
`plan`	Show planned infrastructure changes
`apply`	Apply infrastructure changes
`status`	Show current infrastructure status
`drift`	Detect configuration drift between desired and actual state
`destroy`	Tear down all managed infrastructure
`import`	Import existing resources into IaC state
`state`	Manage state storage (list/export/import)

Flag	Default	Description
`--config`	(auto-detected)	Config file (searches `infra.yaml`, `config/infra.yaml`)
`--auto-approve`	`false`	Skip confirmation prompt (apply/destroy only)
`--parallelism`	`10`	Number of parallel operations
`--lock-timeout`	`0s`	Timeout for state lock acquisition

State Subcommands:

wfctl infra state <subaction> [options]

Subaction	Description
`list`	List all state snapshots and their metadata
`export`	Export current state to file or external system
`import`	Import state from file or external system

Examples:

wfctl infra plan infra.yaml
wfctl infra apply --auto-approve infra.yaml
wfctl infra status --config infra.yaml
wfctl infra drift infra.yaml
wfctl infra destroy --auto-approve infra.yaml
wfctl infra import --config infra.yaml
wfctl infra state list
wfctl infra state export --output state.json
wfctl infra state import --source state.json

`docs generate`

Generate Markdown documentation with Mermaid diagrams from a workflow configuration file. Produces a set of .md files describing modules, pipelines, workflows, external plugins, and system architecture.

wfctl docs generate [options] <config.yaml>

Flag	Default	Description
`-output`	`./docs/generated/`	Output directory for generated documentation
`-plugin-dir`	(none)	Directory containing external plugin manifests (`plugin.json`)
`-title`	(derived from config filename)	Application title used in the README

Generated files:

File	Description
`README.md`	Application overview with metrics, required plugins, and documentation index
`modules.md`	Module inventory table, type breakdown, configuration details, and dependency graph (Mermaid)
`pipelines.md`	Pipeline definitions with trigger info, step tables, workflow diagrams (Mermaid), and compensation steps
`workflows.md`	HTTP routes with route diagrams (Mermaid), messaging subscriptions/producers, and state machine diagrams (Mermaid)
`plugins.md`	External plugin details including version, capabilities, module/step types, and dependencies (only when `-plugin-dir` is provided)
`architecture.md`	System architecture diagram with layered subgraphs and plugin architecture (Mermaid)

Examples:

wfctl docs generate workflow.yaml
wfctl docs generate -output ./docs/ workflow.yaml
wfctl docs generate -output ./docs/ -plugin-dir ./plugins/ workflow.yaml
wfctl docs generate -output ./docs/ -title "Order Service" workflow.yaml

`api extract`

Parse a workflow config file offline and output an OpenAPI 3.0 specification of all HTTP endpoints defined in the config.

wfctl api extract [options] <config.yaml>

Flag	Default	Description
`-format`	`json`	Output format: `json` or `yaml`
`-title`	(from config)	API title
`-version`	`1.0.0`	API version
`-server`	(none)	Server URL to include (repeatable)
`-output`	(stdout)	Write to file instead of stdout
`-include-schemas`	`true`	Infer request/response schemas from step types

Examples:

wfctl api extract config.yaml
wfctl api extract -format yaml -output openapi.yaml config.yaml
wfctl api extract -title "My API" -version "2.0.0" config.yaml
wfctl api extract -server https://api.example.com config.yaml

`diff`

Compare two workflow configuration files and show what changed (modules, pipelines, and breaking changes).

wfctl diff [options] <old-config.yaml> <new-config.yaml>

Flag	Default	Description
`--state`	(none)	Path to deployment state file for resource correlation
`--format`	`text`	Output format: `text` or `json`
`--check-breaking`	`false`	Exit non-zero if breaking changes are detected

Example:

wfctl diff config-v1.yaml config-v2.yaml
wfctl diff --check-breaking --format json config-v1.yaml config-v2.yaml

Output symbols: + added, - removed, ~ changed, = unchanged.

`template validate`

Validate project templates or a specific config file against the engine's known module and step types.

wfctl template validate [options]

Flag	Default	Description
`--template`	(all)	Validate a specific template by name
`--config`	(none)	Validate a specific config file instead of templates
`--strict`	`false`	Fail on warnings (not just errors)
`--format`	`text`	Output format: `text` or `json`
`--plugin-dir`	(none)	Directory of installed external plugins

Examples:

wfctl template validate
wfctl template validate --template api-service
wfctl template validate --config my-config.yaml
wfctl template validate --strict --format json

`contract test`

Generate a contract snapshot from a config and optionally compare it to a baseline to detect breaking changes (removed endpoints, added auth requirements).

wfctl contract test [options] <config.yaml>

(compare is an alias for test.)

Flag	Default	Description
`--baseline`	(none)	Previous version's contract file for comparison
`--output`	(none)	Write contract file to this path
`--format`	`text`	Output format: `text` or `json`

Examples:

# Generate a new contract baseline
wfctl contract test --output contract.json config.yaml

# Compare against baseline
wfctl contract test --baseline contract.json --format text config.yaml

`compat check`

Check whether a workflow config is compatible with the current engine version. Reports which module and step types are available.

wfctl compat check [options] <config.yaml>

Flag	Default	Description
`--format`	`text`	Output format: `text` or `json`

Example:

wfctl compat check config.yaml
wfctl compat check --format json config.yaml

`generate github-actions`

Generate GitHub Actions CI/CD workflow files based on analysis of the workflow config. Detects presence of UI, auth, database, plugins, and HTTP features and generates appropriate workflows.

wfctl generate github-actions [options] <config.yaml>

Flag	Default	Description
`--output`	`.github/workflows/`	Output directory for generated workflow files
`--ci`	`true`	Generate CI workflow (lint, test, validate)
`--cd`	`true`	Generate CD workflow (build, deploy)
`--registry`	`ghcr.io`	Container registry for Docker images
`--platforms`	`linux/amd64,linux/arm64`	Platforms to build for

Examples:

wfctl generate github-actions workflow.yaml
wfctl generate github-actions -output .github/workflows/ -registry ghcr.io workflow.yaml

Generated files:

ci.yml — validates config, runs tests, optionally builds UI
cd.yml — builds multi-platform Docker image and pushes on tag push
release.yml — (if plugin detected) builds and releases plugin binaries

`ci generate`

Generate CI/CD pipeline configuration from a workflow definition. Detects infrastructure modules, deployment steps, and state management to produce environment-specific CI configurations.

wfctl ci generate [options] <config.yaml>

Flag	Default	Description
`--output`	`./ci/generated/`	Output directory for generated CI configurations
`--format`	`yaml`	Output format: `yaml` or `json`
`--environments`	`dev,staging,prod`	Comma-separated environments to generate configs for
`--include-infra`	`true`	Include infrastructure provisioning steps
`--include-tests`	`true`	Include automated test execution steps
`--parallelism`	`4`	Maximum concurrent deployment steps

Examples:

wfctl ci generate workflow.yaml
wfctl ci generate -output ./ci/ -environments dev,staging,prod workflow.yaml
wfctl ci generate -format json -include-infra=true workflow.yaml

Generated configuration includes:

Environment-specific provisioning pipelines (dev/staging/prod)
Infrastructure validation and drift detection
Deployment strategy configuration (rolling, blue-green, canary)
Rollback procedures and health checks
State management and backup/restore operations

`ci run`

Execute CI phases (build, test, deploy) defined in the ci: section of a workflow config.

wfctl ci run [options]

Flag	Default	Description
`--config`	`app.yaml`	Workflow config file
`--phase`	`build,test`	Comma-separated phases: `build`, `test`, `deploy`
`--env`	``	Target environment (required for `deploy` phase)
`--verbose`	`false`	Show detailed command output

Examples:

# Run build and test phases
wfctl ci run --phase build,test

# Deploy to staging
wfctl ci run --phase deploy --env staging

# Full pipeline
wfctl ci run --phase build,test,deploy --env production

Build phase compiles Go binaries (cross-platform), builds container images, and runs asset build commands.

Test phase runs unit, integration, and e2e test phases. For integration/e2e phases with needs: declared, ephemeral Docker containers (postgres, redis, mysql) are started before tests and removed after.

Deploy phase is a placeholder in Tier 1 — full provider implementations (k8s, aws-ecs, etc.) ship in Tier 2.

`ci init`

Generate a bootstrap CI YAML file for GitHub Actions or GitLab CI. The generated file calls wfctl ci run to execute build/test phases, and emits one deploy job per environment declared in ci.deploy.environments.

wfctl ci init [options]

Flag	Default	Description
`--platform`	`github-actions`	CI platform: `github-actions`, `gitlab-ci`
`--config`	`app.yaml`	Workflow config file
`--output`	platform default	Output file path

Examples:

wfctl ci init --platform github-actions
wfctl ci init --platform gitlab-ci
wfctl ci init --platform github-actions --config my-app.yaml

`secrets`

Manage application secret lifecycle. Reads the secrets: section of a workflow config.

wfctl secrets <action> [options]

`secrets detect`

Scan a workflow config for secret-like field values (field names matching token, password, apiKey, dsn, etc.) and env var references.

wfctl secrets detect --config app.yaml

`secrets set`

Set a secret value in the configured provider.

wfctl secrets set DATABASE_URL --value "postgres://..."
wfctl secrets set TLS_CERT --from-file ./certs/server.crt

Flag	Description
`--value`	Secret value to set
`--from-file`	Read secret value from file (for certificates/keys)
`--config`	Workflow config file (default: `app.yaml`)

`secrets list`

List all declared secrets, their store routing, and access-aware set/unset status. For multi-store configs, each secret shows which store it resolves to and whether the store is accessible.

wfctl secrets list --config app.yaml

`secrets validate`

Verify that all secrets declared in secrets.entries are set in the provider. Exits non-zero if any are missing.

wfctl secrets validate --config app.yaml

`secrets init`

Initialize the secrets provider configuration.

wfctl secrets init --provider env --env staging

`secrets rotate`

Trigger rotation of a named secret (logs strategy and interval; full provider implementations in Tier 2).

wfctl secrets rotate DATABASE_URL --env production

`secrets sync`

Copy secret structure from one environment to another (Tier 2 implementation).

wfctl secrets sync --from staging --to production

`secrets setup`

Interactively set all secrets declared in the config for a given environment. Prompts for each secret's value with hidden terminal input. Secrets in inaccessible stores are skipped. Use --auto-gen-keys to automatically generate random values for secrets whose names end in _KEY, _SECRET, _TOKEN, or _SIGNING.

wfctl secrets setup [options]

Flag	Default	Description
`--env`	`local`	Target environment name
`--config`	`app.yaml`	Workflow config file
`--auto-gen-keys`	`false`	Auto-generate random values for key/token/secret-named entries

wfctl secrets setup --env local
wfctl secrets setup --env production --auto-gen-keys
wfctl secrets setup --env staging --config config/staging.yaml

`git connect`

Connect a workflow project to a GitHub repository. Writes a .wfctl.yaml project file and optionally initializes the git repo.

wfctl git connect [options]

Flag	Default	Description
`-repo`	(required)	GitHub repository (`owner/name`)
`-token`	(env: `GITHUB_TOKEN`)	GitHub personal access token
`-init`	`false`	Initialize git repo and push to GitHub if not already set up
`-config`	`workflow.yaml`	Workflow config file for the project
`-deploy-target`	`kubernetes`	Deployment target: `docker`, `kubernetes`, `cloud`
`-namespace`	`default`	Kubernetes namespace for deployment
`-branch`	`main`	Default branch name

Examples:

wfctl git connect -repo GoCodeAlone/my-api
wfctl git connect -repo GoCodeAlone/my-api -init

`git push`

Stage, commit, and push workflow project files to the configured GitHub repository. Reads .wfctl.yaml for repository information.

wfctl git push [options]

Flag	Default	Description
`-message`	`chore: update workflow config [wfctl]`	Commit message
`-tag`	(none)	Create and push an annotated version tag (e.g. `v1.0.0`)
`-config-only`	`false`	Stage only config files (not generated build artifacts)

Examples:

wfctl git push -message "update config"
wfctl git push -tag v1.0.0
wfctl git push -config-only

`registry list`

Show configured plugin registries.

wfctl registry list [options]

Flag	Default	Description
`--config`	`~/.config/wfctl/config.yaml`	Registry config file path

`registry add`

Add a plugin registry source.

wfctl registry add [options] <name>

Flag	Default	Description
`--config`	`~/.config/wfctl/config.yaml`	Registry config file path
`--type`	`github`	Registry type
`--owner`	(required)	GitHub owner/org
`--repo`	(required)	GitHub repo name
`--branch`	`main`	Git branch
`--priority`	`10`	Priority (lower = higher priority)

wfctl registry add --owner myorg --repo my-registry my-registry

`registry remove`

Remove a plugin registry source. Cannot remove the default registry.

wfctl registry remove [options] <name>

Flag	Default	Description
`--config`	`~/.config/wfctl/config.yaml`	Registry config file path

wfctl registry remove my-registry

`update`

Download and install the latest version of wfctl, replacing the current binary. Automatically checks for updates in the background after most commands (suppress with WFCTL_NO_UPDATE_CHECK=1).

wfctl update [options]

Flag	Default	Description
`--check`	`false`	Only check for updates without installing

Examples:

wfctl update
wfctl update --check

`mcp`

Start the workflow MCP (Model Context Protocol) server over stdio. Exposes workflow engine tools and resources to AI assistants such as Claude Desktop, VS Code with GitHub Copilot, and Cursor.

wfctl mcp [options]

Flag	Default	Description
`-plugin-dir`	`data/plugins`	Plugin data directory

The MCP server provides tools for listing module types, validating configs, generating schemas, and inspecting workflow YAML configurations.

Claude Desktop configuration (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "workflow": {
      "command": "wfctl",
      "args": ["mcp", "-plugin-dir", "/path/to/data/plugins"]
    }
  }
}

See docs/mcp.md for full setup instructions.

`modernize`

Detect and fix known YAML config anti-patterns.

wfctl modernize [options] <config.yaml|directory>

Flag	Default	Description
`--apply`	`false`	Write fixes in-place (default: dry-run)
`--list-rules`	`false`	List all available rules
`--rules`	all	Comma-separated rule IDs to run
`--exclude-rules`	none	Comma-separated rule IDs to skip
`--dir`		Scan all YAML files recursively
`--format`	`text`	Output format: text or json
`--plugin-dir`	(none)	Directory of installed external plugins; their modernize rules are loaded

Rules:

ID	Severity	Fixable	Description
`hyphen-steps`	error	yes	Rename hyphenated step names to underscores
`conditional-field`	error	yes	Convert template syntax in conditional field to dot-path
`db-query-mode`	warning	yes	Add mode:single when downstream uses .row/.found
`db-query-index`	error	yes	Convert .steps.X.row.Y to index syntax
`database-to-sqlite`	warning	yes	Convert database.workflow to storage.sqlite
`absolute-dbpath`	warning	no	Warn on absolute dbPath values
`empty-routes`	error	no	Detect empty routes in step.conditional
`camelcase-config`	warning	no	Detect snake_case config keys

Plugin-provided rules are loaded when --plugin-dir is specified. Each installed plugin can declare its own migration rules in its plugin.json manifest under the modernizeRules key. Rules from all plugins in the directory are merged with the built-in rules.

# Run built-in rules only
wfctl modernize config.yaml

# Include migration rules from installed plugins
wfctl modernize --plugin-dir data/plugins config.yaml

# Apply all fixes (built-in + plugin rules)
wfctl modernize --apply --plugin-dir data/plugins config.yaml

# List all available rules including those from plugins
wfctl modernize --plugin-dir data/plugins --list-rules

`ports`

Inspect port usage declared in a workflow config.

wfctl ports list [options] [config.yaml]

Scans the parsed config for all port-bearing sections (top-level modules, services[*].expose, and networking.ingress) and prints a table with service, module, port, protocol, and exposure classification (public / internal).

Flag	Default	Description
`--config`	(auto-detect)	Config file path

Examples:

wfctl ports list
wfctl ports list --config config/app.yaml

Sample output:

SERVICE   MODULE       PORT  PROTOCOL  EXPOSURE
-------   ------       ----  --------  --------
(default) api-server   8080  http      public
api       (expose)     8080  http      internal
api       (ingress)    443   https     public
worker    (expose)     9090  grpc      internal

`security`

Security audit and policy generation for workflow configs.

`wfctl security audit`

Scan a workflow config and report security issues.

wfctl security audit [options] [config.yaml]

Checks TLS configuration, network isolation policy, ingress TLS termination, auth modules, runtime hardening settings, and scanning configuration. Reports each finding with a severity (HIGH, WARN, INFO). Exits with a non-zero status if any HIGH findings are present.

Flag	Default	Description
`--config`	(auto-detect)	Config file path

Examples:

wfctl security audit
wfctl security audit --config config/app.yaml

Sample output:

SEVERITY  CATEGORY  FINDING
--------  --------  -------
HIGH      TLS       security.tls.external is not enabled; external traffic is unencrypted
WARN      Network   security.network.defaultPolicy is "allow"; recommend 'deny' for least-privilege
INFO      Scanning  security.scanning.containerScan is disabled

`wfctl security generate-network-policies`

Generate Kubernetes NetworkPolicy YAML from networking.policies and mesh.routes config.

wfctl security generate-network-policies [options] [config.yaml]

For each service, generates a NetworkPolicy that allows ingress only from the explicitly declared sources. When security.network.defaultPolicy: deny is set, Egress is also included in the policy types.

Flag	Default	Description
`--config`	(auto-detect)	Config file path
`--output`	`k8s`	Output directory for generated YAML files

Examples:

wfctl security generate-network-policies --output k8s/
wfctl security generate-network-policies --config config/app.yaml --output deploy/k8s/

Generated file per service: k8s/netpol-<service>.yaml

`dev`

Manage a local development cluster for a workflow application. Reads the workflow config, generates the appropriate runtime (docker-compose, process, or minikube), and starts infrastructure + application services.

wfctl dev <subcommand> [options]

Subcommands:

Subcommand	Description
`up`	Start local dev cluster
`down`	Stop and remove local dev cluster
`logs`	Stream service logs
`status`	Show service health
`restart`	Restart one or all services

`dev up`

wfctl dev up [options]

Flag	Default	Description
`--config`	`app.yaml`	Workflow config file
`--local`	`false`	Run app services as local Go processes with hot-reload (infra still in Docker)
`--k8s`	`false`	Deploy to local minikube cluster
`--expose`	(from config)	Expose services externally: `tailscale`, `cloudflare`, `ngrok`
`--verbose`	`false`	Show detailed output

The default mode generates docker-compose.dev.yml from the workflow config, mapping infrastructure module types to Docker images:

Module type	Docker image
`database.postgres`, `database.workflow`	`postgres:16`
`nosql.redis`, `cache.redis`	`redis:7-alpine`
`messaging.nats`	`nats:latest`
`messaging.kafka`	`confluentinc/cp-kafka:latest`

Examples:

# Default: docker-compose mode
wfctl dev up

# Process mode: services run as local Go binaries, hot-reload on file change
wfctl dev up --local

# Kubernetes mode: deploy to minikube dev namespace
wfctl dev up --k8s

# Expose via Tailscale Funnel
wfctl dev up --expose tailscale

# Expose via Cloudflare Tunnel
wfctl dev up --expose cloudflare

The --expose method can also be configured in the workflow config under environments.local.exposure.method.

`dev down`

wfctl dev down [options]

Flag	Default	Description
`--k8s`	`false`	Delete the minikube `dev` namespace
`--verbose`	`false`	Show detailed output

`dev logs`

wfctl dev logs [options]

Flag	Default	Description
`--service`	(all)	Service name to filter
`--follow`	`false`	Follow log output
`--k8s`	`false`	Stream from minikube pods

`dev status`

wfctl dev status [options]

Flag	Default	Description
`--k8s`	`false`	Show pod status in minikube dev namespace

`dev restart`

wfctl dev restart [options]

Flag	Default	Description
`--service`	(all)	Service name to restart
`--k8s`	`false`	Restart in minikube

`wizard`

Interactive TUI wizard for generating a app.yaml workflow config. Walks through project setup step by step.

wfctl wizard

No flags. The wizard runs in the terminal and collects:

Project info — name and description
Services — single-service or multi-service (comma-separated names)
Infrastructure — PostgreSQL, Redis cache, NATS message queue (checkboxes)
Infra resolution — per-environment strategy for each selected infrastructure resource (container/provision/existing); if "existing", prompts for host:port
Environments — local, staging, production (checkboxes)
Deployment — provider per environment (Docker Compose, Kubernetes, AWS ECS)
Secret stores — define named stores (env, Vault, AWS Secrets Manager, GCP Secret Manager); Space to add, Delete to remove, Enter to continue
Secret routing — assign each required secret to a store (← → to change store)
Secret values — enter values for required secrets with hidden input; Ctrl+G auto-generates random values for keys/tokens
CI/CD — generate CI bootstrap and select platform (GitHub Actions, GitLab CI)
Review — preview generated YAML
Write — save to app.yaml

Navigation:

Key	Action
`Enter`	Advance to next screen / confirm
`Esc`	Go back to previous screen
`Tab`	Move focus between fields
`Space`	Toggle checkbox / add store
`↑` / `↓`	Move cursor in lists
`←` / `→`	Change strategy or store selection
`Ctrl+G`	Auto-generate a random secret value (bulk secrets screen)
`Ctrl+C`	Quit without saving

Example:

wfctl wizard
# Follow the interactive prompts to generate app.yaml
wfctl validate app.yaml
wfctl secrets setup --env local   # set secret values interactively
wfctl dev up

Project Config File (`.wfctl.yaml`)

wfctl git connect writes a .wfctl.yaml project config. Several deploy commands read defaults from this file.

project:
  name: my-api
  version: "1.0.0"
  configFile: workflow.yaml
git:
  repository: GoCodeAlone/my-api
  branch: main
  autoPush: false
  generateActions: true
deploy:
  target: kubernetes
  namespace: default
  build:
    dockerfile: Dockerfile
    context: .
    runtime: minikube       # minikube | kind | docker-desktop | k3d | remote
    registry: ghcr.io/myorg

FilesExpand file tree

WFCTL.md

Latest commit

History

WFCTL.md

File metadata and controls

wfctl — Workflow Engine CLI Reference

Installation

GitHub Releases (recommended)

From Source

Self-Update

Command Tree

Commands by Category

Command Reference

init

validate

inspect

run

plugin

plugin init

plugin docs

plugin test

plugin search

plugin install

plugin list

plugin update

plugin remove

plugin validate

plugin info

pipeline

pipeline list

pipeline run

schema

editor-schemas

dsl-reference

expr-migrate

snippets

manifest

migrate

Subcommands

build-ui

ui

ui scaffold

ui build

publish

deploy

deploy docker

deploy kubernetes / deploy k8s

deploy helm

deploy cloud

infra

docs generate

api extract

diff

template validate

contract test

compat check

generate github-actions

ci generate

ci run

ci init

secrets

secrets detect

secrets set

secrets list

secrets validate

secrets init

secrets rotate

secrets sync

secrets setup

git connect

git push

registry list

registry add

registry remove

update

mcp

modernize

ports

security

`init`

`validate`

`inspect`

`run`

`plugin`

`plugin init`

`plugin docs`

`plugin test`

`plugin search`

`plugin install`

`plugin list`

`plugin update`

`plugin remove`

`plugin validate`

`plugin info`

`pipeline`

`pipeline list`

`pipeline run`

`schema`

`editor-schemas`

`dsl-reference`

`expr-migrate`

`snippets`

`manifest`

`migrate`

`build-ui`

`ui`

`ui scaffold`

`ui build`

`publish`

`deploy`

`deploy docker`

`deploy kubernetes` / `deploy k8s`

`deploy helm`

`deploy cloud`

`infra`

`docs generate`

`api extract`

`diff`

`template validate`

`contract test`

`compat check`

`generate github-actions`

`ci generate`

`ci run`

`ci init`

`secrets`

`secrets detect`

`secrets set`

`secrets list`

`secrets validate`

`secrets init`

`secrets rotate`

`secrets sync`

`secrets setup`

`git connect`

`git push`

`registry list`

`registry add`

`registry remove`

`update`

`mcp`

`modernize`

`ports`

`security`

`wfctl security audit`

`wfctl security generate-network-policies`

`dev`

`dev up`

`dev down`

`dev logs`

`dev status`

`dev restart`

`wizard`

Project Config File (`.wfctl.yaml`)