ShareFast

Agents

ShareFast Publish Agent Guide

Canonical guidance for publishing generated artifacts as review-ready Drops while keeping raw URLs and Drop Revision Keys private.

ShareFast Publish Agent Guide

Use this guide when you have generated a standalone HTML artifact, Markdown review note, zip package, or built static folder and need to publish it as a ShareFast Drop for review.

Goal

Turn a local artifact into a reviewer-facing Drop URL:

HTML/Markdown/zip/folder -> Publish API -> Reviewer URL

Requirements

  • Publish only standalone HTML, Markdown, packaged zip files, or built folders.
  • Keep the HTML self-contained: inline CSS, inline JavaScript, and absolute

external asset URLs only when they are intentionally public.

  • Treat Markdown as a static preview format. ShareFast escapes embedded HTML and

renders it into a sandboxed HTML Drop Revision.

  • Treat folders and zips as Packaged Drop Revisions. A package needs a root

index.html; the server remains authoritative for path safety, quotas, and allowed asset types.

  • Do not add projects, teams, billing, analytics, browser extensions, custom

domains, encryption, or MCP behavior.

  • Treat the returned url as the primary reviewer-facing URL.
  • Treat the returned raw_url as an implementation/debug URL, not the primary

link to share.

  • Keep the returned revision_key private. Use it only when the user asks you

to publish a new Drop Revision to the same URL.

Publish Command

Use the CLI. Write the artifact to a local .html, .md, .zip, or built folder, then run:

npx -y sharefast ARTIFACT.html
npx -y sharefast REVIEW-NOTES.md
npx -y sharefast dist/

The command prints only the reviewer-facing URL on success:

https://sharefast.app/k3x9m2pq

Use sf login OWNER_EMAIL once to remember the Author Email for future publishes. Passing --owner OWNER_EMAIL also remembers that email. Use --api-url http://localhost:3000/api/publish when publishing to a local or staging server.

If the CLI is not available, use the raw body API:

curl -X POST "https://sharefast.app/api/publish?filename=ARTIFACT.html" \
  -H "Content-Type: text/html; charset=utf-8" \
  --data-binary @ARTIFACT.html

curl -X POST "https://sharefast.app/api/publish?filename=REVIEW-NOTES.md" \
  -H "Content-Type: text/markdown; charset=utf-8" \
  --data-binary @REVIEW-NOTES.md

Replace ARTIFACT.html with a short, descriptive filename or folder such as homepage-review.html, invoice-flow-prototype.html, review-notes.md, or dist/.

Optional Metadata

Add query parameters only when the user or surrounding task provides them:

npx -y sharefast \
  --owner OWNER_EMAIL \
  --project PROJECT \
  --passcode PASSCODE \
  ARTIFACT.html
  • owner: optional owner email. It must pass the app's owner email validation

and is remembered by the CLI for future uploads.

  • project: optional project grouping. The app normalizes it to a bounded,

lowercase Drop Metadata value.

  • passcode: optional Drop Passcode for protected review.

JSON Body

Tool integrations that prefer JSON can send html or markdown:

curl -X POST https://sharefast.app/api/publish \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "homepage-review.html",
    "html": "<!doctype html><html><body><h1>Review me</h1></body></html>",
    "owner": "harley@coderpush.com",
    "project": "homepage",
    "passcode": "review-only"
  }'

Use htmlBase64 instead of html when the caller cannot safely quote the generated HTML string. Use markdownBase64 for the same case with Markdown.

Markdown JSON example:

curl -X POST https://sharefast.app/api/publish \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "homepage-review.md",
    "markdown": "# Homepage review\n\n- Check the owner flow"
  }'

Expected Response

{
  "ok": true,
  "slug": "k3x9m2pq",
  "url": "https://sharefast.app/k3x9m2pq",
  "raw_url": "https://sharefast.app/api/raw/k3x9m2pq",
  "filename": "homepage-review.html",
  "project": "homepage",
  "size": 41302,
  "hasPasscode": true,
  "expiresAt": "2026-06-09T10:30:00.000Z",
  "owner": "harley@coderpush.com",
  "revision_id": "rev_yYu1lWm5M9v9Qk0a",
  "revision_number": 1,
  "revision_key": "revkey_WZ7R9BWmLr9lqY5MrVhA9hJxdjxk6Ja1"
}

Publish A Revision

When the user wants to update an existing Drop URL, publish a new Drop Revision with the Drop slug and Drop Revision Key:

npx -y sharefast \
  --slug DROP_SLUG \
  --revision-key DROP_REVISION_KEY \
  ARTIFACT.html

This sends the Drop Revision Key as X-Drop-Revision-Key. The curl equivalent is:

curl -X POST "https://sharefast.app/api/publish?slug=DROP_SLUG&filename=ARTIFACT.html" \
  -H "Content-Type: text/html; charset=utf-8" \
  -H "X-Drop-Revision-Key: DROP_REVISION_KEY" \
  --data-binary @ARTIFACT.html

The response uses the same url and increments revision_number. Share the same reviewer-facing url unless the user asks for debug details.

Export A Drop

When the user needs a portable representation of an existing Drop, use Drop Export instead of publishing another Drop Revision. Drop Export reads the Current Revision after the same Access Policy checks as the viewer and raw routes. It does not expose the Drop Revision Key, count as a Drop View, or publish an Enhance preview.

curl -L https://sharefast.app/api/drops/DROP_SLUG/exports/markdown -o drop.md
curl -L https://sharefast.app/api/drops/DROP_SLUG/exports/clean-html -o drop.clean.html
open "https://sharefast.app/api/raw/DROP_SLUG?embedded=1&print=1"
  • Markdown is best for content-heavy Drops. It preserves semantic headings,

paragraphs, links, lists, code, and simple tables when those semantics exist.

  • Clean HTML is a stripped semantic HTML export for archives and downstream

tool handoff when Markdown would lose too much structure.

  • PDF is a browser print flow in v1. The user saves as PDF from the print

dialog; ShareFast does not generate or store a server-side PDF file.

Markdown and Clean HTML are best-effort for app-like Drops. JavaScript-rendered, canvas-heavy, or CSS-only meaning may not survive export.

Agent Response

After a successful publish, report only the important result unless the user asks for more detail:

Published: https://sharefast.app/k3x9m2pq

If publishing fails, report the HTTP status and API error. Do not claim the Drop was published unless the response has "ok": true and a url.

Use --json only when the caller needs the API payload for storage or automation. It prints raw_url, revision_key, and other private fields, so do not paste that output into public threads by default.

Compatibility

POST /api/publish is canonical. POST /api/agent/publish remains an alias for older agent integrations.

Supported Formats

  • .html: standalone HTML, MAX_FILE_SIZE limit (5 MB by default).
  • .md / .markdown: Markdown rendered into static HTML, same size limit

before and after rendering.

  • .zip: Packaged Drop Revision with root index.html, package quotas, and

the server-side asset allowlist.

  • folder path: zipped locally by the CLI, then uploaded as a Packaged Drop

Revision.

PDF, notebooks, and images are intentionally unsupported as publish inputs until their renderer, raw access, and annotation behavior are defined. Existing Drops can still be exported through the Drop Export routes above.

Security Notes

ShareFast stores uploaded HTML and rendered Markdown as immutable Drop Revisions and serves the Current Revision through the existing sandboxed viewer and raw-route content security protections. Do not overwrite stored HTML in place; publish a new Drop Revision instead.