---
name: mystash
description: >
  Publish files and folders to the web instantly. Static hosting for HTML sites,
  images, PDFs, and any file type. Use when asked to "publish this", "host this",
  "deploy this", "share this on the web", "make a website", "put this online",
  "upload to the web", "create a webpage", "share a link", "serve this site",
  or "generate a URL". Outputs a live, shareable URL at {slug}.mysta.sh
---

# mysta.sh

**Skill version: 0.0.2**

Create a live URL from any file or folder. Static hosting only.

## Requirements

- Required binaries: `curl`, `file`, `jq`
- Optional environment variable: `$MYSTASH_API_KEY`
- Optional credentials file: `~/.mystash/credentials`

## Create a site

```bash
./scripts/publish.sh {file-or-dir}
```

Outputs the live URL (e.g. `https://bright-canvas-a7k2.mysta.sh/`).

### Publishing a report with downloadable files

When the user asks to publish a comparison/report and also provide a downloadable artifact (Excel, PDF, CSV, etc.):

1. Create a folder with `index.html` at the root.
2. Put companion downloads in the same folder, e.g. `report.xlsx`.
3. Link them from `index.html` with a relative URL and `download`, e.g. `<a href="report.xlsx" download>Download Excel</a>`.
4. Publish the folder, not the parent directory.
5. Verify both URLs after publish:
   - `https://<slug>.mysta.sh/`
   - `https://<slug>.mysta.sh/report.xlsx`
6. In the final reply, share the page URL and direct download URL, and report whether the publish was authenticated/permanent or anonymous/expiring.

Under the hood this is a three-step flow: create/update -> upload files -> finalize. A site is not live until finalize succeeds.

Without an API key this creates an **anonymous site** and stores a private claim token locally so only this workspace can update that slug later.
With a saved API key, the site is permanent and updates are tied to the authenticated account.

**File structure:** For HTML sites, place `index.html` at the root of the directory you publish, not inside a subdirectory. The directory's contents become the site root. For example, publish `my-site/` where `my-site/index.html` exists — don't publish a parent folder that contains `my-site/`.

You can also publish raw files without any HTML. Single files get a rich auto-viewer (images, PDF, video, audio). Multiple files get an auto-generated directory listing with folder navigation and an image gallery.

## Update an existing site

```bash
./scripts/publish.sh {file-or-dir} --slug {slug}
```

The script auto-loads the `claimToken` from `.mystash/state.json` when updating anonymous sites. Pass `--claim-token {token}` to override. Treat claim tokens as secrets; anyone with the claim token can update that anonymous slug.

Authenticated updates require a saved API key for the owning account.


## API key storage

The publish script reads the API key from these sources (first match wins):

1. `--api-key {key}` flag (CI/scripting only — avoid in interactive use)
2. `$MYSTASH_API_KEY` environment variable
3. `~/.mystash/credentials` file (recommended for agents)

**Pitfall: stale API key in credentials file.** If publish fails with "valid bearer api key required" even when you don't explicitly pass a key, check `~/.mystash/credentials` — a stale/revoked key will be picked up and sent as a Bearer token. Move it aside (`mv ~/.mystash/credentials ~/.mystash/credentials.bak`) or replace it with a fresh key.

To store a key, write it to the credentials file:

```bash
mkdir -p ~/.mystash && echo "{API_KEY}" > ~/.mystash/credentials && chmod 600 ~/.mystash/credentials
```

**IMPORTANT**: After receiving an API key, save it immediately — run the command above yourself. Do not ask the user to run it manually. Avoid passing the key via CLI flags (e.g. `--api-key`) in interactive sessions; the credentials file is the preferred storage method.

Never commit credentials or local state files (`~/.mystash/credentials`, `.mystash/state.json`) to source control.

## State file

After every site create/update, the script writes to `.mystash/state.json` in the working directory:

