# curl.md Docs Full

> Full markdown export of the canonical curl.md documentation.

Use this file when you want the entire docs set in a single markdown document.

## /docs/index.md

Turn websites into optimized markdown for agents.

### URL to markdown for agents

Turn websites into optimized, low token output to supercharge your context and save tokens. Works with every agent.

Use the sections below to get set up, learn the core workflows, find integration or reference docs - and start curling!

:::card[Getting Started]{href=/docs/getting-started icon=rocket}
Start with the basics, core concepts, and the quickest path to your first successful fetch.
:::

:::card[Installation]{href=/docs/install icon=download}
Install the CLI, configure your environment, and get curl.md working locally.
:::

:::card[Guide]{href=/docs/guide/features icon=book}
Learn the main features, agent workflows, CLI usage, and API patterns.
:::

:::card[Plugins]{href=/docs/guide/plugins icon=package}
Jump into editor and agent integrations for Amp, Claude, Codex, Cursor, OpenCode, and Pi.
:::

:::card[Why curl.md]{href=/docs/why icon=lightbulb}
See why low token markdown outputs make website context more useful for coding agents.
:::

:::card[CLI]{href=/docs/guide/cli icon=terminal}
Use curl.md from the terminal, script fetches, and shape output with objectives and keywords.
:::

:::note[Sign up]
[Sign up for a free account](/login) for higher limits and a better curl.md experience.
:::

## /docs/getting-started.md

Learn the fastest path from first fetch to a full curl.md workflow.

### Getting Started

`curl.md` is a developer tool gives your agents better context and saves you tokens/money by turning URLs into markdown optimized for agents

You can learn more about the rationale behind the project in the [Why curl.md](/docs/why.md) section or read on to try it out.

#### Quick Start

curl.md works well for humans and agents. It’s worth following both quickstarts below to better understand how curl.md works.

##### For Humans

The best way to try out curl.md is to use the [CLI](/docs/guide/cli.md). First, install:

:::codegroup

```sh [curl]
$ curl -fsSL https://curl.md/install.sh | bash
```

```sh [npm]
$ npm i -g curl.md
```

```sh [bun]
$ bun i -g curl.md
```

:::

Then, use the CLI to fetch these docs as markdown:

```bash
$ md curl.md/docs/getting-started
```

