CLI reference

Every command is safe to run from the artifact folder. Use --json when an agent or script needs structured output.

comments, listen, comment, reply, resolve, reopen, ack, edit, delete, protect, share, unshare, and open also accept --artifact <id> (or the ARTIFACT_CAFE_ARTIFACT_ID env var) to act on an artifact without its folder — useful from CI, a fresh checkout, or a second machine. Authorize with ARTIFACT_CAFE_TOKEN (the artifact's publish token) or a signed-in account key via --api-key. See Tokens and auth. (comment is account-only — a publish token can't open a thread.)

publish

npx artifact-cafe@latest publish [dir]

• --title <title> sets the artifact title.
• --notes <text> records a bullet-point changelog for this version (newline-separated), shown in the versions sidebar.
• --description <text> sets the link preview summary, overriding the entry file's own meta description.
• --entry <file> selects the HTML entry file.
• --review <open|readonly|off> sets what a viewer may do once in. See Reviewing.
• --artifact <id> publishes to a specific existing artifact.
• --workspace <handle> publishes into a workspace you belong to.
• --folder <name-or-id> publishes into a folder in that workspace, and the artifact inherits that folder's visibility — publishing into a workspace folder makes the review link members-only. The resolved placement persists for later bare publishes.
• --password <password> password-protects the artifact (min 6 characters).
• --json prints machine-readable output and does not open a browser.
• --no-open prints the review URL without opening it.

For a new unbound artifact, a signed-in human running in a terminal gets a workspace picker when more than one destination is available. Agents, --json, CI, and non-interactive runs never prompt. They use artifact-cafe.json when the project declares one; without it, signed-in runs publish to Personal and signed-out runs remain anonymous. JSON output includes destination, destinationSource, and visibility — the last tells you whether the review URL you just got needs a sign-in.

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

This project file is safe to commit: it contains no artifact id or token and is not included in the published artifact. Existing linked artifacts always republish in place unless you pass an explicit placement flag.

Every publish records which agent made it — detected from the environment (Claude Code, Codex, Cursor and friends), or whatever you set ARTIFACT_CAFE_AGENT to. That label names the agent in the version history and in every reply it posts to a thread.

workspaces

npx artifact-cafe@latest workspaces

Lists the workspaces the signed-in account belongs to. Pass --json for the workspace ids, handles, names, and roles used by scripts.

folders

npx artifact-cafe@latest folders --workspace acme
npx artifact-cafe@latest folders create "Design specs" --workspace acme

Lists the folder names, visibility, and ids available in a workspace. Pass --json for machine-readable discovery before publishing.

folders create <name> adds a folder (owner/admin in a team workspace; always allowed in Personal). --visibility workspace (default) keeps it members-only; --visibility public lists it on the workspace's public page — and artifacts placed in it default to public. The CLI refuses a name that already exists in the workspace, since duplicate names break --folder <name> addressing. Renaming and deleting folders stay in the dashboard. See Organizing artifacts for how these commands fit together.

move

npx artifact-cafe@latest move --folder "Design specs" [dir]
npx artifact-cafe@latest move --artifact art_x --folder specs
npx artifact-cafe@latest move --artifact art_x --unfiled

Re-files an artifact into a folder of its workspace (or out of one with --unfiled) without publishing a new version — the review link, versions, and comments are untouched.

• --folder <name-or-id> targets a folder by exact name or id; ambiguous names need the id.
• --unfiled moves the artifact to the workspace root.
• --artifact <id> targets an artifact by id instead of the linked folder.
• --json prints the result, including previousVisibility and visibility.

Placement applies the folder's visibility as the artifact's new default when you're a workspace admin or the artifact's publisher (see workspaces) — moving into a public folder publishes the artifact. move is an account action: authorize with artifact-cafe login or --api-key; a publish token can't re-file.

list

npx artifact-cafe@latest list
npx artifact-cafe@latest list --workspace acme

