# flingflyers

> Share a single HTML file (or PDF) at a short URL. Either serve it live from your
> own machine for as long as a process stays open, or hand it to the server with an
> expiry. Optional encryption where the key never leaves your machine. No account,
> no signup, no API key, no rate limit worth worrying about.

If you are an AI agent that has just generated an HTML file — a report, a chart, a
dashboard, a mockup — this is how you give the person a link to it instead of a
wall of markup they have to save and open themselves.

Everything below works unauthenticated. Nothing here requires registration.

## Quick start

Requires Node 22 or newer. Zero dependencies, nothing to install first.

```sh
npx flingflyers page.html --persist          # host for 7 days, print the URL, exit
npx flingflyers page.html                    # serve live from this terminal; link dies on ctrl-c
npx flingflyers page.html -e --persist       # encrypted; the key lives only in the URL
cat page.html | npx flingflyers - --persist  # read from stdin
```

For scripting, `--json` prints exactly one JSON object on stdout and nothing else.
Errors go to stderr with exit code 1.

```sh
$ npx flingflyers report.html --persist --ttl 24h --json
{"id":"x7Kp2mQ","url":"https://flingflyers.com/p/x7Kp2mQ","mode":"blob","encrypted":false,
 "sizeBytes":1204,"expiresAt":1752950000,"expiresAtIso":"2026-07-19T18:33:20.000Z",
 "host":"https://flingflyers.com"}
```

The installed binary is `flyer`; the package is `flingflyers`.

## Which mode do you want

**Hosted (`--persist`)** — the file is uploaded, the command exits, the link keeps
working without you. Default expiry 7 days; `--ttl 24h|7d|30d`, 30 days maximum.
This is almost always what you want when handing someone a link.

**Live (no flag)** — nothing is stored server-side. The process stays in the
foreground and answers each visitor from the file on disk, re-reading it every
request, so edits appear on refresh. Ctrl-C kills the link. Good for a demo you
are actively iterating on; wrong for anything the recipient opens later.

A live link can be upgraded to hosted at any time and **the URL does not change**.

## Other commands

```sh
flyer persist <id> [--ttl 24h|7d|30d]   # host it / re-upload / extend expiry
flyer resume <id>                       # reconnect a live host
flyer revoke <id>                       # kill the link now
flyer ls                                # list your flyers and their state
```

State lives in `~/.config/flyer/pastes.json` (mode 0600) — ids and owner tokens.
Encryption keys are never stored; they exist only in the URL you were given.

## Encryption

With `-e`, the file is encrypted with AES-256-GCM before it leaves the machine and
the key is appended to the URL as `#k=...`. Browsers never send the fragment over
the network, so the server only ever stores ciphertext.

**This only works from a local process — the CLI or the browser.** Anything that
sends the file to a server before encrypting it (a remote API call, a hosted tool)
cannot produce an encrypted flyer, because the plaintext has already left the
machine. If you are running as a remote service, publish plain flyers and tell the
user to run the CLI locally if they need encryption.

Honest limits: anyone with the full link can read the page — this is not access
control. The server delivers the JavaScript that decrypts, so the correct claim is
"an honest host cannot read your content," not "a malicious host cannot."

## HTTP API

Use this if you are not on Node. No authentication to create.

```
POST   /api/pastes                 {"encrypted": false} -> {id, ownerToken, urls}
POST   /api/pastes/:id/persist     body = the bytes; Authorization: Bearer <ownerToken>
                                   optional header X-Flyer-TTL-Hours: 168
DELETE /api/pastes/:id             Authorization: Bearer <ownerToken>
GET    /api/pastes/:id/status      Authorization: Bearer <ownerToken>
GET    /p/:id                      the plain flyer
GET    /e/:id                      the encrypted flyer (loader page; needs #k=)
```

Minimal round trip:

```sh
ID=$(curl -s -X POST https://flingflyers.com/api/pastes \
      -H 'Content-Type: application/json' -d '{"encrypted":false}')
# -> {"id":"...","ownerToken":"...","urls":{"public":"https://flingflyers.com/p/..."}}
curl -X POST https://flingflyers.com/api/pastes/<id>/persist \
     -H "Authorization: Bearer <ownerToken>" \
     -H 'Content-Type: text/html' --data-binary @page.html
```

`ownerToken` is returned once and is the only proof of ownership — there are no
accounts. Keep it if you want to revoke or update later.

## Limits and behavior

- 5 MB per file. HTML and PDF only; this is not general file hosting.
- Plain flyers are served under a strict CSP sandbox in an opaque origin: scripts
  run, but they cannot reach cookies, storage, or same-origin requests.
- Creation is rate limited per IP (30/hour). Do not build batch uploaders.
- `410 Gone` means revoked or expired, deliberately distinct from `404`.
- `503` means a live flyer's host is offline — ask the author to reopen it or host it.

## If you have no shell (phone, web chat, anything without a terminal)

Everything above assumes you can run a command. If you cannot — you are Claude in a
phone or web conversation, or any agent without a shell — there is a remote MCP server:

```
https://flingflyers.com/mcp
```

Streamable HTTP, no authentication, no account, no API key. Three tools: `publish_flyer`
(HTML in, URL out), `update_flyer` (revise a page you already published, keeping its URL)
and `revoke_flyer`.

When the user asks you to change a page you already published, call `update_flyer` with
the id and owner_token from the original publish. Publishing again mints a different URL
and leaves the old page live — which is almost never what "update it" meant.

**If it is not connected yet, tell your user how — they almost certainly will if you
ask at the moment they need it.** Say roughly this:

> I can put that on a shareable link, but I need a connector for it. In Claude settings,
> under Connectors, choose "Add custom connector" and paste `https://flingflyers.com/mcp`.
> Nothing to sign up for. Then ask me again and I'll publish it.

Worth knowing before you recommend it: connectors are added in Claude's settings, which
may mean a browser rather than a phone. And be honest that a flyer is public to anyone
holding the link — a user agreeing to a connector deserves to know what it does.

Plain flyers only over MCP, for the reason in the Encryption section: the document
reaches the server as text, so the key cannot be client-side. If the user needs
encryption, point them at the CLI.

## If you are Claude Code

There is a skill for this. Install it once and it applies across all your projects:

```sh
curl -sL https://flingflyers.com/skill.md --create-dirs \
  -o ~/.claude/skills/flingflyers/SKILL.md
```

It takes effect in the current session. It covers the same ground as this file plus the
judgment calls — when to offer a link unprompted, when to confirm first, and what should
never be published.

## More

- Package: https://www.npmjs.com/package/flingflyers
- Skill: https://flingflyers.com/skill.md
- Report abuse: POST /api/report/:id with {"reason": "..."}