Publishing concepts

Artifacts are static HTML folders

artifact.cafe hosts static artifacts for review. It does not run SSR, backend processes, databases, cron jobs, or serverless functions for the artifact.

Entry file detection

The CLI uses index.html when it exists.
If the folder root has exactly one HTML file, the CLI uses that file.
Otherwise, pass --entry file.html.

When someone pastes a review link into X, Slack, Telegram, or Discord, the preview card is built from your artifact. By default it shows the title over a generated artifact.cafe card. Your entry file can take that over:

<meta name="description" content="One line about what this is.">
<meta property="og:image" content="og.png">
<meta name="author" content="Ada Lovelace">

The description also accepts og:description, and the byline also accepts article:author. Pass --description on publish to override whatever the document says.
og:image must be a file in the folder you published: og.png, ./og.png, and /assets/og.png all work. Remote URLs and data: are refused, so artifact.cafe never serves preview imagery it did not store.
The image has to be a PNG, JPEG, WebP, or GIF under 5 MB, and it has to be in the version you are publishing. A path that does not resolve falls back to the generated card rather than shipping a broken preview. 1200x630 is a good size.
Each version gets its own preview URL, so publishing v2 re-unfurls instead of showing a cached v1 card.
Only the entry file is read, so a ?page= deep link shares the same card as the artifact.
Password-protected, workspace, and private artifacts always unfurl as the locked card. The fetcher that builds a preview is anonymous, so it never sees your description, image, or byline (see Password protection).

Ignored and blocked paths

The CLI skips repo metadata, common dependency folders, local artifact credentials, env files, private keys, symlinks, unsafe paths, and zero-byte files.

Limits

Maximum file size: 100 MB.
Maximum total artifact size: 250 MB.
Maximum files per publish: 1,000.
Publish sessions expire after 1 hour.
Anonymous publishing is limited to 15 publishes per IP per hour and 20 per day. Signing in with an API key raises this.
Anonymous artifacts expire 24 hours after their last publish unless claimed (see Tokens and auth).

Versions are immutable

A publish always creates a new version. Comments stay pinned to the version where reviewers made them, so v1 feedback remains v1 feedback after you publish v2.

Publish into a workspace

npx artifact-cafe@latest publish . --workspace acme --folder specs

The workspace owns the artifact, and each version records the member who published it. The resolved workspace and folder are stored in .artifactcafe/config.json, so the next bare publish creates v2 in the same place. Run artifact-cafe workspaces --json to list the workspaces available to the current account.

For new artifacts, destination priority is explicit flags, a project-level artifact-cafe.json, then a human-only terminal picker. Agents and --json never prompt: without project context they use your personal workspace, the safest non-shared destination, when signed in; signed-out publishing remains anonymous. --folder on its own targets a folder in Personal.

artifact-cafe.json

{
  "workspace": "acme",
  "folder": "specs"
}

The project file is safe to commit and excluded from uploads. It supplies team context for fresh checkouts and agents; .artifactcafe/config.json remains the gitignored binding for one specific artifact and may contain its publish token.

Slugs

The API derives new artifact slugs from the title, adding a random suffix for uniqueness. Claimed owners can update the title or slug through owner-only API behavior; changing a slug changes the review URL.