Documentation and agent interfaces

mdflow turns Markdown flows into repeatable local agent commands. Workflows execute only through the local CLI; the website serves read-only documentation and source facts. Use the installed md / mdflow CLI for running work.

Install and inspect first

Install the official mdflow npm package with npm install -g mdflow, or use npx mdflow to invoke the package. Install and authenticate the engine you intend to use separately. The current source facts identify mdflow 4.9.0, with pi as the default engine; always ask your installed CLI for its version before assuming that it matches this documentation.

mdflow runs on Bun. The interactive launcher offers to install Bun if it is missing; in a non-interactive environment, install Bun first. Package installation and engine authentication are environment changes, not part of the read-only doctor query.

md --version
md doctor --json
md roster --json

md doctor --json is a static, read-only readiness check: it does not execute a flow, load executable sidecars, expand imports, fetch URLs, or write files. Once local setup is approved, npx mdflow init --yes creates a deterministic starter roster without an engine invocation. Bare md opens the searchable Flow Workbench. md init --guided is different: it launches an engine-guided setup and needs separate approval.

Local CLI protocol

The public CLI reference defines Flow UX Protocol v1 (protocolVersion: 1). Check md --version and the protocol version in JSON responses. md doctor --json reports diagnostics and effect-labelled next actions; md roster --json enumerates flows; md explain <flow.md> --json resolves one invocation; and md <flow.md> --events executes a real run and streams NDJSON events. Event streaming is not a free preview. md <flow.md> --json is the separate single-result output mode, not the event stream.

Use stable diagnostic codes, operation effects, and consent requirements rather than parsing terminal styling.

Public source-facts interface

The site's public read-only machine interface is GET https://mdflow.dev/facts.json. It returns application/json: a static snapshot of published CLI source facts, command descriptions, operation effects and consent labels, safety rules, agent prompt templates, and flag descriptions. No authentication, credentials, or request body are required. Reading it performs no mutation and launches no workflow. HEAD is available for HTTP metadata.

curl --fail-with-body -H 'Accept: application/json' https://mdflow.dev/facts.json

The OpenAPI 3.1 specification describes only GET /facts.json. Its info.version is 1.0.0 (interface version 1). The response's contract.contractVersion is 1, which versions the embedded CLI operation contract. The separate versionBase field identifies the CLI source version, currently 4.9.0. The URL remains /facts.json. The schema covers every top-level field and derives nested command and operation shapes from the same source snapshot published at that URL.

The response includes X-API-Version: 1 and Link headers with service-desc and service-doc relations. Additive fields are allowed within v1; clients should tolerate fields they do not yet recognize. Breaking representation changes require a new URL and a new major OpenAPI info.version, rather than silently changing existing fields at /facts.json.

Discover the specification through the RFC 9727 API catalog, served as application/linkset+json. Its service-desc link points to /openapi.json and service-doc points to this page. The snapshot changes when the website is built and published, and hosting caches may serve an earlier snapshot. It describes source capabilities, not your project's files, installed engines, readiness, or execution results. Use the local CLI to inspect those.

HTTP errors and public hosting

Site-handled JSON errors use RFC 9457 Problem Details with Content-Type: application/problem+json. Responses include type (about:blank for standard HTTP problems), title, status, detail, and a resolution hint. An optional instance identifies the failed request when available. Use the HTTP status for control flow and allow additional problem fields.

The site is publicly hosted on Vercel. Hosting receives ordinary request information (such as IP address, URL, and headers); see privacy for infrastructure and third-party processing. Hosting or network failures can occur before site handling and need not use the problem format. Check status and Content-Type before parsing; treat this public, cacheable document as source documentation rather than live local state. Local CLI errors and consent rules are separately defined in the CLI reference.

Costs, permissions, and proof

Operations distinguish FREE (no engine invocation), LOCAL_WRITE (changes local state), and ENGINE (provider-backed work). FREE does not mean every operation is a sandbox: explanation and dry-run may resolve file, URL, or context-provider imports. Use doctor when you require strictly static inspection. Review flows and executable .eval.ts / .hooks.ts sidecars before allowing execution.

A real flow run, eval run, evolution proposal, and source-changing apply each require separate consent. Preview eval cost with md eval <flow.md> --plan; preview evolution with md evolve plan <flow.md>. Proposals remain private and off-path until an explicit md evolve apply <run-id>. Context isolation strips supported engine context, not host access or credentials.

Reference library

Command inventory

This list is generated from the same facts used by the homepage. Use md help <command> for the installed version's command-specific help.

Read as Markdown · Docs · About · Contact · Privacy · For agents