mdedit-cli

mdedit-cli

Official command-line interface for mdedit.ai.

Links:

• CLI docs
• mdedit.ai homepage

Install

npm install -g mdedit-cli

Get an API key

All APIs require authentication. Create an API key here:

• API key docs

Configure

mdedit config login --api-key <YOUR_KEY>

Config is stored at ~/.mdedit-cli/config.json.

Environment variables (optional)

• MDEDIT_API_URL (default: https://apiv2.mdedit.ai)
• MDEDIT_API_KEY
• MDEDIT_WORKSPACE_ID
• MDEDIT_CONFIG_DIR (override config directory)

Usage

mdedit --help
mdedit info
mdedit health

One-shot article edits

Apply a unique text replacement through the same article session used by live collaborators:

mdedit article edit <articleId> --replace "old text" --with "new text"
mdedit article edit <articleId> --ops-file ops.json --format json

An ops file is a non-empty JSON array of replace, insert, or delete operations with quote, heading, section, or range anchors. The command exits 2 when an anchor is missing, 3 when an anchor is ambiguous, and 4 when an edit conflict is reported. In JSON mode, the result or typed error is the only value written to stdout.

Review commands

Review agents can comment and suggest with articles:read,reviews:write; accepting a suggestion also requires articles:write because it changes article text.

mdedit review list <articleId> --status open --format json
mdedit review add <articleId> --quote "claim" --body "Needs a source."
mdedit review reply <articleId> --thread <reviewId> --body "Fixed."
mdedit review resolve <articleId> --thread <reviewId>
mdedit suggest <articleId> --quote "teh" --replace "the" --note "Typo"

One-shot review commands use the REST review resources directly, so listing or commenting does not open a metered collaboration WebSocket. Mutations always use the server-authoritative review-commands API.

Watch an article

Keep an article session open and stream newline-delimited JSON for agent loops:

mdedit article watch <articleId>
mdedit article watch <articleId> --workspace <workspaceId> --agent claude-code
mdedit article watch <articleId> --poll-interval 5000

Each stdout line is one complete JSON event. The stream starts with session.ready, then reports article changes, review history events, and review snapshots. Ctrl+C closes the live session cleanly. Non-collaborative articles use REST polling.

Agent / AI tool integration

The CLI is designed to be used by AI agents without modification.

Agent tips

• Use --format json for machine-readable output (human messages go to stderr)
• Pass all required flags on the command line to avoid interactive prompts
• Use --yes on destructive commands to skip confirmation
• Pipe content via --file - (stdin) or --content-only (stdout)

Skill file

A comprehensive agent skill document is included with the CLI. It covers all commands, flags, workflows, and error handling in a format optimised for AI agents (Claude Code, Cursor, GitHub Copilot, etc.).

# View the skill
mdedit skill show

# Install the skill into all detected agent config files
mdedit skill install

# Install into a specific tool only
mdedit skill install --target claude    # → CLAUDE.md
mdedit skill install --target cursor    # → .cursor/rules/mdedit.mdc
mdedit skill install --target codex     # → .github/copilot-instructions.md

# Install to home-directory (global) targets
mdedit skill install --global

OpenClaw plugin

An openclaw.json plugin manifest is included in the package. It defines every CLI tool as a structured, machine-readable entry that OpenClaw-compatible agents can load directly.

# Find the plugin manifest
node -e "console.log(require.resolve('mdedit-cli/openclaw.json'))"