workflow-manager

Appearance

Getting Started ​

Install and build ​

Install the latest published binary:

bash
curl -fsSL https://github.com/navio/workflow-manager/releases/latest/download/workflow-manager-installer.sh | bash

If wfm is not available immediately in the same terminal, run the shell reload command printed by the installer or open a new shell, then run wfm --help.

Build from source instead:

bash
bun install
bun run build
bun link

Install from npm instead:

bash
npm install -g @workflow-manager/runner
wfm --help

Core CLI commands ​

bash
wfm doctor
wfm skill list
wfm skill install
wfm scaffold ./example-workflow.md
wfm validate ./example-workflow.md
wfm doctor ./example-workflow.md
wfm run ./example-workflow.md --confirm discover,qa_gate:human
wfm run ./example-workflow.md --auto-confirm-all --verbose

# JSON workflow files
wfm scaffold ./example-workflow.json --format json
wfm validate ./example-workflow.json
wfm run ./example-workflow.json --confirm discover,qa_gate:human

# Manual help
wfm man

# Remote registry
wfm auth login --token <token>
wfm auth whoami
wfm search bunny
wfm publish ./example-workflow.json --visibility public
wfm pull alice/remote-bunny --output ./remote-bunny.json

Typical workflow ​

  1. Run wfm doctor to inspect host adapter and key setup.
  2. Run wfm skill install when an agent (Claude Code, opencode) should load WFM usage guidance on demand; --global installs for all projects.
  3. Run wfm scaffold ./example-workflow.md to generate a starter file.
  4. Edit frontmatter (Markdown) or JSON fields with your steps, dependencies, validation, and adapter init config.
  5. Run wfm validate ./example-workflow.md or wfm validate ./example-workflow.json until validation passes.
  6. Run wfm doctor <workflow-file> before real adapter runs.
  7. Run wfm run <workflow-file> to watch live progress in the CLI. Human approvals now show an inline terminal review prompt, and --verbose streams per-step agent output.

Add --ui to wfm run for a full-screen, two-pane terminal UI: a live step list next to a streaming activity view for the selected step, with keys to jump between steps and approve, resume, or cancel a waiting step. It requires an interactive terminal on stdin and stdout; without one, wfm run prints a warning and falls back to the standard renderer. See Terminal UI for the full layout, key bindings, and approval details.

For a repeatable task, skip writing the workflow file by hand: install the bundled authoring skill with wfm skill install workflow-author and have your coding agent elicit the steps, scaffold and validate the file, then run and narrate it for you. See Authoring Workflows With an Agent for the full loop.

Remote registry workflow ​

The hosted web app is available at workflow-manager-ui.netlify.app.

  1. Sign into the web app and create a CLI token.
  2. Run wfm auth login --token <token> locally.
  3. Publish with wfm publish <workflow-file>.
  4. Discover workflows with wfm search <query>.
  5. Pull a shared workflow with wfm pull <owner/slug> and run it locally.

Run docs locally ​

bash
bun run docs:dev
bun run docs:build
bun run docs:preview

The docs site is a manual release target. Build doc/.vitepress/dist and deploy it manually when needed.

Run the remote registry app ​

bash
bun run remote-registry:dev
bun run remote-registry:test
bun run remote-registry:build

Set up browser env values in apps/remote-registry/.env.local using apps/remote-registry/.env.example.

workflow-manager-ui is now the Netlify auto-release target via the root netlify.toml. That enables Deploy Previews for PRs and production deploys for merges to main once the Netlify site is connected to the repository.

See the live app at workflow-manager-ui.netlify.app.

The web app now includes:

  • dashboard analytics for your published workflows
  • analytics refresh and recent download trends
  • authenticated CLI run telemetry insights and effectiveness summaries
  • CLI token creation and revocation
  • browser-based workflow publishing for Markdown and JSON sources
  • workflow metadata editing and version management

Primary routes:

  • /dashboard
  • /dashboard/publish
  • /dashboard/tokens

Build a standalone binary ​

bash
bun run build:bin
./dist/wfm --help

Release binaries ​

bash
# local multi-platform compile
bun run build:bin:all

# CI release (GitHub Actions)
git tag v0.2.0
git push origin v0.2.0

Tag pushes matching v* publish macOS, Linux, and Windows binaries as GitHub Release assets, plus the workflow-manager-installer.sh helper used by the curl install flow.

For installer options, supported platforms, and custom install directories, see Installing the CLI.

Story workflow test plan ​

This repository includes a deterministic story workflow fixture in both formats:

  • tests/fixtures/story-workflow.json
  • tests/fixtures/story-workflow.md

Run unit and e2e coverage:

bash
bun run test:unit
bun run test:e2e

Run the real OpenCode adapter e2e smoke test:

bash
bun run test:e2e:real

This test is opt-in behind WORKFLOW_MANAGER_REAL_OPENCODE=1 and drives a real ACP agent turn against an authenticated opencode CLI through a workflow step (opencode routes through ACP by default, so no useRealAdapter flag is needed to opt in).

The e2e test validates that both workflows produce:

  • two chapter headings (## Chapter 1 and ## Chapter 2)
  • bunny-themed content
  • final markdown output generated by the render step
  • adapter routing checks for both mock and opencode

Debug checklist for failures:

  • run bun run test:e2e and inspect failing assertion output
  • run bun run test:e2e:real for real adapter verification
  • confirm fixtures still have the four expected steps (chapter_one, chapter_two, validate_story, render_markdown)
  • confirm validation payload keeps requiredChapters: 2