# @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/<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/`.

```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 <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](./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.
