droppage

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.

$ droppage upload report.htmlhttps://droppage.dev/p/k3x9qd2m

Website: droppage.dev · Source: github.com/Vilancer/droppage-cli

Install

Requires Node.js 22 or newer.

npm install -g droppagedroppage --version

Quick start

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

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

Commands

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

--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:

<img src="chart.png">

$ droppage upload report.htmldroppage: image chart.png → https://droppage.dev/i/AbCdEfGhIjKl.pnghttps://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>:

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

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.

droppage upload report.html --expires 7d          # also 30m, 12h, 2w, or a date like 2026-12-31droppage update <slug> report.html --expires neverdroppage 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.
• 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 [email protected],[email protected] 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/ directory of the repository. Machine-readable docs for agents and doc tools such as mcpdoc: droppage.dev/llms.txt, or everything in one file at droppage.dev/llms-full.txt.

Use droppage over MCP

From 0.4.0, droppage mcp runs a Model Context Protocol 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.

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):

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

Codex (~/.codex/config.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

droppage upgrade            # upgrade to the latest releasedroppage --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.

Feedback is public and login is optional:

droppage feedback "The preview command should…" --kind ideadroppage 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, 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):

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 © 2026 Vilancer.