openartifacts ยท diff
git:20260904.b2ad8c0 to git:20260908.531773d
60 added, 12 removed. Audit A to A.
---
name: openartifacts
- description: Publish, update, list, fetch, or unshare public OpenArtifacts documents and manage this machine's OpenArtifacts access.
+ description: Publish, update, list, fetch, or unshare OpenArtifacts documents with rendered review before publication.
metadata:
hermes:
category: productivity
tags: [publishing, markdown, artifacts]
---
# OpenArtifacts
- Use `openartifacts` as the command prefix when it is installed. Otherwise use
- `npx --yes openartifacts@latest`; do not require another package install first.
- Do not read OpenArtifacts config files, look for credentials, or print
- `OPENARTIFACTS_TOKEN`.
+ ## Shared publishing rules
- - Publish Markdown or HTML: `openartifacts publish <file>`
+ Host adapters follow these rules and replace the standalone CLI
+ instructions below with their own execution, authentication, document identity,
+ and approval UI. Never run standalone commands when a host adapter supplies them.
+
+ Before every publish or update:
+
+ 1. Prepare the requested page, preserving the source content. Themes are optional;
+ a missing theme must not block publishing. HTML is accepted unchanged, including
+ CSS, scripts, forms, frames, and external resources.
+ 2. Present a protected local browser preview before publishing. The review copy
+ must block page scripts, network requests, and navigation. This shows the static
+ appearance; interactive behavior and external resources are unavailable during
+ review. Never open the unrestricted source HTML as a fallback. Showing source,
+ a path, or a summary does not count as a rendered preview. If the protected
+ preview cannot be presented, stop; never publish to obtain a preview.
+ 3. Wait for the user's explicit approval of the displayed page. The initial publish
+ request and sign-in approval do not replace review. Hosts may enforce approval
+ in an existing confirmation dialog. Never simulate the user's confirmation.
+ 4. Publish the original reviewed HTML, without the preview's restrictions or shell.
+ If the content changes, generate and present another preview and obtain fresh
+ approval. Host branding may be added by the publishing integration; OpenArtifacts
+ serving decorations need not appear in the local preview.
+
+ Preserve source identity so repeat publishing updates the same document. Keep the
+ prepared artifact on cancellation or failure so review can be reopened. Hosts may
+ remove temporary staged copies after confirmed success or explicit discard, but
+ must retain the original source document. Return only the successful publisher's
+ public URL. A pending review is not a successful publish.
+
+ Report actual failures without guessing causes, removing styling, bypassing review,
+ or blindly retrying. If an update returns `not_found`, stop; do not create a replacement
+ without the user's explicit request. For `quota_exceeded`, report whether to wait or
+ remove an unused document. For `limit_reached`, show the supplied limit and upgrade
+ link, and retry only after the user confirms the limit changed. Do not read credential
+ files, print tokens, or ask the user to copy credentials.
+
+ ## Standalone CLI
+
+ This section applies only when no host adapter supplies execution instructions.
+ Use `openartifacts` when installed, otherwise `npx --yes openartifacts@latest`.
+
+ - Preview Markdown or HTML locally: `openartifacts preview <file>`
+ - Publish Markdown or HTML after review: `openartifacts publish <file>`
- List documents: `openartifacts list`
- Fetch current HTML: `openartifacts get <docId>`
- Withdraw a document: `openartifacts unshare <docId>`
- List machine tokens: `openartifacts tokens`
- Revoke one: `openartifacts revoke <tokenId>`
- Sign in again after an `unauthorized` response: `openartifacts login`
- The first authenticated command may wait for approval. Relay both sign-in URLs and the user code printed by the CLI, then keep waiting; never ask the user to copy a token. Return the public URL printed by `publish`.
- Publishing the same local file again updates its existing document. If an update returns `not_found`, stop and report it; do not create a replacement.
-
- Markdown files use ordinary Markdown rendering. Obsidian wikilinks, embeds, and callouts are not expanded and will appear as literal text.
+ Run `openartifacts preview <file> > <separate-review.html>`. Never overwrite the
+ source. The command runs without authentication and prints the reviewed HTML's
+ SHA-256 to stderr. Open the protected review file in a user-visible browser and
+ wait for explicit approval. If `preview` is unavailable, use a release supporting
+ it or stop. After approval, run
+ `openartifacts publish <original-file> --reviewed-sha256 <printed-hash>`.
+ A changed source is rejected before authentication or upload; preview it again.
+ Keep the original source path so repeat publishing preserves document identity.
- If the user explicitly wants a new link after an update returns `not_found`, ask for confirmation, run `openartifacts unshare <oldDocId>` to forget the stale local mapping, then publish the file again. Never take that recovery path automatically.
+ The first authenticated command may wait for browser sign-in approval. Relay both
+ sign-in URLs and the user code printed by the CLI, then keep waiting. Browser
+ sign-in is separate from approval of the rendered page.
- If publishing returns `quota_exceeded`, show the error and advise the user to wait for the current quota window or remove an unused document, as appropriate. Do not blindly retry. If publishing returns `limit_reached`, show its limit and upgrade link when present, and retry only after the user confirms the limit was changed.
+ Markdown uses ordinary Markdown rendering; Obsidian wikilinks, embeds, and callouts
+ are not expanded. If the user explicitly requests a replacement after `not_found`,
+ run `openartifacts unshare <oldDocId>` to forget the stale local mapping, then repeat
+ preview, approval, and publishing. Never take that recovery path automatically.