MarkdStage CLI

Present, validate, inspect, capture, and export MarkdStage Markdown decks from a terminal — no GitHub Copilot canvas required.

This README describes the npm CLI, whose interactive commands remain browser-based. The Windows MSIX package also provides a markdstage alias, but bare invocation, direct Markdown, preview, and present activate its native app by default. That distribution requires no Node.js; interactive presentation uses WebView2, while console inspect/capture/export and GUI exports still need external Chromium. Microsoft Store installs the GUI and CLI together; Windows users do not need this npm installation. Desktop also provides workspace-scoped Agent Skill installation from Install skills…. See the CLI guide for packaged activation, acceptance JSON, and --no-open differences. Use npx @markdstage/markdstage to select npm explicitly if both are installed.

The CLI reuses the very same Markdown parser, renderer, Architecture DSL validation, theme handling, and PDF/PNG/PowerPoint pipeline as the MarkdStage canvas Extension and Desktop. Fonts, browser versions, and export-format limitations can affect the appearance; review final PDF and hybrid editable PowerPoint output.

Requirements

• Node.js 24 or later.
• An installed Microsoft Edge, Google Chrome, or Chromium. MarkdStage never downloads a browser.

Install

npx @markdstage/markdstage --workspace .
npx @markdstage/markdstage slides.md
npm install --global @markdstage/markdstage

For offline installation, download the versioned .tgz asset from the GitHub Release and install it locally:

npm install --global .\markdstage-markdstage-<version>.tgz

Commands

markdstage --workspace .
markdstage slides.md
markdstage present slides.md
markdstage preview slides.md --watch
markdstage validate slides.md --json
markdstage inspect slides.md --json
markdstage capture slides.md --pages 2,4
markdstage export slides.md --output slides.pdf
markdstage export slides.md --output slides.pptx
markdstage export slides.md --output slides.pptx --mermaid-image-fallback
markdstage guide overview
markdstage guide slide-format
markdstage guide architecture-dsl
markdstage guide adaptive-cards
markdstage skill install --target codex
markdstage skill install --target claude

markdstage --workspace . opens an empty Canvas-equivalent UI for the explicitly chosen workspace. Choose Open Markdown to load a deck. markdstage slides.md opens the same UI in slide view with automatic refresh enabled.

| Command | Description | | --- | --- | | present | Opens the full MarkdStage UI in presenter view. Open Markdown, automatic refresh, editing, export, and audience controls remain available. --watch starts in live mode, and --no-open serves the UI without launching a browser. | | preview | Opens the same full UI in slide view. It is a compatibility/convenience entry point; --watch starts in live mode, and --no-open serves the UI without launching a browser. | | validate | Checks deck structure, Architecture DSL, resolved static Adaptive Card JSON, themes, and theme paths. Card image bytes/availability and SDK rendering require browser inspection. | | inspect | Reports the same compact 1280x720 diagnostics as Canvas inspect_layout, with Architecture routing and Adaptive Card content diagnostics separate from clipping. --slide <n> limits it to one page, --all includes slides that fit, and --fail-on-issues exits with code 5 for clipping or card content diagnostics. | | capture | Writes 1280x720 PNG files. Without --pages only the slides reported as clipped are captured. | | export | Produces the same 16:9 PDF or hybrid editable PowerPoint as the canvas Extension. PowerPoint output includes speaker-note Markdown as readable plain text notes. The --output extension selects the format; PDF remains the default. Use --mermaid-image-fallback with an explicit .pptx output to place each Mermaid diagram as one image instead of editable PowerPoint shapes, equivalent to choosing Images in the UI export dialog. | | guide | Prints the canonical markdstage_guide topics. | | skill | Installs or checks the portable Agent Skills for Codex (.agents/skills/markdstage/), Claude Code (.claude/skills/markdstage/), and GitHub Copilot (.github/skills/markdstage/). Locally modified files are never overwritten without --force. | | help | Shows the overview, or the help for one command. markdstage help <command> prints the same text as markdstage <command> --help. |

Application options: --workspace <dir>, --theme <name>, --theme-file <path>, --no-open, and --json. Use --help and --version for global information.

A bare invocation uses the caller's current directory as the workspace. Without --workspace, a file selects its nearest ancestor containing a .git entry, or its containing directory if there is none; Git need not be installed. Relative command-line arguments are first made absolute against the caller's directory. Files outside an explicit workspace are rejected. skill install and skill check also use the current directory when neither --root nor --workspace is supplied.

Archify imports

An archify fence can reference an Archify SVG export such as assets/checkout-architecture.svg. The shared renderer preserves its geometry, applies the deck theme, and exports supported shapes, connectors, and text as editable PowerPoint objects. Run markdstage guide overview to discover this workflow and markdstage guide slide-format for the fence example, asset rules, and limitations. Re-export in Archify and refresh to update the diagram; Architecture editing applies only to architecture fences.

Adaptive Cards

For static Adaptive Cards, use an adaptive-card fence with resolved schema-1.5 JSON and read markdstage guide adaptive-cards. Unsupported cards show errors; blocked/failed images use placeholders without removing the rest of the card. PowerPoint exports the supported static subset as editable text, shapes, images and tables, using bounded PNGs for unsupported children. Inputs/actions/media have explicit non-interactive treatment. JSON and plain reports distinguish native, approximated and rasterized content with authored source locations.

Architecture editing

Run markdstage slides.md for the live authoring workflow. The browser starts in the fixed 16:9 output preview and remains in viewing mode. Ensure Output preview is enabled when checking fixed output; toggling it off shows the responsive layout. More controls > Shape editing opens the detailed designer directly for the source-backed deck. Move elements or change their properties, then select Save to atomically update the matching architecture fence. The draft is not saved merely by moving a shape.

The server rejects a save if the Markdown changed outside the editor. Successful saves reload the watched deck without changing the current slide. Automatic refresh can be toggled without disabling Architecture editing. Presenter, capture, inspect, and export views contain no editing UI.

markdstage help
markdstage help capture
markdstage capture --help

Exit codes

| Code | Meaning | | --- | --- | | 0 | success | | 1 | usage error | | 2 | deck or input error | | 3 | environment error (no Chromium-based browser) | | 4 | rendering or output failure | | 5 | layout or validation issues were found |

Security

• Presentation servers bind to loopback only and serve every route below an unguessable per-process URL token.
• Requests must carry a loopback Host header, and mutating routes require a same-origin Origin header. Mutable state is served with no-store.
• Deck files, assets, themes, and generated output stay inside the resolved workspace (canonical paths, symlink checks, and size limits included).

Development

The package mirrors the canonical runtime from .github/extensions/markdstage/ into shared/ before packing and testing:

npm run sync    # refresh shared/
npm test        # node --test

Agent Skills are generated from src/skills.mjs and the canonical guide topics when markdstage skill install runs; generated Skill trees are not checked into this development repository.

License

MIT