# clawd.html

> Publish HTML pages from your terminal or an agent and get a clean, sandboxed
> share link. Same visibility, workspace, and expiry options as the web app.

Human docs: https://clawd-html-puce.vercel.app/docs
npm package: https://www.npmjs.com/package/@avr00/clawd-html
API base URL: https://clawd-html-puce.vercel.app

## Authentication

Create a token at https://clawd-html-puce.vercel.app/app/settings (Settings -> API tokens). It is shown
once. Send it as: `Authorization: Bearer clawd_live_...`

CLI token resolution order: `--token` flag, then `CLAWD_TOKEN` env var,
then `~/.config/clawd/config.json`.

## CLI

Install: `npm i -g @avr00/clawd-html` (command is `clawd`).

- `clawd publish [input]` — create a page. `input` is a file (single HTML),
  a directory (multi-file bundle), or omitted to read stdin. Options: `-t/--title`,
  `-v/--visibility <private|workspace|unlisted|public>` (default unlisted),
  `-w/--workspace <slug>`, `-e/--expires <never|12h|7d|...>`, `--json`.
  Prints the share URL to stdout. For bundles, the URL is the entry point
  (`index.html` if present); other files are at `/v/<slug>/<path>`.
- `clawd update <slug> [input]` — edit an existing page. A file replaces just
  `index.html` (keeping other bundle files). A directory replaces the whole
  bundle. Same flags as `publish` (all optional). Pass an empty string to
  `-w`/`-f` to remove from workspace/folder.
- `clawd files <slug>` — list files in a bundle.
- `clawd list [--json]` — list your pages.
- `clawd get <slug> [--json]` — print a page's HTML, or metadata with --json.
- `clawd rm <slug>` — delete a page.
- `clawd whoami [--json]` — show the token's account.
- `clawd login [token]` — save a token to the config file.
- `clawd folder create <name>` — create a folder (-v visibility, -w workspace, -e expires).
- `clawd folder list [--json]` — list your folders.
- `clawd folder get <slug> [--json]` — list the pages in a folder.
- `clawd folder rm <slug>` — delete a folder (its pages are kept).
- `clawd publish --folder <slug>` — publish a page straight into a folder.

Behavior: messages on stderr, URL/JSON on stdout, non-zero exit on error.

Example:
```
export CLAWD_TOKEN=clawd_live_...
cat index.html | clawd publish --title "My page" --visibility unlisted
clawd folder create "Weekly analyses" --visibility unlisted
cat week-1.html | clawd publish --title "Week 1" --folder weekly-analyses
```

## HTTP API

Base: https://clawd-html-puce.vercel.app — all JSON, Bearer auth.

- `GET /api/v1/me` — verify token, return owner.
- `GET /api/v1/pages` — list your pages.
- `POST /api/v1/pages` — create. Body: either `content` (HTML string) OR
  `files` (array of `{ path, content }` for multi-file bundles), plus
  `title`, `visibility`, `workspaceSlug`, `expiresInHours`. Returns
  `{ id, slug, url, visibility, entryPath }`. Bundle limits: 64 files, 400KB
  per file, 1MB total. Allowed: .html .htm .css .js .mjs .svg .json .txt.
- `GET /api/v1/pages/:slug` — fetch a page including content.
- `GET /api/v1/pages/:slug/files` — list files in a bundle.
- `PATCH /api/v1/pages/:slug` — edit a page. Body: any subset of the POST
  fields. `content` replaces just index.html; `files` replaces the whole
  bundle. `workspaceSlug`, `folderSlug`, and `expiresInHours` accept
  `null` to clear. Returns `{ updated, id, slug, url }`.
- `DELETE /api/v1/pages/:slug` — delete a page.
- `GET /api/v1/folders` — list your folders.
- `POST /api/v1/folders` — create. Body: `name` (required), `visibility`,
  `workspaceSlug`, `expiresInHours`. Returns `{ id, slug, url, visibility }`.
- `GET /api/v1/folders/:slug` — fetch a folder and the pages inside it.
- `DELETE /api/v1/folders/:slug` — delete a folder (its pages are kept).

A shared folder grants access to every page inside it — even individually
private pages — so one link shares the whole set.

Example:
```
curl -X POST https://clawd-html-puce.vercel.app/api/v1/pages \
  -H "Authorization: Bearer clawd_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","content":"<h1>hi</h1>","visibility":"unlisted"}'
```

## Visibility

- private: only you. Not indexed. Cannot be in a workspace.
- workspace: you + workspace members. Not indexed.
- unlisted: anyone with the link. Not indexed.
- public: anyone with the link. Indexed by search engines.

Expiry is optional; expired links stop being viewable.

## Agent skill

We also publish an installable agent skill (skills.sh ecosystem) at
https://clawd-html-puce.vercel.app/.well-known/agent-skills/index.json. Install into any supported agent
(Claude Code, Cursor, Codex, ...):

```
npx skills add https://clawd-html-puce.vercel.app
```

## MCP server

Streamable HTTP MCP server at https://clawd-html-puce.vercel.app/mcp. Same Bearer-token auth as the CLI.
Exposes nine tools mirroring the REST API: clawd_me, clawd_list_pages,
clawd_create_page, clawd_get_page, clawd_delete_page, clawd_list_folders,
clawd_create_folder, clawd_get_folder, clawd_delete_folder.

```
claude mcp add clawd https://clawd-html-puce.vercel.app/mcp --header "Authorization: Bearer clawd_live_..."
```