mad CLI Reference: All Subcommands, Flags, and Usage

The mad binary is MarkApiDown’s command-line interface — a single executable that covers the full API development lifecycle, from scaffolding a new workspace to executing requests in CI. Every command described here is authoritative: flag names, default values, and behavior are drawn directly from the source code. Use the accordions below to jump to the command you need.

Global flags

Place these flags before the subcommand name. They apply to every mad command.

Flag	Short	Default	Description
`--config <path>`	—	auto-discover	Path to `api-docs/mad.md`. Overrides the automatic workspace discovery.
`--no-color`	—	`false`	Disable ANSI color output. Also respected when the `NO_COLOR` environment variable is set.
`--verbose`	`-v`	`false`	Enable verbose diagnostic output for all subcommands.

Subcommands

mad init

Scaffold a new api-docs/ workspace in the current directory. After creating the directory structure, mad init automatically runs mad import project to discover existing API routes, then prints a reminder to run mad serve.

mad init [--name=<name>] [--dev-url=<url>] [--yes]

--name

string

default:"interactive"

Project name written into mad.md. When omitted and --yes is not set, you are prompted interactively. MarkApiDown attempts to detect the name from package.json, Cargo.toml, pyproject.toml, go.mod, composer.json, or pom.xml before falling back to my-api.

--dev-url

string

default:"interactive"

Base URL written into _shared/env.md for the dev environment. When omitted without --yes, you are prompted. Defaults to http://localhost:8080 when --yes is set and no value is provided.

--yes

boolean

default:"false"

Accept all defaults without interactive prompts. Useful in CI or automated setup scripts.

mad init never overwrites existing files. If a file already exists it exits with an error naming the conflicting path. It also appends .env.local to .gitignore automatically if that entry is not already present.

Examples

# Interactive — prompts for name and base URL
mad init

# Fully specified — no prompts
mad init --name=payments-api --dev-url=http://localhost:3000

# Headless / CI — accept all defaults
mad init --yes

mad exec <file>

Execute a single endpoint spec file. mad exec resolves all variables, builds the HTTP request, sends it, and compares the actual response against the ## Expected response block in your spec. Results are printed in the chosen output format.

mad exec <file> [--env=<env>] [--output=<format>] [--var key=value]... [--dry-run] [--timeout=<ms>]

file

path

required

Path to an endpoint markdown file (e.g., api-docs/apis/users/get-user.md).

--env

string

default:"dev"

Environment name. Must match a heading in _shared/env.md. Variables for the chosen environment are loaded automatically.

--output

enum

default:"console"

Output format. One of console, json, junit, or markdown. See Output Formats for details.

--var

string

Inject a variable as key=value. Repeatable. CLI variables take the highest precedence and override environment files, .env.local, and MAD_* OS variables.

--dry-run

boolean

default:"false"

Print the fully resolved request without sending it. No network connection is made. Useful for debugging variable substitution.

--timeout

integer

Override the request timeout in milliseconds. Takes precedence over endpoint-level and project-level timeout settings.

Examples

# Basic execution against the dev environment
mad exec api-docs/apis/users/get-user.md

# Override environment and inject a variable at runtime
mad exec api-docs/apis/users/get-user.md --env=staging --var userId=42

# JUnit XML output for CI test reporters
mad exec api-docs/apis/users/get-user.md --output=junit > results.xml

# Dry-run — inspect the resolved request without sending
mad exec api-docs/apis/users/create-user.md --dry-run --var [email protected]

# Override the timeout for a slow endpoint
mad exec api-docs/apis/orders/create-order.md --timeout=15000

Exit codes: 0 response matches, 1 assertion fails, 2 invalid spec, 3 engine error, 4 network error, 5 secret detected.

mad flow <pipeline>

Execute a pipeline file. Steps run sequentially by default. Override the pipeline’s own parallel setting with --parallel or --no-parallel.

mad flow <pipeline> [--env=<env>] [--output=<format>] [--var key=value]... [--parallel] [--no-parallel] [--timeout=<ms>]

pipeline

path

required

Path to a pipeline markdown file (e.g., api-docs/flows/user-onboarding.md).

--env

string

