<!-- 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. |

## platform

| 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
```