Without flags, lists the artifacts your personal workspace owns. With --workspace <handle>, lists that workspace's artifacts grouped by folder; its --json output includes both the artifacts (each with its folderId) and the folder list, so one call answers "what exists, and where is it filed".

comments

npx artifact-cafe@latest comments [dir]

• --status open | resolved | all filters threads. Default: open.
• --version current | all filters versions. Default: current.
• --wait blocks until a new thread or reply arrives.
• --timeout <seconds> controls how long wait mode listens. Default: 900.
• --artifact <id> targets an artifact by id instead of the linked folder (see intro for the env equivalents), so wait mode can run detached from where you published.
• --json prints the full export for agents.

Wait mode heartbeats agent presence while it runs, which shows Agent is listening on the review page; when it hands feedback over and exits, the indicator flips to Agent is editing for a few minutes. It exits 0 after returning new feedback and exits 2 when the timeout elapses. See the Live agent loop for the optional local live-editing workflow. Publishing does not start wait mode automatically.

listen

npx artifact-cafe@latest listen [dir]

The live-loop entry point — an alias for comments --wait, named for what it does. It takes the same --status, --version, --timeout, --artifact, --api-key, and --json flags and produces identical output and exit codes (0 on new feedback, 2 on timeout). It does not run a local preview server or auto-republish on save; cutting the next version stays an explicit publish.

status

npx artifact-cafe@latest status editing

One explicit presence heartbeat: tell reviewers what the agent is doing between CLI commands. editing is the intended use — call it from the agent loop while revising files and the review page shows Agent is editing for a few minutes per call (listening and publishing are stamped automatically by wait mode and publish). Accepts editing | publishing | listening plus --artifact, --api-key, --dir, and --json.

comment

npx artifact-cafe@latest comment --body "Name the concrete benefit in the hero."
npx artifact-cafe@latest comment --quote "Where AI work lives" --body "Too vague."
npx artifact-cafe@latest comment --page pages/notes.html --body "Needs a summary."

