CLI and projects

npm i -g @mozaik/cli opens a store as a file-tree project: design as files an agent can read, diff and edit with ordinary tools, synced against the server draft under CAS. The full command table is generated at /reference/cli; this page is the working loop.

The loop

mozaik login --token mzk_…        # once per machine
mozaik open st_mystore            # Tree v1 + mozaik.json + AGENTS.md + .mcp.json
# edit design/ with anything
mozaik push                       # validate server-side, save as the workspace draft (CAS)
mozaik preview                    # stable preview URL of the workspace draft
mozaik propose --title "…"        # agent tokens: submit the open proposal for review

open is idempotent (≈ pull); dev watches design/, pushes on change and keeps the preview URL live; status and diff compare the tree against the lock, the server draft or the live design. Catalog data has its own arm: mozaik catalog export|plan|apply (catalog) round-trips catalog/*.jsonl as idempotent commands, and cmd runs any single command through the bus — for an Ajan token, recorded as a proposal item like every mutation.

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

The design/ tree assembles to exactly the server draft — same hash — so "what would change" is always answerable locally. validate runs the server-side bundle checks (validate.bundle) without saving anything.

Credentials never live in the project

The token sits in ~/.config/mozaik/credentials.json (0600) or MOZAIK_API_TOKEN — never under the project root. mozaik.json, .mozaik/ and .mcp.json contain zero secret material (the .mcp.json uses env substitution), so a project tree is always safe to commit, zip or hand to another agent.

.mcp.json wiring

open writes an .mcp.json that gives any MCP-aware editor or agent two servers, both pinned to the project's CLI version:

• admin MCP — https://api.mozaik-dev.com/mcp with the bearer from the environment: the store's tools, live.
• dev MCP — mozaik dev-mcp (dev-mcp) over stdio: docs search, schema introspection and validators for the current platform build. No auth, no store access.

AGENTS.md in the tree carries the store-specific working notes; Claude Code reads it via CLAUDE.md = @AGENTS.md.

Exit codes

Everything the CLI does is the public API — the same commands, routes and version discipline as every other client; there is nothing the CLI can do that your own HTTP calls cannot.