Artifact CLI

CLI to manage and preview artifacts generated by coding agents — standalone HTML, Markdown or MDX. Each artifact lives in docs/artifacts/<slug>/ as index.html, index.md or index.mdx; the dashboard renders them isolated with automatic reload.

Toolchain: Bun only. No npm/pnpm/yarn.

Requirements

• Bun >= 1.0
• A project with artifacts in docs/artifacts/*/

Installation

bun install -g @tarileo/artifacts-cli

From source:

bun install
bun link

Skill for agents

bunx skills add leobar37/artifacts-cli

This installs the artifacts-cli skill (compatible with skills.sh): artifact workflow, command reference, html/md/mdx conventions with the full authoring reference for MDX components, and troubleshooting.

Usage

# One daemon serves all projects; each project gets its own URL
# (`http://localhost:7000/p/<projectId>/`). Run `artifact init` first for new projects.
artifact init                           # scaffold docs/artifacts/ + .gitignore entry
artifact create <slug>                  # scaffold docs/artifacts/<slug>/index.html
artifact create <slug> --format md      # scaffold a Markdown artifact (also: mdx)
artifact start                          # ensure daemon + register project + open dashboard
artifact list                           # daemon status + registered projects
artifact url                            # link to the all-artifacts overview
artifact url <projectId>                # link to one project's dashboard
artifact stop                           # stop the daemon
artifact reload <slug>                  # reload an artifact in the dashboard

Commands

• artifact init — scaffold docs/artifacts/ and add it to .gitignore
• artifact create <slug> [-t <title>] [--type <type>] [--format html|md|mdx] [--force] — scaffold the entry file
• artifact start [-p <port>] [--host <host>] [--tailscale] [--no-open] [--build] [--dev] — ensure the daemon is running, register this project, open its dashboard
• artifact list — daemon status + registered projects with per-project URLs
• artifact url [projectId] — print the dashboard link: the all-artifacts overview, or one project
• artifact stop — stop the daemon
• artifact logs [-n 100] [-f] — show the daemon log (~/.artifact/daemon.log)
• artifact capabilities [--json] — what the viewer supports: formats, MDX components, mermaid, features (--json for agents)
• artifact guide — open the live MDX guide in the browser

artifact start --host tailscale  # or: artifact start --tailscale
artifact start --host 192.168.1.50
ARTIFACT_HOST=my-host artifact start

With a non-loopback --host the daemon listens on 0.0.0.0 and daemon.json stores the visible host (artifact list shows the correct URL).

Remote server setup

One daemon, one port, one firewall rule. artifact start run from a project root registers that directory in ~/.artifact/projects.json and ensures the daemon is running. On a remote host:

curl -fsSL https://bun.sh/install | bash   # if Bun is missing
bun install -g @tarileo/artifacts-cli
cd /srv/my-project
artifact init                               # one time: docs/artifacts/ + .gitignore
artifact start --host <server-ip> --no-open
# or over your Tailnet: artifact start --tailscale --no-open

Register more projects with artifact start from each directory — they all share the daemon, each at http://<host>:7000/p/<projectId>/ (artifact list prints every URL).

Notes:

• start spawns the daemon detached; artifact serve runs it in the foreground (for systemd/tmux: ExecStart=artifact serve --port 7000). SIGTERM shuts down cleanly and removes the daemon lock (the registry persists).
• Open the port in the firewall, or put a reverse proxy in front for TLS.

Agent extension (omp)

@tarileo/artifact-omp gives coding agents seven tools (artifact_create/read/update/versions/list/show/capabilities) plus artifacts:// reads, so agents never hand-write docs/artifacts/ and always answer with dashboard links.

omp plugin install @tarileo/artifact-omp   # from npm

From source instead:

git clone https://github.com/leobar37/artifacts-cli.git
cd artifacts-cli
bun install
bun run --cwd packages/store build
bun run --cwd packages/pi-extension build
omp plugin link ./packages/pi-extension

Features

• React dashboard with smooth navigation

• Isolated rendering of artifacts via sandboxed iframe

• Markdown/MDX artifacts — index.md / index.mdx render in a built-in viewer page (GFM tables and task lists, fenced code with syntax highlighting, dark/light theme that follows the dashboard). Append ?raw=1 to a preview URL for the plain source.

• MDX components — Chart (bar/line/area/pie, server-rendered with recharts), Stats+Stat (KPI grids), Callout (info/warning/success/ danger), Section (titled card that joins the index) and Svg (declarative boxes/circles/arrows/texts from literal data) render for real; props must be literals, so agents inline their data. Module statements and {/* comments */} are hidden; unknown components keep visible placeholders.

• Cards and collections — Card references an image/video/audio/file asset, Cards creates a responsive grid, Carousel adds scrolling and keyboard controls, and Table renders literal rows/columns or Markdown tables.

• Multi-page MDX — keep index.mdx as the overview and attach focused sibling pages. Pages provides a page map, active-page highlighting and previous/next links. Copy for agent identifies the current page's source.

