---
name: artifacts
description: >
  Publish agent-made HTML (reports, prototypes, mockups, visualizations, static
  bundles) to unlisted, expiring URLs on artifacts.benperlman.dev. Use when asked
  to publish HTML, share a report or prototype URL, host a static bundle, put a
  deliverable online for someone, check who viewed a shared artifact, change
  how long a share lasts, password-protect a share, or make a separate link
  for one recipient.
---

# artifacts.benperlman.dev

Skill version: 0.2.0

Artifacts turns local agent output into an unlisted Publication URL at
`https://artifacts.benperlman.dev/a/{id}`. URLs expire after 30 days by default
and every entry-page view is logged.

The service is CLI-first. Prefer the `bparti` command over raw HTTP. If an
`artifacts` MCP server is connected, prefer its tools.

## Current docs

Before answering capability or workflow questions, read
https://artifacts.benperlman.dev/llms.txt. If this skill and the live docs
disagree, prefer the live docs and live CLI output.

## When to use

- Publish HTML reports, prototypes, mockups, visualizations or static directories that need a URL.
- Hotfix a recently shared Publication during the 15-minute Revision Window (same URL).
- Extend, keep or remove a share. Check its access log.
- Lock a share with a password, or give each recipient their own link with its own expiry, view limit and log.

Do not use Artifacts for server-side compute, authenticated apps or private file storage. Publications are unlisted, not private.

## Auth

Non-interactive (preferred for agents):

```bash
export ARTIFACTS_TOKEN=artk_...
```

Interactive, when a human is present:

```bash
bparti login      # opens the dashboard; approve to store a token
bparti whoami
```

Local token state lives under `~/.config/benperlman-artifacts/`. Do not commit tokens.

## Publish

```bash
bparti publish ./artifact.html
bparti publish ./report.html --title "Q2 Results"
bparti publish ./dist --expires 7d --open
cat report.html | bparti publish - --open
```

Always return the printed Publication URL to the user, and say when it expires.

Flags:

- `--title "Name"` — human-readable title (default: the HTML `<title>`)
- `--expires 7d|2w|30d|6mo|never` — lifetime (default 30d); `--keep` = never
- `--entry-page path/to/page.html` — Entry Page inside a directory (default `index.html`)
- `--new` — force a new URL during the Revision Window
- `--update <URL>` — replace an older Publication in place
- `--open` — open the URL after publishing
- `--password` — lock the URL. Bare `--password` generates a password and prints it once (put the flag last); `--password=PW` picks one. Tell the user the password with the URL.

## Manage

```bash
bparti list                      # active publications
bparti list --all                # include expired and removed
bparti views <URL>               # access log: totals + recent views
bparti extend <URL> 30d          # add 30 days; `never` keeps it
bparti remove <URL> --yes
bparti password <URL>            # set a generated password (printed once); `<URL> PW` picks one; `--clear` removes it
```

## Per-recipient share links

When the user wants to share with specific people, or wants to cut off one person later, make a share
link per recipient instead of handing out the Publication URL:

```bash
bparti link create <URL> --label "Will" --expires 7d          # prints https://artifacts.benperlman.dev/s/{id}
bparti link create <URL> --label "Board" --max-views 3 --password
bparti link list <URL>                                         # status, views, expiry per link
bparti link revoke <link URL>                                  # that link returns 404; the rest keep working
```

A share link follows the artifact's expiry unless it has its own. It uses the artifact's password unless
it has its own. Views through a link appear in `bparti views` with the link's label.

## MCP instead of the CLI

Connect `https://artifacts.benperlman.dev/mcp` as a remote MCP server with
`Authorization: Bearer artk_...`. Tools: `publish_artifact`, `update_artifact`,
`remove_artifact`, `extend_artifact`, `list_artifacts`, `artifact_views`,
`set_artifact_password`, `create_share_link`, `list_share_links`,
`revoke_share_link`, `whoami`. Send content inline (`html`, or `files` with `text`/`contentBase64`).
There is no Revision Window over MCP: `publish_artifact` always creates a new
URL; use `update_artifact` to change one in place.

## Constraints

- Unlisted, not private. Anyone with the exact URL can view it, unless a password is set.
- Do not crawl, guess or enumerate `/a/` or `/s/` URLs.
- Directory Artifacts need a root `index.html` unless `--entry-page` is set.
- Packaging excludes secrets, dependency folders, caches and hidden paths except `.well-known/`. Symlinks are skipped. Limits: 25 MB per file, 100 MB total, 1,000 files.

## What to tell the user

- The Publication URL from the current run and its expiry date.
- The password, when one was set or generated. It is shown once.
- That the URL is unlisted, not private, and that views are logged.
- Never invent URLs.