Install MarkApiDown: macOS, Linux, and Windows Guide

MarkApiDown ships as a single static Rust binary with no runtime dependencies — no Node.js, no Python, no JVM. Pick the install method that matches your environment, verify the binary is on your PATH, and you are ready to run specs within a minute of starting.

Requirements

Each install method has a different prerequisite. If you are unsure which to choose, use the Shell installer on macOS or Linux or the Windows MSI on Windows — neither requires an existing language toolchain.

Install method	Requirement
Shell installer	macOS or Linux, `curl`, `sh`
Cargo	Rust 1.75 or later (`rustup update stable`)
Homebrew	macOS or Linux with Homebrew installed
npm	Node.js 18 or later
Docker	Docker Engine (any recent version)
Windows MSI	Windows 10 or Windows Server 2019 or later

Install methods

The shell installer is the recommended method for macOS and Linux users. It fetches the latest prebuilt binary for your platform and places it in ~/.local/bin — no compiler or package manager required.

curl -fsSL https://markapidown.net/install.sh | sh

If ~/.local/bin is not already on your PATH, the installer detects this and prints the exact line to add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.profile). Follow that prompt, then open a new terminal tab.

The installer script is open-source and auditable at github.com/mark-api-down/mad. Review it before piping to sh if that is your policy.

Install directly from crates.io. This compiles MarkApiDown from source and places the mad binary in ~/.cargo/bin.

cargo install mark-api-down

Cargo builds take a few minutes on the first install. Subsequent installs reuse the build cache. If your Rust toolchain is older than 1.75, update it first:

rustup update stable

Install via the official MarkApiDown tap. This works on macOS and on Linux with Homebrew.

brew install mark-api-down/tap/mad

The formula includes the tap URL, so no separate brew tap step is needed. Homebrew manages the binary and handles upgrades via brew upgrade mad.

Install via npm for projects that already use a Node.js toolchain. The npm package is a thin wrapper that downloads a prebuilt binary for your platform — no Rust compiler required.

npm install -g mark-api-down

To pin the version per project instead of installing globally, add it as a devDependency and invoke it with npx:

npm install --save-dev mark-api-down
npx mad validate api-docs/

Pinning as a devDependency ensures that every contributor and your CI pipeline use the same mad version without a global install.

Pull the official image from GitHub Container Registry and mount your project directory at /work. Every mad subcommand works through the container.

docker pull ghcr.io/mark-api-down/mad:latest

docker run --rm \
  -v "$(pwd)":/work \
  -w /work \
  ghcr.io/mark-api-down/mad:latest \
  validate api-docs/

Replace validate api-docs/ with any mad subcommand. To execute endpoints against a server running on your host machine, add --network=host or use Docker Compose to place both containers on a shared network.

Pin a specific version tag in CI to prevent unexpected behaviour from the latest tag. For example: ghcr.io/mark-api-down/mad:0.1.0.

Download the .msi installer from the releases page. Run the installer and mad is added to your system PATH automatically — no manual environment variable edits needed.After installation, open a new Command Prompt or PowerShell window and run:

mad version

Windows support is available from MarkApiDown 0.1.0. The MSI targets Windows 10 and Windows Server 2019 or later. Windows Subsystem for Linux (WSL2) users can use the Shell installer instead.

Verify the installation

After installing, confirm that mad is on your PATH and that your environment passes the built-in diagnostics check.

mad version
# 0.1.0

mad doctor

mad version prints the installed binary version. mad doctor runs a broader set of checks:

Confirms api-docs/ exists in the current project (or a parent directory).
Verifies that .env.local is listed in .gitignore so secrets are not committed.
Parses every spec in the project and reports structural errors.
Checks that any installed AI agent skill files match the current binary version.

If you run mad doctor outside of a MarkApiDown project directory, some checks are skipped. Navigate to your project root (or create one with mad init) to see a full diagnostic report.

Shell completions

Generate tab-completion scripts for your shell so you get auto-complete for subcommands, flags, and file paths when you press Tab.

Bash
Zsh
Fish

Append the completion script to your Bash config and reload the shell:

mad completion bash >> ~/.bashrc
source ~/.bashrc

Write the completion function to a directory on your fpath and restart your shell:

mad completion zsh > "${fpath[1]}/_mad"
exec zsh

If you use Oh My Zsh, write the file to ~/.oh-my-zsh/completions/_mad instead.

Write the completion file to Fish’s completions directory:

mad completion fish > ~/.config/fish/completions/mad.fish

Fish picks up new completion files automatically — no reload needed.

Upgrading

Use the same method you used to install. Each command replaces the existing binary in place.

Shell installer
Cargo
Homebrew
npm

Re-run the installer script. It detects the existing binary and overwrites it with the latest release.

curl -fsSL https://markapidown.net/install.sh | sh

Pass --force to reinstall even if the same version is already present:

cargo install mark-api-down --force

brew upgrade mad

Re-run the global install command. npm replaces the existing package:

npm install -g mark-api-down

After any upgrade, run mad doctor --fix to automatically update installed AI agent skill files (Claude Code, Cursor, Copilot) to match the new binary version. Stale skill files can cause agents to call deprecated flags or miss newly available commands.

Documentation Index

​Requirements

​Install methods

​Verify the installation

​Shell completions

​Upgrading

Requirements

Install methods

Verify the installation

Shell completions

Upgrading