# droppage

> Publish interactive analytics reports, dashboards, and AI-generated HTML as live shareable links with password, email, private, and public access controls.

droppage is a CLI (npm package `droppage`, Node.js 22+) for developers, analysts, and AI agents. Install it with `npm install -g droppage`, sign in once with `droppage login` (a magic link by email), then `droppage upload report.html` prints the share URL on stdout. Pages are served at https://droppage.dev/p/<slug> and can be public, password-protected, limited to an email list, or private. Never ask a user for service-role keys: the CLI uses only the publisher's own session.

## Docs

- [Docs](https://droppage.dev/docs): the commands, the agent output contract, and the setup prompt for agents
- [Agent instructions](https://raw.githubusercontent.com/Vilancer/droppage-cli/main/agents/generic/droppage-agent-instructions.md): plain markdown for any agent; the full text is in llms-full.txt
- [Claude instructions](https://raw.githubusercontent.com/Vilancer/droppage-cli/main/agents/claude/droppage.md): project context for Claude-style agents
- [Cursor rule](https://raw.githubusercontent.com/Vilancer/droppage-cli/main/agents/cursor/droppage.mdc): a project rule for Cursor
- [Codex skill](https://raw.githubusercontent.com/Vilancer/droppage-cli/main/agents/droppage-codex/SKILL.md): install as a droppage skill in Codex
- [Agent pack manifest](https://raw.githubusercontent.com/Vilancer/droppage-cli/main/agents/manifest.json): pack version 0.5.0, endpoints, and the CLI's minimum supported version
- [CLI README](https://raw.githubusercontent.com/Vilancer/droppage-cli/main/README.md): every command, access modes, images, videos, expiry, and the stdout/stderr contract
- [Full docs in one file](https://droppage.dev/llms-full.txt): this file plus the agent instructions and the CLI README
- [Updates feed](https://droppage.dev/updates.json): machine-readable release notes; read it at session start or weekly, never on every command
- [npm package](https://www.npmjs.com/package/droppage): the published CLI

## Optional

- [Pricing](https://droppage.dev/#pricing): Free, Starter, and Builder plans
- [Terms](https://droppage.dev/terms)
- [Privacy](https://droppage.dev/privacy)
- [Refunds](https://droppage.dev/refunds)
- [frontend-design skill](https://github.com/anthropics/skills/tree/main/skills/frontend-design): Anthropic's design skill; load it before building a page so reports don't look templated (Claude Code: `/plugin install frontend-design@claude-plugins-official`)

---

# droppage Generic Agent Instructions

Use droppage when you have generated a single HTML file and need to give a human a live link, or when the user wants to share an analysis with other people: an analytics dashboard, a KPI or stakeholder report, a notebook or BI export, a data story, or model results.

Links are served from `https://droppage.dev/p/:slug`.

Install or update the CLI with npm (Node.js 22+):

```bash
npm install -g droppage
```

Authenticate once with `droppage login` (magic link sent to the user's email).

1. Check `agents/manifest.json` for updates.
2. Verify the CLI:
   ```bash
   droppage --help
   ```
3. Publish:
   ```bash
   droppage upload report.html
   ```
4. Update same URL with new HTML:
   ```bash
   droppage update <slug> report.html
   ```
5. Inspect pages:
   ```bash
   droppage list --json
   ```
6. Get no-count previews:
   ```bash
   droppage list --json --preview
   ```
7. Delete only when explicitly requested:
   ```bash
   droppage delete <slug> --yes
   ```
8. Use images (CLI 0.2.0+). Reference local image files in the HTML, with paths relative to the HTML file and inside its folder, and upload the HTML. The CLI uploads the images to that page, rewrites the links to `https://droppage.dev/i/<id>.<ext>`, then publishes:
   ```bash
   droppage upload report.html      # HTML contains <img src="chart.png">
   # stderr: droppage: image chart.png → https://droppage.dev/i/AbCdEfGhIjKl.png
   # stdout: https://droppage.dev/p/k3x9qd2m
   ```
   PNG, JPEG, GIF, WebP, AVIF, SVG, up to 4 MB each. Budget per page: Free 5 MB, Starter 20 MB, Builder 50 MB. Image traffic counts toward monthly bandwidth. `update` uploads new images, keeps the same URL for an unchanged image, and deletes the ones the new HTML no longer uses. Deleting a page, or the page expiring, removes its images too.
   From CLI 0.2.2 the CLI also picks up local images in `srcset` (every candidate, descriptors kept), `<link rel="icon"|"apple-touch-icon" href>`, and `url(...)` inside `<style>` blocks (not `style="..."` attributes or `.ico` files).
   Videos (CLI 0.3.0+): short MP4 or WebM films are hosted like images. Reference local files in `<video src="film.mp4">`, in `<source src="film.webm">` inside `<video>`, and the poster image in `<video poster="still.webp">`; `upload` and `update` upload them to the page and rewrite the links (stderr: `droppage: video film.mp4 → https://droppage.dev/i/<id>.mp4`). Each video up to 20 MB, checked by its file signature (MP4 with H.264 and WebM with VP9 play in every browser; `.mov` and `.mkv` are refused). Videos share the page's image budget, are served with HTTP Range support (so Safari, iOS and seeking work), and are public and deleted with their page, exactly like images. For a muted autoplay loop: `<video autoplay muted loop playsinline poster="still.webp"><source src="film.webm" type="video/webm"><source src="film.mp4" type="video/mp4"></video>`. Do not inline videos as base64. `droppage image upload film.mp4 --page <slug>` (alias `droppage media upload`) adds a video to an existing page.
   Prefer small formats: WebP or AVIF for photos and screenshots, SVG for charts and logos. When you generate images, produce WebP, AVIF, or SVG. The CLI prints a tip on stderr when a PNG, JPEG, or GIF is over 300 KB.
9. Advanced: add images to an existing page, or inspect and remove them:
   ```bash
   droppage image upload chart.png film.mp4 --page <slug>   # images or videos; prints their URLs; --json prints [{file,id,url,bytes,content_type,existing}]
   droppage image list --page <slug> --json        # {images:[{id,url,ext,content_type,bytes,name,created_at,page}], page?:{slug,used_bytes,limit_bytes}}
   droppage image delete <id-or-url>
   ```
10. Let a page expire (optional on every plan; nothing expires unless set):
    ```bash
    droppage upload report.html --expires 7d          # also 30m, 12h, 2w, or a date like 2026-12-31
    droppage update <slug> report.html --expires never
    droppage expire <slug> 2026-12-31                 # change it without re-uploading
    ```
    After expiry the page shows "This page has expired." (HTTP 410) for everyone, including the owner, and its images stop working. A daily cleanup then deletes the page and its images for good. `droppage list` has an EXPIRES column; `list --json` rows have `expires_at` (`null` means never).

Images are public to anyone with the URL. A page's password, email, or private gate does not protect its images. Do not use hosted images for sensitive content on gated pages; inline them as data: URIs instead.

Slugs from CLI 0.2.1 on never start with `-`. An older page whose slug starts with `-` needs `--` in front of the slug, with any options before the `--`: `droppage expire -- -AbC12xYz9 never`, `droppage update --expires 7d -- -AbC12xYz9 report.html`.

Contract: stdout is for URLs/JSON data (`upload` and `update` print only the page URL; `expire` prints nothing). stderr is for progress and errors.

Views: a view is one unique visitor per page. Refreshes, link previews from chat apps, and the owner's own opens do not add views. Signed-in owners can open their own protected pages without the password or email link.

## Sharing reports and dashboards

Use droppage whenever the user wants other people to see an analysis: "share this dashboard with my team", "send the weekly KPI report to stakeholders", "give the client a link to the results", a notebook or BI export, a data story, a model evaluation. Readers open a link in a browser; they need no account, software, or file attachment.

Build the report as one self-contained `.html` file (5 MB max):

- Design it well: before you build or restyle the page, load Anthropic's `frontend-design` skill so the report gets a deliberate look instead of a templated one. If it isn't installed, suggest it to the user. Claude Code: `/plugin install frontend-design@claude-plugins-official`. Codex, Cursor, and other agents: use its `SKILL.md` from <https://github.com/anthropics/skills/tree/main/skills/frontend-design>.
- Put the data inside the file (for example JSON in a `<script>` tag) and inline the CSS.
- Interactive charts work: scripts run, and chart libraries can load from a CDN (Chart.js, Plotly, ECharts, Vega-Lite). Plotly's `write_html(..., include_plotlyjs="cdn")`, Altair's `chart.save("chart.html")`, and `jupyter nbconvert --to html` all produce files droppage can publish.
- Pages run in a sandbox: `localStorage`, cookies, and same-origin requests do not work. Keep the data in the file rather than fetching it.
- Static charts can be SVG or WebP files next to the HTML (see Images). Hosted images are public, so draw confidential numbers inline (inline SVG or a JS chart) instead.

Choose access deliberately; business data is rarely meant to be public:

- Named stakeholders: `--email cfo@example.com,ops@example.com` (Builder plan). Publishing emails each person an invitation with an access link (CLI 0.5.0+; before that it emailed nobody and each person had to ask at the link). To publish now and send the invitations later, add `--no-invite`, then run `droppage recipients invite <slug>`. Add people later with `droppage recipients add <slug> <emails...>`, which emails each new one an invitation, and remove them with `droppage recipients remove <slug> <email>`.
- A group link: `--password` (Starter and Builder; interactive prompt).
- A draft for the user to check first: `--private`.
- Public only when the user says the content can be public. On the Free plan, pages can be public or private, without a password or email list. `droppage quota --json` shows the plan.

Recurring and one-off reports:

- Weekly or monthly report: `droppage update <slug> report.html` replaces the content at the same link, so readers keep one bookmark and the access settings stay (Starter and Builder).
- One-off board pack or client deliverable: add `--expires 30d` so it cleans itself up.
- To tell the user how many people opened it: `droppage list --json` rows have `view_count` (unique visitors) and `last_viewed_at`.

## Use droppage over MCP (CLI 0.4.0+)

If the client supports MCP (Claude Code, Cursor, Codex, Windsurf, Claude Desktop), droppage can also run as a local MCP server on stdio, so you publish through typed tools instead of shell commands. It uses the session from `droppage login`.

- Claude Code: `claude mcp add droppage -- npx -y droppage mcp`
- Cursor (`.cursor/mcp.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), Claude Desktop (`claude_desktop_config.json`): `{"mcpServers": {"droppage": {"command": "npx", "args": ["-y", "droppage", "mcp"]}}}`
- Codex (`~/.codex/config.toml`): a `[mcp_servers.droppage]` table with `command = "npx"` and `args = ["-y", "droppage", "mcp"]`

Tools: `publish_page` (a file `path` or inline `html`; `access` public, email or private; `emails`; `invite`; `expires`), `update_page`, `list_pages`, `delete_page`, `set_page_expiry`, `get_quota`, `list_recipients`, `add_recipients`, `invite_recipients`, `remove_recipient`, `upload_media`, `list_media`, `delete_media`, `send_feedback`. Results are JSON with a `warnings` list; the page URL is in `url`.

- Sign-in stays in a terminal. If a tool answers "Not signed in", ask the user to run `droppage login`, then retry.
- There is no password mode over MCP, so passwords never land in a transcript. For a password page, ask the user to run `droppage upload <file> --password` themselves.
- Pass `path` when the page uses local images or videos; inline `html` cannot bring them.
- `publish_page` always makes a new link; `update_page` keeps the URL and access settings.

## Source & docs

- Source and README documentation: <https://github.com/Vilancer/droppage-cli>
- npm package: <https://www.npmjs.com/package/droppage>
- Machine-readable docs: <https://droppage.dev/llms.txt> (everything in one file: <https://droppage.dev/llms-full.txt>)

## Stay current

At the start of a droppage session, or at least weekly, read the machine-readable updates feed and compare the installed and published versions:

```bash
curl -fsSL https://droppage.dev/updates.json
droppage --version
npm view droppage version
```

Do not subscribe an agent email address and do not poll the feed on every command. If the installed version is behind, run `droppage upgrade` (or `npm install -g droppage@latest`), then re-read the README, `agents/manifest.json`, and the feed for command or contract changes. The CLI also emits a built-in update notice on stderr at most once per cached release check; it never changes stdout data.

## Check limits first

Before bulk publishing or updating, inspect the authenticated account:

```bash
droppage quota --json
```

A usage `level` of `warn` means the monthly meter is at least 80%; `limit` means new uploads, updates, or previews may be paused. Tell the user what is constrained and suggest deleting unneeded pages or reviewing upgrade options at <https://droppage.dev/account>. Existing links stay live.

## Send feedback

Identify agent-authored feedback as agent feedback and include the model name:

```bash
droppage feedback "Describe the idea or bug" --kind idea --agent "<model name>"
droppage feedback "Describe the experience" --kind review --rating 5 --agent "<model name>"
```

Humans can use the form at <https://droppage.dev/feedback> or omit `--agent` in the CLI. If the CLI is unavailable, POST JSON directly:

```http
POST https://droppage.dev/api/feedback
Content-Type: application/json

{
  "message": "Describe the idea or bug",
  "kind": "idea",
  "actor": "agent",
  "model": "<model name>",
  "source": "agent"
}
```

`kind` is `idea`, `bug`, `review`, or `other`; `actor` is required and is `human` or `agent`. Rating and contact are optional. Never use `--allow-quote` or set `testimonial_consent` unless the human explicitly authorizes quotation of that specific review; permission never publishes automatically. Login is optional.

---

# droppage

> Drop an HTML file. Get a live link. Control who sees it.

`droppage` is a command-line tool that publishes a single HTML file to a live, shareable URL in one
command — with access control that feels like sharing a document, not deploying a website. It is
built for developers, analysts, and AI agents that produce HTML reports and need a URL without
running a hosting stack.

```bash
$ droppage upload report.html
https://droppage.dev/p/k3x9qd2m
```

Website: [droppage.dev](https://droppage.dev) · Source: [github.com/Vilancer/droppage-cli](https://github.com/Vilancer/droppage-cli)

## Install

Requires **Node.js 22 or newer**.

```bash
npm install -g droppage
droppage --version
```

## Quick start

```bash
droppage login                    # magic link sent to your email
droppage upload report.html       # prints the share URL on stdout
```

Open the printed link in any browser. That's it.

## Commands

| Command | What it does |
|---|---|
| `droppage login` | Authenticate with a magic link (session stored in `~/.droppage/config.json`, or under `DROPPAGE_HOME`). |
| `droppage logout` | Sign out and clear local credentials. |
| `droppage upload <file>` | Publish an `.html`/`.htm` file (and the local images and videos it references) and print its URL. Options: `--password`, `--email <addr>` (with `--no-invite`), `--private`, `--expires <when>`. |
| `droppage update <slug> <file>` | Replace the HTML (and images and videos) behind an existing URL. Keeps the URL, access mode, and stats. `--expires <when\|never>` changes the expiry. |
| `droppage expire <slug> <when\|never>` | Set or clear when a page expires without re-uploading. |
| `droppage list` | List your pages, including an EXPIRES column. `--json` for machines (rows have `expires_at`), `--preview` for no-count preview URLs. |
| `droppage delete <slug>` | Delete a page and its images and videos. `--yes` skips the confirmation prompt. |
| `droppage recipients list <slug>` | List recipients of an email-gated page (`--json`, `--page <n>`). |
| `droppage recipients add <slug> <emails...>` | Add recipients and queue their invitation emails. |
| `droppage recipients remove <slug> <email>` | Revoke a recipient; their invitation link stops working (`--yes`). |
| `droppage recipients invite <slug>` | Email an invitation to everyone on the page who hasn't had one yet (after `upload --no-invite`, or to retry). |
| `droppage recipients resend <slug> <email>` | Queue a fresh invitation for an existing recipient. |
| `droppage image upload <files...> --page <slug>` | Advanced: add images (PNG, JPEG, GIF, WebP, AVIF, SVG; up to 4 MB each) or videos (MP4, WebM; up to 20 MB each) to an existing page and print their URLs. Alias: `droppage media upload`. `--json` prints `[{file,id,url,bytes,content_type,existing}]`. |
| `droppage image list [--page <slug>]` | List your pages' images and videos; with `--page`, one page and its image budget. `--json` for machines. |
| `droppage image delete <id-or-url...>` | Delete images or videos. They stop being served within 5 minutes; a browser that already loaded one may keep it up to a day. |
| `droppage quota` | Show the current plan, page usage, monthly meter, reset date, and enabled features. `--json` returns the account API body. |
| `droppage feedback <message>` | Send feedback without requiring login. Options: `--kind idea|bug|review|other`, `--agent [model]`, `--contact <email>`, review-only `--rating <1-5>` and `--allow-quote`. Quote permission never publishes automatically. |
| `droppage upgrade` | Install the latest CLI globally with npm and report the installed version. |
| `droppage mcp` | Run a local MCP server on stdio for AI agents (see [Use droppage over MCP](#use-droppage-over-mcp)). |

Run `droppage <command> --help` for full option details.

Slugs from 0.2.1 on never start with `-`. If an older page's slug does (say `-AbC12xYz9`), put `--` in front of
it, with any options before the `--`: `droppage expire -- -AbC12xYz9 never` or
`droppage update --expires 7d -- -AbC12xYz9 report.html`. The CLI prints the same hint when it happens.

## Access modes

| Upload flag | Mode | Who can open the link |
|---|---|---|
| *(none)* | public | Anyone with the link. |
| `--password` | password | Visitors who enter the password (prompted securely at upload time). |
| `--email a@x.com,b@y.com` | email | Allowlisted addresses, verified by a magic link. Each person is emailed an invitation when the page is published (0.5.0+); add `--no-invite` to send them later with `recipients invite`. |
| `--private` | private | Only you (your account email). Useful for drafts. |

`--password`, `--email`, and `--private` are mutually exclusive. `update` never changes the access
mode — it only swaps the HTML. When you are signed in to droppage.dev, your own protected pages
open directly, without the password or email link.

## Rules for uploads

- One `.html` or `.htm` file per upload; the file is validated before any network call.
- Inline your CSS, JS, and data. Relative asset paths other than images will not resolve. Local
  images referenced in `<img src>` are uploaded with the page (see below); sensitive images belong
  inline as data: URIs.
- Views shown by `list` count one unique visitor per page. Refreshes, reopening in the same browser,
  link previews from chat apps, and your own opens do not add views.
- Preview URLs (`list --preview`) never increment the view count.

## Images

Images belong to a page. Reference local image files in your HTML (inside the HTML file's folder; `../` and absolute paths are ignored), with paths relative to the HTML
file, and upload it:

```html
<img src="chart.png">
```

```bash
$ droppage upload report.html
droppage: image chart.png → https://droppage.dev/i/AbCdEfGhIjKl.png
https://droppage.dev/p/k3x9qd2m
```

`upload` finds the images, uploads them to that page, rewrites the links to
`https://droppage.dev/i/<id>.<ext>`, then publishes. The image lines go to stderr; stdout is still
only the page URL.

- `update` uploads any new local images, keeps the same URL for an unchanged image, and deletes
  the page's images the new HTML no longer uses.
- Besides `<img src>`, the CLI picks up local images in `srcset` on `<img>`/`<source>` (every
  candidate, descriptors kept), `<link rel="icon"|"apple-touch-icon" href>`, and `url(...)` inside
  `<style>` blocks (0.2.2+). Not picked up: `style="..."` attributes and `.ico` files.
- Deleting a page, or the page expiring, removes its images too. Images never outlive their page.
- Image budget per page by plan: Free 5 MB, Starter 20 MB, Builder 50 MB. Each image up to 4 MB.
  PNG, JPEG, GIF, WebP, AVIF, SVG. Image traffic counts toward your monthly bandwidth.
- Prefer small formats: WebP or AVIF for photos and screenshots, SVG for charts and logos (often
  several times smaller than PNG or JPEG). The CLI prints a tip on stderr when a PNG, JPEG, or GIF
  is over 300 KB.
- **Images are public** to anyone with the URL. A page's password, email, or private gate does not
  protect them. Keep sensitive images inline in the HTML as data: URIs instead.
- Advanced: `droppage image upload <files...> --page <slug>` adds images to an existing page and
  prints their URLs; `droppage image list [--page <slug>] [--json]` shows them (`--json` prints
  `{images:[{id,url,ext,content_type,bytes,name,created_at,page}], page?:{slug,used_bytes,limit_bytes}}`);
  `droppage image delete <id-or-url...>` removes them.

## Videos

Short product films (CLI 0.3.0+) are hosted exactly like images. Reference local MP4 or WebM files,
and a poster image, in a `<video>`:

```html
<video autoplay muted loop playsinline poster="still.webp">
  <source src="film.webm" type="video/webm">
  <source src="film.mp4" type="video/mp4">
</video>
```

```bash
droppage upload page.html
# stderr: droppage: image still.webp → https://droppage.dev/i/AbCdEfGhIjKl.webp
# stderr: droppage: video film.webm → https://droppage.dev/i/MnOpQrStUvWx.webm
# stderr: droppage: video film.mp4 → https://droppage.dev/i/YzAbCdEfGhIj.mp4
```

- Picked up: `<video src>`, `<source src>` (inside `<video>`, and `<picture>` as before), and
  `<video poster>`. Same folder rule as images.
- Each video up to 20 MB (20,000,000 bytes), checked by its file signature, not its name: MP4
  (H.264 plays everywhere) and WebM (VP9). `.mov` and `.mkv` are refused; convert them first, e.g.
  `ffmpeg -i in.mov -c:v libx264 -pix_fmt yuv420p -movflags +faststart -an film.mp4`.
- Videos share the page's image budget (Free 5 MB, Starter 20 MB, Builder 50 MB per page), are
  pruned by `update` and deleted with the page, like images. Video traffic counts toward your
  monthly bandwidth.
- Served from `https://droppage.dev/i/<id>.mp4|webm` with HTTP Range support (`206 Partial Content`),
  so Safari, iOS and seeking work. Public to anyone with the URL, like images.
- No need to inline films as base64 any more. `droppage image upload film.mp4 --page <slug>` (or
  `droppage media upload`) adds a video to an existing page.

## Expiry

Pages can expire. Nothing expires unless you set it, on any plan.

```bash
droppage upload report.html --expires 7d          # also 30m, 12h, 2w, or a date like 2026-12-31
droppage update <slug> report.html --expires never
droppage expire <slug> 2026-12-31                 # change it without re-uploading; `never` clears it
```

After expiry the page shows "This page has expired." (HTTP 410) to everyone, including you, and
its images stop working. A daily cleanup then deletes the page and its images for good.
`droppage list` shows an EXPIRES column (`never` or a date); `list --json` rows have `expires_at`
(`null` means never).

## Sharing reports and dashboards

droppage is a quick way to send an analysis to people who don't have your tools: a dashboard for your
team, a weekly KPI or stakeholder report, a client deliverable, a notebook export. They open a link.

- **Design it well.** Agents should load Anthropic's `frontend-design` skill before building the page, so
  the report gets a deliberate look instead of a templated one. Claude Code:
  `/plugin install frontend-design@claude-plugins-official`; Codex, Cursor, and other agents: use its
  `SKILL.md` from [anthropics/skills](https://github.com/anthropics/skills/tree/main/skills/frontend-design).
- **Export one HTML file**, up to 5 MB, with the data inside it: `jupyter nbconvert --to html
  analysis.ipynb`, Plotly's `fig.write_html("report.html", include_plotlyjs="cdn")`, Altair's
  `chart.save("report.html")`, or your own Chart.js / ECharts page. Scripts run, so interactive
  charts work, and chart libraries can load from a CDN.
- **Pages run in a sandbox**: `localStorage`, cookies, and same-origin requests are not available, so
  keep the data in the file rather than fetching it.
- **Pick who sees it.** `--email cfo@example.com,ops@example.com` for named people (Builder; manage
  them later with `droppage recipients`), `--password` for a group link (Starter and Builder),
  `--private` for a draft. On the Free plan, pages can be public or private, without a password or email list.
- **Same link every week.** `droppage update <slug> report.html` replaces the report and keeps the
  link and its access settings (Starter and Builder). Use `--expires 30d` for one-off deliverables.
- **Views are people.** `droppage list --json` shows `view_count` (unique visitors) and
  `last_viewed_at` for each report.

## For agents and scripts

droppage keeps a strict stream contract so it is safe to call from automation:

- `upload` and `update` print **only the URL** on stdout, even when they upload images;
  `image upload` prints **only the image or video URL(s)**; `expire` prints **nothing** on stdout.
- `list --json`, `image list --json`, `recipients list --json`, and `quota --json` print **only JSON** on stdout.
- Progress, warnings, prompts, errors, and the per-file `droppage: image … → …` / `droppage: video … → …` lines go to **stderr**.
- Non-zero exit code on any failure.
- Use `--yes` on `delete` / `recipients remove` for non-interactive runs.

Ready-made instruction packs for Codex, Cursor, and Claude-style agents live in the
[`agents/`](https://github.com/Vilancer/droppage-cli/tree/main/agents) directory of the repository.
Machine-readable docs for agents and doc tools such as mcpdoc:
[droppage.dev/llms.txt](https://droppage.dev/llms.txt), or everything in one file at
[droppage.dev/llms-full.txt](https://droppage.dev/llms-full.txt).

## Use droppage over MCP

From 0.4.0, `droppage mcp` runs a [Model Context Protocol](https://modelcontextprotocol.io) server on stdio, so
agents in Claude Code, Cursor, Codex, Windsurf, or Claude Desktop publish through typed tools instead of shell
commands. It runs on your machine and uses the session from `droppage login`; sign in once in a terminal first.

```bash
claude mcp add droppage -- npx -y droppage mcp          # Claude Code
```

Cursor (`.cursor/mcp.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), and Claude Desktop
(`claude_desktop_config.json`):

```json
{ "mcpServers": { "droppage": { "command": "npx", "args": ["-y", "droppage", "mcp"] } } }
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.droppage]
command = "npx"
args = ["-y", "droppage", "mcp"]
```

Tools: `publish_page` (a file `path` or inline `html`; `access` public, email or private; `emails`; `invite`; `expires`), `update_page`, `list_pages`, `delete_page`, `set_page_expiry`, `get_quota`, `list_recipients`, `add_recipients`, `invite_recipients`, `remove_recipient`, `upload_media`, `list_media`, `delete_media`, `send_feedback`. Results are JSON with a `warnings` list.

- Signed out, every tool answers "Not signed in. Ask the user to run `droppage login` in a terminal, then retry."
  There is no login tool: login needs the terminal, and stdin belongs to the protocol.
- There is no password mode over MCP, so a password never lands in an agent transcript. Run
  `droppage upload <file> --password` yourself for a password page.
- Pass a file `path` when the page uses local images or videos; inline `html` cannot bring them.
- `update_page`, `delete_page`, `set_page_expiry`, `remove_recipient`, and `delete_media` are marked destructive, so MCP clients ask before running them.
- Any client you configure with this server can publish, change, and delete pages as you. Add it only to agents you trust with your droppage account.

## Updating

```bash
droppage upgrade            # upgrade to the latest release
droppage --version          # confirm the installed version
```

After a command finishes, interactive terminals check npm for a new release at most once every 24
hours and put any update notice on stderr only. The check sends no identifier or usage data, and
all errors are ignored. Set `DROPPAGE_NO_UPDATE_CHECK=1` to opt out. This registry lookup is the
CLI's only non-backend network request; droppage still collects no telemetry.

Before bulk publishing, use `droppage quota --json`. A `warn` level means the monthly meter is at
least 80% used; `limit` means new uploads, updates, or previews may pause. Existing links remain
live. Delete unneeded pages or review plan options at [droppage.dev/account](https://droppage.dev/account).

Feedback is public and login is optional:

```bash
droppage feedback "The preview command should…" --kind idea
droppage feedback "Upload failed after…" --kind bug --agent "my-model"
```

Agent-authored feedback should always use `--agent` and include the model name.

Releases are published from GitHub Actions with
[npm provenance](https://docs.npmjs.com/generating-provenance-statements), so every version on npm
is verifiably built from a tagged commit in the public repository.

## Configuration

droppage works with zero configuration against the hosted service. For self-hosted or development
setups, these environment variables are honoured (in order of precedence):

| Variable | Purpose |
|---|---|
| `DROPPAGE_SUPABASE_URL` / `DROPPAGE_SUPABASE_ANON_KEY` | Point the CLI at another backend. |
| `SUPABASE_URL` / `SUPABASE_ANON_KEY` | Fallback names for the same. |
| `DROPPAGE_SHARE_BASE_URL` | Origin used when printing share URLs (default `https://droppage.dev`). |
| `DROPPAGE_NO_UPDATE_CHECK` | Set to `1` to disable the optional 24-hour npm release check. |
| `DROPPAGE_HOME` | Folder for the login session and the release-check cache (default `~/.droppage`; 0.5.0+). Use it to keep a separate session for CI, scripts or a test backend: `DROPPAGE_HOME=/tmp/droppage-ci droppage login`. Read only from the environment, never from `./.env`. |

## Security

- The CLI is a thin client. It holds **no secrets**: only a public (anon) API key and *your own*
  login session. All access control is enforced server-side.
- The CLI refuses to start if a privileged `service_role`/`sb_secret` key is found in its
  environment or config file — those keys must never be used with droppage.
- Passwords are hashed with bcrypt before they leave your machine.
- Your session is stored in `~/.droppage/config.json` (or `$DROPPAGE_HOME/config.json`) with `0600`
  permissions. A project's `./.env` cannot move it.

## License

[Apache-2.0](./LICENSE) © 2026 Vilancer.