• Native SVG in MDX — write a lowercase <svg viewBox="..."> block for detailed architecture diagrams with groups, paths, markers and multiline labels. XML is validated, active content is filtered, IDs/references are isolated per diagram, and wide graphics expand at natural canvas width. The live guide explains chart-vs-diagram choices, layout, real data and safe literal SVG authoring.

  Authoring JSON data views (TaskList / Kanban / Properties)

  Three read-only components render a version-1 JSON snapshot: TaskList (work items, optional groupBy="group"), Kanban (columns in declared order) and Properties (labeled scalar values, optional sections). Feed each with exactly one of a literal data={...} object (server-rendered) or a sibling src="tasks.json" (same-origin, document-relative, fetched by the viewer at render time):

  <TaskList src="tasks.json" groupBy="group" title="Work items" />
  <Kanban data={{ version: 1, columns: [{ id: "done", label: "Done" }], items: [] }} title="Status board" />
  <Properties src="profile.json" title="Execution profile" />

  Limits per source: 1 MiB JSON, 1,000 items, 50 columns, 100 groups, 100 property entries — over-limit or malformed data renders a visible per-component error, never a crash or silent truncation. The views are snapshots, not live (generatedAt/sourceLabel are display-only metadata) and read-only: no write-back, no drag-and-drop. Item links accept document-relative paths or #fragments only, and producers must explicitly select safe fields — credentials are never auto-redacted. See the live guide (artifact guide) for full examples.

• Sections index — 3+ headings get anchor ids and a Secciones sidebar (sticky + scroll-spy, stacked on mobile); short docs keep the single-column look.

• Folder standard — an artifact is a folder: sibling images referenced by relative path, .md/.mdx siblings render as viewer sub-routes, and <Webframe src="wireframe.html" /> embeds HTML mocks in a browser chrome. Agents attach bytes via the artifact_asset omp tool (store-backed); symlinked folders are served too.

• Mermaid diagrams — fenced blocks tagged mermaid (flowchart, sequence, ER, gantt, …) render client-side from a bundle served by your own daemon: works offline and over Tailscale; source stays visible without JS.

• Capability discovery — artifact capabilities [--json] prints formats, components with props, mermaid and features (machine-readable for agents); artifact guide opens the live reference at /mdx-guide (served by every daemon and broker, linked from the viewer bar).

• Single daemon — one server on port 7000 serves all projects

• Automatic build — if dist/ is missing, it compiles on start

• Multiple projects — each project gets its own URL (/p/<projectId>/) with a project switcher

• Configurable host — --host / --tailscale for LAN or Tailnet

• Dark theme

Development

bun install          # dependencies (root workspace + packages/*)
bun run build        # dashboard + server
bun run dev          # dashboard with HMR
bun run dev:server   # server with watch
bun run typecheck    # tsc dashboard + node
bunx vitest run      # tests

Preview UI changes with mock data (before deploying)

bun run mock                                              # seed /tmp/artifact-mock (shop/blog/empty)
ARTIFACT_DIR=/tmp/artifact-mock/home artifact start       # daemon with isolated registry

Visual checklist: overview grouping + counts, project switcher (mouse + keyboard), viewer load, viewer timeout (stop the daemon on purpose, expect the error panel with Retry, not an endless spinner), narrow viewport. Clean up with artifact stop and rm -rf /tmp/artifact-mock.

Daemon logs

The daemon tees every log line to ~/.artifact/daemon.log (rotated at 1 MB). Read it with artifact logs [-n 100] [-f].

Structure

.
├── src/
│   ├── cli/         # entry point and commands
│   ├── server/      # Hono server + watcher + dashboard API + markdown/mdx viewer
│   ├── dashboard/   # React app (Vite)
│   ├── handlers/    # artifact types (generic/study/wireframe)
│   └── utils/       # scanner, registry, daemon, ports, host/tailscale
├── packages/
│   ├── store/         # @tarileo/artifact-store: shared storage
│   └── pi-extension/  # @tarileo/artifact-omp: agent extension
├── skills/
│   └── artifacts-cli/ # portable skill (SKILL.md)
├── landing/           # static site (Vercel deploy)
└── dist/              # build output (generated, not committed)

Notes

• The CLI automatically detects whether the dashboard needs to be compiled; use --build to force it.
• Each project is identified by its absolute path and registered in ~/.artifact/projects.json; the running daemon is tracked in ~/.artifact/daemon.json.
• npm publishing via GitHub Actions with NPM_TOKEN (see .github/workflows/publish.yml).

Storage and versions

docs/artifacts/ is a local working copy and git-ignored. The source of truth lives in the global store ~/.artifact/store/<repoId>/ (same id across all your worktrees of the repo): each save creates versions/v001… with the format's extension, updates index.<ext> (latest) + meta.json + manifest.json, and leaves docs/artifacts/<slug>/index.<ext> as a symlink to latest.

With the omp extension (@tarileo/artifact-omp): artifact_create/read/update/ versions/list/show/capabilities (show returns the shareable dashboard link — agents answer with links, never pasted content; capabilities returns formats, MDX components with props, mermaid and features so agents know what they can render before writing). artifact_create/artifact_update take content plus format: html|md|mdx — agents can move a Markdown or MDX document and the dashboard renders it in the built-in viewer; artifact_read returns the source for editing. The skill ships a full authoring reference (references/mdx-components.md) for agents. Direct reads: artifacts://<slug> or artifacts://<slug>/<version> — served as text/html or text/markdown depending on the artifact's format.