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.

curl-md