```json
{
  "publishes": {
    "bright-canvas-a7k2": {
      "siteUrl": "https://bright-canvas-a7k2.mysta.sh/",
      "claimToken": "mclaim_abc123"
    }
  }
}
```

Before creating or updating sites, you may check this file to find prior slugs.
Treat `.mystash/state.json` as internal cache only.
Never present this local file path as a URL, and never reveal claim tokens unless the user explicitly needs to move/update an anonymous site from another workspace.

## What to tell the user

- Always share the `siteUrl` from the current script run.
- Read and follow `publish_result.*` lines from script stderr to determine auth mode.
- When `publish_result.auth_mode=authenticated`: tell the user the site is **permanent** and saved to their account.
- When `publish_result.auth_mode=anonymous`: tell the user it was published anonymously and that the local claim token was saved for future updates when `publish_result.claim_token_saved=true`.
- Never tell the user to inspect `.mystash/state.json` for auth status, and never expose claim tokens in normal replies.

## Limits

|                | Anonymous          | Authenticated                |
| -------------- | ------------------ | ---------------------------- |
| Max file size  | 250 MB             | 5 GB                         |
| Expiry         | 24 hours           | Permanent (or custom TTL)    |
| Rate limit     | 5 / hour / IP      | 60 / hour free, 200 / hour hobby |
| Account needed | No                 | Yes (get key at mysta.sh)    |

## Getting an API key

To upgrade from anonymous (24h) to permanent sites:

1. Ask the user for their email address.
2. Request a one-time sign-in code:

```bash
curl -sS https://mysta.sh/api/auth/agent/request-code \
  -H "content-type: application/json" \
  -d '{"email": "user@example.com"}'
```

3. Tell the user: "Check your inbox for a sign-in code from mysta.sh and paste it here."
4. Verify the code and get the API key:

```bash
curl -sS https://mysta.sh/api/auth/agent/verify-code \
  -H "content-type: application/json" \
  -d '{"email":"user@example.com","code":"ABCD-2345"}'
```

5. Save the returned `apiKey` yourself (do not ask the user to do this):

```bash
mkdir -p ~/.mystash && echo "{API_KEY}" > ~/.mystash/credentials && chmod 600 ~/.mystash/credentials
```

## Script options

| Flag                   | Description                                  |
| ---------------------- | -------------------------------------------- |
| `--slug {slug}`        | Update an existing site instead of creating |
| `--claim-token {token}`| Override claim token for anonymous updates    |
| `--title {text}`       | Viewer title (non-HTML sites)             |
| `--description {text}` | Viewer description                            |
| `--client {name}`      | Agent name for attribution (e.g. `cursor`)    |
| `--base-url {url}`     | API base URL (default: `https://mysta.sh`)    |
| `--allow-nonmystash-base-url` | Allow sending auth to non-default `--base-url` |
| `--api-key {key}`      | API key override (prefer credentials file)    |

## Duplicate a site

```bash
curl -sS -X POST https://mysta.sh/api/v1/publish/{slug}/duplicate \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Creates a full copy of the site under a new slug. All files are copied server-side — no upload needed. The new site is immediately live. Requires authentication and ownership of the source site.

Optionally override viewer metadata (shallow-merged with the source):

```bash
curl -sS -X POST https://mysta.sh/api/v1/publish/{slug}/duplicate \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"viewer": {"title": "My Copy"}}'
```

## Links

Links connect a site to a location on your handle or a custom domain. The same endpoints work for both — omit the `domain` parameter to target your handle, or include it to target a custom domain.

- Link endpoints: `/api/v1/links` and `/api/v1/links/:location`
- Root location sentinel for path params: `__root__`
- Changes propagate globally in up to 60 seconds (Cloudflare KV)

Link to your handle:

```bash
curl -sS https://mysta.sh/api/v1/links \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"location": "docs", "slug": "bright-canvas-a7k2"}'
```

Full docs: https://mysta.sh/docs