# ZeroPress CLI Tools

ZeroPress provides a small set of command line tools for creating themes, checking theme packages, previewing local work, and building static site output.

These tools support the Preview Data v0.7 publishing workflow and Theme Runtime v0.7. They are not runtime contracts themselves, but they are the recommended way to work with those contracts.

## Choose The Tool

| Goal | Tool |
| --- | --- |
| Create a starter theme and fixture preview-data | `@zeropress/create-theme` |
| Preview, validate, or package a theme | `@zeropress/theme` |
| Build directly from `preview-data.json` and `theme/` | `@zeropress/build` |
| Build a Markdown source tree for static hosting | `@zeropress/build-pages` |

## Markdown Sites

Use `@zeropress/build-pages` when a repository contains Markdown files, public assets, and optional `.zeropress/config.json`. Build Pages is documented separately at [build-pages.zeropress.dev](https://build-pages.zeropress.dev/).

An authored config file uses the strict [Build Pages Config v0.7 Schema](https://schemas.zeropress.dev/build-pages-config/v0.7/schema.json) and must declare `"version": "0.7"`. If the default config path does not exist, Build Pages continues with its documented defaults; a missing path supplied explicitly with `--config` is an error. The resolved config always records the v0.7 schema URL and `version: "0.7"`.

As a temporary CLI-only migration path, an explicit `version: "0.1"` config is accepted with one warning and normalized into the v0.7 model. This does not make v0.1 schema-valid. Only that compatibility path translates historical `site.indexing` into `site.robots: { "allow_indexing": boolean }`; v0.7 rejects `site.indexing`, a missing version, non-string versions, and every other version.

Build Pages validates source-relative file paths against controls, backslashes, traversal, and empty/dot segments. Menu URLs use the Preview Data navigation policy: safe single-slash root-relative or credential-free HTTP(S) only. Omitted `menus` materializes a `primary` menu containing Home, while an explicit `{}` opts out. An omitted menu `name` uses its menu id, and an omitted collection `title` uses its collection id. These deterministic fallbacks are recorded in the resolved config before Preview Data is generated.

## Theme Development

Create a starter theme:

```bash
npx @zeropress/create-theme --name my-docs-theme --template docs
```

Preview the generated theme:

```bash
npx @zeropress/theme dev ./my-docs-theme/theme --data ./my-docs-theme/preview-data.json
```

Validate and package the theme:

```bash
npx @zeropress/theme validate ./my-docs-theme/theme
npx @zeropress/theme pack ./my-docs-theme/theme
```

The old unscoped `create-zeropress-theme` package is deprecated. Use `@zeropress/create-theme` for new projects.

## Direct Preview Data Builds

Use `@zeropress/build` when you already have a v0.7 `preview-data.json` file and a ZeroPress theme:

```bash
npx @zeropress/build ./theme --data ./preview-data.json --out ./dist
```

This path is useful for AI-generated sites, admin-generated preview-data, importers, and custom pipelines.

## Package References

For copy-paste command snippets, see [Package Quick Starts](../../packages/index.md).

The package READMEs are the source of truth for command options and release metadata:

- [`@zeropress/build-pages`](https://build-pages.zeropress.dev/)
- [`@zeropress/create-theme`](https://www.npmjs.com/package/@zeropress/create-theme)
- [`@zeropress/theme`](https://www.npmjs.com/package/@zeropress/theme)
- [`@zeropress/build`](https://www.npmjs.com/package/@zeropress/build)

## Related Contracts

- [Theme Runtime Reference](../../reference/theme-runtime/index.md)
- [Preview Data Reference](../../reference/preview-data/index.md)
- [Theme Manifest Runtime v0.7 Schema](https://schemas.zeropress.dev/theme-runtime/v0.7/schema.json)
- [Preview Data v0.7 Schema](https://schemas.zeropress.dev/preview-data/v0.7/schema.json)
- [Build Pages Config v0.7 Schema](https://schemas.zeropress.dev/build-pages-config/v0.7/schema.json)