default:"dev"

Environment name used for all steps in the pipeline.

--output

enum

default:"console"

Output format: console, json, junit, or markdown.

--var

string

Inject a variable as key=value. Repeatable. Applies to every step.

--parallel

boolean

default:"false"

Force parallel execution, overriding the parallel field in the pipeline file.

--no-parallel

boolean

default:"false"

Force sequential execution, overriding the parallel field in the pipeline file.

--timeout

integer

Timeout override in milliseconds applied to every step.

--parallel and --no-parallel are mutually exclusive. Pass at most one. Steps that consume a captured value from a prior step always wait for that step to finish regardless of parallel mode.

Examples

# Run a pipeline against the staging environment
mad flow api-docs/flows/user-onboarding.md --env=staging

# Force sequential execution for easier debugging
mad flow api-docs/flows/user-onboarding.md --no-parallel

# Emit JUnit XML for CI pipeline reports
mad flow api-docs/flows/checkout.md --output=junit > flow-results.xml

# Pass a variable into every step
mad flow api-docs/flows/auth.md --var clientId=abc123

Exit codes: 0 all steps pass, 1 any step fails, 2 pipeline spec invalid, 3 engine error, 4 network error.

mad request <METHOD> <URL>

Send a one-off HTTP request without a spec file. Think of it as a curl replacement that understands MarkApiDown variables. By default it prints a compact status + body. Add --verbose for the full request/response diff. Use --save to persist the result as a spec file.

mad request <METHOD> <URL> [-H "Name: Value"]... [-d <body>] [--env=<env>] [--var key=value]... [--dry-run] [--timeout=<ms>] [--save [path]] [--verbose] [--output=<format>]

METHOD

string

required

HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS.

URL

string

required

Target URL. May contain {{variable}} references resolved from the active environment.

-H / --header

string

Add a request header as Name: Value. Repeatable.

-d / --data

string

Request body as a raw string, or @file to read the body from a file path.

--env

string

default:"dev"

Environment for variable resolution.

--var

string

Inject a variable as key=value. Repeatable.

--dry-run

boolean

default:"false"

Print the resolved request without sending it.

--timeout

integer

Timeout override in milliseconds.

--save

path

Save the request and response as a spec file. Provide a path to save there, or omit the path to auto-save into the current collection at api-docs/apis/scratch/.

--verbose

boolean

default:"false"

Show the full request/response diff instead of the compact status + body view.

--output

enum

default:"console"

Output format: console, json, junit, or markdown.

Examples

# Simple GET request
mad request GET https://api.example.com/users

# POST with JSON body
mad request POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace"}'

# Use a variable from the active environment
mad request GET https://api.example.com/users/{{userId}} --var userId=42

# Read body from a file
mad request POST https://api.example.com/events -d @payload.json

# Dry-run — print the resolved request, don't send
mad request GET https://api.example.com/users --dry-run

# Save the result as a named spec file
mad request GET https://api.example.com/users --save api-docs/apis/users/get-users.md

# Auto-save into the current collection
mad request GET https://api.example.com/users --save

# Full verbose diff
mad request GET https://api.example.com/users --verbose

mad validate <path>

Validate one endpoint file, one pipeline file, or every markdown file under a directory. Each file is classified by its location and name:

Files named env.md → validated as environment config.
Files under flows/ or pipelines/ → validated as pipeline files.
mad.md and README.md → frontmatter check only.
All other .md files → validated as endpoint specs.

Every error message includes the file path, line number when available, and a suggested fix.

mad validate <path>

path

required

File or directory to validate. Pass api-docs/ to validate the entire workspace.

Examples

# Validate the entire workspace
mad validate api-docs/

# Validate a single endpoint file
mad validate api-docs/apis/users/get-user.md

# Validate a pipeline
mad validate api-docs/flows/checkout.md

Exit codes: 0 all valid, 2 any spec is invalid, 5 secret detected.

mad serve

Start the local web preview server. The preview reads the same markdown files as the CLI — no build step is required. The server watches for file changes and refreshes connected browsers automatically.

mad serve [<path>] [--port=8080] [--host=127.0.0.1] [--env=<env>] [--mock]

