# eggox blueprint

Local voxel files, complete-frame uploads, saved iterations and minting.

| Command | Effect |
| --- | --- |
| `eggox blueprints` | List owned empty blueprints and latest prototypes |
| `eggox blueprint schema` | Print the JSON schema and authoring rules, offline |
| `eggox blueprint init [file]` | Create an empty local file; no purchase or network request |
| `eggox blueprint pull <id> [file]` | Download full frames, layers and metadata; default `blueprint.json` |
| `eggox blueprint check [file]` | Validate locally; add `--remote` for server validation |
| `eggox blueprint frame <file> <index> <frame.json>` | Replace a complete frame locally, or append at `frames.length` |
| `eggox blueprint render [file]` | See any local frame as a PNG without saving; `--id` selects a saved iteration |
| `eggox blueprint push [file]` | Save a draft iteration and update the file's id/revision |
| `eggox blueprint history <id>` | List lineage iterations |
| `eggox blueprint mint <id> <count>` | Strike the editions of a published iteration, once |

The CLI works only with what is already in your bag: it never spends Voxels. Take a blank blueprint in Eggox (free, in the Market's STUDIO section), and `eggox blueprints` lists it. Publishing an iteration costs Voxels (more for bigger, many-framed designs), so it happens in Eggox, from the item's Versions window, where the price is shown. Minting is free: once a version is published, `eggox blueprint mint <id> <count>` strikes its editions. A design is minted once, and the count is its whole supply.

A push can be refused with `design_taken`: one of its frames is exactly the same as a frame of somebody else's blueprint (the visible outside and its colours). Change that frame and push again. Frames unchanged from a starter character and nearly empty frames never clash, and your own blueprint never clashes with itself. See [One design, one blueprint](/studio/blueprints#one-design-one-blueprint).

Use `--force` only when deliberately overwriting a local file or saving from an older revision. Publishing in the game (or minting) does not make your file stale: push again without it. A push with nothing changed saves nothing and returns the latest iteration.

A `solid` thing taller than 24 voxels (a step) with no `footprint` and no `collision_height` would let players climb onto it. `check` warns about that, and `push` saves it with a footprint that blocks every tile, so a wall or cabinet is a wall. Give it a `footprint` to have tiles players can walk through or stand on. `init` creates an unattached file: to upload it, pull a blueprint you own (bought in Eggox) and copy its `id`, `revision`, and `server` into your generated document.

All blueprint commands return compact JSON except the human `blueprints` listing; add `--json` for that listing. Frames remain in files, never in MCP tool responses. `eggox docs blueprints` prints the complete workflow and format contract as Markdown.

MCP exposes `eggox_blueprints` and `eggox_blueprint_schema`, `init`, `pull`, `check`, `frame`, `push`, `history`, `mint`. File operations accept `file`; `frame` also takes `index` and `frame_file`; `pull`, `history` and `mint` take `id`, and `mint` a `count`. `pull`/`push`/`init` accept `force`, and `check` accepts `remote`.

See [Blueprint files](/studio/blueprints) and [Frame format](/studio/frames).

See [Render previews](/cli/render) for frame/layer selection, views, PNG output, MCP image replies and the shared hourly account allowance.