BizzPocket

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:

bash
bunx @bizzpocket/cli init my-theme
cd my-theme && bun install

bizzpocket 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:

bash
bizzpocket dev --mock
BIZZPOCKET_DEV_TOKEN=bpdt_... bizzpocket dev --store my-store

bizzpocket 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:

bash
BIZZPOCKET_DEV_TOKEN=bpdt_... bizzpocket whoami --store my-store

bizzpocket 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:

bash
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:

bash
bizzpocket add product-card hero-banner

bizzpocket 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:

bash
bizzpocket diff product-card

bizzpocket 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:

bash
bizzpocket add-to-layout hero --page home

bizzpocket 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:

bash
bizzpocket check
bizzpocket check --strict --json

bizzpocket 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:

bash
bizzpocket typegen
bizzpocket typegen --check

bizzpocket 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:

bash
bizzpocket css-split --plan
bizzpocket css-split --write --out ../my-theme-split

bizzpocket 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:

bash
bizzpocket package --out my-theme.tgz

bizzpocket 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:

bash
bizzpocket publish --dry-run --store my-store

bizzpocket 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:

bash
bizzpocket migrate ./my-old-theme --dry-run

Environment 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.