---
name: shareout
description: Publish a self-contained HTML document (report, RCA, RFC, PRD, status report, presentation, interactive page) to Shareout and return a shareable link. Use when asked to share, publish, or send an HTML deliverable, to create an expiring link, to update a published document, or to check who viewed one.
---

# Shareout

Shareout hosts self-contained HTML documents on isolated per-document origins. You publish a file or directory, get a document ID, and hand out named links that expire and can be revoked. Documents can run scripts and read their own bundled files; they cannot call other servers, submit forms, or embed other sites.

Base URL: `https://shareout.io`. Machine-readable references: `/guidelines.md` (what renders), `/v1/limits` (allowlist and your tier), `/v1/templates` (document types), `/v1/brands/default` (design tokens), `/llms.txt` (index).

## Setup (once per machine)

```bash
npm i -g @shareout/cli
shareout init --key so_live_...      # or export SHAREOUT_API_KEY=so_live_...
shareout whoami
```

Without the CLI, every step below has a plain HTTP equivalent shown in the last section.

## Workflow

1. **Pick a template and read its brief.** `shareout templates` lists them; `shareout template rca --out ./rca-kit` writes `brief.md`, `theme.css`, `exemplar.html`, and `brand.css`. Follow the brief's section order. Read `https://shareout.io/guidelines.md` once.
2. **Author `index.html`.** Inline `brand.css` then `theme.css` in `<style>` tags, then your content. Rules that matter most:
   - Self-contained. Reference bundled files with relative paths only (`assets/app.js`, never `/assets/app.js`). Root-relative paths break under access grants.
   - Network: only your own bundled files (`fetch('data.json')` works). Scripts may load from `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.tailwindcss.com`, `code.jquery.com`; stylesheets from `fonts.googleapis.com`. Everything else is blocked silently.
   - No `<form>`, `<iframe>`, `<object>`, `<embed>`. A specific `<title>`. Light and dark via the `--so-*` tokens and `prefers-color-scheme`.
   - Size: free tier 10 MB and 100 files per document; owner tier 16 MB and 255 files.
3. **Check locally.** `shareout check ./rca` runs the same validation the server uses and prints warnings for anything the policy will block.
4. **Publish and link in one step.**
   ```bash
   shareout publish ./rca --title "Checkout outage RCA" --template rca --link "Leadership" --expires 14d
   ```
   Prints the document ID, the viewer URL, and the link URL. The link URL is shown once; give it to the person you are working for. Public documents: add `--visibility public` and share `urls.direct` or the viewer URL.
5. **Update on the same URL.** `shareout update <id> ./rca` adds a version; existing links show it unless pinned. `shareout activate <id> 1` rolls back.
6. **More audiences, revocation, insight.** `shareout link <id> --label "Acme" --expires 7d`, `shareout revoke <id> <link-id>`, `shareout views <id>`, `shareout stats <id>`.

Defaults: visibility `link`, link expiry 14 days, retention never for owner tier and 90 days for free tier (`--retention 30d` or `never` to change), links open in a viewer with a click-to-open gate that survives email link scanners. Use `--path-token` for audiences whose mail security strips URL fragments.

## Output conventions

- All commands print JSON when stdout is not a terminal or with `--json`.
- Exit codes: 2 validation, 3 authentication, 4 limit reached, 5 not found, 1 other. Errors include a `code`, a `message`, and for limits the `limit`, `value`, `max`, and `resets_at`.
- Never paste link tokens into logs, tickets, or commit messages. Store the document ID instead; links can always be re-issued.

## Plain HTTP equivalents

```bash
API=https://shareout.io/v1; H="Authorization: Bearer $SHAREOUT_API_KEY"
curl -s $API/limits
curl -s $API/templates/rca | jq -r .brief
curl -s $API/brands/default | jq -r .css > brand.css
# publish: one multipart request; file field names are file:<relative path>
curl -s -X POST $API/documents -H "$H" \
  -F 'meta={"title":"Checkout outage RCA","visibility":"link","link":{"label":"Leadership","expires":"14d"}}' \
  -F 'file:index.html=@rca/index.html' -F 'file:assets/app.js=@rca/assets/app.js'
curl -s -X POST $API/documents/<id>/versions -H "$H" -F 'meta={}' -F 'file:index.html=@rca/index.html'
curl -s -X POST $API/documents/<id>/links -H "$H" -H 'content-type: application/json' -d '{"label":"Acme","expires":"7d"}'
curl -s -X DELETE $API/documents/<id>/links/<link-id> -H "$H"
curl -s $API/documents/<id>/stats -H "$H"
```

Responses carry `document.urls.shell` (viewer page) and, for public documents, `document.urls.direct` (the document's own origin).