path

Root directory of the MarkApiDown project. Defaults to the current directory.

--port

integer

default:"8080"

TCP port to listen on.

--host

string

default:"127.0.0.1"

Host address to bind to. Set to 0.0.0.0 to expose the preview on your local network (a warning is printed when you do this).

--env

string

default:"dev"

Environment used when executing endpoints from the web preview UI.

--mock

boolean

default:"false"

Start in mock mode. The Send button in the preview returns the recorded ## Expected response block instead of making a real HTTP request.

Examples

# Start on the default port
mad serve

# Serve on a custom port against the staging environment
mad serve --port=9000 --env=staging

# Serve in mock mode (no real requests)
mad serve --mock

# Serve a project in another directory
mad serve /path/to/other-project

Exit codes: 0 on clean shutdown (Ctrl-C), 3 on startup error.

mad mock

Start a standalone mock HTTP server. The server reads ## Expected response blocks from your endpoint files and serves those bodies at the corresponding HTTP methods and paths. Use it for frontend development when the live backend is unavailable, or for latency simulation.

mad mock [<dir>] [--port=4001] [--latency=<ms>]

dir

path

default:"api-docs"

Root directory containing the spec files. Defaults to api-docs.

--port

integer

default:"4001"

TCP port to listen on.

--latency

integer

Artificial response delay in milliseconds. Omit for zero-latency responses. Useful for testing loading states and timeout handling.

Examples

# Start mock server on the default port
mad mock

# Simulate 200 ms of network latency
mad mock --latency=200

# Use a custom port and a custom spec directory
mad mock ./my-api-docs --port=5000

# Simulate slow responses for timeout testing
mad mock --latency=5000 --port=4001

mad import

Convert specs from another API tool into MarkApiDown endpoint markdown files. All subcommands write files under api-docs/ and run mad index automatically. Complex logic — pre-request scripts, dynamic variables, JavaScript assertions — is imported as agent-task blocks for manual review.After any import, run mad validate api-docs/ and move any embedded secrets to .env.local.

mad import postman

Import a Postman Collection v2.1 JSON export.

mad import postman <file>

mad import postman my-collection.json

mad import insomnia

Import an Insomnia v4 JSON export.

mad import insomnia <file>

mad import insomnia insomnia_export.json

mad import openapi

Import an OpenAPI 3.x spec in YAML or JSON format.

mad import openapi <file>

mad import openapi openapi.yaml
mad import openapi openapi.json

mad import curl

Import a raw curl command as a MarkApiDown endpoint file. Reads from a file if provided, otherwise reads from stdin — ideal for pasting directly from browser DevTools.

mad import curl [<file>]

# From clipboard (macOS)
pbpaste | mad import curl

# From a saved file
mad import curl curl-command.txt

mad import project

Scan project source code for route definitions and import them. Uses a priority chain:

--url — fetch an OpenAPI spec from an explicit URL.
Static OpenAPI/Swagger file found in the project (openapi.yaml, swagger.json, etc.).
Running dev server probed on localhost (--port or common framework defaults).
Regex-based source-code scan as a fallback (method + path only).

mad import project [<path>] [--port=<port>] [--url=<url>]

path

Root directory to scan. Defaults to the current directory.

--port

integer

Port of a running development server to probe for an OpenAPI spec. If omitted, common framework defaults (8000, 8080, 3000, …) are tried automatically.

--url

string

Explicit OpenAPI/Swagger spec URL. When set, all other discovery strategies are skipped.

# Auto-detect everything
mad import project

# Scan a specific directory and probe port 8000
mad import project ./src --port 8000

# Fetch spec from an explicit URL
mad import project --url http://localhost:8000/openapi.json

Exit codes (all import subcommands): 0 on success, 2 if the input is not a valid spec, 3 on filesystem error.

mad install

Install skills, slash commands, or the MCP server for AI agent integration. Skills and slash commands are embedded in the binary — no network access is required.

mad install skills

Install AI agent skill files into detected agent config directories.

mad install skills [<name>] [--agent=<agent>]

name

string

Install only one specific skill by name (e.g., mad-sync, mad-debug). Omit to install all available skills.

--agent

