# @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: ```sh npx -y @markdown-ai/cli demo ``` ![mda demo in one command](./demo.gif) 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`](./demo.tape) using [charm vhs](https://github.com/charmbracelet/vhs); rerun `vhs demo.tape` after changing CLI output to refresh `demo.gif`. ## Install Run without installing: ```sh npx @markdown-ai/cli --help ``` Install globally: ```sh 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: ```sh mda init hello-skill --out hello.mda ``` Validate it: ```sh mda validate hello.mda ``` Compile it into agent-readable Markdown: ```sh mda compile hello.mda --target SKILL.md AGENTS.md --out-dir out --integrity ``` Validate the output: ```sh 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: ```text config/llm/ source//.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/`. ```sh 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: ```sh 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: ```sh 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 ]` | Generate a source plus all four compiled targets with integrity in one step. | | `mda init --out ` | Create a source scaffold. | | `mda init --template llmix-preset --module --preset --provider --model ` | Create an LLMix preset source scaffold. | | `mda validate [--target ]` | Validate source or generated Markdown. | | `mda compile --target SKILL.md AGENTS.md --out-dir out --integrity` | Compile source into agent-readable artifacts. | | `mda canonicalize --target ` | Produce deterministic canonical bytes. | | `mda integrity compute --target ` | Compute a stable digest. | | `mda integrity verify --target ` | Check the declared digest against current content. | | `mda sign --profile did-web --did --key-id --key-file --in-place` | Sign an artifact with explicit did:web key material. | | `mda sign --profile github-actions --repo --workflow --ref --rekor --offline-sigstore-fixture --in-place` | Sign with explicit GitHub Actions Sigstore/Rekor evidence. | | `mda verify --policy ` | Verify signatures against a local trust policy and explicit evidence. | | `mda release prepare --target llmix-registry --source --registry-dir --policy --out ` | Verify signed LLMix presets and write a deterministic release plan. | | `llmix publish-registry --root config/llm --release-plan --revision --policy --root-did --root-key-id --root-key-file ` | Publish source presets into `current.json`, `compiled/`, and a signed registry root. | | `mda release finalize --target llmix-registry --registry-dir --registry-root --release-plan --policy --derive-root-digest --out ` | Verify signed registry-root evidence, write an external trust manifest, or snippets. | | `llmix check-registry --root config/llm --trust --preset --tamper-proof` | Prove runtime loading and tamper rejection with the external trust anchor. | | `mda doctor release --target llmix-registry --source --registry-dir --release-plan --manifest ` | 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](./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](https://github.com/sno-ai/mda#readme) and the [MDA Open Spec](https://github.com/sno-ai/mda/blob/main/SPEC.md). ## 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.