curl-md

curl.md

Use curl.md to turn URLs into agent-friendly markdown with less noise and fewer tokens.

When to Use

Use curl.md when:

• The user shares a URL or asks what a page says
• You just need to quickly fetch one page without setting up a deeper integration
• You need docs, changelogs, articles, reference pages, or API docs as markdown before answering
• You want to narrow a long page to a specific question or task
• You need current curl.md usage for the CLI, hosted HTTP endpoint, skills, or MCP

Preferred Entry Points

Prefer these in order:

• The local curl.md CLI or md alias when available
• The hosted HTTP endpoint at https://curl.md/<url>
• For curl.md's own docs, the canonical .md docs endpoints or Accept: text/markdown

For normal page fetches, prefer the stable top-level fetch interface (curl.md/<url> or client.fetch(...)). Avoid lower-level experimental /api routes unless the task is specifically about auth, orgs, tokens, invites, or request history.

Stable Request Vocabulary

Prefer these names in new usage:

• objective — narrow output to a specific question or task
• keywords — pre-filter the page before extraction; comma-separated in HTTP/CLI strings
• mode — smart or rush; only matters with objective
• fresh — bypass cache and force a fresh fetch
• token — API key auth in the CLI; raw HTTP should prefer Authorization: Bearer <token>

smart is the default and best for most docs lookups. Use rush when speed matters more than recall.

HTTP aliases still work (q/o, k, m, f), but prefer the full names above in new examples and instructions.

CLI

Prefer the CLI when it is installed locally. It handles auth, organization context, higher-level commands, and agent-friendly workflows.

# Basic fetch
curl.md example.com
md example.com

# Narrow to a specific task
curl.md docs.github.com/en/webhooks/webhook-events-and-payloads \
  --objective "pull request webhook event payload and actions" \
  --keywords pull_request

# Faster, less thorough pass
curl.md developers.cloudflare.com/d1/get-started \
  --objective "how to query D1 from a worker" \
  --keywords D1,bindings \
  --mode rush

# Force a fresh fetch
curl.md example.com --fresh

# Use API key auth
curl.md example.com --token "$CURLMD_API_KEY"

Notes:

• No protocol required for the target URL. curl.md normalizes to HTTPS unless the URL already specifies http:// or https://.
• curl.md fetch <url> is equivalent to the root curl.md <url> command.
• If the user asks for latest or recent content, add --fresh.

Hosted HTTP Endpoint

Use the hosted HTTP endpoint when the CLI is unavailable or when you just need to quickly fetch one page.

Examples

# Default response is markdown
curl "https://curl.md/example.com"

# Narrow with stable query names
curl "https://curl.md/developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch?objective=streaming+response+body&keywords=ReadableStream,getReader"

# Force a fresh fetch
curl "https://curl.md/example.com?fresh"

# Request JSON instead of markdown
curl "https://curl.md/example.com" -H 'Accept: application/json'

# Authenticated request
curl "https://curl.md/example.com" -H "Authorization: Bearer $CURLMD_API_KEY"

Successful fetches return markdown by default. JSON responses have the shape:

{
  "content": "# Example\n..."
}

Agent Setup

When the user asks to install or wire curl.md into an agent/editor, use the current setup commands:

# Install hosted skills
npx skills add https://curl.md --yes

# Sync CLI-generated skills into supported agents
curl.md skills add
curl.md skills add --no-global

# Run as MCP stdio server
curl.md --mcp

# Register the MCP server with an agent
curl.md mcp add
curl.md mcp add --agent claude-code

Prefer first-party plugins over raw CLI or MCP when the target agent has an official curl.md integration.

Best Practices

• Use objective when only part of a long page matters.
• Add keywords when you already know the terms that matter and want to shrink the search space first.
• Use fresh for changelogs, status pages, release notes, or any request where freshness matters.
• Use auth when the user needs higher limits, paid usage, or account/org-scoped behavior.
• For curl.md docs, prefer .md docs pages or llms.txt over HTML fetches.

Limitations

• Paywalled or authenticated content still requires valid access.
• Some highly dynamic pages may still be incomplete or noisy.
• Errors are returned as JSON with stable string code and human-readable message fields.