@markdown-ai/cli

@markdown-ai/cli installs one command: mda.

It helps you create, validate, compile, sign, verify, and release Markdown AI (MDA) artifacts. The main job is simple: keep the source clean, keep the output predictable, and give humans or AI agents a clear next step when something is wrong.

Most users start with one .mda source file. From that file, the CLI can emit the Markdown files agent systems already understand: SKILL.md, AGENTS.md, and MCP-SERVER.md.

Try It In One Command

No install, no scaffolding, no flags to memorize:

npx -y @markdown-ai/cli demo

That drops a mda-demo/ folder in the current directory with one hello.mda source and three compiled outputs (out/SKILL.md, out/AGENTS.md, out/MCP-SERVER.md) plus an MCP sidecar, each with a sha256 integrity digest in the frontmatter. From there you can edit mda-demo/hello.mda and rerun mda compile to see the four artifacts move together.

The recording above is rendered from demo.tape using charm vhs; rerun vhs demo.tape after changing CLI output to refresh demo.gif.

Install

Run without installing:

npx @markdown-ai/cli --help

Install globally:

npm install -g @markdown-ai/cli
mda --help

The installed binary is mda.

Running mda with no arguments prints help. It does not write files, validate files, sign anything, verify anything, or touch the network.

Quick Start

Create a source file:

mda init hello-skill --out hello.mda

Validate it:

mda validate hello.mda

Compile it into agent-readable Markdown:

mda compile hello.mda --target SKILL.md AGENTS.md --out-dir out --integrity

Validate the output:

mda validate out/SKILL.md --target SKILL.md
mda validate out/AGENTS.md --target AGENTS.md
mda integrity verify out/SKILL.md --target SKILL.md

That is the everyday flow. Create the source. Check it. Compile it. Check what came out.

Release Quick Path For LLMix Registry

For LLMix releases, use one public layout and one handoff:

config/llm/
  source/<module>/<preset>.mda
  current.json
  compiled/

source/ is human-edited MDA preset source. current.json and compiled/ are machine-generated by LLMix. Keep the deployment trust anchor outside config/llm/. Do not write a registry compiler or publisher in the app repo: MDA CLI gates the source release, then the official llmix publish-registry command publishes the registry. The examples below assume release/did-web-private-key.pem and release/did.json already exist under release/, outside config/llm/.

mkdir -p config/llm/source/search_summary release deploy
mda init --template llmix-preset --module search_summary --preset openai_fast --provider openai --model gpt-5-mini --out config/llm/source/search_summary/openai_fast.mda
mda validate config/llm/source/search_summary/openai_fast.mda --target source --json
mda integrity compute config/llm/source/search_summary/openai_fast.mda --target source --write --json
mda release trust policy --target llmix-registry --profile did-web --domain config.example.com --out release/trust-policy.json --json
mda sign config/llm/source/search_summary/openai_fast.mda --profile did-web --did did:web:config.example.com --key-id did:web:config.example.com#release --key-file release/did-web-private-key.pem --in-place --json
mda verify config/llm/source/search_summary/openai_fast.mda --target source --policy release/trust-policy.json --did-document release/did.json --json
mda release prepare --target llmix-registry --source config/llm/source --registry-dir config/llm --policy release/trust-policy.json --did-document release/did.json --out release/plan.json --json
llmix publish-registry --root config/llm --release-plan release/plan.json --revision 2026-05-14T000000Z --policy release/trust-policy.json --did-document release/did.json --root-did did:web:config.example.com --root-key-id did:web:config.example.com#release --root-key-file release/did-web-private-key.pem --json
mda release finalize --target llmix-registry --registry-dir config/llm --registry-root config/llm/compiled/2026-05-14T000000Z/registry-root.json --release-plan release/plan.json --policy release/trust-policy.json --derive-root-digest --minimum-revision 2026-05-14T000000Z --out deploy/llmix-trust.json --did-document release/did.json --json
mda doctor release --target llmix-registry --source config/llm/source --registry-dir config/llm --release-plan release/plan.json --manifest deploy/llmix-trust.json --did-document release/did.json --json
llmix check-registry --root config/llm --trust deploy/llmix-trust.json --preset search_summary/openai_fast --did-document release/did.json --tamper-proof --json

llmix publish-registry generates config/llm/current.json, config/llm/compiled/, and the native signed registry root envelope. The mda release finalize command verifies that root and writes the external trust manifest. llmix check-registry --tamper-proof proves the runtime can open the registry with the external trust anchor and rejects modified registry content while that trust anchor still pins the trusted release.

GitHub Actions Sigstore/Rekor can be used instead of did:web signing when that is the release identity, but keep the same layout and LLMix publisher handoff.

AI Agent Usage

Use --json when another program is driving the CLI.

Human output is meant to be read. JSON output is meant to be used. It gives stable fields:

• ok
• command
• exitCode
• summary
• artifacts
• diagnostics
• nextActions

Recommended agent flow:

mda validate task.mda --target source --json
mda compile task.mda --target SKILL.md AGENTS.md MCP-SERVER.md --out-dir out --integrity --json
mda validate out/SKILL.md --target SKILL.md --json
mda validate out/AGENTS.md --target AGENTS.md --json
mda validate out/MCP-SERVER.md --target MCP-SERVER.md --json
mda integrity verify out/SKILL.md --target SKILL.md --json

Agent rules:

• Treat exit code 0 and ok: true as success.
• Treat any non-zero exit as a stop signal.
• Read diagnostics[0].code before parsing messages.
• Use artifacts and nextActions to decide the next command.
• Pass --target when a Markdown filename is not exact.
• Write generated files into a temp or staging directory first.