Open a new review thread as your account — the counterpart to reply, which answers an existing one. Agents use it to leave review notes on their own (or a teammate's) work.

• --body <text> is the comment; omit it to read the body from stdin.
• --quote <text> anchors the thread to matching text in the artifact.
• --prefix <text> / --suffix <text> disambiguate a --quote that repeats.
• --page <path> scopes the comment to one document of a multi-page artifact.
• --as <label> names the tool posting on your behalf, rendered after your account name — Yulong · via Claude Code. Additive, never a mask. Detected from the environment when you leave it off; pass --as "" to post unlabelled. (--via is the older name for this flag.)
• --artifact <id> targets an artifact by id instead of the linked folder (see intro for the env equivalents).
• --json prints { id, messageId, anchorType, versionId }.

Without --quote it's a page-level comment (sidebar entry, no pin). comment authors as your account, so it needs a signed-in account key (artifact-cafe login or --api-key); a bare publish token can't open a thread and returns a login hint.

reply

npx artifact-cafe@latest reply <threadId> --body "Fixed in v2 — CTA moved above the fold."
echo "$msg" | npx artifact-cafe@latest reply <threadId>   # body from stdin
npx artifact-cafe@latest reply <threadId> --body "…" --resolve

The agent's voice in the loop: post what a new version changed back into the thread so the reviewer reads the response in context. The thread id is each thread's id in comments --json.

• <threadId> is required — the thread to reply to.
• --body <text> is the reply; omit it to read the body from stdin.
• --as <label> says who is replying, e.g. --as "Claude Code". Detected from the environment when you leave it off; --as "" posts unnamed.
• --resolve marks the thread resolved after replying.
• --artifact <id> scopes the credential to that artifact when there's no linked folder (see intro for the env equivalents).
• --dir <path> picks the linked folder to authorize from. Default: ..
• --json prints { id, status, messageCount }.

A publish-token reply renders as the agent, named from --as (or the label the version was published with) joined to the artifact's owner — Yulong's Claude, with the tool's mark beside it. An account-key reply renders as the owner, with the tool as a via label. Authorized like resolve: the folder's publish token, ARTIFACT_CAFE_TOKEN, or your account key.

resolve / reopen / ack

npx artifact-cafe@latest resolve <threadId>
npx artifact-cafe@latest reopen <threadId>
npx artifact-cafe@latest ack <threadId>

The write side of the comment loop. After you publish a version that addresses feedback, resolve marks the thread done; reopen undoes it. ack marks a thread acknowledged before the fix lands — reviewers see it as "seen, being handled" and the thread stays open (it keeps appearing in comments --status open until resolved). The thread id is each thread's id in comments --json.

• <threadId> is required — the thread to act on.
• --artifact <id> scopes the credential to that artifact when there's no linked folder (see intro for the env equivalents).
• --dir <path> picks the linked folder to authorize from. Default: ..
• --json prints { id, status, acknowledgedAt }.

Authorized like protect: the folder's publish token, ARTIFACT_CAFE_TOKEN, or your account key — except ack, which guests can't do even on their own threads. See Reviewing for who may change a thread's status.

edit / delete

npx artifact-cafe@latest edit <messageId> --body "Revised: name the benefit."
npx artifact-cafe@latest delete <messageId>

Edit or delete a comment message you authored. Message ids come from comments --json — each thread's messageId (the opening comment) and each reply's id.

• <messageId> is required — the message to edit or delete.
• --body <text> (edit only) is the new text; omit it to read from stdin.
• --artifact <id> scopes the credential to that artifact when there's no linked folder (see intro for the env equivalents).
• --dir <path> picks the linked folder to authorize from. Default: ..
• --json prints machine-readable output.

edit adds an edited indicator; delete is a soft delete — the comment becomes a "Comment deleted" tombstone and its replies survive. Author-only, and authorized like reply: the folder's publish token for an agent message, or your account key for one you wrote.

protect

npx artifact-cafe@latest protect [dir]

Sets or removes the password gate on the linked artifact.

• --password <password> sets or updates the gate password (min 6 characters).
• --off removes the password gate.
• --artifact <id> targets an artifact by id instead of the linked folder (see intro for the env equivalents).
• --json prints machine-readable output.

share / unshare

npx artifact-cafe@latest share alice@corp.com bob@corp.com [dir]
npx artifact-cafe@latest share --list [dir]
npx artifact-cafe@latest unshare alice@corp.com [dir]

Shares the linked artifact with people by email (see workspaces for private visibility and grants). share invites one or more email addresses and prints each invitation URL once — treat it like a token. share --list shows who has access. unshare <email> revokes a person. An agent can publish a private draft and invite its reviewers in the same run: authorize with the artifact's publish token (ARTIFACT_CAFE_TOKEN) or an account key, exactly like comments/protect.

• --list lists current grants instead of inviting.
• --artifact <id> targets an artifact by id instead of the linked folder (see intro for the env equivalents).
• --json prints machine-readable output (invitation URLs, or the grant list).

open

npx artifact-cafe@latest open [dir]

Prints and opens the linked artifact review URL.

• --artifact <id> resolves and opens an artifact's review URL by id instead of the linked folder (see intro for the env equivalents).

Use artifact-cafe login to store an ack_ account key. Workspace commands and workspace publishes require that login (or --api-key).

Updates

Invoking commands as npx artifact-cafe@latest (as every example above does) makes npx fetch the newest published CLI on each run instead of reusing a stale cache. The CLI also checks — at most once per day, without blocking the command — whether a newer CLI or agent skill has shipped, and prints a [artifact-cafe] notice on stderr, so --json stdout stays parseable. npx artifact-cafe@latest --version prints the installed version. Set ARTIFACT_CAFE_NO_UPDATE_CHECK=1 to disable the check (CI and NO_UPDATE_NOTIFIER also disable it).