@markdy/cli

First-party command-line tooling for MarkdyScript.

Install

npm i -D @markdy/cli

If you install it into a project, run it with npx markdy ... or npm exec markdy ... from that project. To make markdy available as a shell command everywhere, install it globally with npm i -g @markdy/cli.

Package position (text)

@markdy/cli
  -> reads .markdy files from disk
  -> uses parser/runtime packages internally
  -> outputs diagnostics, formatted source, or rendered HTML

Output preview

Use this command to generate a local HTML preview:

npx markdy render examples/showcase/url-shortener-architecture.markdy --out scene.html

Commands

markdy                                   # launch a local browser playground on http://127.0.0.1:4242
markdy lint scene.markdy                 # syntax validation
markdy lint scene.markdy --arch-rules    # run Well-Architected governance & cycle rules
markdy fmt scene.markdy --write          # format MarkdyScript file
markdy import flow.mmd --out scene.markdy # import Mermaid, draw.io, Compose, K8s, or Terraform
markdy diff v1.markdy v2.markdy          # semantic AST diff summary table
markdy diff v1.markdy v2.markdy --evolution # generate animated migration scene
markdy share scene.markdy                # create compressed playground link
markdy render scene.markdy --out dist/scene.html # export self-contained HTML preview
markdy explain scene.markdy              # display AST structure and stats
markdy new demo.markdy                   # scaffold fresh starter scene
markdy docs                              # display docs and tutorial links
markdy ai                                # generate prompt context for LLMs
markdy check docs/                       # validate diagrams in Markdown, MDX, and .markdy files
markdy check docs/ --json                # machine-readable validation report
markdy check --dist dist/                # validate diagrams embedded in built HTML
markdy check-all . --arch-rules          # batch lint entire workspace

Validate Documentation

Run markdy check docs/ to validate embedded diagrams alongside standalone .markdy files. Markdown fences accept the markdy and markdyscript language names, backticks or tildes, and optional metadata. Fences inside lists and blockquotes are supported. As in Markdown, an unclosed fence continues to the end of its container or document.

Live MDX <Markdy> and <MarkdyDiagram> components with literal code values are also checked. Fences and components quoted inside other code blocks, plus inline code examples, are ignored. Diagnostics point to the original document's line numbers.

Use --strict to treat warnings as failures, --arch-rules for architecture governance, or --json for structured CI output. Validation errors return a nonzero exit code.

Notes

• The CLI resolves import "file.markdy" as ns from disk before parsing.
• fmt canonicalizes aliases and indentation, places optional player: configuration last, and preserves its behavior; it may expand higher-level scene sugar into parsed form.
• render --out writes a self-contained HTML preview to the exact path you pass in.
• If the path is relative, it is resolved from the current working directory.
• If you see zsh: command not found: markdy, the package is installed locally but that directory is not on your PATH.