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

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)

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