CLI reference
On this page
Every bizzpocket command, flag, environment variable and exit code. The usage lines and descriptions are the CLI's own help text (bizzpocket help <command>). Run the CLI with bunx bizzpocket <command> inside a theme (it is a dev dependency of every theme), or bunx @bizzpocket/cli <command> anywhere. For a walkthrough, read The CLI.
usage: bizzpocket init <dir> [--from <themeDir> | --blank]
bizzpocket dev (--store <slug> | --mock | --mock-guest) [--locale <tag>] [--port 4321] [--api <base>] [--dir .] [--prod]
bizzpocket whoami --store <slug> [--api <base>]
bizzpocket build [--target next|bun|both] [--dir .] [--out <folder>] [--json]
bizzpocket add <name...> [--overwrite] [--trust-registry <host>]... [--allow-proxy]
bizzpocket diff [name] [--trust-registry <host>]... [--allow-proxy]
bizzpocket add-to-layout <block> [--page home] [--parent <id>] [--dir .]
bizzpocket check [--dir .] [--json] [--strict] [--verbose] [--max-client-kb N] [--max-block-client-kb N] [--max-page-client-kb N] [--max-css-kb N] [--max-block-css-kb N] [--max-page-css-kb N]
bizzpocket typegen [--dir <theme>] [--out <file.d.ts>] [--check]
bizzpocket css-split [--dir <theme>] [--plan] [--out <folder> --write [--include-likely] [--rules <file.json>]] [--list N] [--json]
bizzpocket package [--dir .] [--out <file.tgz>] [--json] [--strict] [--skip-check]
bizzpocket publish [--dir . | --package <file.tgz>] [--store <slug> [--api <base>] | --registry <url>] [--dry-run] [--strict] [--skip-check] [--trust-registry <host>]... [--allow-proxy]
bizzpocket migrate [themeDir] [--dry-run] [--json]| Command | What it does |
|---|---|
init |
Create a theme folder: the blank starter (default, or --blank) or a copy of another theme. |
dev |
Serve the theme locally and rebuild on save. --mock uses built-in sample data (no store, no token) with a signed-in sample shopper; --mock-guest is the same data with nobody signed in; --locale shows the pages in one of the theme's locales (for example hi) instead of the store's own, for this dev server only; any other tag is an error that lists the theme's locales. --store uses a real store through --api and needs BIZZPOCKET_DEV_TOKEN (a bpdt_ developer token from the store's Settings → Developers). |
whoami |
Check the developer token in BIZZPOCKET_DEV_TOKEN: print its store and when it expires. |
build |
Build dist/ and print the size report (server bytes, client JS, CSS, data mode per block, and why a block is runtime, with file:line). --out writes everything there instead of the theme's dist/ (the theme folder is left untouched). The folder must be empty, new, or one an earlier build made (it holds a .bizzpocket-build marker); a folder with other files is refused, never emptied. --json prints the report as JSON instead. |
add |
Copy blocks / components from the @bizzpocket/blocks registry into the theme. |
diff |
Show how registry items differ from your copies. |
add-to-layout |
Append an instance of blocks/ (new id, default props) to layouts/.json; --parent puts it inside that container block. |
check |
Check the theme before you publish: layouts against the blocks (unknown blocks and props, nesting, duplicate ids, unsafe URLs, placeholder text), data mode and size budgets from the build, the ESLint config and SDK 2 leftovers. Prints findings by severity, each with a rule id, file:line, what is wrong and how to fix it. Exit code 1 on any error (or any warning with --strict). Rules can be turned off or re-levelled in package.json ("bizzpocket"."check"). --json prints { findings, summary } as JSON. Nothing is written to the theme folder. Info findings are hidden unless --verbose. Budgets in KB gzip: --max-client-kb 50, --max-block-client-kb 10, --max-page-client-kb 30, --max-css-kb 20, --max-block-css-kb 7, --max-page-css-kb 14. |
typegen |
Write types/bizzpocket.d.ts (block props and data, layout nodes, message keys), types/bizzpocket.register.d.ts (registers the messages with the SDK; include only one theme's types/ per TypeScript program) and types/layout.schema.json (layouts/*.json). --check writes nothing and exits 1 when any of the files is stale. |
css-split |
Plan or write the move of global CSS rules into the blocks that own them (blocks//.css), so a page loads only the CSS of its blocks. --plan (default) prints, per block, the rules of styles/global.css that could move, by confidence: safe (the build's order proof holds), likely (one owner, the order guard held it back, with the reason), shared (several blocks), unknown (no block names the class); and the gzip sizes before and after. --write --out writes a copy of the theme with the safe rules (plus the likely ones with --include-likely) moved; the theme folder is never written. Prove a copy with scripts/css-parity.ts. --list N shows N selectors per group (0 = all). |
package |
Check the theme, build it into a temp folder and write a reproducible .tgz plus its manifest (sha256 per file, SDK versions, blocks, locales, sizes). Prints the size table and the sha512. --json prints the manifest. Refuses on check errors (--strict: warnings too). Refuses secrets, absolute paths, escaping symlinks and oversize packages. |
publish |
Validate a package and show where it would go. --dry-run prints what would be uploaded and whether the token would be sent. Upload itself is not built yet (no backend endpoint); without --dry-run it exits 1 and names the manual path. |
migrate |
Convert a theme-sdk 2 theme to SDK 3 blocks. |
bizzpocket init
bizzpocket init <dir> [--from <themeDir> | --blank]Create a theme folder: the blank starter (default, or --blank) or a copy of another theme.
| Argument | Meaning |
|---|---|
<dir> |
The folder to create: new or empty, and its name is the theme id, so it must be lowercase-kebab (my-theme), else INVALID_THEME_ID. |
--from |
Copy another theme folder instead of the starter. dist, node_modules, .git, .npmrc, .env*, *.pem/*.key/*.p12 and symlinks are skipped; package.json gets the name @bizzpocket/theme-<dir>, and id in theme.config.ts (and themeId in layouts/*.json) becomes <dir>. |
--blank |
The blank starter: one hello block and a home layout. This is the default. |
Example:
bunx @bizzpocket/cli init my-theme
cd my-theme && bun installbizzpocket dev
bizzpocket dev (--store <slug> | --mock | --mock-guest) [--locale <tag>] [--port 4321] [--api <base>] [--dir .] [--prod]Serve the theme locally and rebuild on save. --mock uses built-in sample data (no store, no token) with a signed-in sample shopper; --mock-guest is the same data with nobody signed in; --locale shows the pages in one of the theme's locales (for example hi) instead of the store's own, for this dev server only; any other tag is an error that lists the theme's locales. --store uses a real store through --api and needs BIZZPOCKET_DEV_TOKEN (a bpdt_ developer token from the store's Settings → Developers).
| Argument | Meaning |
|---|---|
--store |
Serve a real store's data: the store slug. Needs BIZZPOCKET_DEV_TOKEN. |
--mock |
Serve built-in sample data (a toy store). No store, no token, no network. |
--mock-guest |
Like --mock, but nobody is signed in: the account, cart and wishlist pages show the signed-out state. |
--locale |
Show the pages in one of the theme's locales/ (for example hi) instead of the store's own, for this dev server only. Any other tag is an error that lists the theme's locales. |
--port |
Local port, 0-65535 (0 picks a free one). Default 4321. |
--api |
API base the store data comes from. Default https://api.dev.bizzpocket.com. Not allowed with --mock. |
--dir |
The theme folder. Default .. |
--prod |
Serve React's production build (the CLI restarts itself with NODE_ENV=production), to see the page as shoppers get it. |
The server listens on 127.0.0.1 only and answers only localhost, 127.0.0.1 and [::1] Host headers. It watches blocks/, layouts/ and components/, rebuilds on save and reloads the page; a build error is shown in the page and the last good build keeps serving.
Example:
bizzpocket dev --mock
BIZZPOCKET_DEV_TOKEN=bpdt_... bizzpocket dev --store my-storebizzpocket whoami
bizzpocket whoami --store <slug> [--api <base>]Check the developer token in BIZZPOCKET_DEV_TOKEN: print its store and when it expires.
| Argument | Meaning |
|---|---|
--store |
The store slug the token should belong to. |
--api |
API base. Default https://api.dev.bizzpocket.com. |
Prints the token's store and expiry. A revoked, expired or mistyped token is reported as not valid (HTTP 401); too many requests as HTTP 429. See Errors.
Example:
BIZZPOCKET_DEV_TOKEN=bpdt_... bizzpocket whoami --store my-storebizzpocket build
bizzpocket build [--target next|bun|both] [--dir .] [--out <folder>] [--json]Build dist/ and print the size report (server bytes, client JS, CSS, data mode per block, and why a block is runtime, with file:line). --out writes everything there instead of the theme's dist/ (the theme folder is left untouched). The folder must be empty, new, or one an earlier build made (it holds a .bizzpocket-build marker); a folder with other files is refused, never emptied. --json prints the report as JSON instead.
| Argument | Meaning |
|---|---|
--target |
next (the Next.js host bundle), bun (the Bun runtime bundle) or both (default). |
--dir |
The theme folder. Default .. |
--out |
Write everything into this folder instead of dist/; the theme folder is left untouched. The folder must be new, empty, or one an earlier build made (it holds a .bizzpocket-build marker). A folder with other files is refused, never emptied. |
--json |
Print the size report as JSON on stdout (warnings go to stderr). The report is also written to dist/size-report.json. |
On failure the CLI prints CODE: message for each build error and exits 1. Every code is in Errors.
Example:
bizzpocket build
bizzpocket build --json | jq '.blocks[] | select(.data == "runtime")'bizzpocket add
bizzpocket add <name...> [--overwrite] [--trust-registry <host>]... [--allow-proxy]Copy blocks / components from the @bizzpocket/blocks registry into the theme.
| Argument | Meaning |
|---|---|
<name...> |
One or more registry items (blocks, components, data helpers, traits) by name. |
--overwrite |
Replace files you already have (a modified file is otherwise refused with MODIFIED_FILE). |
--trust-registry |
Also send registry tokens to this host (repeatable). Only npm.bizzpocket.com is trusted by default; nothing in env or files can add trust. |
--allow-proxy |
Send tokens even while HTTP(S)_PROXY, ALL_PROXY or NODE_TLS_REJECT_UNAUTHORIZED is set (still warns). A CA variable always withholds them. |
Installed items are recorded in bizzpocket.json. See Registry.
Example:
bizzpocket add product-card hero-bannerbizzpocket diff
bizzpocket diff [name] [--trust-registry <host>]... [--allow-proxy]Show how registry items differ from your copies.
| Argument | Meaning |
|---|---|
[name] |
One installed item; without it, every installed item. |
--trust-registry |
As for add. |
--allow-proxy |
As for add. |
Example:
bizzpocket diff product-cardbizzpocket add-to-layout
bizzpocket add-to-layout <block> [--page home] [--parent <id>] [--dir .]Append an instance of blocks/ (new id, default props) to layouts/.json; --parent puts it inside that container block.
| Argument | Meaning |
|---|---|
<block> |
The block folder name under blocks/. |
--page |
Which layout: layouts/<page>.json. Default home. |
--parent |
Put the new instance inside this container block (by instance id) instead of at the end of the page. |
--dir |
The theme folder. Default .. |
Example:
bizzpocket add-to-layout hero --page homebizzpocket check
bizzpocket check [--dir .] [--json] [--strict] [--verbose] [--max-client-kb N] [--max-block-client-kb N] [--max-page-client-kb N] [--max-css-kb N] [--max-block-css-kb N] [--max-page-css-kb N]Check the theme before you publish: layouts against the blocks (unknown blocks and props, nesting, duplicate ids, unsafe URLs, placeholder text), data mode and size budgets from the build, the ESLint config and SDK 2 leftovers. Prints findings by severity, each with a rule id, file:line, what is wrong and how to fix it. Exit code 1 on any error (or any warning with --strict). Rules can be turned off or re-levelled in package.json ("bizzpocket"."check"). --json prints { findings, summary } as JSON. Nothing is written to the theme folder. Info findings are hidden unless --verbose. Budgets in KB gzip: --max-client-kb 50, --max-block-client-kb 10, --max-page-client-kb 30, --max-css-kb 20, --max-block-css-kb 7, --max-page-css-kb 14.
| Argument | Meaning |
|---|---|
--dir |
The theme folder. Default .. |
--json |
Print { findings, summary } as JSON. |
--strict |
Exit 1 on any warning too, not only errors. Use it in CI. |
--verbose |
Also print info findings. |
--max-client-kb |
Budget for the whole theme's client JS, KB gzip. Default 50. |
--max-block-client-kb |
Budget for one block's client JS, KB gzip. Default 10. |
--max-page-client-kb |
Budget for one page's client JS, KB gzip. Default 30. |
--max-css-kb |
Budget for the whole theme's CSS, KB gzip. Default 20. |
--max-block-css-kb |
Budget for one block's CSS, KB gzip. Default 7. |
--max-page-css-kb |
Budget for one page's CSS, KB gzip. Default 14. |
Checks layouts against the blocks (unknown blocks and props, nesting, duplicate ids, unsafe URLs, placeholder text), data mode and size budgets from the build, the ESLint config, locale files and SDK 2 leftovers. Each finding has a rule id, file:line, what is wrong and how to fix it. Rules can be turned off or re-levelled under "bizzpocket"."check" in package.json. Writes nothing to the theme folder.
Example:
bizzpocket check
bizzpocket check --strict --jsonbizzpocket typegen
bizzpocket typegen [--dir <theme>] [--out <file.d.ts>] [--check]Write types/bizzpocket.d.ts (block props and data, layout nodes, message keys), types/bizzpocket.register.d.ts (registers the messages with the SDK; include only one theme's types/ per TypeScript program) and types/layout.schema.json (layouts/*.json). --check writes nothing and exits 1 when any of the files is stale.
| Argument | Meaning |
|---|---|
--dir |
The theme folder. Default .. |
--out |
Write the main declaration file here instead of types/bizzpocket.d.ts. |
--check |
Write nothing; exit 1 when any generated file is stale. Use it in CI. |
Writes types/bizzpocket.d.ts (block props and data, layout nodes, message keys), types/bizzpocket.register.d.ts (registers the messages with the SDK: include only one theme's types/ per TypeScript program) and types/layout.schema.json (for layouts/*.json).
Example:
bizzpocket typegen
bizzpocket typegen --checkbizzpocket css-split
bizzpocket css-split [--dir <theme>] [--plan] [--out <folder> --write [--include-likely] [--rules <file.json>]] [--list N] [--json]Plan or write the move of global CSS rules into the blocks that own them (blocks//.css), so a page loads only the CSS of its blocks. --plan (default) prints, per block, the rules of styles/global.css that could move, by confidence: safe (the build's order proof holds), likely (one owner, the order guard held it back, with the reason), shared (several blocks), unknown (no block names the class); and the gzip sizes before and after. --write --out writes a copy of the theme with the safe rules (plus the likely ones with --include-likely) moved; the theme folder is never written. Prove a copy with scripts/css-parity.ts. --list N shows N selectors per group (0 = all).
| Argument | Meaning |
|---|---|
--dir |
The theme folder. Default .. |
--plan |
Print the plan and write nothing. This is the default. |
--out |
Folder for the --write copy. |
--write |
Write a copy of the theme with the safe rules moved. Needs --out; the theme folder is never written. |
--include-likely |
Also move the likely rules (one owner, held back by the order guard). |
--rules |
With --write: move exactly the rules a JSON file names instead of the analysis' choice. Replaces --include-likely. |
--list |
Show N selectors per group (0 = all). |
--json |
Print the plan as JSON. |
Plans or writes the move of global CSS rules (styles/global.css) into the blocks that own them (blocks/<name>/<name>.css), so a page loads only the CSS of its blocks. Rules are grouped by confidence: safe (the build's order proof holds), likely, shared (several blocks) and unknown. Opt-in: nothing moves unless you run --write. Prove a copy with packages/cli/scripts/css-parity.ts. A usage error exits 2.
Example:
bizzpocket css-split --plan
bizzpocket css-split --write --out ../my-theme-splitbizzpocket package
bizzpocket package [--dir .] [--out <file.tgz>] [--json] [--strict] [--skip-check]Check the theme, build it into a temp folder and write a reproducible .tgz plus its manifest (sha256 per file, SDK versions, blocks, locales, sizes). Prints the size table and the sha512. --json prints the manifest. Refuses on check errors (--strict: warnings too). Refuses secrets, absolute paths, escaping symlinks and oversize packages.
| Argument | Meaning |
|---|---|
--dir |
The theme folder. Default .. |
--out |
Where to write the .tgz. |
--json |
Print the package manifest as JSON. |
--strict |
Refuse on warnings too. |
--skip-check |
Do not run check first. |
Checks the theme, builds it into a temporary folder and writes a reproducible .tgz plus its manifest (sha256 per file, SDK versions, blocks, locales, sizes). Refuses on check errors, secrets, absolute paths, escaping symlinks and oversize packages.
Example:
bizzpocket package --out my-theme.tgzbizzpocket publish
bizzpocket publish [--dir . | --package <file.tgz>] [--store <slug> [--api <base>] | --registry <url>] [--dry-run] [--strict] [--skip-check] [--trust-registry <host>]... [--allow-proxy]Validate a package and show where it would go. --dry-run prints what would be uploaded and whether the token would be sent. Upload itself is not built yet (no backend endpoint); without --dry-run it exits 1 and names the manual path.
| Argument | Meaning |
|---|---|
--dir |
The theme folder. Default .. |
--package |
Validate this .tgz instead of packaging the folder. |
--store |
The store slug the package would go to. |
--api |
API base for --store. |
--registry |
Registry URL the package would go to. |
--dry-run |
Print what would be uploaded and whether the token would be sent. |
--strict |
Refuse on warnings too. |
--skip-check |
Do not run check first. |
--trust-registry |
As for add. |
--allow-proxy |
As for add. |
Not available yet: it validates a package and shows where it would go, but the upload itself is not built (there is no backend endpoint). Without --dry-run it exits 1 and names the manual path.
Example:
bizzpocket publish --dry-run --store my-storebizzpocket migrate
bizzpocket migrate [themeDir] [--dry-run] [--json]Convert a theme-sdk 2 theme to SDK 3 blocks.
| Argument | Meaning |
|---|---|
[themeDir] |
The theme-sdk 2 theme to convert. Default .. |
--dry-run |
Report what would change without writing. |
--json |
Print the report as JSON. |
See Migrating from 2.x. Exits 1 when something could not be converted (MIGRATE_INCOMPLETE).
Example:
bizzpocket migrate ./my-old-theme --dry-runEnvironment variables
| Variable | Read by | Meaning |
|---|---|---|
ALL_PROXY |
cli/src/registry/source.ts |
As HTTP_PROXY. |
BIZZPOCKET_DEV_TOKEN |
cli/src/commands/dev.ts, cli/src/commands/publish.ts, cli/src/commands/whoami.ts |
The developer token (bpdt_...) for dev --store and whoami, from the store's Settings → Developers. Export it in your shell, never in the theme folder. Sent only in the x-bp-dev-token header to the --api host. |
BIZZPOCKET_NPM_TOKEN |
cli/src/registry/source.ts |
As NPM_TOKEN. |
BP_DEBUG_HEADERS |
theme-runtime/src/server.ts |
1 makes the Bun runtime add x-bp-data-requests and server-timing headers to every page (how many GraphQL requests the page made, and page/render time). |
BUN_RUNTIME_TRANSPILER_CACHE_PATH |
cli/src/prod-env.ts |
When dev restarts itself to set NODE_ENV, the child runs with Bun's transpiler cache off (0), because the cache does not key on NODE_ENV. Set it yourself to keep a cache. |
HTTPS_PROXY |
cli/src/registry/source.ts |
As HTTP_PROXY. |
HTTP_PROXY |
cli/src/registry/source.ts |
Registry commands (add, diff) withhold registry tokens while it is set, unless --allow-proxy. |
NODE_ENV |
cli/src/build/islands.ts, cli/src/commands/dev.ts, cli/src/prod-env.ts, theme-runtime/src/env.ts, theme-runtime/src/runtime-assets.ts, theme-runtime/src/server.ts |
dev re-runs itself with development when unset (production with --prod), so React's build matches throughout. The runtime warns when React's development build is loaded outside development/test. |
NODE_EXTRA_CA_CERTS |
cli/src/registry/source.ts |
Registry tokens are always withheld while a CA variable is set; no flag overrides it. |
NODE_TLS_REJECT_UNAUTHORIZED |
cli/src/registry/source.ts |
As HTTP_PROXY: tokens are withheld while it is set, unless --allow-proxy. Certificate checks stay on for registry requests regardless. |
NO_COLOR |
cli/src/commands/check.ts |
check prints plain text, without colour, when it is set. |
NPM_TOKEN |
cli/src/registry/source.ts |
May be referenced as ${NPM_TOKEN} in the theme's .npmrc for the registry token. Any other ${X} there is an INVALID_REGISTRY error. |
SSL_CERT_DIR |
cli/src/registry/source.ts |
As NODE_EXTRA_CA_CERTS. |
SSL_CERT_FILE |
cli/src/registry/source.ts |
As NODE_EXTRA_CA_CERTS. |
VERDACCIO_TOKEN |
cli/src/registry/source.ts |
As NPM_TOKEN. |
The developer token is read only from BIZZPOCKET_DEV_TOKEN. Bun loads a theme's .env into the environment, so a token there would work but would also be easy to commit: keep tokens in your shell. See Tokens.
Exit codes
| Code | Meaning |
|---|---|
0 |
Success (also --help). |
1 |
Any failure: a build error, a bad flag or usage, a registry or migrate error, a token problem. Also plain bizzpocket with no command (it prints usage). |
2 |
css-split was called with bad arguments. |
128 + n |
dev was killed by signal n (e.g. 130 for Ctrl-C) while running as its own restarted child (see NODE_ENV). |
130 |
Interrupted with Ctrl-C (SIGINT) while build --out, check or package was writing a temporary folder: the folder is removed first. |
143 |
As 130, for SIGTERM. |