The CLI is a good external gate. Application runtime loaders should still keep their own verifier hooks instead of shelling out to mda.

Secure Release Flow

For signed LLMix registry releases, MDA is the source gate and LLMix is the registry publisher. Starting from the same config/llm/source/search_summary/openai_fast.mda preset above:

mda validate config/llm/source/search_summary/openai_fast.mda --target source --json
mda integrity compute config/llm/source/search_summary/openai_fast.mda --target source --write --json
mda release trust policy --target llmix-registry --profile did-web --domain config.example.com --out release/trust-policy.json --json
mda sign config/llm/source/search_summary/openai_fast.mda --profile did-web --did did:web:config.example.com --key-id did:web:config.example.com#release --key-file release/did-web-private-key.pem --in-place --json
mda verify config/llm/source/search_summary/openai_fast.mda --target source --policy release/trust-policy.json --did-document release/did.json --json
mda release prepare --target llmix-registry --source config/llm/source --registry-dir config/llm --policy release/trust-policy.json --did-document release/did.json --out release/plan.json --json
llmix publish-registry --root config/llm --release-plan release/plan.json --revision 2026-05-14T000000Z --policy release/trust-policy.json --did-document release/did.json --root-did did:web:config.example.com --root-key-id did:web:config.example.com#release --root-key-file release/did-web-private-key.pem --json
mda release finalize --target llmix-registry --registry-dir config/llm --registry-root config/llm/compiled/2026-05-14T000000Z/registry-root.json --release-plan release/plan.json --policy release/trust-policy.json --derive-root-digest --minimum-revision 2026-05-14T000000Z --out deploy/llmix-trust.json --did-document release/did.json --json
mda doctor release --target llmix-registry --source config/llm/source --registry-dir config/llm --release-plan release/plan.json --manifest deploy/llmix-trust.json --did-document release/did.json --json
llmix check-registry --root config/llm --trust deploy/llmix-trust.json --preset search_summary/openai_fast --did-document release/did.json --tamper-proof --json

The registry root is the native signed root envelope written by llmix publish-registry. It is checked against the actual registry directory and release plan before the external trust manifest is written.

Keep private keys and deployment trust manifests outside the registry directory. Trust authority should live outside config/llm/. The CLI checks that because it is the kind of mistake that looks fine until it matters.

Common Commands

| Command | Use it for | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | mda | Print help. | | mda demo [--out-dir <dir>] | Generate a source plus all four compiled targets with integrity in one step. | | mda init <name> --out <file.mda> | Create a source scaffold. | | mda init --template llmix-preset --module <module> --preset <preset> --provider <provider> --model <model> | Create an LLMix preset source scaffold. | | mda validate <file> [--target <target>] | Validate source or generated Markdown. | | mda compile <file.mda> --target SKILL.md AGENTS.md --out-dir out --integrity | Compile source into agent-readable artifacts. | | mda canonicalize <file> --target <target> | Produce deterministic canonical bytes. | | mda integrity compute <file> --target <target> | Compute a stable digest. | | mda integrity verify <file> --target <target> | Check the declared digest against current content. | | mda sign <file> --profile did-web --did <did> --key-id <key-id> --key-file <pem> --in-place | Sign an artifact with explicit did:web key material. | | mda sign <file> --profile github-actions --repo <owner/repo> --workflow <workflow> --ref <ref> --rekor --offline-sigstore-fixture <path> --in-place | Sign with explicit GitHub Actions Sigstore/Rekor evidence. | | mda verify <file> --policy <policy.json> | Verify signatures against a local trust policy and explicit evidence. | | mda release prepare --target llmix-registry --source <dir> --registry-dir <dir> --policy <path> --out <file> | Verify signed LLMix presets and write a deterministic release plan. | | llmix publish-registry --root config/llm --release-plan <file> --revision <id> --policy <policy> --root-did <did> --root-key-id <id> --root-key-file <pem> | Publish source presets into current.json, compiled/, and a signed registry root. | | mda release finalize --target llmix-registry --registry-dir <dir> --registry-root <file> --release-plan <file> --policy <path> --derive-root-digest --out <file> | Verify signed registry-root evidence, write an external trust manifest, or snippets. | | llmix check-registry --root config/llm --trust <external-trust.json> --preset <module/preset> --tamper-proof | Prove runtime loading and tamper rejection with the external trust anchor. | | mda doctor release --target llmix-registry --source <dir> --registry-dir <dir> --release-plan <path> --manifest <path> | Check release state before deployment. | | mda conformance --level V --json | Run validation conformance. | | mda conformance --level C --json | Run compile/equality conformance. |

Allowed targets:

• source
• SKILL.md
• AGENTS.md
• MCP-SERVER.md
• auto

Auto-detection is exact:

• *.mda means source
• SKILL.md means SKILL.md
• AGENTS.md means AGENTS.md
• MCP-SERVER.md means MCP-SERVER.md
• any other Markdown filename should pass --target

Full Manual

Read HOW-TO-USE.md for the complete manual. It covers the human flow, AI agent JSON flow, signing, verification, LLMix secure release, MCP sidecars, integrity commands, global flags, exit codes, and conformance.

For the broader project context, read the repository README and the MDA Open Spec.

Status

This is the 1.1 reference CLI for the Markdown AI / MDA artifact format.

The useful path is covered: author .mda, validate it, compile it, validate the outputs, run integrity checks, sign and verify release artifacts with explicit GitHub Actions Sigstore/Rekor evidence or did:web key material, and use the LLMix release/manifest/snippet/doctor commands before publishing or handing files to an agent.