Extension API v0 — pre-1.0. Interfaces may change without notice until P2 seals the custom-code format. First-party extensions track HEAD.
The mozaik CLI
npm i -g @mozaik/cli — open a store as a project, edit design as files, push drafts, propose changes. The CLI carries X-Mozaik-Client on every request; a build below the platform's supported floor is refused with HTTP 426 (exit code 3) and the exact upgrade command. Credentials live in ~/.config/mozaik/credentials.json or MOZAIK_API_TOKEN — never inside a project.
Exit codes: 0 ok · 1 error · 2 usage · 3 version/format refusal · 4 conflict (draft moved; the server never merges).
project
| command | what it does |
|---|
mozaik open <storeId> [--workspace ws_…|main] [--from draft|live] [--dir path] [--non-interactive] | Open a store as a project: Tree v1 + mozaik.json + AGENTS.md + .mcp.json + pinned package.json. Idempotent (≈ pull). |
mozaik pull [--force] | Re-sync the tree from the server draft (or live). Refuses to overwrite local edits without --force. |
mozaik status | Local changes vs the lock, remote draft rev, platform drift. |
mozaik diff [--remote|--live] | File-level diff vs the last sync (default), the server draft, or the live design. |
design
| command | what it does |
|---|
mozaik push | Validate server-side, then save the tree as the workspace draft under optimistic concurrency (409 = exit 4, never merged). |
mozaik publish [--label text] | Publish the workspace draft to the live store. Developer tokens with the design:publish scope only — agents propose instead. |
mozaik dev | Watch design/, push on change, print the stable workspace preview URL. Pauses on conflict. |
mozaik preview | Print the stable preview URL of the workspace draft. |
mozaik validate | Assemble the tree and run the server-side bundle checks without saving. |
data
| command | what it does |
|---|
mozaik cmd <name> [--payload '<json>'|@file] [--dry-run] [--note text] | Run one command through the command bus (agents: recorded as a proposal item). |
mozaik audit [--entity id] [--actor merchant|agent|cli|system] [--limit n] | Recent audit rows. |
mozaik catalog export|plan|apply [--dry-run] | Export catalog to jsonl files; plan/apply row diffs as idempotent commands (one storefront bump). |
mozaik media manifest|push | Sync media/manifest.json; upload files from media/uploads/. |
agents
| command | what it does |
|---|
mozaik propose [--title text] [--message text] | Submit your open proposal for owner review (agent tokens). |
mozaik proposal list|status [id]|withdraw <id> | Inspect or withdraw proposals this token created. |
mozaik ext ops <extensionId> | An installed extension's agent operations and their live readiness. |
mozaik workspace list|attach <ws> | List workspaces; point this project at another workspace (owner/developer). |
mozaik dev-mcp | Stdio MCP server for editors/agents: docs search, schemas and validators for the CURRENT platform build. No auth. |
| command | what it does |
|---|
mozaik login [--token mzk_…] [--origin URL] | Store an API token (developer or agent) for this machine — kept in ~/.config/mozaik/credentials.json, never in a project. |
mozaik whoami | Which store, token kind, scopes and workspace this credential resolves to. |
mozaik meta | Platform build identity: buildId, apiVersion, registry hashes, CLI floor/latest. |
mozaik log [--limit n] | Versions, audit entries and proposals, interleaved newest-first. |
mozaik commands | The command registry visible to this token (name + summary). |
mozaik routes | The typed route catalog visible to this token. |
mozaik upgrade | Re-pin the project to the current platform build (package.json, .mcp.json, lock). |
Project layout (Tree v1)
mozaik.json project manifest (format, store, workspace, pinned CLI) — no secrets
.mozaik/base.lock last-sync state (platform build, draft rev/hash, file hashes)
AGENTS.md how agents should work here (CLAUDE.md = @AGENTS.md)
.mcp.json MCP wiring: hosted admin MCP + local dev-mcp, both pinned
design/ the store design as files (assembled hash == server hash)
catalog/*.jsonl optional catalog export
media/manifest.json media inventory
sections/ islands/ hooks/ css/ reserved