CLI

The mdedit.ai CLI (mdedit-cli) lets you manage workspaces, folders, documents, public links, reviews, and existing API keys from your terminal. It’s useful for automation, CI/CD pipelines, and terminal workflows.

The CLI uses document for user-facing commands. The API still uses article in routes, scopes, and response fields such as articleId; they refer to the same resource. The older mdedit article command remains available as a deprecated alias.

When to use it

Automate exports and reporting in CI
Batch-create folders and documents for a workspace
Script against workspaces with JSON output
Apply anchored edits while humans are in the same collaborative document
Publish a Live or Snapshot public document to a shareable mded.it link

Install

npm install -g mdedit-cli
mdedit --version

Authentication

Browser OAuth

Browser OAuth is rolling out gradually and may not be enabled for your account yet. Where available, sign in with authorization code + PKCE:

mdedit auth login
mdedit auth status

The callback is fixed at http://localhost:17643/oauth/callback. Tokens are stored in the operating-system credential manager, not in ~/.mdedit-cli/config.json. Use --no-browser to print the authorization URL for a browser on the same machine; this is not device flow.

Named profiles are supported:

mdedit auth login --profile work
mdedit auth status --profile work
mdedit auth logout --profile work
mdedit auth logout --all

API keys for CI and automation

Generate an API key from your account settings:

Create an API key

Log in

mdedit config login --api-key <YOUR_KEY>

API keys saved with config login are stored in ~/.mdedit-cli/config.json. Prefer MDEDIT_API_KEY in a CI secret manager.

Authentication precedence is: command or MDEDIT_API_KEY override, active OAuth profile, then a legacy stored API key.

Log out

mdedit config logout

config logout removes a stored API key. Use mdedit auth logout to revoke an OAuth profile.

Quickstart

# Check who you are and which workspace is active
mdedit info
 
# List workspaces
mdedit workspace list
 
# Switch to a workspace
mdedit config use-workspace <workspaceId>
 
# List documents
mdedit document list
 
# Export a document as a ZIP file
mdedit document export <documentId> --output ./document.zip

Global flags

These flags can be appended to any command:

Flag	Description
`--api-key <key>`	Override the API key for this invocation
`--api-url <url>`	Override the API base URL (default: `https://apiv2.mdedit.ai`)
`--workspace <id>`	Override the active workspace for this invocation
`--format <plain\|table\|json>`	Control output format (default: `table`, unless overridden by config/env). Use `json` for scripting / raw output.
`--debug`	Print stack traces and request debug info on errors

Commands

`config`

Manage local CLI configuration stored in ~/.mdedit-cli/config.json.

mdedit config show                          # Print current config
mdedit config set <key> <value>             # Set a config key
mdedit config login --api-key <key>         # Save credentials
mdedit config logout                        # Remove saved credentials
mdedit config use-workspace <workspaceId>   # Set the active workspace
mdedit config clear                         # Reset config to defaults

`auth`

Manage browser OAuth profiles stored in the operating-system credential manager.

mdedit auth login [--profile <name>] [--no-browser]
mdedit auth status [--profile <name>]
mdedit auth logout [--profile <name>]
mdedit auth logout --all

`api-key` / `apikey`

List or revoke existing API keys for your account. Create new keys in Settings → Integrations → API Keys in the web app.

mdedit apikey list               # List all API keys
mdedit apikey revoke <keyId>     # Permanently revoke an API key

`workspace`

mdedit workspace list                         # List all workspaces
mdedit workspace list --full                  # Full/raw output (human formats)
mdedit workspace get <workspaceId>            # Get details for a workspace
mdedit workspace get <workspaceId> --full     # Full/raw output (human formats)
mdedit workspace create                       # Create a new workspace (interactive)
mdedit workspace update <workspaceId>         # Update workspace metadata
mdedit workspace delete <workspaceId>         # Delete a workspace

`folder`

mdedit folder list                   # List folders in the active workspace
mdedit folder list --full            # Full/raw output (human formats)
mdedit folder list --include-deleted # Include deleted folders
mdedit folder get <folderId>         # Get folder details
mdedit folder get <folderId> --full  # Full/raw output (human formats)
mdedit folder create                 # Create a folder (interactive)
mdedit folder update <folderId>      # Update folder metadata
mdedit folder delete <folderId>      # Delete a folder

`document`

Manage documents. Use mdedit document; mdedit article is a deprecated compatibility alias.

mdedit document list                    # List documents in the active workspace
mdedit document list --full             # Full/raw output (human formats)
mdedit document list --folder <folderId>          # List documents in a folder
mdedit document get <documentId>         # Get document details and metadata
mdedit document get <documentId> --content-only      # Print only markdown content (stdout)
mdedit document get <documentId> --include-content   # Include markdown content in the output object
mdedit document get <documentId> --full              # Full/raw output (human formats)
mdedit document create                  # Create a document (interactive)
mdedit document create --file document.md --publish       # Create + Live link
mdedit document create --file document.md --publish --snapshot # Frozen artifact
mdedit document update <documentId>      # Update document metadata
mdedit document edit <documentId> --replace "old" --with "new" # One-shot anchored edit
mdedit document edit <documentId> --ops-file ops.json            # Batch anchored edits
mdedit document watch <documentId>                               # Stream JSONL changes/reviews
mdedit document publish <documentId>                             # New link defaults Live
mdedit document publish <documentId> --snapshot                  # Explicit frozen Snapshot
mdedit document publish <documentId> --live                      # Switch existing link to Live
mdedit document publish-status <documentId> --format json        # Inspect mode and sync state
mdedit document unpublish <documentId> --yes                     # Disable public link
mdedit document delete <documentId>      # Delete a document
mdedit document export <documentId>      # Export a document as a ZIP file

