@workflow-manager/runner 0.1.0 → 0.3.0

package/dist/events.d.ts

@@ -2,6 +2,6 @@ import type { RunEvent } from "./types.js";
 export declare class EventLog {
     private sequence;
     private events;
-    push(runId: string, type: RunEvent["type"], payload?: Record<string, unknown>, stepRunId?: string, actor?: string): void;
+    push(runId: string, type: RunEvent["type"], payload?: Record<string, unknown>, stepRunId?: string, actor?: string): RunEvent;
     all(): RunEvent[];
 }

package/dist/events.js

@@ -4,7 +4,7 @@ export class EventLog {
     events = [];
     push(runId, type, payload = {}, stepRunId, actor = "system") {
         this.sequence += 1;
-        this.events.push({
+        const event = {
             id: randomUUID(),
             runId,
             stepRunId,
@@ -13,7 +13,9 @@ export class EventLog {
             occurredAt: new Date().toISOString(),
             actor,
             payload,
-        });
+        };
+        this.events.push(event);
+        return event;
     }
     all() {
         return [...this.events];

package/dist/index.js

@@ -1,27 +1,37 @@
 #!/usr/bin/env node
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { CliRunRenderer } from "./cliRunRenderer.js";
+import { startRunnerApiServer } from "./runnerApi.js";
+import { RunnerSessionStore } from "./runnerSession.js";
 import { parseWorkflowFile, validateWorkflow } from "./parser.js";
-import { runWorkflow } from "./engine.js";
+import { MAN_PAGE_SOURCE } from "./manPage.js";
+import { promptForApprovalDecision, runWorkflow } from "./engine.js";
 import { cmdAuth, cmdPublish, cmdPull, cmdRemoteInfo, cmdSearch } from "./remote/commands.js";
 import { emitRunTelemetryBestEffort } from "./remote/telemetry.js";
-const DISCOVERY_QUESTIONS = [
-    "1) What set of workflow objectives should be tracked per run (one or many)?",
-    "2) Which steps require human validation vs external validation?",
-    "3) Which approvals are mandatory and who can confirm each approval?",
-    "4) Which steps require explicit confirmation before proceeding?",
-    "5) For each step, which adapter should run it (opencode, codex, claude-code, mock)?",
-    "6) What per-step initialization is needed (context, skills, MCPs, system prompts, model)?",
-    "7) What output format should this session produce (JSON run report, markdown summary, event timeline)?",
-    "8) What retry/rollback policy should be default and where should exceptions apply?",
-];
+import { adapterImplementationStatuses, runtimeDoctorChecks, validateRuntimeRequirements, } from "./runtimePreflight.js";
+function cliDisplayName() {
+    const invokedAs = path.basename(process.argv[1] ?? "");
+    if (invokedAs === "workflow-manager" || invokedAs === "wfm") {
+        return invokedAs;
+    }
+    return "wfm";
+}
 function usage() {
-    console.log(`wfm commands:
-  questions
+    const cli = cliDisplayName();
+    console.log(`${cli} commands:
+  doctor [workflow.md|workflow.json] [--json]
+  agent [path] [--force]
   scaffold [path] [--format markdown|json]
   validate <workflow.md|workflow.json>
-  run <workflow.md|workflow.json> [--input input.json] [--objective "string"] [--confirm stepA,stepB:human] [--auto-confirm-all]
+  run <workflow.md|workflow.json> [--input input.json] [--objective "string"] [--confirm stepA,stepB:human] [--auto-confirm-all] [--port 43121] [--verbose] [--json]
+  approve [--url http://127.0.0.1:43121] [--token token] [--run-id run_123] [--step review] [--actor alice] [--note "LGTM"]
+  resume [--url http://127.0.0.1:43121] [--token token] [--run-id run_123] [--step review] [--actor alice] [--note "continue"]
+  cancel [--url http://127.0.0.1:43121] [--token token] [--run-id run_123] [--step review] [--actor alice] [--note "stop this run"]
   auth <login|whoami|logout> [--token <token>]
   publish <workflow.md|workflow.json> [--slug slug] [--title title] [--description text] [--visibility public|private] [--version version] [--tag a,b] [--draft]
   pull <owner/slug> [--version version] [--output path]
@@ -38,15 +48,34 @@ function getFlag(name) {
 function hasFlag(name) {
     return process.argv.includes(name);
 }
-function cmdQuestions() {
-    console.log("Project definition questions:");
-    for (const q of DISCOVERY_QUESTIONS)
-        console.log(`- ${q}`);
-    console.log("\nExpected output of this session:");
-    console.log("- Finalized workflow file (markdown or json) with per-step objectives");
-    console.log("- Validation/approval confirmation map per step");
-    console.log("- Adapter init map (opencode/codex/claude-code with context+skills+mcps)");
-    console.log("- Runnable CLI command examples + run JSON output");
+function getFlagFromArgs(args, name) {
+    const idx = args.indexOf(name);
+    if (idx >= 0 && idx + 1 < args.length)
+        return args[idx + 1];
+    return undefined;
+}
+function combineRunObservers(...observers) {
+    const active = observers.filter((observer) => observer !== undefined);
+    if (active.length === 0) {
+        return undefined;
+    }
+    return {
+        onEvent(event) {
+            for (const observer of active) {
+                observer.onEvent(event);
+            }
+        },
+        onSnapshot(snapshot, stepDetails) {
+            for (const observer of active) {
+                observer.onSnapshot(snapshot, stepDetails);
+            }
+        },
+        onLog(log) {
+            for (const observer of active) {
+                observer.onLog(log);
+            }
+        },
+    };
 }
 const WORKFLOW_SCAFFOLD_JSON = {
     key: "workflow-manager-sample",
@@ -73,7 +102,6 @@ const WORKFLOW_SCAFFOLD_JSON = {
             dependsOn: [],
             validation: { mode: "human", required: true, autoConfirm: false },
             taskSpec: {
-                adapterKey: "opencode",
                 init: {
                     context: { repo: "example/repo" },
                     skills: ["architecture", "planning"],
@@ -157,7 +185,6 @@ steps:
       required: true
       autoConfirm: false
     taskSpec:
-      adapterKey: opencode
       init:
         context:
           repo: example/repo
@@ -221,6 +248,36 @@ steps:
 
 Edit frontmatter to configure orchestration behavior.
 `;
+const AGENT_RULES_TEMPLATE = `# WFM Agent Rules
+
+Use these rules when creating, validating, running, or publishing workflow-manager workflows with the \`wfm\` CLI.
+
+## Core Flow
+
+1. Start with \`wfm doctor\` to inspect local adapter and API key setup.
+2. Create a starter workflow with \`wfm scaffold ./workflow.md\` or \`wfm scaffold ./workflow.json --format json\`.
+3. Edit stable workflow keys, step objectives, dependencies, validation modes, and adapter initialization.
+4. Run \`wfm validate <workflow>\` before every run or publish.
+5. Run \`wfm doctor <workflow>\` before using real host-backed adapters.
+6. Run with \`wfm run <workflow>\`; use \`--verbose\` when agent logs are needed.
+7. Publish only after validation succeeds with \`wfm publish <workflow>\`.
+
+## Workflow Authoring
+
+- Keep workflow, step, and adapter keys stable; external tools and tests may reference them.
+- Omit \`taskSpec.adapterKey\` for the default \`pi-agent\` adapter.
+- Use \`adapterKey: mock\` for deterministic tests and examples.
+- Put skills, MCP endpoints, system prompts, model, and context under \`taskSpec.init\`.
+- Model-backed steps should declare required environment variables through provider-specific model names or \`taskSpec.payload.requiredEnv\`.
+- Human or external validation should be explicit in the workflow file.
+
+## Running Safely
+
+- Do not use \`--auto-confirm-all\` unless the workflow is intentionally non-interactive.
+- Prefer \`wfm doctor <workflow>\` before runs that use \`pi-agent\`, real \`opencode\`, or real \`claude-code\`.
+- Use the attach API output from \`wfm run\` for approval, resume, and cancel commands.
+- Preserve Markdown workflows when humans will review notes; use JSON for generated or machine-edited workflows.
+`;
 function resolveScaffoldFormat(targetPath, explicitFormat) {
     if (explicitFormat === "markdown" || explicitFormat === "json") {
         return explicitFormat;
@@ -243,6 +300,31 @@ function parseScaffoldArgs(args) {
     }
     return { targetPath, format };
 }
+function parseAgentArgs(args) {
+    let targetPath;
+    let force = false;
+    for (const arg of args) {
+        if (arg === "--force" || arg === "-f") {
+            force = true;
+            continue;
+        }
+        if (!arg.startsWith("-") && !targetPath) {
+            targetPath = arg;
+        }
+    }
+    return { targetPath, force };
+}
+function cmdAgent(targetPath, force = false) {
+    const resolvedPath = path.resolve(targetPath ?? "./AGENTS.md");
+    if (fs.existsSync(resolvedPath) && !force) {
+        console.error(`Agent rules already exist at ${resolvedPath}. Pass --force to overwrite.`);
+        return 1;
+    }
+    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+    fs.writeFileSync(resolvedPath, AGENT_RULES_TEMPLATE, "utf-8");
+    console.log(`Wrote WFM agent rules: ${resolvedPath}`);
+    return 0;
+}
 function cmdScaffold(targetPath, format) {
     const resolvedPath = targetPath ? path.resolve(targetPath) : path.resolve("./example-workflow.md");
     const normalizedFormat = format?.toLowerCase();
@@ -259,18 +341,36 @@ function cmdScaffold(targetPath, format) {
     return 0;
 }
 function cmdMan() {
-    const manPagePath = path.resolve("./man/wfm.1");
-    if (!fs.existsSync(manPagePath)) {
-        console.error(`Man page not found at ${manPagePath}`);
-        return 1;
+    const modulePath = fileURLToPath(import.meta.url);
+    const packageRoot = path.dirname(path.dirname(modulePath));
+    const candidatePaths = [path.join(packageRoot, "man", "wfm.1"), path.resolve("./man/wfm.1")];
+    const manPagePath = candidatePaths.find((candidatePath) => fs.existsSync(candidatePath));
+    let fallbackSource = MAN_PAGE_SOURCE;
+    let tempDir;
+    const resolvedManPagePath = manPagePath ??
+        (() => {
+            tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "wfm-man-"));
+            const tempManPagePath = path.join(tempDir, "wfm.1");
+            fs.writeFileSync(tempManPagePath, MAN_PAGE_SOURCE, "utf-8");
+            return tempManPagePath;
+        })();
+    if (manPagePath) {
+        fallbackSource = fs.readFileSync(manPagePath, "utf-8");
     }
-    const result = spawnSync("man", [manPagePath], { stdio: "inherit" });
-    if (result.status === 0) {
+    try {
+        const result = spawnSync("man", [resolvedManPagePath], { stdio: "inherit" });
+        if (result.status === 0) {
+            return 0;
+        }
+        console.log("\n' man ' command unavailable, printing page contents:\n");
+        console.log(fallbackSource);
         return 0;
     }
-    console.log("\n' man ' command unavailable, printing page contents:\n");
-    console.log(fs.readFileSync(manPagePath, "utf-8"));
-    return 0;
+    finally {
+        if (tempDir) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    }
 }
 function cmdValidate(filePath) {
     try {
@@ -290,10 +390,151 @@ function cmdValidate(filePath) {
         return 1;
     }
 }
+function renderStatus(status) {
+    if (status === "ok")
+        return "OK";
+    if (status === "missing")
+        return "MISSING";
+    return "INFO";
+}
+function cmdDoctor(args) {
+    const workflowPath = args.find((arg) => !arg.startsWith("-"));
+    const json = args.includes("--json");
+    const hostChecks = runtimeDoctorChecks();
+    const adapterStatuses = adapterImplementationStatuses();
+    let workflow = null;
+    let workflowErrors = [];
+    let runtimeErrors = [];
+    if (workflowPath) {
+        try {
+            workflow = parseWorkflowFile(path.resolve(workflowPath));
+            workflowErrors = validateWorkflow(workflow);
+            if (workflowErrors.length === 0) {
+                runtimeErrors = validateRuntimeRequirements(workflow);
+            }
+        }
+        catch (err) {
+            workflowErrors = [err.message];
+        }
+    }
+    const baselineErrors = workflowPath
+        ? []
+        : hostChecks
+            .filter((check) => check.required && check.status === "missing")
+            .map((check) => `${check.label}: ${check.detail}`);
+    const exitCode = baselineErrors.length > 0 || workflowErrors.length > 0 || runtimeErrors.length > 0 ? 1 : 0;
+    if (json) {
+        console.log(JSON.stringify({
+            ok: exitCode === 0,
+            hostChecks,
+            adapterStatuses,
+            workflow: workflow
+                ? {
+                    key: workflow.key,
+                    title: workflow.title,
+                    errors: workflowErrors,
+                    runtimeErrors,
+                }
+                : null,
+            baselineErrors,
+        }, null, 2));
+        return exitCode;
+    }
+    console.log("Workflow Manager Doctor");
+    console.log("\nHost runtime:");
+    for (const check of hostChecks) {
+        const required = check.required ? "required" : "optional";
+        console.log(`- ${renderStatus(check.status)} ${check.label} (${required}): ${check.detail}`);
+    }
+    console.log("\nAdapter implementation:");
+    for (const adapter of adapterStatuses) {
+        console.log(`- ${adapter.adapter}: ${adapter.status} - ${adapter.detail}`);
+    }
+    if (workflowPath) {
+        console.log(`\nWorkflow: ${workflowPath}`);
+        if (workflowErrors.length > 0) {
+            console.log("- INVALID schema:");
+            for (const error of workflowErrors) {
+                console.log(`  - ${error}`);
+            }
+        }
+        else if (runtimeErrors.length > 0) {
+            console.log("- INVALID runtime:");
+            for (const error of runtimeErrors) {
+                console.log(`  - ${error}`);
+            }
+        }
+        else {
+            console.log("- OK workflow schema and runtime requirements");
+        }
+    }
+    return exitCode;
+}
+async function runnerControlRequest(action, args) {
+    const baseUrl = getFlagFromArgs(args, "--url") ?? process.env.WFM_RUNNER_URL;
+    const token = getFlagFromArgs(args, "--token") ?? process.env.WFM_RUNNER_TOKEN;
+    const stepKey = getFlagFromArgs(args, "--step");
+    const actor = getFlagFromArgs(args, "--actor");
+    const note = getFlagFromArgs(args, "--note");
+    const source = getFlagFromArgs(args, "--source") ?? "cli";
+    if (!baseUrl) {
+        console.error(`Missing --url. You can also set WFM_RUNNER_URL.`);
+        return 1;
+    }
+    if (!token) {
+        console.error(`Missing --token. You can also set WFM_RUNNER_TOKEN.`);
+        return 1;
+    }
+    const headers = {
+        Authorization: `Bearer ${token}`,
+    };
+    let runId = getFlagFromArgs(args, "--run-id");
+    if (!runId) {
+        const sessionResponse = await fetch(`${baseUrl}/session`, { headers });
+        if (!sessionResponse.ok) {
+            const message = await sessionResponse.text();
+            console.error(`Failed to discover run id: ${message}`);
+            return 1;
+        }
+        const session = (await sessionResponse.json());
+        runId = session.run?.runId;
+    }
+    if (!runId) {
+        console.error("Could not determine run id. Pass --run-id explicitly.");
+        return 1;
+    }
+    const response = await fetch(`${baseUrl}/runs/${runId}/${action}`, {
+        method: "POST",
+        headers: {
+            ...headers,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            stepKey,
+            actor,
+            note,
+            source,
+        }),
+    });
+    const payloadText = await response.text();
+    const payload = payloadText ? JSON.parse(payloadText) : {};
+    if (!response.ok) {
+        const message = typeof payload.message === "string" ? payload.message : `Request failed with status ${response.status}`;
+        console.error(`${action} failed: ${message}`);
+        return 1;
+    }
+    const decision = typeof payload.decision === "string" ? payload.decision : action === "cancel" ? "cancelled" : "approved";
+    const resolvedStep = typeof payload.stepKey === "string" ? payload.stepKey : stepKey ?? "current";
+    console.log(`${decision} ${resolvedStep}`);
+    return 0;
+}
 async function cmdRun(filePath) {
     const resolvedPath = path.resolve(filePath);
     const startedAt = Date.now();
     let workflow;
+    let runnerServer;
+    let sessionStore;
+    let liveRenderer;
     try {
         workflow = parseWorkflowFile(resolvedPath);
         const errors = validateWorkflow(workflow);
@@ -308,20 +549,98 @@ async function cmdRun(filePath) {
             return 1;
         }
         const objective = getFlag("--objective");
-        const inputPath = getFlag("--input");
-        const input = inputPath ? JSON.parse(fs.readFileSync(path.resolve(inputPath), "utf-8")) : {};
+        const inputRaw = getFlag("--input");
+        let input = {};
+        if (inputRaw) {
+            const parsed = inputRaw.trimStart().startsWith("{")
+                ? JSON.parse(inputRaw.replace(/[\n\r]/g, " "))
+                : JSON.parse(fs.readFileSync(path.resolve(inputRaw), "utf-8"));
+            if (typeof parsed !== "object" || Array.isArray(parsed) || parsed === null) {
+                console.error("--input must be a JSON object");
+                return 1;
+            }
+            input = parsed;
+        }
         const confirmRaw = getFlag("--confirm") ?? "";
         const confirmations = confirmRaw
             .split(",")
             .map((x) => x.trim())
             .filter(Boolean);
-        const result = runWorkflow(workflow, {
+        const runId = randomUUID();
+        const requestedPortRaw = getFlag("--port");
+        const requestedPort = requestedPortRaw === undefined ? 0 : Number.parseInt(requestedPortRaw, 10);
+        if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
+            console.error("--port must be an integer between 0 and 65535");
+            return 1;
+        }
+        sessionStore = new RunnerSessionStore({
+            runId,
+            workflow,
+            objective: objective ?? workflow.title,
+            objectives: workflow.objectives ?? [],
+        });
+        liveRenderer = new CliRunRenderer({
+            workflow,
+            verbose: hasFlag("--verbose"),
+        });
+        runnerServer = await startRunnerApiServer(sessionStore, requestedPort);
+        const session = sessionStore.sessionInfo();
+        process.stderr.write(`Attach API: ${session.baseUrl} (token ${session.attachToken})\n`);
+        const result = await runWorkflow(workflow, {
+            runId,
             objective,
             input,
             confirmations,
             autoConfirmAll: hasFlag("--auto-confirm-all"),
+            interactive: process.stdin.isTTY,
+            workflowFilePath: resolvedPath,
+            approvalPrompt: async (request) => {
+                liveRenderer?.pauseHeartbeat();
+                try {
+                    const decision = await promptForApprovalDecision(request.stepKey, request.reason, request.validation ?? "external", request.preview ?? null, "cli", request.signal);
+                    if (!decision) {
+                        return null;
+                    }
+                    const metadata = {
+                        actor: decision.actor,
+                        note: decision.note,
+                        source: decision.source,
+                    };
+                    const outcome = decision.decision === "cancelled"
+                        ? sessionStore?.cancel(request.stepKey, metadata)
+                        : request.validation === "external"
+                            ? sessionStore?.resume(request.stepKey, metadata)
+                            : sessionStore?.approve(request.stepKey, metadata);
+                    if (outcome && !outcome.ok) {
+                        process.stderr.write(`Could not apply terminal decision for ${request.stepKey}: ${outcome.reason ?? "unknown error"}\n`);
+                    }
+                    return null;
+                }
+                finally {
+                    liveRenderer?.resumeHeartbeat();
+                }
+            },
+            observer: combineRunObservers(sessionStore, liveRenderer),
+            controller: sessionStore,
         });
-        console.log(JSON.stringify(result, null, 2));
+        liveRenderer.close();
+        if (hasFlag("--json")) {
+            console.log(JSON.stringify({ session: sessionStore.sessionInfo(), ...result }, null, 2));
+        }
+        else {
+            const icon = result.status === "succeeded" ? "✓" : result.status === "waiting_for_approval" ? "◌" : "✗";
+            process.stderr.write(`\n${icon} ${result.status} — ${workflow.title}\n\n`);
+            for (const sr of result.stepRuns) {
+                const stepIcon = sr.status === "succeeded" ? "✓" : sr.status === "waiting_for_approval" ? "◌" : "✗";
+                const step = workflow.steps.find((s) => s.key === sr.stepKey);
+                const adapterKey = step?.kind === "task" ? (step.taskSpec?.adapterKey ?? "pi-agent") : "approval";
+                process.stderr.write(`  ${stepIcon} ${sr.stepKey.padEnd(20)} ${adapterKey}\n`);
+            }
+            if (result.status !== "succeeded") {
+                process.stderr.write(`\nRun --json to see full output.\n`);
+            }
+            process.stderr.write("\n");
+        }
         await emitRunTelemetryBestEffort({
             definition: workflow,
             sourceFilePath: resolvedPath,
@@ -332,6 +651,7 @@ async function cmdRun(filePath) {
         return result.status === "succeeded" ? 0 : 2;
     }
     catch (err) {
+        liveRenderer?.close();
         console.error(`Run error: ${err.message}`);
         if (workflow) {
             await emitRunTelemetryBestEffort({
@@ -343,6 +663,10 @@ async function cmdRun(filePath) {
         }
         return 1;
     }
+    finally {
+        liveRenderer?.close();
+        await runnerServer?.close().catch(() => undefined);
+    }
 }
 async function main() {
     const cmd = process.argv[2];
@@ -350,9 +674,12 @@ async function main() {
         usage();
         process.exit(0);
     }
-    if (cmd === "questions") {
-        cmdQuestions();
-        process.exit(0);
+    if (cmd === "doctor") {
+        process.exit(cmdDoctor(process.argv.slice(3)));
+    }
+    if (cmd === "agent") {
+        const { targetPath, force } = parseAgentArgs(process.argv.slice(3));
+        process.exit(cmdAgent(targetPath, force));
     }
     if (cmd === "scaffold") {
         const { targetPath, format } = parseScaffoldArgs(process.argv.slice(3));
@@ -377,6 +704,9 @@ async function main() {
         }
         process.exit(await cmdRun(file));
     }
+    if (cmd === "approve" || cmd === "resume" || cmd === "cancel") {
+        process.exit(await runnerControlRequest(cmd, process.argv.slice(3)));
+    }
     if (cmd === "auth") {
         process.exit(await cmdAuth(process.argv.slice(3)));
     }

package/dist/manPage.d.ts

@@ -0,0 +1 @@
+export declare const MAN_PAGE_SOURCE = ".TH WFM 1 \"April 2026\" \"@workflow-manager/runner\" \"User Commands\"\n.SH NAME\nwfm \\- run markdown or json workflows from the CLI\n.SH SYNOPSIS\n.B wfm\n.I command\n[options]\n.SH DESCRIPTION\nwfm parses a workflow definition file, validates it, and executes\nit with deterministic in-memory orchestration.\n\nWorkflow files can be Markdown with YAML frontmatter or JSON.\n.SH COMMANDS\n.TP\n.B doctor [workflow.md|workflow.json] [--json]\nInspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.\n.TP\n.B agent [path] [--force]\nCreate WFM-focused agent rules. The default path is ./AGENTS.md. Existing files are not overwritten unless --force is passed.\n.TP\n.B scaffold [path] [--format markdown|json]\nCreate a starter workflow file. Format defaults to markdown unless the output\npath ends in .json.\n.TP\n.B validate <workflow.md|workflow.json>\nValidate workflow structure and report schema errors.\n.TP\n.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json]\nRun the workflow with live CLI progress and optional JSON output.\n.TP\n.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nApprove the current waiting runner step through the local attach API.\n.TP\n.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nAlias for approve, intended for external resume flows.\n.TP\n.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nCancel the current waiting runner step through the local attach API.\n.TP\n.B auth <login|whoami|logout> [--token value]\nManage remote registry authentication for CLI publish and pull flows.\n.TP\n.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]\nPublish a validated local workflow to the remote registry.\n.TP\n.B pull <owner/slug> [--version label] [--output path]\nDownload a remote workflow and write it to a local file.\n.TP\n.B search [query]\nSearch public workflows from the remote registry.\n.TP\n.B remote info <owner/slug>\nShow metadata and source information for a remote workflow.\n.TP\n.B man\nOpen this man page.\n.SH RUN OPTIONS\n.TP\n.B --input <path>\nJSON file merged into global workflow input state.\n.TP\n.B --objective <text>\nOverride the default run objective.\n.TP\n.B --confirm <stepA,stepB:human,...>\nProvide explicit confirmations for steps that require validation.\n.TP\n.B --auto-confirm-all\nBypass confirmation gating for all steps.\n.TP\n.B --port <number>\nBind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.\n.TP\n.B --verbose\nStream per-step agent output and execution updates to stderr while the workflow runs.\n.TP\n.B --json\nPrint the final run result as JSON on stdout while keeping live progress on stderr.\n.TP\nHuman approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.\n.TP\n.B --url <value>\nRunner attach API base URL for approve, resume, or cancel commands.\n.TP\n.B --token <value>\nRunner attach API bearer token for approve, resume, or cancel commands.\n.TP\n.B --run-id <value>\nRunner id to control. If omitted, the CLI reads it from /session.\n.TP\n.B --step <value>\nOptional step key when controlling a specific waiting step.\n.TP\n.B --actor <value>\nActor name recorded in approval audit events.\n.TP\n.B --note <text>\nOptional approval or cancellation note recorded in the event payload.\n.SH EXAMPLES\n.TP\nValidate markdown workflow:\n.B wfm validate ./example-workflow.md\n.TP\nValidate json workflow:\n.B wfm validate ./example-workflow.json\n.TP\nScaffold json workflow file:\n.B wfm scaffold ./new-workflow.json --format json\n.TP\nAuthenticate with a CLI token:\n.B wfm auth login --token wm_exampletoken\n.TP\nPublish a workflow:\n.B wfm publish ./example-workflow.json --visibility public --tag example,automation\n.TP\nPull a remote workflow:\n.B wfm pull alice/remote-bunny --output ./remote-bunny.json\n.TP\nSearch the remote registry:\n.B wfm search bunny\n.TP\nRun with explicit confirmations:\n.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human\n.TP\nInspect host setup:\n.B wfm doctor\n.TP\nCheck a workflow before running it:\n.B wfm doctor ./example-workflow.json\n.TP\nCreate agent rules:\n.B wfm agent ./AGENTS.md\n.SH FILES\n.TP\n.B man/wfm.1\nThe manual page source shipped with this repository.\n.SH EXIT STATUS\n.TP\n.B 0\nSuccessful command execution.\n.TP\n.B 1\nValidation or runtime error.\n.TP\n.B 2\nRun completed in non-success terminal status.\n";