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

Interactive browser OAuth is also available in explicitly enabled cohorts. It uses authorization code + PKCE, a fixed loopback callback, and the operating system credential manager:

mdedit auth login
mdedit auth status
mdedit auth logout

Headless and CI environments should continue to use scoped API keys. Browser OAuth remains release-gated and --no-browser is not a device flow.

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.

Public links

Use a key with publishing:write to create a public mded.it link. New links are Live by default: later durable document edits update the same URL automatically. Use --snapshot for a frozen artifact that changes only when you publish again.

mdedit article publish <articleId>
mdedit article publish <articleId> --snapshot
mdedit article publish <articleId> --slug my-document
mdedit article publish-status <articleId> --format json
mdedit article unpublish <articleId> --yes

Create a document from Markdown and publish a Live link in one command, without a confirmation flag:

mdedit article create \
  --file document.md \
  --publish

Without --title, the CLI uses the first Markdown H1 or the filename. The JSON result includes the stable URL, mode, source revision/version fields, and syncStatus under publication. publish-status --format json returns the same synchronization metadata and syncError when a Live update fails.

Publishing an existing link without --live or --snapshot preserves its stored mode. Use --live or --snapshot to switch deliberately; the URL does not change. Links created before Live mode remain Snapshots until explicitly switched:

mdedit article publish <articleId> --live

If article creation succeeds but publishing fails, the article is kept private and the command reports its article ID.

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)

Agent skills

The canonical Save, Find, Revise, and Publish skills are bundled in focused CLI-backed and MCP-backed variants.

# List and inspect skills
mdedit skill list
mdedit skill show save-mdedit-document --via cli
mdedit skill show revise-mdedit-document --via mcp

# Install all four CLI-backed skills for the current project
mdedit skill install

# Select a host-native directory or MCP-backed variant
mdedit skill install --target claude --via mcp
mdedit skill install --target cursor
mdedit skill install publish-mdedit-document --target gemini --via mcp

# User scope, diagnostics, and safe removal
mdedit skill install --scope user
mdedit skill doctor
mdedit skill uninstall save-mdedit-document

Project scope is the default. Installations carry mdedit ownership and content checksums: edited or unowned skills are not overwritten without --force, and uninstall removes only unchanged mdedit-owned artifacts. doctor reports legacy monolithic CLAUDE.md, Cursor rule, and Copilot instruction installs without modifying them.

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'))"