string

Target a specific agent by name (e.g., claude-code, cursor, copilot). Omit to install for all detected agents.

# Install all skills for all detected agents
mad install skills

# Install a specific skill
mad install skills mad-sync

# Install for a specific agent only
mad install skills --agent=cursor

mad install slashcmd

Install slash commands for Claude Code and Codex CLI.

mad install slashcmd [<name>] [--agent=<agent>]

name

string

Install only one command by name (e.g., mad-scan, mad-debug). Omit to install all.

--agent

string

Agent name: claude-code or codex-cli. Omit to install for all detected agents.

# Install all slash commands
mad install slashcmd

# Install a specific slash command
mad install slashcmd mad-scan

# Install for Codex CLI only
mad install slashcmd --agent=codex-cli

mad install mcp

mad install mcp

mad install mcp
# ✓ Registered. Verify with: claude mcp list

mad install list

List all detected agents and their current installation status.

mad install list

mad install list
# claude-code: detected
# cursor: not detected
# copilot: not detected

mad doctor

Diagnose your project setup. mad doctor checks whether api-docs/ exists, whether .env.local is in .gitignore, whether all specs are valid, which AI agent directories are present, and whether skills match the current binary version. Use --fix to apply safe automatic repairs.

mad doctor [--fix]

--fix

boolean

default:"false"

Automatically apply safe fixes: adds .env.local to .gitignore if missing and reinstalls any stale skill files.

Examples

# Run diagnostics
mad doctor

# Run diagnostics and fix safe issues
mad doctor --fix

Run mad doctor as your first debugging step whenever mad exec, mad validate, or an AI agent skill behaves unexpectedly.

mad index

Regenerate api-docs/README.md from the current set of markdown files under api-docs/. The generated file contains a linked list of all specs. Do not edit it by hand — it is overwritten on every run.

mad index

mad index runs automatically after mad init and after every mad import subcommand. Run it manually only when you have added or renamed spec files directly.

Example

mad index
# indexed: api-docs/README.md

Exit codes: 0 on success, 3 on filesystem error.

mad mcp

Start a Model Context Protocol (MCP) server using the stdio transport. This exposes MarkApiDown tools to any MCP-compatible AI agent, including Claude Code.

mad mcp

No flags. Register the server with Claude Code using:

claude mcp add mad -- mad mcp

Or use mad install mcp to run that registration command automatically.

mad version

Print the installed version of MarkApiDown and exit.

mad version

Example

mad version
# 1.0.0

Exit codes: 0 always.

mad completion <shell>

Print a shell completion script to stdout. Pipe the output to the appropriate location for your shell.

mad completion <shell>

shell

enum

required

One of: bash, zsh, fish, elvish, or powershell.

Bash
Zsh
Fish
Elvish
PowerShell

mad completion bash >> ~/.bash_completion

mad completion zsh > ~/.zfunc/_mad
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc
autoload -Uz compinit && compinit

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

mad completion elvish >> ~/.config/elvish/rc.elv

mad completion powershell >> $PROFILE

After installing completions, restart your shell (or run source ~/.bashrc / exec zsh) to activate tab completion for all mad subcommands and flags. Use mad completion <shell> any time you upgrade mad to refresh the completion script.

Output formats

All execution commands (mad exec, mad flow, mad request --verbose) accept --output=<format>.

Format	Flag value	Best for
Console	`console`	Human-readable terminal output with color-coded diffs (default)
JSON	`json`	Scripting, programmatic result parsing, custom dashboards
JUnit XML	`junit`	CI systems: GitHub Actions, Jenkins, CircleCI test reporters
Markdown	`markdown`	Saving reports to files or posting summaries to pull request comments

See Output Formats for sample payloads and CI upload examples.

Documentation Index

​Global flags

​Subcommands

​mad import postman

​mad import insomnia

​mad import openapi

​mad import curl

​mad import project

​mad install skills

​mad install slashcmd

​mad install mcp

​mad install list

​Output formats

Global flags

Subcommands

mad import postman

mad import insomnia

mad import openapi

mad import curl

mad import project

mad install skills

mad install slashcmd

mad install mcp

mad install list

Output formats