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 and API use article in command names and identifiers. An article is the same resource the app calls a document.

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 release-gated and may be disabled in your environment. When enabled for an interactive cohort, 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 article list
 
# Export a document as a ZIP file
mdedit article export <articleId> --output ./article.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

`article`

Manage documents. The command remains article for API compatibility.

mdedit article list                    # List documents in the active workspace
mdedit article list --full             # Full/raw output (human formats)
mdedit article list --folder <folderId>          # List documents in a folder
mdedit article get <articleId>         # Get document details and metadata
mdedit article get <articleId> --content-only      # Print only markdown content (stdout)
mdedit article get <articleId> --include-content   # Include markdown content in the output object
mdedit article get <articleId> --full              # Full/raw output (human formats)
mdedit article create                  # Create a document (interactive)
mdedit article create --file document.md --publish       # Create + Live link
mdedit article create --file document.md --publish --snapshot # Frozen artifact
mdedit article update <articleId>      # Update document metadata
mdedit article edit <articleId> --replace "old" --with "new" # One-shot anchored edit
mdedit article edit <articleId> --ops-file ops.json            # Batch anchored edits
mdedit article watch <articleId>                               # Stream JSONL changes/reviews
mdedit article publish <articleId>                             # New link defaults Live
mdedit article publish <articleId> --snapshot                  # Explicit frozen Snapshot
mdedit article publish <articleId> --live                      # Switch existing link to Live
mdedit article publish-status <articleId> --format json        # Inspect mode and sync state
mdedit article unpublish <articleId> --yes                     # Disable public link
mdedit article delete <articleId>      # Delete a document
mdedit article export <articleId>      # 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 <articleId> [--status <status>]
mdedit review add <articleId> --quote "quoted text" --body "Comment"
mdedit suggest <articleId> --quote "old text" --replace "new text" [--note "Why"]
mdedit review reply <articleId> --thread <reviewId> --body "Reply"
mdedit review resolve <articleId> --thread <reviewId>
mdedit review reopen <articleId> --thread <reviewId>
mdedit review accept <articleId> --thread <reviewId>
mdedit review reject <articleId> --thread <reviewId>
mdedit review delete <articleId> --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 article list --format json | jq '.[].articleId'
 
# Export a document as a ZIP
mdedit article export <articleId> --output ./article.zip

article 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.

article 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 article 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 article 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 article create --publish creates the private article successfully but the publish request fails, the article 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 article publish-status <articleId> --format json
mdedit article publish <articleId> --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 ships with a built-in skill document — a compact, agent-optimised reference that covers every command, flag, and common workflow.

# Print the skill to stdout (pipe to your agent's context)
mdedit skill show
 
# Install into all detected agent config files (project-local)
mdedit skill install
 
# Install for 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 / Codex → .github/copilot-instructions.md
 
# Install to home-directory (global) targets instead of project directory
mdedit skill install --global

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

Agent webhooks API Keys

CLI