---
title: Documentation and agent interfaces — mdflow
description: Install mdflow, inspect the local CLI, read the public source-facts snapshot, and respect version contracts, operation effects, and separate consent.
url: https://mdflow.dev/docs/
---
# 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](https://www.npmjs.com/package/mdflow) 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](https://bun.sh). 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.

```bash
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](https://mdflow.dev/docs/public-api.md) 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.

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

The [OpenAPI 3.1 specification](https://mdflow.dev/openapi.json) 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](https://mdflow.dev/.well-known/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](https://www.rfc-editor.org/rfc/rfc9457) 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.

- **404 Not Found:** a requested JSON resource is missing. Check the resource URL against the catalog and specification.
- **405 Method Not Allowed:** an unsupported method is used on the read-only facts resource. The `Allow` header is `GET, HEAD`; use GET to read the snapshot. There are no mutation operations.
- **406 Not Acceptable:** the request excludes the available JSON representation. Send `Accept: application/json`.

The site is publicly hosted on Vercel. Hosting receives ordinary request information (such as IP address, URL, and headers); see [privacy](https://mdflow.dev/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](https://mdflow.dev/docs/public-api.md).

## 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

- [Complete CLI reference](https://mdflow.dev/docs/public-api.md): flags, configuration, JSON objects, event ordering, and error contracts.
- [Project README](https://mdflow.dev/README.md): installation and workflow examples.
- [Evolution specification](https://mdflow.dev/docs/evolve.md) and [illustrated deep dive](https://mdflow.dev/evolve-deep-dive/): feedback, proof, review, apply, and rollback.
- [Security policy](https://mdflow.dev/SECURITY.md): execution boundaries and private reporting.
- [Agent skill](https://mdflow.dev/skills/mdflow/SKILL.md): the repository's actual flow-authoring instructions. Install with `npx skills add johnlindquist/mdflow`; inspect the [SHA-256 index](https://mdflow.dev/.well-known/agent-skills/index.json) when comparing downloaded bytes.
- [llms.txt](https://mdflow.dev/llms.txt) is the concise resource map; [llms-full.txt](https://mdflow.dev/llms-full.txt) includes the source documentation for offline reading.

## 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.

- `md doctor [--json]` — Inspect project readiness and safe next actions without execution.
- `md init [--guided] [--engine <e>] [--yes] [--agents] [--print-guide]` — Initialize a project flow roster.
- `md create [intent] [--global] [--dry-run]` — Create a flow and a fail-closed draft eval suite.
- `md capture` — Print the guide for capturing the current agent conversation as a flow.
- `md explain <flow.md> [--json]` — Resolve one flow without launching its engine.
- `md render <flow.md> [--json|--out <path>|--open]` — Inspect, write, or open a rendered flow explanation.
- `md hooks add|list|remove <flow.md> [event...]` — Manage executable lifecycle hook sidecars.
- `md eval <flow.md> [--plan] [--yes] [--json]` — Plan or run a flow's behavioral eval suite.
- `md feedback <flow.md> <message> | list|show|distill|dismiss|reopen|forget` — Manage durable evolution evidence.
- `md complain <flow.md> <message>` — Compatibility alias for feedback.
- `md evolve plan|status|propose|show|apply|reject|retry|rollback|history|prune` — Manage proposal-first flow evolution.
- `md install <url|gh:org/repo/path@ref> [--global]` — Install one flow into the registry.
- `md remove <name>` — Remove an installed registry flow.
- `md list [--project|--global]` — List installed registry flows.
- `md roster --json | roster sync [--check] [--agents] [--json]` — Inspect flows or synchronize the managed operator card.
- `md catalog [--json]` — Machine-readable catalog of every discoverable flow (project, global, installed, PATH).
- `md setup` — Configure shell integration.
- `md logs` — Show flow log locations.
- `md help [command]` — Show CLI or command help.