@braevi/theme-cli

Command line tools for first-party Braevi declarative theme authoring.

braevi theme init studio-one
cd studio-one
braevi theme
braevi theme dev
braevi theme studio
braevi theme check .
braevi theme build .
braevi theme pack .

The CLI executes a developer's local theme.ts on the developer machine. Braevi API imports only the built JSON artifact.

Run braevi theme without a subcommand in an interactive terminal to open a keyboard navigation menu for init, dev, studio, check, build, and pack. Non-interactive shells print command usage instead of waiting for input.

Use braevi theme check . --json to emit deterministic machine-readable validation output with ok, diagnostics, errors, and summary metadata. JSON mode writes only JSON to stdout and exits nonzero when validation errors are present.

theme check --json includes schemaVersion: 1 and a structured compatibility result. Human output shows artifact format, document schema, manifest, runtime contract, minimum platform, capabilities, migration status, and actionable diagnostics. Compatible artifacts exit zero; invalid or incompatible artifacts exit nonzero. Deprecated legacy artifacts are valid but should be rebuilt to refresh the full compatibility object.

braevi theme studio opens the Charm Bubble Tea diagnostics dashboard. The dashboard consumes braevi theme check --json, refreshes on a short interval, and lets theme authors inspect validation status, counts, diagnostic paths, and remediation details from the terminal. Published npm packages include prebuilt studio binaries for supported macOS, Linux, and Windows platforms. If you are developing the CLI locally, build the dashboard with npm run studio:build --workspace @braevi/theme-cli or set BRAEVI_THEME_STUDIO_BIN to a custom executable.

braevi theme dev starts a loopback-only localhost preview on 127.0.0.1 by default. It renders the same approved Essential section registry and runtime package used by the hosted storefront, with deterministic fixture products, collections, variants, prices, media, and cart/search capability notices. It watches theme.ts, styles/theme.css, and local assets, keeps the last valid preview visible after an invalid edit, and shows file/path diagnostics in the browser.

styles/theme.css is structurally validated, scoped to [data-braevi-theme-root], and embedded into the JSON artifact as processed CSS with a reproducible SHA-256 hash. Use documented hooks such as [data-braevi-section="product-grid"] and [data-braevi-slot="heading"]; global selectors, remote URLs, @import, executable CSS features, and high-overlay CSS are rejected.

theme pack writes the exact built artifact plus a .sha256 sidecar. The checksum is an integrity check for the packed bytes; compatibility is evaluated separately from the artifact metadata.