executable.md

Getting started

executable.md runs markdown documents as executable workflows using the xmd command. This page gets you from install to your first run.

xmd runRuns a document against the current environment. Operations complete correctly, but nothing promises that another execution can restore or reattach to that environment.
xmd workflowstart · resumeRuns a document in a retained Workspace, so an interrupted workflow resumes from its journal frontier instead of starting again. Unsupported operations fail explicitly instead of falling back to the host. Available through the Deno entrypoint and the compiled binary.

Install

Install the standalone xmd binary (macOS / Linux):

curl -fsSL https://executable.md/install.sh | sh

Or, for Deno users, run it straight from JSR:

deno run -A jsr:@executablemd/cli run doc.md

Prebuilt binaries for every platform are on the releases page. The binary is self-contained — no Node or Deno needed to run it.

Keeping it up to date

A standalone binary on macOS or Linux replaces itself. This installs the latest published stable release, verifies its checksum, and swaps the binary you just ran:

xmd upgrade

To see what would change without downloading or replacing anything:

xmd upgrade --status

The command prints what it is doing as it goes: the release it selected, the binary it downloaded, what it verified, and the replacement itself. Add --journal <path> to also write a diagnostic JSONL trace to a new file.

Name an exact tag — xmd upgrade v1.2.3 — to install one specific release. Installing an older version needs --allow-downgrade, and a prerelease tag needs --allow-prerelease.

Every other installation is updated by whatever installed it, and xmd upgrade says so rather than replacing files it does not own: npm installs with npm install -g @executablemd/cli@latest, Bun with bun add -g @executablemd/cli@latest, Deno by naming a newer jsr:@executablemd/cli version, and a Windows binary by running the installer again or downloading the release asset.

From npm

xmd is published to npm as @executablemd/cli:

npm install -g @executablemd/cli

No registry configuration is needed — every @executablemd package resolves from the default npm registry.

Your first document

A document is a component. Frontmatter becomes meta, capitalized JSX tags expand other markdown files, and fenced blocks marked exec run and render their output.

README.md
---
title: My Project
---

# {meta.title}

<Greeting name="world" />

```bash exec
ls ./src
```

Run it:

xmd run README.md

Write a diagnostic journal

Pass --journal to write a JSONL trace of the run to a new file for troubleshooting. The path must not already exist, and the trace is never replayed.

xmd run README.md --journal .xmd/events.jsonl

Useful flags

NextComponents→