CLI commands

Full reference for every numu-theme subcommand.

`init`

numu-theme init <name> [--template <slug>] [--dir <path>]

Scaffolds a fresh theme. Creates:

<name>/
├── package.json
├── tsconfig.json
├── vite.config.ts
├── theme.json
├── settings_schema.json
├── src/
│   ├── main.tsx
│   ├── pages/{Home,Product,Cart,NotFound}.tsx
│   ├── sections/Hero.tsx
│   └── blocks/CtaButton.tsx
├── schemas/
│   ├── sections/hero.json
│   └── blocks/cta-button.json
├── locales/
│   ├── en.default.json
│   └── ar.json
├── templates/
│   ├── error.html
│   └── loading.html
└── assets/
    └── placeholder.png

Then runs npm install. After: cd <name> && numu-theme dev.

`dev`

numu-theme dev [--port <n>] [--watch] [--api-url <url>]

Starts Vite's dev server (default port 3001) with the plugin's middleware. Serves:

/theme.js — your bundle (HMR)

/theme.css — your styles

/manifest.json — current bundle's manifest

/sections.json — section schema index

/runtime/* — React + SDK so the bundle resolves bare specifiers

/__numu/preview — HTML shell that mounts your bundle with mock data

Open http://localhost:3001/__numu/preview to see your theme rendering against a fake store. Or point the customizer's external_theme.bundle_url to http://localhost:3001/theme.js to preview with real merchant data.

--watch re-runs schema codegen on schemas/**/*.json changes.

`check`

numu-theme check [--dir <path>]

Syntax-validates theme.json, every schemas/**/*.json, and every locales/*.json. Exits non-zero if any file fails to parse or violates a schema invariant (e.g. a section preset referencing a setting id not declared in its schema).

Faster than lint. Run on every save as part of your editor's "save-and-validate" loop.

`lint`

numu-theme lint [--strict] [--json] [--rules id1,id2,...] [--dir <path>]

Runs the 10 lint rules. See Lint Rules for what each catches.

--strict promotes warnings to errors (use in CI). --json outputs machine-readable diagnostics for editor integration. --rules runs only the listed rule ids.

Exit code:

0 — no issues, or only warnings (without --strict)

1 — errors found, or warnings with --strict

`build`

numu-theme build [--dir <path>] [--watch]

Production build via Vite. Output: dist/.

Runs:

Contract validator (strict)

Schema codegen

Vite build with lib config + federation externals

Asset pipeline (content-hashes assets/*)

Manifest emission

Outputs:

dist/
├── theme.js
├── theme.css
├── manifest.json
├── sections.json
├── assets/
│   └── <hash>.<ext>
├── error.html       (if templates/error.html exists)
└── loading.html

--watch re-builds on changes — useful for numu-theme push flows.

`push`

numu-theme push [--dir <path>]

Uploads dist/ to your developer sandbox on the marketplace. This is not a public submission — it just stages a version under your account so you can install it on your own test store via numu-theme install <your-theme-id>.

Requires numu-theme login first.

`submit`

numu-theme submit [--dir <path>] [--release-notes "..."]

Submits the current dist/ for public marketplace review. The server-side flow:

Receive ZIP

AST-scan for forbidden patterns (raw eval, network exfiltration, etc.)

Re-build in a sandboxed Docker worker — ignores the dev's dist/, builds from source

Diff against the previous published version

Queue for admin review

On approve → upload to R2 → public install URL

Detailed flow in Theme Dev E2E → Submit Stage.

`install`

numu-theme install <theme-id> [--store <subdomain>]

Installs a published or developer-pushed theme into your active store. Without --store, uses the store linked to your marketplace account.

For developer-install flow (install your own pushed theme into your own test store), this works even before admin approval — owners can always install their own.

`login`

numu-theme login [--api-url <url>]

Opens a browser to the marketplace login page, captures the resulting token, stores it in ~/.numu/credentials.json. Required for push, submit, install.

`status`

numu-theme status

Prints:

Logged-in identity

Active theme (current directory's theme.json id + version)

Last build status (dist/ mtime + manifest.json summary)

Server-side: last submitted version, current review state

`doctor`

numu-theme doctor

Diagnostic checklist. Reports:

Node version match (expect 20.x)

React + SDK pinned to compatible versions

package.json declares them as peerDependencies

vite.config.ts includes the plugin

theme.json valid

schemas/sections/*.json syntactically valid

Locale files match (default keys are present in every locale)

All sections referenced in presets have schemas

All sections in main.tsx's dispatch are registered

dist/ exists and is fresh

Use doctor as your first stop when something feels off.

`add-section`

numu-theme add-section <name> [--from-library <slug>] [--list]

Scaffolds a new section.

Empty mode (default): generates a minimal Pascal.tsx + kebab.json schema

--from-library <slug>: copies one of the 15 library entries — fully styled, ready to drop in

--list: prints the library catalog

The command also:

Writes src/sections/<Pascal>.tsx

Writes schemas/sections/<kebab>.json

Best-effort wires the import + section.type dispatch in src/main.tsx (regex-based, falls back to a TODO comment)

Appends a default instance to theme.json's home preset so it appears in the customizer immediately

`add-block`

numu-theme add-block <section-type> <block-name>

Same shape as add-section but scoped to a section. Creates src/blocks/<Pascal>.tsx + schemas/blocks/<kebab>.json, then updates the section's schema to register the block.

`pull`

numu-theme pull <theme-id> [--version <semver>] [--dir <path>]

Downloads the source of a published theme as a ZIP, extracts to <dir> (default ./<theme-id>/). Closes the "iterate on an existing theme" loop. Source code is only available for themes you own.

`delete`

numu-theme delete <theme-id>

Soft-deletes a draft theme or unpublishes a published one. Existing installs continue to work (the bundle stays on R2) but the marketplace listing is hidden. Requires confirmation (--yes to skip).

Common flags

Flag	Effect
`--dir <path>`	Run against `<path>` instead of CWD
`--api-url <url>`	Override marketplace API endpoint (for staging)
`--quiet`	Suppress progress logs (errors still print)
`--verbose`	Print debug info
`--no-color`	Disable ANSI colors

Exit codes

Code	Meaning
0	Success
1	User error (bad args, missing file, lint errors)
2	Network / API error (auth, marketplace 5xx)
3	Build error (Vite failed, contract validator rejected)

init#

dev#

check#

lint#

build#

push#

submit#

install#

login#

status#

doctor#

add-section#

add-block#

pull#

delete#

Common flags#

Exit codes#