You can add an [objective](/docs/guide/features.md#objective-based-narrowing) and/or [keywords](/docs/guide/features.md#keyword-pre-filtering) to focus the output.

```bash
$ md curl.md/docs/getting-started --objective fastest way to get started
$ md curl.md/docs/getting-started --keywords quick,start
```

Want more curl.md? You can also use curl.md:

- **in the browser** (prefix any URL with curl.md),
- with **`curl`** (e.g. `curl curl.md/example.com{:sh}`),
- via the [**API**](/docs/guide/api.md#http-api) and [**SDK**](/docs/guide/api.md#typescript-sdk),
- and by installing [**agent plugins**](/docs/guide/plugins.md).

By far the best thing to do is just give curl.md to your agents and let them rip.

##### For Agents

If you are an agent or want to copy-paste so your agent can try out curl.md, use this prompt:

```text
I'd like you to set up https://curl.md, the best way to turn URLs into markdown.

First install the CLI. If I have npm, run: npm i -g curl.md
If not, run: curl -fsSL https://curl.md/install.sh | bash

Then install skills. If I have Node, run: npx skills add https://curl.md --yes
If I don't have Node, run: curl.md skills add

Next install the official curl.md plugin for this agent if one exists: https://curl.md/docs/guide/plugins

Once set up, use curl.md whenever you fetch URLs.
To verify, use curl.md to read this page and show me how it works: https://curl.md/docs/getting-started
```

For deeper curl.md agent integration, read the [Plugins Guide](/docs/guide/plugins.md).

:::tip[TL;DR]
Agents should use curl.md to turn URLs into high-quality, optimized markdown for supercharged context and increased tokens savings.
:::

#### Next Steps

Congrats! You finished the quickstart. Here’s what’s on next.

:::card[Why curl.md]{href=/docs/why icon=lightbulb}
Learn more about why you should even use curl.md in your workflows.
:::

:::card[Installation]{href=/docs/install icon=download}
Learn more about the different installation options.
:::

:::card[Guide]{href=/docs/guide/features icon=book}
Learn more about curl.md’s features and how things work.
:::

:::card[Plugins]{href=/docs/guide/plugins icon=package}
Learn more about curl.md’s first-party agent plugins.
:::

#### Contribute

curl.md is [open source](https://github.com/wevm/curl.md) and welcomes contributions (no slop please). Read the [Contributing Guide](/docs/dev/develop.md) for info on how to contribute to curl.md.

#### Community

If you have questions or need help, reach out on the [GitHub Discussions](https://github.com/wevm/curl.md/discussions) community or _nicely_ yell at us on [Twitter](https://twitter.com/wevm_dev).

## /docs/install.md

Install curl.md in your terminal, browser workflow, or favorite coding agent.

### Installation

Install curl.md in the environment you use most. Start with the [CLI](#cli) if you want the broadest support or install curl.md first-party agent [plugins](#plugins).

:::tip[Pick one install path]
You only need one primary install path to get value from curl.md and can always add more integrations later.
:::

#### Plugins

Integrate curl.md into your favorite coding agent.

:::card[Amp]{href=/docs/plugins/amp icon=amp}
Install and use curl.md with Amp
:::

:::card[Claude]{href=/docs/plugins/claude icon=claude}
Install and use curl.md with Claude
:::

:::card[Codex]{href=/docs/plugins/codex icon=codex}
Install and use curl.md with Codex
:::

:::card[Cursor]{href=/docs/plugins/cursor icon=cursor}
Install and use curl.md with Cursor
:::

:::card[OpenCode]{href=/docs/plugins/opencode icon=opencode}
Install and use curl.md with OpenCode
:::

:::card[Pi]{href=/docs/plugins/pi icon=pi}
Install and use curl.md with Pi
:::

Learn more about plugins in the [Plugins Guide](/docs/guide/plugins.md).

#### CLI

Install the CLI via curl, npm, or bun.

:::codegroup

```sh [curl]
$ curl -fsSL https://curl.md/install.sh | bash
```

```sh [npm]
$ npm i -g curl.md
```

```sh [bun]
$ bun i -g curl.md
```

:::

:::tip[Using curl.md with an agent]
Install the CLI first. Then, if your agent supports skills and you have Node, install the hosted skills with `npx skills add https://curl.md --yes`. If you don’t have Node, run `curl.md skills add` to sync curl.md’s local CLI skills into your agent.
:::

Learn more about the CLI in the [CLI Guide](/docs/guide/cli.md).

#### SDK

Install `curl.md` with your favorite package manager:

:::codegroup

```sh [npm]
$ npm i curl.md
```

```sh [pnpm]
$ pnpm i curl.md
```

```sh [bun]
$ bun i curl.md
```

```sh [yarn]
$ yarn add curl.md
```

:::

Learn more about the SDK in the [API & SDK Guide](/docs/guide/api.md).

#### No Code

Don’t want to install anything? Respect. You can use curl.md directly with `curl`:

```sh
$ curl curl.md/example.com
```

or in your browser by prefixing any URL with [curl.md](https://curl.md).

```sh
$ open https://curl.md/example.com
```

## /docs/why.md

Agents love the web. The web was not designed for them. curl.md fixes that.

### Why curl.md

Agents love the web. The web was not designed for them.

#### The Problem curl.md is Solving

Coding agents need high-quality context to do useful work. The web should be perfect for that. It has documentation, changelogs, release notes, engineering blogs, and loads of other resources they can use.

But most webpages are terrible inputs for agents. HTML is noisy and token-heavy, JavaScript can change what renders, and page elements like navigation, sidebars, cookie banners, and scripts often make it difficult to extract the content that actually matter.

Markdown is a much better fit: plain text, structured, and easy for agents to process. Converting URLs to markdown isn’t trivial. That’s where curl.md comes in.

curl.md is built for developers and coding agents. It turns the web into agent-optimized markdown so you can ship faster, waste fewer tokens, and save money.

#### Fits Right Into Your Workflow

curl.md is built around the common loop in developer and coding-agent workflows:

- Fetch a URL from a prompt, doc, or search result
- Pull the useful parts into the context window
- Use that context to code, debug, or decide what to do next

Many agent tools already include built-in `read_web_page` or `webfetch` support. curl.md goes further for coding workflows:

- **Fetch markdown directly** and shortcut HTML conversion with source-aware rules, `Accept` headers, and other optimizations.
- **Narrow long pages to [an objective](/docs/guide/features.md#objective-based-narrowing)** or **[pre-filter with keywords](/docs/guide/features.md#keyword-pre-filtering)** to extract only what matters and reduce tokens.
- **Read optimized markdown** through curl.md by cleaning up syntax with markdown engineered especially for agents.

You can use all of this through the [CLI](/docs/guide/cli.md), [plugins](/docs/guide/plugins.md), [skills](/docs/skills.md), and [API & SDK](/docs/guide/api.md), with caching built in.

#### Save Money on Tokens

Coding agents are powerful, but they are not known for being token efficient. Their business is selling tokens, not reducing how many you use.

Pulling raw URLs into context is one of the fastest ways to burn tokens and bloat context. curl.md reduces that overhead by returning [optimized markdown](/docs/guide/features.md#markdown-optimized-for-agents) by default.

Features like [objective-based narrowing](/docs/guide/features.md#objective-based-narrowing) reduce input tokens even further by returning only the content needed for the task.

curl.md also adds observability, so you can see how many tokens and how much money you are saving as an individual or across a team.

#### Fully Open Source

curl.md is fully open source and not a black box platform. You (or your agent) can inspect the source, submit improvements, fork it, build on top of it, and do whatever you want with the code.

We welcome contributions from the community. See our [Contributing Guide](/docs/dev/develop.md) to get involved.

#### Easy to Type, Easy to Remember

curl.md is short, memorable, and easy to use in prompts, terminals, and tools. It is also an homage to (we think) [the greatest CLI tool of all time](https://curl.se).

## /docs/faq.md

Frequently asked questions about curl.md.

### FAQ

Frequently asked questions about curl.md. Ask a question by opening a [GitHub Issue](https://github.com/wevm/curl.md/issues/new?template=docs.yml).

#### What is curl.md?

curl.md turns URLs into markdown optimized for agents to help you get better context and save tokens/money.

#### How do I use curl.md?

You can use it in [the browser](https://curl.md/example.com) by prefixing any URL with `curl.md/`, in the terminal via `curl curl.md/<url>`, with [the CLI](/docs/guide/cli.md), [agent plugins](/docs/guide/plugins.md), or through the [API and SDK](/docs/guide/api.md).

#### How much does curl.md cost?

You can use curl.md for free with generous [rate limits](/docs/guide/api.md#rate-limiting). [Sign in](/login) for higher limits or use prepaid credits to skip rate limits.

#### Which coding agents does curl.md support?

Official integrations exist for [Amp](/docs/plugins/amp.md), [Claude](/docs/plugins/claude.md), [OpenCode](/docs/plugins/opencode.md), and [Pi](/docs/plugins/pi.md). Codex, Cursor, and other agents can use [skills](/docs/skills.md), the [CLI/MCP server](/docs/guide/cli.md#mcp), or add their own integrations by reading the [Plugins Guide](/docs/guide/plugins.md#build-your-own-integration).

#### Is curl.md open source?

Yes. The source code is public on [GitHub](https://github.com/wevm/curl.md) under the [MIT License](https://github.com/wevm/curl.md/blob/main/LICENSE). Anyone can use it, modify it, or contribute.

## /docs/guide/features.md

Learn how curl.md turns URLs into agent-ready markdown with objectives and keywords.

### Features

curl.md is intentionally small in surface area. The goal is simple: turn URLs into markdown that is easier for agents to use.

:::tip
The following walks through curl.md’s features using the curl.md [CLI](/docs/guide/cli.md). [Install](/docs/install.md#cli) the CLI to follow along.
:::

#### Markdown Optimized For Agents

Fetch a webpage and get optimized markdown back instead of full HTML.

```sh
$ md example.com
```

curl.md uses a combination of site-specific rules and generalized extraction methods to make sure your agent only gets the best markdown.

#### Objective-Based Narrowing

Use an objective when you need the output narrowed to a specific question or task.

```sh
$ md zod.dev/error-formatting --objective tree error formatting
```

Most of the time, your coding agent will set objectives for you based on your prompts. Agents tend to be very good at this.

When you need to control how that narrowing is applied, use [`mode`](/docs/guide/api.md#mode) to choose between a faster or more thorough pass.

#### Keyword Pre-Filtering

Use keywords when you know the terms that matter and want to shrink the search space before the final output is generated.

```sh
md developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch \
  --objective "streaming response body" \
  --keywords ReadableStream,getReader
```

Keywords are a quick way to filter markdown before the objective-based narrowing takes a pass.

#### Multiple Entry Points

There are multiple ways to use curl.md, making it simple to integrate into different agent workflows.

:::card[curl.md/ prefix]{href=/docs/guide/api#http-api icon=browser}
Add `curl.md/` in front of any URL in your browser or use with `curl` -> `curl curl.md/example.com{:sh}`.
:::

:::card[CLI]{href=/docs/guide/cli icon=terminal}
Use the agent-optimized `curl.md` CLI from the terminal to give your coding agent markdown vision.
:::

:::card[API & SDK]{href=/docs/guide/api icon=rocket}
Call curl.md from application code when you need markdown fetching inside your own tools or services.
:::

:::card[Agent Plugins]{href=/docs/guide/plugins icon=package}
Use native integrations for popular coding agents when you want curl.md directly inside your agent workflow.
:::

## /docs/guide/agent-usage.md

Tools and best practices when using curl.md with agents.

### Agent Usage

Tools and best practices when using curl.md (and these docs) with agents.

#### Tell Your Agent To Use curl.md

One of the simplest ways to get better URL context is to tell your agent to use curl.md whenever it fetches URLs. You can add a project rule like:

```text
When you need to fetch a URL, prefer curl.md so you get markdown instead of raw HTML.
Use curl.md for docs pages, articles, changelogs, and reference material.
If curl.md docs are relevant, prefer .md docs pages or llms.txt over raw page fetches.
```

This usually gives the agent cleaner, lower-noise context than a raw page fetch or browser snapshot.

:::tip[Go deeper]
Install a native [plugin](/docs/guide/plugins.md) (recommended), or use [skills](/docs/skills.md) or [MCP mode](/docs/guide/cli.md#mcp) to integrate more deeply.
:::

#### Skills

If your agent supports [skills](https://agentskills.io/home), install the official curl.md skills with:

```sh
$ npx skills add https://curl.md --yes
```

Hosted skills are available at [`https://curl.md/.well-known/skills/index.json`](https://curl.md/.well-known/skills/index.json).

Skills are useful when you want the agent to:

- fetch pages through the [CLI](/docs/guide/cli.md)
- use curl.md inside local terminal workflows
- follow recommended curl.md usage patterns without manual prompt setup

For broader integration options, see [Plugins](/docs/guide/plugins.md), [CLI](/docs/guide/cli.md), and [API & SDK](/docs/guide/api.md).

#### Single-Page Markdown Access

There are multiple ways to get the curl.md docs as markdown.

##### .md Endpoints

Append `.md` to any documentation URL to get the markdown version of that page.

Example:

- HTML: [`https://curl.md/docs/guide/cli`](https://curl.md/docs/guide/cli)
- Markdown: [`https://curl.md/docs/guide/cli.md`](https://curl.md/docs/guide/cli.md)

The markdown version includes features such as: full page content in plain markdown format, metadata for agents, code blocks with syntax markers, links preserved as markdown links, and tables formatted as markdown tables.

##### Using .md Endpoints

You can use these endpoints in various ways:

```sh
# Fetch documentation content with curl
curl https://curl.md/docs/guide/cli.md

# Pipe directly to an AI tool
curl https://curl.md/docs/guide/cli.md | pbcopy
```

You can also use `curl.md` itself to render docs pages as markdown in the browser or terminal, for example with `https://curl.md/curl.md/docs/guide/cli` (a little inception never hurt).

##### Content Negotiation

To obtain the markdown version of a single documentation page, you can:

- Use a `.md` endpoint - Append `.md` to the end of any docs page URL to get the markdown version.
- Use `Accept: text/markdown` - Send the header to a normal `/docs/...` URL when you want markdown without rewriting the path.

For example:

```sh
$ curl https://curl.md/docs/guide/cli -H 'Accept: text/markdown'
```

That returns the same generated markdown as [`https://curl.md/docs/guide/cli.md`](https://curl.md/docs/guide/cli.md).

If you omit the header, `/docs/...` keeps serving the normal HTML docs page.

```sh
$ curl https://curl.md/docs/guide/cli
```

Prefer `.md` URLs when you want a canonical markdown link you can paste into prompts, rules, or agent context. Use content negotiation when you already have a `/docs/...` URL and want markdown without rewriting the path.

##### Copy Page

Every docs page includes agent-friendly page actions:

- `Copy page` copies the page’s canonical markdown to your clipboard
- `View markdown` opens the generated `.md` page in a new tab

This is the fastest manual workflow:

1. Open the docs page.
2. Click `Copy page`.
3. Paste the markdown into your agent.

Use `View markdown` when your agent can fetch URLs directly and you want to give it a stable markdown endpoint instead of pasted content.

#### llms.txt

We implement [`llms.txt`](https://curl.md/llms.txt) and [`llms-full.txt`](https://curl.md/llms-full.txt) as follows:

- [`llms.txt`](https://curl.md/llms.txt) - A compact directory of curl.md’s docs and agent entry points. It includes a short product summary, example CLI and HTTP usage, links to important docs pages, and links to things like [skills](/docs/skills.md).
- [`llms-full.txt`](https://curl.md/llms-full.txt) - The full contents of the canonical curl.md documentation in a single file, intended for broad indexing, bulk ingestion, or large-context workflows. It is much larger than `llms.txt`, so it is usually not the right default for routine prompts.

Prefer page-level `.md` URLs first, then `llms.txt`, then `llms-full.txt` only when broader context is necessary.

## /docs/guide/cli.md

Turn URLs into optimized markdown with the curl.md CLI

### CLI

The CLI is the most flexible way to use curl.md. It works well with agents or in terminals, editors, scripts, and anywhere else you can shell out.

- [curl.md](https://www.npmjs.com/package/curl.md)
- [Source code](https://github.com/wevm/curl.md/blob/main/cli/src/cli.ts)

#### Quick Start

Install the CLI, optionally authenticate, and fetch your first page.

::::steps

##### Install CLI

Install the CLI via curl, npm, or bun.

:::codegroup

```sh [curl]
$ curl -fsSL https://curl.md/install.sh | bash
```

```sh [npm]
$ npm i -g curl.md
```

```sh [bun]
$ bun i -g curl.md
```

:::

##### Authenticate

Optionally log in to unlock higher usage limits and features, like [objective extraction](/docs/guide/features.md#objective-based-narrowing).

```sh
$ curl.md auth login
```

##### Use CLI

Fetch a page from your terminal:

```sh
$ curl.md curl.md/docs/guide/cli
```

::::

#### Install

Install the CLI using your favorite method.

```sh
$ npm i -g curl.md
```

Or with Bun:

```sh
$ bun i -g curl.md
```

If you prefer a script-based install:

```sh
$ curl -fsSL https://curl.md/install.sh | bash
```

Verify it works:

```sh
$ curl.md --version
```

You can also install by downloading releases on the [GitHub Releases](https://github.com/wevm/curl.md/releases) page.

#### Usage

:::tip
The CLI can be invoked through `curl.md` or via the short `md` alias.
:::

Fetch a page:

```sh
$ md example.com
```

Narrow by [objective](/docs/guide/api.md#objective) with `--objective`:

```sh
$ md zod.dev/error-formatting --objective tree error formatting
```

Add [keywords](/docs/guide/api.md#keywords) with `--keywords`:

```sh
md developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch \
  --objective streaming response body \
  --keywords ReadableStream,getReader
```

Choose a [mode](/docs/guide/api.md#mode) with `--mode`:

```sh
md developers.cloudflare.com/d1/get-started \
  --objective how to query D1 from a worker \
  --keywords D1,bindings \
  --mode rush
```

:::tip[Choosing a mode]
`smart` is the default and is best for most docs lookups. Use `rush` when you want a faster pass over the page.
:::

Bypass cache with `--fresh`:

```sh
$ md example.com --fresh
```

Finally, learn more about the CLI with `--help`:

```sh
$ md --help
```

##### Authentication

Log in from the CLI to unlock higher usage limits and features, like [objective extraction](/docs/guide/features.md#objective-based-narrowing).

```sh
$ curl.md auth login
```

For non-interactive environments, set [`CURLMD_API_KEY`](#environment-variables).

##### Agents

If your agent can shell out locally and does not already have a [first-party integration](/docs/guide/plugins.md), sync the curl.md CLI skills into it:

```sh
$ curl.md skills add
```

These generated skills teach the agent how to use the curl.md CLI effectively inside your terminal workflow.

If you want to install the skills into the current project instead of your global agent config, use:

```sh
$ curl.md skills add --no-global
```

It’s recommended to use native agent [plugins](/docs/guide/plugins.md) instead of direct CLI usage when possible.

##### MCP

If your editor or agent supports MCP stdio servers, you can run the CLI directly in MCP mode:

```sh
$ curl.md --mcp
```

That exposes curl.md’s `fetch` command as an MCP tool, so hosts without a first-party curl.md integration can still fetch URLs through the normal CLI/API path.

If your agent supports automatic MCP registration, you can also use:

```sh
$ curl.md mcp add
```

See [`mcp add`](#mcp-add) below for supported options and agent targeting.

#### Commands

{/* GENERATED:cli-commands:start */}

##### `curl.md <url>`

URL to markdown for agents

| Argument | Type  | Description  |
| -------- | ----- | ------------ |
| `url`    | `url` | URL to fetch |

| Option            | Type          | Default | Description                                        |
| ----------------- | ------------- | ------- | -------------------------------------------------- |
| `--fresh, -f`     | `boolean`     |         | Force fresh fetch (bypass cache)                   |
| `--keywords, -k`  | `array`       |         | Pre-filter by keywords (comma-separated)           |
| `--mode, -m`      | `rush\|smart` | `smart` | Mode when narrowing content with --objective       |
| `--objective, -o` | `string`      |         | Narrow content to a specific objective             |
| `--token, -t`     | `string`      |         | API token for authentication (env: CURLMD_API_KEY) |

```sh
$ curl.md example.com
$ curl.md docs.github.com/en/webhooks/webhook-events-and-payloads --objective pull request webhook event payload and actions --keywords pull_request
$ curl.md developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch --objective streaming response body --keywords ReadableStream,getReader
$ curl.md developers.cloudflare.com/d1/get-started --objective how to query D1 from a worker --keywords D1,bindings
$ curl.md ai-sdk.dev/docs/ai-sdk-core/generating-text --objective how to stream text with the ai sdk --keywords streamText,generateText
$ curl.md zod.dev/error-formatting --objective tree error formatting --keywords treeifyError
```

<a id="auth"></a>
##### `auth`

Authenticate with curl.md (login, logout, status)

| Command                  | Description                 |
| ------------------------ | --------------------------- |
| [`login`](#auth-login)   | Log in with curl.md         |
| [`logout`](#auth-logout) | Log out of the curl.md CLI  |
| [`status`](#auth-status) | Check authentication status |

<a id="auth-login"></a>
###### `login`

Log in with curl.md

```sh
$ curl.md auth login
```

<a id="auth-logout"></a>
###### `logout`

Log out of the curl.md CLI

```sh
$ curl.md auth logout
```

<a id="auth-status"></a>
###### `status`

Check authentication status

```sh
$ curl.md auth status [options]
```

| Option    | Type     | Description        |
| --------- | -------- | ------------------ |
| `--token` | `string` | API token to check |

<a id="credits"></a>
##### `credits`

Manage prepaid credits (add, status)

| Command                     | Description   |
| --------------------------- | ------------- |
| [`add`](#credits-add)       | Add credits   |
| [`status`](#credits-status) | Check credits |

<a id="credits-add"></a>
###### `add`

Add credits

```sh
$ curl.md credits add <5|10|20|50>
```

| Argument | Type            | Description       |
| -------- | --------------- | ----------------- |
| `amount` | `5\|10\|20\|50` | Amount in dollars |

<a id="credits-status"></a>
###### `status`

Check credits

```sh
$ curl.md credits status
```

<a id="fetch"></a>
##### `fetch`

Fetch URL as markdown

```sh
$ curl.md fetch <url> [options]
```

| Argument | Type  | Description  |
| -------- | ----- | ------------ |
| `url`    | `url` | URL to fetch |

| Option            | Type          | Default | Description                                        |
| ----------------- | ------------- | ------- | -------------------------------------------------- |
| `--fresh, -f`     | `boolean`     |         | Force fresh fetch (bypass cache)                   |
| `--keywords, -k`  | `array`       |         | Pre-filter by keywords (comma-separated)           |
| `--mode, -m`      | `rush\|smart` | `smart` | Mode when narrowing content with --objective       |
| `--objective, -o` | `string`      |         | Narrow content to a specific objective             |
| `--token, -t`     | `string`      |         | API token for authentication (env: CURLMD_API_KEY) |

```sh
$ curl.md fetch example.com
$ curl.md fetch docs.github.com/en/webhooks/webhook-events-and-payloads --objective pull request webhook event payload and actions --keywords pull_request
$ curl.md fetch developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch --objective streaming response body --keywords ReadableStream,getReader
$ curl.md fetch developers.cloudflare.com/d1/get-started --objective how to query D1 from a worker --keywords D1,bindings
$ curl.md fetch ai-sdk.dev/docs/ai-sdk-core/generating-text --objective how to stream text with the ai sdk --keywords streamText,generateText
$ curl.md fetch zod.dev/error-formatting --objective tree error formatting --keywords treeifyError
```

<a id="org"></a>
##### `org`

Manage organizations (create, invite, list, member, switch, view)

| Command                   | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| [`create`](#org-create)   | Create organization                                        |
| [`invite`](#org-invite)   | Manage organization invites (accept, create, list, revoke) |
| [`list`](#org-list), `ls` | List organizations                                         |
| [`member`](#org-member)   | Manage organization members (add, list, remove, role)      |
| [`switch`](#org-switch)   | Switch organization                                        |
| [`view`](#org-view)       | View active organization                                   |

<a id="org-create"></a>
###### `create`

Create organization

```sh
$ curl.md org create <login> [options]
```

| Argument | Type    | Description                      |
| -------- | ------- | -------------------------------- |
| `login`  | `login` | Organization login (e.g. "wevm") |

| Option   | Type     | Description  |
| -------- | -------- | ------------ |
| `--name` | `string` | Display name |

<a id="org-invite"></a>
###### `invite`

Manage organization invites (accept, create, list, revoke)

| Command                          | Description                     |
| -------------------------------- | ------------------------------- |
| [`accept`](#org-invite-accept)   | Accept organization invite      |
| [`create`](#org-invite-create)   | Create organization invite link |
| [`list`](#org-invite-list), `ls` | List organization invites       |
| [`revoke`](#org-invite-revoke)   | Revoke organization invite      |

<a id="org-invite-accept"></a>
###### `accept`

Accept organization invite

```sh
$ curl.md org invite accept <token>
```

| Argument | Type    | Description         |
| -------- | ------- | ------------------- |
| `token`  | `token` | Invite URL or token |

<a id="org-invite-create"></a>
###### `create`

Create organization invite link

```sh
$ curl.md org invite create [options]
```

| Option             | Type            | Default  | Description              |
| ------------------ | --------------- | -------- | ------------------------ |
| `--expires-in, -e` | `number`        | `604800` | Expiry in seconds        |
| `--max-uses, -m`   | `number`        |          | Maximum number of uses   |
| `--role, -r`       | `member\|admin` | `member` | Role for invited members |

<a id="org-invite-list"></a>
###### `list`

List organization invites

```sh
$ curl.md org invite list
```

<a id="org-invite-revoke"></a>
###### `revoke`

Revoke organization invite

```sh
$ curl.md org invite revoke [invite] [options]
```

| Argument | Type     | Description                  |
| -------- | -------- | ---------------------------- |
| `invite` | `invite` | Invite token or ID to revoke |

| Option        | Type      | Description       |
| ------------- | --------- | ----------------- |
| `--force, -f` | `boolean` | Skip confirmation |

<a id="org-list"></a>
###### `list`

List organizations

```sh
$ curl.md org list
```

<a id="org-member"></a>
###### `member`

Manage organization members (add, list, remove, role)

| Command                              | Description                             |
| ------------------------------------ | --------------------------------------- |
| [`add`](#org-member-add)             | Add member to active organization       |
| [`list`](#org-member-list), `ls`     | List members of the active organization |
| [`remove`](#org-member-remove), `rm` | Remove member from active organization  |
| [`role`](#org-member-role)           | Change member role                      |

<a id="org-member-add"></a>
###### `add`

Add member to active organization

```sh
$ curl.md org member add <login> [options]
```

| Argument | Type    | Description          |
| -------- | ------- | -------------------- |
| `login`  | `login` | Account login to add |

| Option       | Type            | Default  | Description             |
| ------------ | --------------- | -------- | ----------------------- |
| `--role, -r` | `member\|admin` | `member` | Role for the new member |

<a id="org-member-list"></a>
###### `list`

List members of the active organization

```sh
$ curl.md org member list
```

<a id="org-member-remove"></a>
###### `remove`

Remove member from active organization

```sh
$ curl.md org member remove [login] [options]
```

| Argument | Type    | Description            |
| -------- | ------- | ---------------------- |
| `login`  | `login` | Member login to remove |

| Option        | Type      | Description       |
| ------------- | --------- | ----------------- |
| `--force, -f` | `boolean` | Skip confirmation |

<a id="org-member-role"></a>
###### `role`

Change member role

```sh
$ curl.md org member role [login] [options]
```

| Argument | Type    | Description                     |
| -------- | ------- | ------------------------------- |
| `login`  | `login` | Member login to change role for |

| Option        | Type            | Description       |
| ------------- | --------------- | ----------------- |
| `--force, -f` | `boolean`       | Skip confirmation |
| `--role, -r`  | `member\|admin` | New role          |

<a id="org-switch"></a>
###### `switch`

Switch organization

```sh
$ curl.md org switch [login]
```

| Argument | Type    | Description                                    |
| -------- | ------- | ---------------------------------------------- |
| `login`  | `login` | Organization login to switch to (or "account") |

<a id="org-view"></a>
###### `view`

View active organization

```sh
$ curl.md org view [options]
```

| Option      | Type      | Description     |
| ----------- | --------- | --------------- |
| `--web, -w` | `boolean` | Open in browser |

<a id="request"></a>
##### `request`

Manage requests (list, view)

| Command                       | Description   |
| ----------------------------- | ------------- |
| [`list`](#request-list), `ls` | List requests |
| [`view`](#request-view)       | View request  |

<a id="request-list"></a>
###### `list`

List requests

```sh
$ curl.md request list [options]
```

| Option         | Type     | Description                |
| -------------- | -------- | -------------------------- |
| `--limit, -l`  | `number` | Number of requests to show |
| `--page, -p`   | `number` | Page number                |
| `--search, -s` | `string` | Filter by URL              |

<a id="request-view"></a>
###### `view`

View request

```sh
$ curl.md request view [request] [options]
```

| Argument  | Type      | Description        |
| --------- | --------- | ------------------ |
| `request` | `request` | Request ID to view |

| Option      | Type      | Description                  |
| ----------- | --------- | ---------------------------- |
| `--verbose` | `boolean` | Show all request fields      |
| `--web, -w` | `boolean` | Open original URL in browser |

<a id="token"></a>
##### `token`

Manage API tokens (create, list, delete)

| Command                         | Description      |
| ------------------------------- | ---------------- |
| [`create`](#token-create)       | Create API token |
| [`delete`](#token-delete), `rm` | Delete API token |
| [`list`](#token-list), `ls`     | List API tokens  |

<a id="token-create"></a>
###### `create`

Create API token

```sh
$ curl.md token create <name>
```

| Argument | Type   | Description |
| -------- | ------ | ----------- |
| `name`   | `name` | Token name  |

<a id="token-delete"></a>
###### `delete`

Delete API token

```sh
$ curl.md token delete [name] [options]
```

| Argument | Type   | Description          |
| -------- | ------ | -------------------- |
| `name`   | `name` | Token name to delete |

| Option        | Type      | Description       |
| ------------- | --------- | ----------------- |
| `--force, -f` | `boolean` | Skip confirmation |

<a id="token-list"></a>
###### `list`

List API tokens

```sh
$ curl.md token list
```

<a id="update"></a>
##### `update`

Update curl.md CLI

```sh
$ curl.md update [options]
```

| Option     | Type     | Description                |
| ---------- | -------- | -------------------------- |
| `--target` | `string` | Update to specific version |

{/* GENERATED:cli-commands:end */}

#### Integrations

{/* GENERATED:cli-integrations:start */}

<a id="completions"></a>
##### `completions`

Generate shell completion script

```sh
$ curl.md completions <bash|fish|nushell|zsh>
```

| Argument | Type                       | Description                       |
| -------- | -------------------------- | --------------------------------- |
| `shell`  | `bash\|fish\|nushell\|zsh` | Shell to generate completions for |

<a id="mcp-add"></a>
##### `mcp add`

Register as MCP server

```sh
$ curl.md mcp add [options]
```

| Option          | Type      | Description                                                     |
| --------------- | --------- | --------------------------------------------------------------- |
| `--agent`       | `string`  | Target a specific agent (e.g. claude-code, cursor)              |
| `--command, -c` | `string`  | Override the command agents will run (e.g. "pnpm my-cli --mcp") |
| `--no-global`   | `boolean` | Install to project instead of globally                          |

<a id="skills"></a>
##### `skills`

Sync skill files to agents (add, list)

| Command                      | Description                |
| ---------------------------- | -------------------------- |
| [`add`](#skills-add)         | Sync skill files to agents |
| [`list`](#skills-list), `ls` | List skills                |

<a id="skills-add"></a>
###### `add`

Sync skill files to agents

```sh
$ curl.md skills add [options]
```

| Option        | Type      | Default | Description                            |
| ------------- | --------- | ------- | -------------------------------------- |
| `--depth`     | `number`  | `1`     | Grouping depth for skill files         |
| `--no-global` | `boolean` |         | Install to project instead of globally |

<a id="skills-list"></a>
###### `list`

List skills

```sh
$ curl.md skills list
```

{/* GENERATED:cli-integrations:end */}

#### Environment Variables

{/* GENERATED:cli-environment-variables:start */}

| Variable          | Type     | Default           | Description                  |
| ----------------- | -------- | ----------------- | ---------------------------- |
| `CURLMD_API_KEY`  | `string` |                   | API token for authentication |
| `CURLMD_BASE_URL` | `string` | `https://curl.md` | Base URL                     |

{/* GENERATED:cli-environment-variables:end */}

#### When to use the CLI

Use the CLI when you want your agent to be able to use `curl.md`, but there isn’t a [plugin](/docs/guide/plugins.md), or in shell scripts, editor terminals, local automation, or quick one-off research.

## /docs/guide/api.md

Fetch optimized markdown over HTTP or with the typed TypeScript SDK.

### API & SDK

Use `curl.md` directly over HTTP or through the published TypeScript SDK.

#### HTTP API

The simplest HTTP interface is the hosted `curl.md/<url>` path:

```sh
$ curl curl.md/developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch?objective=streaming+response+body&keywords=ReadableStream,getReader"
```

This is useful for quick integrations, shell scripts, and server-side fetches.
The public `/api` surface also includes experimental routes for auth, API keys, organizations, invites, members, and more.

:::tip[Browser shortcut]
You can also use curl.md in your browser by adding `curl.md/` in front of any URL. For example, [`curl.md/example.com`](https://curl.md/example.com)
:::

#### TypeScript SDK

Use the [`curl.md`](https://www.npmjs.com/package/curl.md) npm package when you want a typed client in TypeScript.

- [curl.md](https://www.npmjs.com/package/curl.md)
- [Source code](https://github.com/wevm/curl.md/blob/main/cli/src/client.ts)

##### Install

Install `curl.md` with your favorite package manager:

:::codegroup

```sh [npm]
$ npm i curl.md
```

```sh [pnpm]
$ pnpm i curl.md
```

```sh [bun]
$ bun i curl.md
```

```sh [yarn]
$ yarn add curl.md
```

:::

<details>
<summary>Using Unreleased Commits</summary>

Commits are continuously released via [pkg.pr.new](https://pkg.pr.new) and can be installed using the pull request number or short commit ID.

:::codegroup

```sh [npm]
$ npm i https://pkg.pr.new/curl.md@123
```

```sh [pnpm]
$ pnpm i https://pkg.pr.new/curl.md@123
```

```sh [bun]
$ bun i https://pkg.pr.new/curl.md@123
```

```sh [yarn]
$ yarn add https://pkg.pr.new/curl.md@123
```

:::

When using unreleased commits, please keep in mind there can be breaking changes, especially for pull requests.

</details>

##### Usage

Create a typed curl.md client, then call `fetch` with a URL and request options.

```ts
import { createClient } from 'curl.md'

const client = createClient()
const res = await client.fetch('docs.github.com/en/webhooks/webhook-events-and-payloads', {
  keywords: ['pull_request'],
  objective: 'pull request webhook event payload and actions',
})

const json = await res.json()
```

The SDK gives you typed access to request options like [`objective`](#objective), [`keywords`](#keywords), [`mode`](#mode), [`fresh`](#fresh), and [`token`](#token).

The lower-level `client.api` key exposes experimental `/api` routes directly.

#### Request Options

Use these options with the HTTP API query string or the TypeScript SDK.

##### objective

Use `objective` to narrow the response to content relevant to a specific goal.
HTTP also accepts the aliases `o` and `q`.

##### keywords

Use `keywords` to pre-filter the page before extraction.
In HTTP, send them as a comma-separated string.
HTTP also accepts the alias `k`.

##### mode

Use `mode` to control the extraction model when `objective` is set.
Supported values are `smart` and `rush`.
HTTP also accepts the alias `m`.

##### fresh

Use `fresh` to bypass cache and force a fresh fetch.
In HTTP, you can send `fresh=true` or just include `?fresh`.
HTTP also accepts the alias `f`.

##### token

Use `token` in the SDK to send an API key as a Bearer token.
For raw HTTP requests, use the `Authorization` header instead.

#### Authentication

Authenticated requests can use a Bearer token through the `Authorization` header.

##### API Keys

For server-side apps, CI, and other non-interactive integrations, prefer an API key.

Create one from the CLI:

```sh
$ curl.md auth login
$ curl.md token create my-app
```

If you want an organization-scoped token, switch to that organization before creating it:

```sh
$ curl.md org switch acme
$ curl.md token create ci
```

Then send the token as a Bearer token over HTTP:

```sh
$ curl curl.md/example.com -H 'Authorization: Bearer curlmd_xxx'
```

Or pass it to the TypeScript SDK per request:

```ts
import { createClient } from 'curl.md'

const client = createClient()
const res = await client.fetch('example.com', {
  token: process.env.CURLMD_API_KEY,
})
```

API keys also work through the `token` or `t` query parameter when sending headers is inconvenient, though `Authorization` is recommended.

If you are using session-based auth instead of an API key and need to act within a specific organization, send `x-organization-id` as well.

#### Response Format

The hosted HTTP endpoint returns markdown by default:

```sh
$ curl curl.md/example.com
```

That response uses `text/markdown` and returns the final markdown document directly.

If you prefer JSON, send `Accept: application/json`:

```sh
$ curl curl.md/example.com -H 'Accept: application/json'
```

The JSON shape is:

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

#### Response Headers

Successful fetch responses include useful metadata headers:

- `x-cache` — whether the response was a cache `HIT` or `MISS`
- `x-request-id` — request identifier for debugging
- `x-tokens-count` — estimated token count for the final response
- `x-tokens-saved` — estimated tokens saved versus the source content
- `x-cost-mills` — request cost in mills
- `x-credits-remaining` — remaining prepaid credits, when available

#### Error Handling

Errors are returned as JSON with a stable string `code` and a human-readable `message`.
Some errors include extra fields, like validation `issues`.

```json
{
  "code": "invalid_api_key",
  "message": "Invalid API key"
}
```

In the TypeScript SDK, narrow on `res.status` before reading `res.json()`.
That gives you endpoint-specific error types in TypeScript.

```ts
const res = await client.fetch('example.com')

switch (res.status) {
  case 200:
    return await res.json()
  case 400: {
    const json = await res.json()
    console.error(json.code) // "validation_error"
    return
  }
  case 502: {
    const json = await res.json()
    console.error(json.code) // "fetch_failed" | "ai_failed"
    return
  }
}
```

#### Rate Limiting

On the main fetch endpoint, free usage is rate limited and returns `429` with code `rate_limit_exceeded` when exceeded.

- Standard fetches: `100/hour` anonymous, `1,000/hour` authenticated
- Objective queries: `3/hour` anonymous, `10/hour` authenticated
- Paid usage skips these rate limits

:::note[Higher limits]
[Sign up for a free account](/login) for higher usage limits.
:::

Successful responses include rate-limit headers:

- `x-ratelimit-limit`
- `x-ratelimit-remaining`
- `x-ratelimit-reset`

Rate-limited responses also include `retry-after`.

#### When to use the API/SDK

- Use the [HTTP API](#http-api) for quick fetches from browsers, scripts, and simple integrations.
- Use the [TypeScript SDK](#typescript-sdk) when you want typed request options and status-aware responses in app code. For example, tool plugins, like the [OpenCode plugin](https://github.com/wevm/curl.md/blob/main/plugins/opencode/src/server.ts) and [Pi extension](https://github.com/wevm/curl.md/blob/main/plugins/pi/src/index.ts).
- Use the [CLI](/docs/guide/cli.md) when you want shell workflows, local auth, and token or organization management.

## /docs/guide/plugins.md

Use curl.md from native agent and editor integrations.

### Plugins

curl.md integrates into popular coding agents and tools for native URL-to-markdown workflows directly inside your agent or editor.

#### Official plugins

Official plugins for curl.md, developed by the curl.md team and community.

:::card[Amp]{href=/docs/plugins/amp icon=amp}
Install and use curl.md with Amp
:::

:::card[Claude]{href=/docs/plugins/claude icon=claude}
Install and use curl.md with Claude
:::

:::card[Codex]{href=/docs/plugins/codex icon=codex}
Install and use curl.md with Codex
:::

:::card[Cursor]{href=/docs/plugins/cursor icon=cursor}
Install and use curl.md with Cursor
:::

:::card[OpenCode]{href=/docs/plugins/opencode icon=opencode}
Install and use curl.md with OpenCode
:::

:::card[Pi]{href=/docs/plugins/pi icon=pi}
Install and use curl.md with Pi
:::

#### Build your own integration

If curl.md doesn’t support your favorite coding agent or tool, adding support is quite easy.

Likely you can one-shot support by pointing your agent to the docs and existing plugins, and letting it rip. For example, this prompt created the first version of the OpenCode plugin.

```text
Read curl.md/docs and create an OpenCode plugin that uses curl.md to fetch URLs as markdown instead of the built-in webfetch tool.
```

If you feel the community would benefit from your custom curl.md plugin, you are welcome to open a [pull request](https://github.com/wevm/curl.md/pulls) or share in the [discussion forum](https://github.com/wevm/curl.md/discussions/new?category=ideas).

##### Use the API & SDK

The curl.md [API and SDK](/docs/guide/api.md) make it simple to use curl.md in code.

If you are using TypeScript to create your plugin, the SDK is highly recommended because of its end-to-end type-safety support for responses and errors.

```ts
import { createClient } from 'curl.md'

const client = createClient()
const res = await client.fetch('example.com')
```

Check out the [OpenCode plugin source](https://github.com/wevm/curl.md/blob/main/plugins/opencode/src/server.ts) and [Pi extension source](https://github.com/wevm/curl.md/blob/main/plugins/pi/src/index.ts) for comprehensive examples on how to use the TypeScript SDK.

If you aren’t using TypeScript, check out the [API docs](/docs/guide/api.md) for more info on how to work with the API.

##### Use the CLI

The curl.md [CLI](/docs/guide/cli.md) can also be used to power your own integration. The CLI uses the [incur](https://github.com/wevm/incur) CLI framework for building agent-optimized CLIs that are easily navigable by agents. The CLI is a great option for integrating curl.md into your existing terminal environment and workflows.

:::tip
The curl.md [CLI source](https://github.com/wevm/curl.md/blob/main/cli/src/cli.ts) is also a great example on how to use the SDK.
:::

## /docs/plugins/amp.md

Install and use curl.md with Amp

### Amp

First-party [Amp](https://ampcode.com) plugin that routes Amp’s built-in `read_web_page` tool through curl.md and also adds a specific `curl_md` tool.

- [@curl.md/amp](https://www.npmjs.com/package/@curl.md/amp)
- [Source code](https://github.com/wevm/curl.md/tree/main/plugins/amp)

:::important
The Amp [Plugin API](https://ampcode.com/manual/plugin-api) is still experimental. As a result, the curl.md Amp plugin may also change without warning.
:::

#### Quick Start

Install the plugin, launch Amp, and start curling.

::::steps

##### Install plugin

Run the [`@curl.md/amp`](https://www.npmjs.com/package/@curl.md/amp) package installer:

```sh
$ npx @curl.md/amp install --yes
```

Successful installs create the Amp plugin shim in `~/.config/amp/plugins/curlmd.ts`.

##### Start Amp

Start Amp with plugins enabled via the `PLUGINS=all` env var:

```sh
$ PLUGINS=all amp
```

:::tip
Amp requires `PLUGINS=all` to be set in order to load plugins. Add this to your environment so you do not need to prefix every Amp command manually.
:::

##### Use Amp

Now that Amp is running with the curl.md plugin, all you need to do is use Amp. To confirm everything is set up, try this out:

```text
Read the curl.md Amp plugin docs and summarize how it works.
https://curl.md/docs/plugins/amp
```

Amp will automatically use curl.md to turn URLs you paste, or URLs it decides to fetch on its own, into markdown.

::::

#### Install

Run the [`@curl.md/amp`](https://www.npmjs.com/package/@curl.md/amp) npm package installer:

```sh
$ npx @curl.md/amp install --yes
```

This installs the package into Amp’s config directory and writes the plugin shim Amp loads from `~/.config/amp/plugins/curlmd.ts`.

To update an existing install, rerun the installer at the latest version:

```sh
$ npx @curl.md/amp@latest install --yes
```

If you prefer to add the shim manually, create your own plugin entry in `~/.config/amp/plugins`:

```ts title="~/.config/amp/plugins/curlmd.ts"
// @i-know-the-amp-plugin-api-is-wip-and-very-experimental-right-now
import plugin from '@curl.md/amp'
export default plugin
```

#### Usage

Ask for a page, paste links, or let Amp figure out what it needs to fetch.

##### Prompting

Inside Amp, prompt like you normally would, for example:

```text
Read the Cloudflare Agents docs and summarize the core concepts.
https://developers.cloudflare.com/agents
```

In this example, Amp will use curl.md to fetch the page and return markdown optimized for agents.

You can also tell Amp to use a specific [objective](/docs/guide/api.md#objective), [keywords](/docs/guide/api.md#keywords), or let it decide what to use on its own (it’s really good at this).

##### Authentication

The plugin uses the same auth model as the [CLI](/docs/guide/cli.md#authentication). Log in to connect the plugin to your curl.md account or organization.

```sh
$ curl.md auth login
```

For non-interactive environments, set [`CURLMD_API_KEY`](/docs/guide/cli.md#environment-variables).

##### Tools

The plugin registers the following tools:

| Tool            | Description                                              |
| --------------- | -------------------------------------------------------- |
| `curl_md`       | Fetch a URL as markdown.                                 |
| `read_web_page` | Overrides built-in `read_web_page` with markdown output. |

Both `curl_md` and the intercepted `read_web_page` tool accept the following inputs:

| Input        | Type             | Description                                                                          |
| ------------ | ---------------- | ------------------------------------------------------------------------------------ |
| `url`        | `string`         | HTTP(S) URL or bare domain to fetch. Prefer the canonical docs or article URL.       |
| `objective?` | `string`         | Specific question to answer from the page. Use when only part matters.               |
| `keywords?`  | `string[]`       | Keywords to focus extraction on relevant sections.                                   |
| `mode?`      | `rush` / `smart` | Use `rush` for speed or `smart` for better section selection on long or noisy pages. |
| `fresh?`     | `boolean`        | Bypass cache when freshness matters.                                                 |

#### Contributing

We welcome contributions to make the Amp plugin better. Feel free to create issues or pull requests [on GitHub](https://github.com/wevm/curl.md) if there are issues or something could be improved.

## /docs/plugins/claude.md

Install and use curl.md with Claude Code

### Claude

First-party [Claude Code](https://code.claude.com) plugin that adds a `fetch` MCP tool, `/curl-md:fetch` slash skill, and an opt-in `WebFetch` redirect hook.

- [@curl.md/claude](https://www.npmjs.com/package/@curl.md/claude)
- [Source code](https://github.com/wevm/curl.md/tree/main/plugins/claude)

#### Quick Start

Add the marketplace and plugin, launch Claude Code, and start curling.

::::steps

##### Add marketplace

Add the curl.md [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces#plugin-marketplace-add) to Claude Code.

```sh
$ claude plugin marketplace add wevm/curl.md
```

##### Install plugin

Install the `curl-md` plugin from the marketplace you just added:

```sh
$ claude plugin install curl-md@curl-md
```

:::tip
If Claude is already running, use the `/reload-plugins` command.
:::

##### Use Claude

Now that Claude is running with the curl.md plugin, all you need to do is use Claude. To confirm everything is set up, try this out:

```text
Read the curl.md Claude plugin docs and summarize how it works.
https://curl.md/docs/plugins/claude
```

Claude will automatically use curl.md to turn URLs you paste, or URLs it decides to fetch on its own, into markdown.

:::tip
Optionally, [authenticate](#authentication) with `curl.md auth login` or `CURLMD_API_KEY` to unlock higher usage limits.
:::

::::

#### Install

Claude installs plugins through marketplaces, and curl.md ships its marketplace manifest at [`.claude-plugin/marketplace.json`](https://github.com/wevm/curl.md/blob/main/.claude-plugin/marketplace.json) in this repository.

From your terminal:

```sh
$ claude plugin marketplace add wevm/curl.md
$ claude plugin install curl-md@curl-md
```

Or inside Claude:

```sh
/plugin marketplace add wevm/curl.md
/plugin install curl-md@curl-md
/reload-plugins
```

To update when a new version is available, refresh the marketplace, then reinstall the plugin:

```sh
$ claude plugin marketplace update curl-md
$ claude plugin install curl-md@curl-md
```

Or inside Claude:

```sh
/plugin marketplace update curl-md
/plugin install curl-md@curl-md
/reload-plugins
```

:::tip
If the plugin still reports the old version after updating, force-update the npm cache and reinstall:

```sh
$ npm install --prefix ~/.claude/plugins/npm-cache @curl.md/claude@latest
$ claude plugin install curl-md@curl-md
```

:::

#### Configuration

Claude Code’s built-in web reader is `WebFetch`. Since Claude plugins cannot transparently replace built-in tool results, the curl.md plugin ships a redirect hook that blocks `WebFetch` and tells Claude to retry with curl.md `fetch` using the same URL.

| Option              | Type      | Default | Description                                                                                                                           |
| ------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `webfetch_redirect` | `boolean` | `true`  | Redirect Claude’s built-in `WebFetch` tool and tell Claude to retry with curl.md `fetch`, mapping the original prompt to `objective`. |

:::note
By default, the plugin redirects Claude’s built-in `WebFetch` to curl.md `fetch`. If you want to turn that redirect off, add the plugin option to your Claude settings:

```json title="~/.claude/settings.json"
{
  "pluginConfigs": {
    "curl-md@curl-md": {
      "options": {
        "webfetch_redirect": false
      }
    }
  }
}
```

Claude also prompts for `webfetch_redirect` when configuring the plugin, and exposes the saved value to the redirect hook automatically.

:::

#### Usage

Ask for a page, paste links, or let Claude figure out what it needs to fetch.

##### Prompting

Inside Claude, prompt like you normally would, for example:

```text
Read the Cloudflare Agents docs and summarize the core concepts.
https://developers.cloudflare.com/agents
```

In this example, Claude will use curl.md to fetch the page and return markdown optimized for agents.

You can also tell Claude to use a specific [objective](/docs/guide/api.md#objective), [keywords](/docs/guide/api.md#keywords), or let it decide what to use on its own (it’s really good at this).

##### Authentication

The plugin uses the same auth model as the [CLI](/docs/guide/cli.md#authentication). Log in to connect the plugin to your curl.md account or organization:

```sh
$ curl.md auth login
```

For non-interactive environments, set [`CURLMD_API_KEY`](/docs/guide/cli.md#environment-variables).

##### Skills

After installing, Claude registers the following slash skill:

| Skill            | Description                                      |
| ---------------- | ------------------------------------------------ |
| `/curl-md:fetch` | Explicitly tells Claude to use the `fetch` tool. |

##### Tools

The plugin also registers the following tool:

| Tool    | Description              |
| ------- | ------------------------ |
| `fetch` | Fetch a URL as markdown. |

The `fetch` tool accepts the following inputs:

| Input        | Type             | Description                                                                          |
| ------------ | ---------------- | ------------------------------------------------------------------------------------ |
| `url`        | `string`         | HTTP(S) URL or bare domain to fetch. Prefer the canonical docs or article URL.       |
| `objective?` | `string`         | Specific question to answer from the page. Use when only part matters.               |
| `keywords?`  | `string[]`       | Keywords to focus extraction on relevant sections.                                   |
| `mode?`      | `rush` / `smart` | Use `rush` for speed or `smart` for better section selection on long or noisy pages. |
| `fresh?`     | `boolean`        | Bypass cache when freshness matters.                                                 |

##### Status/Debugging

If you want to confirm Claude loaded the plugin correctly:

```sh
/mcp
/skills
```

You should see the `fetch` MCP tool and the `/curl-md:fetch` skill.

#### Contributing

We welcome improvements to make the Claude plugin better. Feel free to create issues or pull requests [on GitHub](https://github.com/wevm/curl.md) if there are issues or something could be improved.

## /docs/plugins/codex.md

Install and use curl.md with Codex

### Codex

curl.md doesn’t have a first-party Codex plugin yet. In the meantime, we recommend adding the [curl.md skills](/docs/skills.md) to your agent instead.

```sh
$ npx skills add https://curl.md --agent codex --yes
```

:::tip[Contributions welcome]
If you use Codex and would like to contribute the curl.md Codex plugin, check out the [Contributing Guide](/docs/dev/develop.md) and open a [pull request](https://github.com/wevm/curl.md).

If it meets the quality bar (please no slop) and is merged, we will give you **$100 in curl.md credits**. That’s _a lot_ of requests.
:::

## /docs/plugins/cursor.md

Install and use curl.md with Cursor

### Cursor

curl.md doesn’t have a first-party Cursor plugin yet. In the meantime, we recommend adding the [curl.md skills](/docs/skills.md) to your agent instead.

```sh
$ npx skills add https://curl.md --agent cursor --yes
```

:::tip[Contributions welcome]
If you use Cursor and would like to contribute the curl.md Cursor plugin, check out the [Contributing Guide](/docs/dev/develop.md) and open a [pull request](https://github.com/wevm/curl.md).

If it meets the quality bar (please no slop) and is merged, we will give you **$100 in curl.md credits**. That’s _a lot_ of requests.
:::

## /docs/plugins/opencode.md

Install and use curl.md with OpenCode

### OpenCode

First-party [OpenCode](https://opencode.ai) plugin that adds curl.md support to the built-in `webfetch` tool as well as a specific `curl_md` tool.

- [@curl.md/opencode](https://www.npmjs.com/package/@curl.md/opencode)
- [Source code](https://github.com/wevm/curl.md/tree/main/plugins/opencode)

#### Quick Start

Install the plugin, launch OpenCode, and start curling.

::::steps

##### Install plugin

Install the [`@curl.md/opencode`](https://www.npmjs.com/package/@curl.md/opencode) package with OpenCode:

```sh
$ opencode plugin -g @curl.md/opencode
```

This adds `@curl.md/opencode` to your OpenCode config so OpenCode installs it automatically at startup.

##### Start OpenCode

Run OpenCode just like you normally do.

```sh
$ opencode
```

##### Use OpenCode

Now that OpenCode is running with the curl.md plugin, all you need to do is use OpenCode. To confirm everything is set up, try this out:

```text
Read the curl.md OpenCode plugin docs and summarize how it works.
https://curl.md/docs/plugins/opencode
```

OpenCode will automatically use curl.md to turn URLs (you give it or it decides to fetch on its own) into markdown.

:::tip
Optionally, [authenticate](#authentication) with the [`curl_md_login`](#commands) command to unlock higher usage limits and features, like [objective extraction](/docs/guide/features.md#objective-based-narrowing).
:::
::::

#### Install

Install the [`@curl.md/opencode`](https://www.npmjs.com/package/@curl.md/opencode) npm package with OpenCode:

```sh
$ opencode plugin -g @curl.md/opencode
```

If you want to install it only for the current project instead of your global OpenCode config, use:

```sh
$ opencode plugin @curl.md/opencode
```

If you prefer to edit config manually, add the package to your `opencode.json`:

```json title="~/.config/opencode/opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@curl.md/opencode"]
}
```

To update an existing install, rerun the plugin install command with `--force`.

```sh
$ opencode plugin -g @curl.md/opencode --force
```

#### Configuration

| Option     | Type      | Default | Description                                                |
| ---------- | --------- | ------- | ---------------------------------------------------------- |
| `webfetch` | `boolean` | `true`  | Override built-in `webfetch` so it routes through curl.md. |

:::note
By default, the plugin overrides the built-in `webfetch` tool to ensure maximum curl.md usage. If you want to keep `curl_md`, but disable the built-in `webfetch` override, pass a plugin option:

```json title="~/.config/opencode/opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    [
      "@curl.md/opencode",
      {
        "webfetch": false
      }
    ]
  ]
}
```

:::

#### Usage

Ask for a page, paste links, or let OpenCode figure out what it needs to fetch.

##### Prompting

Inside OpenCode, prompt like you normally would, for example:

```text
Read the Cloudflare Agents docs and summarize the core concepts.
https://developers.cloudflare.com/agents
```

In this example, OpenCode will use curl.md to fetch the page and return markdown optimized for agents.

You can also tell OpenCode to use a specific [objective](/docs/guide/api.md#objective), [keywords](/docs/guide/api.md#keywords), or let it decide what to use on its own (it’s really good at this).

##### Authentication

Authenticate inside OpenCode to connect the plugin to your curl.md account or organization:

```text
/curl_md_login
```

The plugin uses the same auth model as the [CLI](/docs/guide/cli.md#authentication) so you can also use the `auth login` command.

```sh
$ curl.md auth login
```

For non-interactive environments, set [`CURLMD_API_KEY`](/docs/guide/cli.md#environment-variables).

##### Commands

After installing, OpenCode registers the following commands:

| Command          | Description          |
| ---------------- | -------------------- |
| `curl_md_login`  | Log in.              |
| `curl_md_logout` | Log out.             |
| `curl_md_org`    | Switch organization. |
| `curl_md_status` | Show status.         |

##### Tools

The plugin registers the following tools:

| Tool       | Description                                         |
| ---------- | --------------------------------------------------- |
| `curl_md`  | Fetch a URL as markdown.                            |
| `webfetch` | Overrides built-in `webfetch` with markdown output. |

The `curl_md` tool accepts the following inputs:

| Input      | Type     | Description                                                                    |
| ---------- | -------- | ------------------------------------------------------------------------------ |
| `url`      | `string` | HTTP(S) URL or bare domain to fetch. Prefer the canonical docs or article URL. |
| `options?` | `object` | Optional fetch settings.                                                       |

The `options` object accepts the following inputs:

| Input        | Type             | Description                                                                          |
| ------------ | ---------------- | ------------------------------------------------------------------------------------ |
| `objective?` | `string`         | Specific question to answer from the page. Use when only part matters.               |
| `keywords?`  | `string[]`       | Keywords to focus extraction on relevant sections.                                   |
| `mode?`      | `rush` / `smart` | Use `rush` for speed or `smart` for better section selection on long or noisy pages. |
| `fresh?`     | `boolean`        | Bypass cache when freshness matters.                                                 |

##### Status/Debugging

Use the `/curl_md_status` command to confirm auth state, tool registration, and CLI availability.

```text
/curl_md_status
```

#### Contributing

We welcome contributions to make the OpenCode plugin better. Feel free to create issues or pull requests [on GitHub](https://github.com/wevm/curl.md) if there are issues or something could be improved.

## /docs/plugins/pi.md

Install and use curl.md with Pi

### Pi

First-party [Pi](https://pi.dev) extension that adds `curl.md` auth and management commands plus `read_web_page` and `curl_md` tools.

- [@curl.md/pi](https://www.npmjs.com/package/@curl.md/pi)
- [Source code](https://github.com/wevm/curl.md/tree/main/plugins/pi)

#### Quick Start

Install the extension, launch Pi, and start curling.

::::steps

##### Install extension

Install the [`@curl.md/pi`](https://www.npmjs.com/package/@curl.md/pi) package with Pi:

```sh
$ pi install npm:@curl.md/pi
```

##### Start Pi

Run Pi just like you normally do.

```sh
$ pi
```

##### Use Pi

Now that Pi is running with the curl.md extension, all you need to do is use Pi. To confirm everything is set up, try this out:

```text
Read the curl.md Pi extension docs and summarize how it works.
https://curl.md/docs/plugins/pi
```

Pi will automatically use curl.md to turn URLs (you give it or it decides to fetch on its own) into markdown.

:::tip
Optionally, [authenticate](#authentication) with the [`curl_md_login`](#commands) command to unlock higher usage limits and features, like [objective extraction](/docs/guide/features.md#objective-based-narrowing).
:::

::::

#### Install

Install the [`@curl.md/pi`](https://www.npmjs.com/package/@curl.md/pi) npm package with Pi:

```sh
$ pi install @curl.md/pi
```

:::note
When the `@curl.md/pi` package is updated, Pi will ask if you want to update to the latest version.
:::

If you prefer to edit config manually, add the extension to your Pi settings:

```json title="~/.pi/agent/settings.json"
{
  "packages": ["npm:@curl.md/pi"]
}
```

Test without installing:

```sh
$ pi -e npm:@curl.md/pi
```

To update:

```sh
$ pi update npm:@curl.md/pi
```

#### Usage

Ask for a page, paste links, or let Pi figure out what it needs to fetch.

##### Prompting

Inside Pi, prompt like you normally would, for example:

```text
Read the Cloudflare Agents docs and summarize the core concepts.
https://developers.cloudflare.com/agents
```

In this example, Pi will use curl.md to fetch the page and return markdown optimized for agents.

You can also tell Pi to use a specific [objective](/docs/guide/api.md#objective), [keywords](/docs/guide/api.md#keywords), or let it decide what to use on its own (it’s really good at this).

##### Authentication

Authenticate inside Pi to connect the extension to your curl.md account or organization:

```text
/curl_md_login
```

The extension uses the same auth model as the [CLI](/docs/guide/cli.md#authentication) so you can also use the `auth login` command.

```sh
$ curl.md auth login
```

For non-interactive environments, set [`CURLMD_API_KEY`](/docs/guide/cli.md#environment-variables).

##### Commands

After installing, Pi registers the following commands:

| Command          | Description          |
| ---------------- | -------------------- |
| `curl_md_login`  | Log in.              |
| `curl_md_logout` | Log out.             |
| `curl_md_org`    | Switch organization. |
| `curl_md_status` | Show status.         |

##### Tools

The plugin also registers the following tools:

| Tool            | Description                              |
| --------------- | ---------------------------------------- |
| `curl_md`       | Compatibility alias for `read_web_page`. |
| `read_web_page` | Fetch a URL as markdown.                 |

Both `read_web_page` and the `curl_md` alias accept the following inputs:

| Input        | Type             | Description                                                                          |
| ------------ | ---------------- | ------------------------------------------------------------------------------------ |
| `url`        | `string`         | HTTP(S) URL or bare domain to fetch. Prefer the canonical docs or article URL.       |
| `objective?` | `string`         | Specific question to answer from the page. Use when only part matters.               |
| `keywords?`  | `string[]`       | Keywords to focus extraction on relevant sections.                                   |
| `mode?`      | `rush` / `smart` | Use `rush` for speed or `smart` for better section selection on long or noisy pages. |
| `fresh?`     | `boolean`        | Bypass cache when freshness matters.                                                 |

##### Status/Debugging

Use the `curl_md_status` command to confirm auth state, tool registration, and CLI availability.

```text
/curl_md_status
```

#### Contributing

We welcome contributions to make the Pi extension better. Feel free to create issues or pull requests [on GitHub](https://github.com/wevm/curl.md) if there are issues or something could be improved.

## /docs/skills.md

Official curl.md skills ready to integration into your agent

### Skills

Skills are useful when you want your agent to automatically use curl.md when fetching URLs and follow best practices.

#### Quick Start

Install the curl.md skills and CLI, and start curling.

::::steps

##### Install skills

```sh
$ npx skills add https://curl.md --yes
```

##### Install CLI

Optionally, install the CLI (agents love using it).

:::codegroup

```sh [curl]
$ curl -fsSL https://curl.md/install.sh | bash
```

```sh [npm]
$ npm i -g curl.md
```

```sh [bun]
$ bun i -g curl.md
```

:::

If the CLI is not installed, the skills fallback to using `curl`, e.g. `curl curl.md/<url>{:sh}`.

##### Start curling

Start your favorite agent and try this out:

```text
Read the curl.md skills docs and summarize how it works.
https://curl.md/docs/skills
```

Your agent should automatically use curl.md to turn URLs you paste, or URLs it decides to fetch on its own, into markdown.

::::

#### Install

Install the official curl.md skills with:

```sh
$ npx skills add https://curl.md --yes
```

Hosted skills are available at [`https://curl.md/.well-known/skills/index.json`](https://curl.md/.well-known/skills/index.json).

#### Usage

Once the curl.md skills are installed, there’s nothing more to do. Your coding agent should automatically use curl.md to turn URLs you paste, or URLs it decides to fetch on its own, into markdown.

:::important
If your agent is struggling to use curl.md automatically, please [open an issue](https://github.com/wevm/curl.md/issues/new?template=issue.yml) so we can get to the bottom of it.
:::

## /docs/dev/develop.md

Learn the best ways to contribute and get a local development environment running.

### Contributing

Thank you for your interest in contributing to curl.md! We’re building the best way to go from URL to markdown, and we’d love your help.

Use this page to get a local curl.md development environment running and learn how to contribute.

#### Ways To Contribute

We welcome and appreciate any form of contributions, here are some ideas:

- **Bug Reports** Report markdown extraction issues, share performance regressions, or document edge cases
- **Feature Development** Add new agent plugins or site profiles, rules, and extraction methods.
- **Documentation** Add new guides or improve areas that were difficult to understand.
- **Testing** Improve test coverage, create performance benchmarks, or level up plugin tests.
- **Infrastructure** Improve build and CI systems, or maintain compat with other tools.

You can also check out [GitHub issues](https://github.com/wevm/curl.md/issues) for good first issues.

#### Prerequisites

- [OrbStack](https://orbstack.dev) for local Docker support on macOS
- Node.js and `pnpm` for local tools

#### Local Setup

:::steps

##### Install and start OrbStack

OrbStack provides the local Docker runtime used by curl.md on macOS.

```sh
$ orb start
```

##### Copy the environment file

And fill out any missing env vars.

```sh
$ cp .env.example .env
```

##### Start the app with Docker Compose

You can also run the `pnpm dev` script.

```sh
$ docker compose up -d
```

##### Open curl.md locally

Open [https://curl.local](https://curl.local) or request a page directly:

```sh
$ curl curl.local/example.com
```

:::

#### Dev Workflow

The app runs inside Docker during local development.

```sh
$ docker compose up
$ docker logs curl -f
```

#### Local Package Scripts

Use these scripts to exercise the shipped CLI and plugin entrypoints against your local app at `https://curl.local`.

```sh
$ pnpm md example.com
$ pnpm plugin amp
```

- `pnpm md` runs the local CLI against `https://curl.local`
- `pnpm plugin [name]` runs agent plugin locally. You can also run short versions: `pnpm amp`, `pnpm opencode`, `pnpm pi`, etc.

#### Testing

Use scoped Vitest projects while iterating, then run the broader set that matches your change.

```sh
$ pnpm test --project cli
$ pnpm test --project plugins:pi
$ pnpm test --project app --project md --project workers
```

When working on browser behavior, run browser or E2E coverage as needed:

```sh
$ pnpm test --project browser
$ pnpm test:e2e
```

#### Checks

Run these before opening a PR:

```sh
$ pnpm check
$ pnpm check:types
```

If you changed dependencies in `cli/` or `plugins/`, also run:

```sh
$ pnpm check:deps
```

#### DB Migrations

When you change the schema, create a migration, apply it locally, then regenerate database types.

```sh
$ pnpm db:make your_migration_name
$ pnpm db:migrate latest
$ pnpm db:codegen
```

Use a descriptive snake_case migration name.

#### Changesets

If your change affects a published package or release notes, add a changeset.

```sh
$ pnpm changeset
```

That creates a markdown file in `.changeset/` where you select the package and bump type.

Docs-only or purely local dev changes usually do not need a changeset.

#### Docs

Docs live in `docs/` and are rendered through the `src/docs/` route in app.

If you add or update docs, make sure the sidebar in `docs/_sidebar.ts` stays in sync.

## /docs/dev/deploy.md

Production and preview deployment notes for curl.md.

### Deploy

`curl.md` deploys on Cloudflare Workers and uses GitHub Actions for production and preview environments.

:::note
This guide is mostly for the team working on `curl.md` itself. If you are self-hosting, you can still adapt the same patterns for your own Cloudflare, database, auth, and CI setup.
:::

#### Production

Production requires configuration across a few systems:

- Cloudflare for Workers, routes, KV, queues, and related services
- PlanetScale Postgres for the database
- GitHub Environments and Actions secrets for CI-driven deploys
- Stripe and GitHub OAuth for billing and auth flows

##### GitHub Actions Secrets

Secrets are managed via [GitHub Environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) and repo-level secrets.

[**Repository secrets**](https://github.com/wevm/curl.md/settings/secrets/actions) - shared across all environments:

| Name                           | Purpose                                                                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `CLOUDFLARE_ACCOUNT_ID`        | Cloudflare account ID. Used by CI, deploys, and Browser Rendering fallback at runtime.                                       |
| `CLOUDFLARE_API_TOKEN`         | Cloudflare API token for deploys and admin scripts. See [Creating a Cloudflare API Token](#creating-a-cloudflare-api-token). |
| `CLOUDFLARE_BROWSER_API_TOKEN` | Cloudflare Browser Rendering runtime token. Scope it to `Browser Rendering - Edit` on the `curl.md` account only.            |
| `COOKIE_SECRET`                | Secret for signing session cookies. Generate with `openssl rand -base64 32`.                                                 |
| `GH_CLIENT_ID`                 | GitHub App client ID. See [GitHub App Setup](#github-app-setup).                                                             |
| `GH_CLIENT_SECRET`             | GitHub App client secret. See [GitHub App Setup](#github-app-setup).                                                         |
| `SENTRY_DSN`                   | Sentry DSN for error tracking. See [Sentry](#sentry).                                                                        |
| `SENTRY_AUTH_TOKEN`            | Sentry auth token for release creation and source map uploads. See [Sentry](#sentry).                                        |
| `TOKEN_ENCRYPTION_KEY`         | Base64-encoded 256-bit key for encrypting OAuth tokens. Generate with `openssl rand -base64 32`.                             |

**[`production`](https://github.com/wevm/curl.md/settings/environments/12871461617/edit) environment secrets**:

| Name                    | Purpose                                                           |
| ----------------------- | ----------------------------------------------------------------- |
| `DB_URL`                | PlanetScale Postgres connection string for production migrations. |
| `STRIPE_SECRET_KEY`     | Stripe live secret key. See [Stripe Setup](#stripe-setup).        |
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret. See [Stripe Setup](#stripe-setup). |

**[`production`](https://github.com/wevm/curl.md/settings/environments/12871461617/edit) environment variables**:

| Name                     | Purpose                                                                         |
| ------------------------ | ------------------------------------------------------------------------------- |
| `STRIPE_PUBLISHABLE_KEY` | Stripe live publishable key (`pk_live_...`). See [Stripe Setup](#stripe-setup). |

##### PlanetScale

1. Create a [PlanetScale](https://planetscale.com) account and organization.
2. Create a new database with the **Postgres** engine:

   ```bash
   pscale database create curl --region <REGION_SLUG> --engine postgres
   ```

3. Create two roles on the `main` branch.
   - **App role** for Hyperdrive and production. Select `pg_read_all_data` and `pg_write_all_data`.
   - **Migrations role** for CI. Select `postgres` for full DDL access used by `kysely migrate`.

4. Record the connection strings: `postgres://<user>:<password>@<host>:5432/postgres?sslmode=require`.
5. Connect to Cloudflare Workers via the [PlanetScale Hyperdrive integration](https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/planetscale-postgres/) and copy the Hyperdrive ID into `wrangler.jsonc` under `env.production.hyperdrive[0].id`.

##### Creating a Cloudflare API Token

1. Go to [Cloudflare API Tokens](https://dash.cloudflare.com/?to=/:account/api-tokens).
2. Click “Create Token”.
3. Select “Create Custom Token”.
4. Add these permissions.
   - **Account** -> **Browser Rendering** -> **Edit**
   - **Account** -> **Workers AI** -> **Edit**
   - **Account** -> **Queues** -> **Edit**
   - **Account** -> **Hyperdrive** -> **Edit**
   - **Account** -> **Workers KV Storage** -> **Edit**
   - **Account** -> **Workers Scripts** -> **Edit**
   - **Zone** -> **Zone WAF** -> **Edit**
   - **Zone** -> **Workers Routes** -> **Edit**

5. Set Account Resources to your account.
6. Set Zone Resources to your domain, for example `curl.md`.
7. Click “Continue to summary” and then “Create Token”.

Create a second Cloudflare token for Browser Rendering runtime access:

1. Create another custom token.
2. Add **Account** -> **Browser Rendering** -> **Edit** only.
3. Scope it to the `curl.md` account.
4. Save it as `CLOUDFLARE_BROWSER_API_TOKEN` in GitHub Actions secrets and your local `.env`.

##### GitHub App Setup

1. Go to [GitHub Developer Settings -> GitHub Apps](https://github.com/organizations/wevm/settings/apps).
2. Click “New GitHub App”.
3. Fill in:
   - **GitHub App name**: `curl.md`
   - **Homepage URL**: `https://curl.md`
   - **Callback URL**: `https://curl.md/api/auth/github/callback`
   - Check “Expire user authorization tokens”
   - Check “Enable Device Flow” for CLI authentication
   - Uncheck “Active” under Webhook

4. Under Permissions, set **Account permissions** -> **Email addresses** -> **Read-only**.
5. Click “Create GitHub App”.
6. Copy the **Client ID** into `GH_CLIENT_ID`.
7. Generate a new client secret and copy it into `GH_CLIENT_SECRET`.

##### Stripe Setup

Stripe powers prepaid credit billing. A single Stripe account is used with test mode for development and live mode for production.

1. Go to [Stripe Dashboard](https://dashboard.stripe.com).
2. Copy your **Publishable key** from [API keys](https://dashboard.stripe.com/apikeys) into `STRIPE_PUBLISHABLE_KEY`.
3. Copy your **Secret key** from [API keys](https://dashboard.stripe.com/apikeys) into `STRIPE_SECRET_KEY`.
4. Set the callback webhook URL and get the webhook secret.
   - Go to [Webhooks](https://dashboard.stripe.com/webhooks) and click “Add endpoint”.
   - Set URL to `https://curl.md/api/stripe/webhook`.
   - Select events: `payment_intent.succeeded`, `charge.dispute.created`, `refund.created`.
   - Copy the signing secret into `STRIPE_WEBHOOK_SECRET`.

##### Sentry

Error tracking covers server-side Workers, the Hono API, and the React client. CI also uploads production and preview source maps to Sentry during `pnpm build`.

The app uses these Sentry values:

| Name                | Where it is used                                  | Required                  |
| ------------------- | ------------------------------------------------- | ------------------------- |
| `SENTRY_DSN`        | Worker runtime, browser client, and tunnel target | Yes                       |
| `SENTRY_AUTH_TOKEN` | Build-time release creation and source map upload | Yes for source maps       |
| `SENTRY_ORG`        | Build-time source map upload                      | No, defaults to `wevm`    |
| `SENTRY_PROJECT`    | Build-time source map upload                      | No, defaults to `curl_md` |

1. Create a [Sentry project](https://sentry.io/projects/new/) for JavaScript / Cloudflare.
2. Copy `SENTRY_DSN` from [Project Settings -> Client Keys (DSN)](https://sentry.io/settings/projects/).
3. Create `SENTRY_AUTH_TOKEN` from [Settings -> Developer Settings -> Auth Tokens](https://sentry.io/settings/account/api/auth-tokens/).
   - Use an Organization Auth Token if available.
   - Required permissions: `org:read` and `project:releases`.
   - A Personal Token also works with **Project: Read & Write** and **Release: Admin** permissions.
4. Add `SENTRY_DSN` and `SENTRY_AUTH_TOKEN` as GitHub repository secrets.

`SENTRY_ORG` and `SENTRY_PROJECT` are hardcoded to `wevm` and `curl_md` in `vite.config.ts`. Override them only when self-hosting or uploading to a different Sentry project.

If `SENTRY_AUTH_TOKEN` is missing, builds still pass, but Sentry releases and source maps are not uploaded.

##### HTTPS Enforcement

Keep Cloudflare's blanket HTTP-to-HTTPS redirect off so bare `curl curl.md/<url>` requests reach the Worker. The Worker serves unauthenticated URL-fetch paths over HTTP and redirects all other HTTP routes to HTTPS.

1. Go to [Edge Certificates](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/edge-certificates) for the `curl.md` zone.
2. Disable [Always Use HTTPS](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/always-use-https/).
3. Enable [HTTP Strict Transport Security (HSTS)](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/http-strict-transport-security/).
4. Use these HSTS settings.
   - **Max Age Header**: `6 months`
   - **Apply HSTS policy to subdomains**: `off`
   - **Preload**: `off`
   - **No-Sniff Header**: `on`

Keep `includeSubDomains` off unless every current and future `*.curl.md` hostname should be HTTPS-only. Preview environments use `*.curl.md` custom domains, so enabling `includeSubDomains` would apply HSTS to them too.

##### WWW Redirect

Redirect `www.curl.md` to `curl.md` via [Bulk Redirects](https://developers.cloudflare.com/rules/url-forwarding/bulk-redirects/).

1. Go to [DNS Records](https://dash.cloudflare.com/?to=/:account/:zone/dns/records) for the `curl.md` zone.
2. Add a proxied A record: `www` -> `192.0.2.1`.
3. Go to [Bulk Redirects](https://dash.cloudflare.com/?to=/:account/bulk-redirects).
4. Create a bulk redirect list with `www.curl.md` -> `https://curl.md` using a 301, preserve query string, subpath matching, and preserve path suffix.

#### Preview

Preview environments deploy per PR with isolated PlanetScale database branches and Cloudflare Hyperdrive configs. On PR close or draft, cleanup deletes the Worker, Hyperdrive config, PlanetScale branch, KV namespace, Queues, and Stripe webhook. A daily sweep catches orphans.

##### GitHub Environments

Preview secrets are scoped via [GitHub Environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment).

**[`preview`](https://github.com/wevm/curl.md/settings/environments/12873481464/edit) environment secrets**:

| Name                           | Purpose                                                                            |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| `PLANETSCALE_SERVICE_TOKEN`    | PlanetScale service token. See [PlanetScale Branching](#planetscale-branching).    |
| `PLANETSCALE_SERVICE_TOKEN_ID` | PlanetScale service token ID. See [PlanetScale Branching](#planetscale-branching). |
| `PLANETSCALE_ORG`              | PlanetScale organization slug, for example `wevm`.                                 |
| `PLANETSCALE_DB`               | PlanetScale database name, same as production, for example `curl`.                 |
| `STRIPE_SECRET_KEY`            | Stripe test mode secret key. See [Preview Stripe](#preview-stripe).                |

**[`preview`](https://github.com/wevm/curl.md/settings/environments/12873481464/edit) environment variables**:

| Name                     | Purpose                                           |
| ------------------------ | ------------------------------------------------- |
| `STRIPE_PUBLISHABLE_KEY` | Stripe test mode publishable key (`pk_test_...`). |

##### PlanetScale Branching

1. Create a [service token](https://app.planetscale.com/~/settings/service-tokens) in PlanetScale with the following access on your database.
   - `create_branch`
   - `delete_branch`
   - `read_branch`
   - `connect_branch`

2. Add these secrets to the `preview` environment.

   | Name                           | Purpose                                                     |
   | ------------------------------ | ----------------------------------------------------------- |
   | `PLANETSCALE_SERVICE_TOKEN`    | The token value.                                            |
   | `PLANETSCALE_SERVICE_TOKEN_ID` | The token ID.                                               |
   | `PLANETSCALE_ORG`              | Your PlanetScale organization slug, for example `wevm`.     |
   | `PLANETSCALE_DB`               | Your database name, same as production, for example `curl`. |

##### Preview Stripe

Preview environments use Stripe test mode keys so no real charges occur.

1. Copy your **test mode** secret key from [API keys](https://dashboard.stripe.com/test/apikeys).
2. Add `STRIPE_SECRET_KEY` to the `preview` environment.