`review` and `suggest`

Read and update review feedback without directly rewriting the document. Quote anchors keep comments and suggestions attached to the intended text.

mdedit review list <documentId> [--status <status>]
mdedit review add <documentId> --quote "quoted text" --body "Comment"
mdedit suggest <documentId> --quote "old text" --replace "new text" [--note "Why"]
mdedit review reply <documentId> --thread <reviewId> --body "Reply"
mdedit review resolve <documentId> --thread <reviewId>
mdedit review reopen <documentId> --thread <reviewId>
mdedit review accept <documentId> --thread <reviewId>
mdedit review reject <documentId> --thread <reviewId>
mdedit review delete <documentId> --thread <reviewId> [--reply <replyId>]

Add --occurrence, --before, or --after when quoted text repeats. Add --target <targetId> to work with a Markdown target other than content.md.

Utilities

mdedit health    # Check API health / connectivity
mdedit info      # Print CLI + API connectivity summary

CI/CD usage

Use --format json to get machine-readable output suitable for scripts and pipelines:

# List documents as JSON and pipe into jq
mdedit document list --format json | jq '.[].articleId'
 
# Export a document as a ZIP
mdedit document export <documentId> --output ./document.zip

document edit joins the live collaboration session when available and uses a revision-checked request otherwise. Its stable edit exit codes are 2 for a missing anchor, 3 for an ambiguous anchor, and 4 for a reported conflict. On code 4, re-read the document before continuing because the edit may already have landed.

document watch keeps the same agent session open and writes one JSON event per line. It starts with session.ready, then emits document changes and review events until you press Ctrl+C. Collaborative documents stream live updates; other documents use periodic requests. Use --poll-interval <milliseconds> to tune that interval.

Public-link commands require publishing:write, except publish-status, which needs publishing:read. CLI publishing does not prompt: the presence of --publish or the document publish command is the explicit public-visibility action.

A new public link defaults to Live. Later durable edits update the same URL through the backend synchronization path. Pass --snapshot when the public artifact must stay frozen until the next document publish command. Publishing an existing link without --live or --snapshot preserves its stored mode; either flag switches modes without changing the URL.

JSON publish output includes shortUrl, mode, sourceArticleRevision, sourceContentRevision, sourcePackageRevision, sourceContentHash, sourceVersionId, lastSuccessfulSyncAt, and syncStatus. publish-status also returns syncError for a failed Live update. The stable URL continues serving the last good content, so treat syncStatus: "failed" as stale rather than unpublished.

When document create --publish creates the private document successfully but the publish request fails, the document is kept and the command reports that outcome. For file-based creation without --title, the first Markdown H1 is used, then the filename as a fallback.

Upgrade existing public links

Links created before Live mode remain Snapshots. Inspect the stored mode, then opt one into automatic updates explicitly:

mdedit document publish-status <documentId> --format json
mdedit document publish <documentId> --live --format json

The mded.it URL, slug, metadata, publication date, and view count stay with the existing publication.

You can supply --api-key and --workspace as environment variables or flags to avoid storing credentials in CI secrets files.

Configuration file

The config file lives at ~/.mdedit-cli/config.json and contains:

{
  "apiKey": "...",
  "apiUrl": "https://apiv2.mdedit.ai",
  "workspaceId": "..."
}

All keys can be overridden at invocation time with the corresponding global flag.

Agent / AI tool integration

The CLI is built to be used by AI agents (Claude Code, Cursor, GitHub Copilot, Codex, etc.) without modification.

Agent tips

Use --format json for machine-readable output. In json mode all human-facing messages are routed to stderr, keeping stdout clean for parsing.
Pass all required flags on the command line to avoid interactive prompts.
Use --yes / -y on destructive commands to skip confirmation.
Pipe markdown content via --file - (stdin) or read it back with --content-only (stdout).

`skill`

The CLI bundles the canonical Save, Find, Revise, Review, and Publish skills 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 five CLI-backed skills in .agents/skills
mdedit skill install
 
# Select transport, target, scope, or individual skills
mdedit skill install --via mcp --target claude
mdedit skill install publish-mdedit-document --target cursor --via mcp
mdedit skill install --scope user
 
# Diagnose updates and legacy monolithic installs; safely remove owned skills
mdedit skill doctor --format json
mdedit skill uninstall save-mdedit-document

Installs are atomic and idempotent. Unowned or edited skills are not overwritten without --force, and uninstall removes only unchanged mdedit-owned artifacts. See Install mdedit skills for native target directories, authentication, updates, and migration.

OpenClaw plugin

An openclaw.json plugin manifest is bundled with the npm package. It describes every CLI tool as a structured entry that OpenClaw-compatible agents can load directly.

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

Install skills API Keys

CLI