CLI

Interactive terminal access to the same server-side conversion engine used by the API.

Install#

npx @mdcraft/cli

The default command opens the guided flow. Choose login, approve the browser code, then choose a file or folder and the output format.

Guided Mode#

npx @mdcraft/cli
mdcraft interactive
mdcraft convert --interactive

Use this for day-to-day terminal work. It prompts for:

• file or folder path
• output format
• output location
• final confirmation before conversion

Scripted Mode#

Use flags for repeatable jobs, CI, and agent workflows.

mdcraft login
mdcraft convert ./report.pdf --to markdown
mdcraft convert ./brief.md --to pdf
mdcraft convert ./brief.md --to docx
mdcraft convert ./brief.md --to html

Single-file conversions write beside the input file. Use --out for a path and --stdout for text outputs.

CI can skip browser login with:

export MDCRAFT_API_KEY=mdc_beta_...

Batch#

mdcraft convert ./inbox --recursive --out-dir ./markdown --to markdown

Folder conversion requires --out-dir.

CI#

MDCRAFT_API_KEY=mdc_beta_... mdcraft convert ./report.pdf --to markdown --json

--json returns conversion IDs and output paths.

MCP stdio fallback#

Hosted MCP is the primary agent path. For clients that only support local stdio servers:

mdcraft login
mdcraft mcp

MCP client config:

{
  "mcpServers": {
    "mdcraft": {
      "command": "mdcraft",
      "args": ["mcp"]
    }
  }
}

Use mdcraft mcp --help for the adapter options.

Limits#

CLI requests use API beta limits:

• project conversions: 30 requests per 10 minutes
• key conversions: 20 requests per 10 minutes
• project concurrency: 3 in-flight conversions
• key concurrency: 2 in-flight conversions

The CLI prints retry timing when limits are hit.

Troubleshooting#

Run:

mdcraft doctor
mdcraft status
mdcraft usage

Use MDCRAFT_API_BASE_URL to target a local or staging API.