CLI reference
Every queek theme command: flags, environment variables and examples.
The starter already installs @usequeek/cli. Otherwise add it to your theme project:
npm install -D @usequeek/cliRun a command as npx queek theme <command>, or through the npm scripts the starter provides (npm run dev, npm run check). Flags also read from environment variables, so a value you always pass can live in your shell instead.
queek theme dev
Preview your theme as a whole store: every design of every template, every page of each.
Renders the theme with real Next.js against its designs (its demo stores) — theme/demo.json, the main template's first design, at /default, each theme/demos/<id>.json at /<id> — with the same composition a live Queek storefront uses. The index lists them by template, as theme.config.ts declares them. Edits reload the page.
The preview app is written to .queek/preview in your project and regenerated on every run; it ignores itself for git.
queek theme dev [flags]| Flag | Description | Default | Env |
|---|---|---|---|
--path <value> | The theme project (or its theme folder). | . | QUEEK_THEME_PATH |
--port <value> | Port to serve on [default: 7833, or the next free port]. | — | QUEEK_THEME_PORT |
--host <value> | Host to bind. Use 0.0.0.0 to reach it from another device. | 127.0.0.1 | QUEEK_THEME_HOST |
--vocabulary <value> | A pinned vocabulary file (default: the live copy). | — | — |
--offline | Use the bundled vocabulary snapshot; no network. | false | — |
--verbose | Print debug lines to stderr. | false | QUEEK_THEME_VERBOSE |
queek theme dev
queek theme dev --port 4000
queek theme dev --path ../my-themequeek theme check
Check your theme against the Queek theme contract.
Runs the same rules Queek runs when you submit, except the few that need Queek's side (they are listed at the end of the report). Errors block submission; warnings are advice.
Exit codes: 0 — no errors (or no findings at --fail-level warning); 1 — findings at or above the fail level; 2 — the check could not run.
With --init, writes a starter .queek-theme.yml in the project instead of checking.
queek theme check [flags]| Flag | Description | Default | Env |
|---|---|---|---|
--path <value> | The theme project (or its theme folder). | . | QUEEK_THEME_PATH |
--format <value> | Output format. One of: stylish, json, github-actions. | stylish | QUEEK_THEME_FORMAT |
--fail-level <value> | Lowest level that makes the command exit 1. One of: error, warning. | error | — |
--quiet | Report errors only. | false | — |
--init | Write a starter .queek-theme.yml in the project and exit. | false | — |
--vocabulary <value> | A pinned vocabulary file (default: the live copy). | — | — |
--offline | Use the bundled vocabulary snapshot; no network. | false | — |
--verbose | Print debug lines to stderr. | false | QUEEK_THEME_VERBOSE |
--json | Print the result as JSON on stdout. | — | — |
queek theme check
queek theme check --format json > report.json
queek theme check --format github-actions # annotations on a pull request
queek theme check --init # starter .queek-theme.ymlqueek theme screenshot
Capture every design's first screen at 1280×800 into the files the checker reads.
Starts the same preview dev serves, opens every design (its demo store) at 1280×800, and writes the screenshot the checker reads: theme/theme.jpg for the primary design, theme/demos/<id>.jpg for the rest. Pass design ids to capture only those.
Needs a Chromium-based browser: Google Chrome, Microsoft Edge, Playwright's own chromium (npx playwright install chromium), or QUEEK_THEME_BROWSER pointing at an executable.
queek theme screenshot [designs…] [flags]| Flag | Description | Default | Env |
|---|---|---|---|
--path <value> | The theme project (or its theme folder). | . | QUEEK_THEME_PATH |
--port <value> | Port to serve the preview on [default: 7833, or the next free port]. | — | QUEEK_THEME_PORT |
--verbose | Print debug lines to stderr. | false | QUEEK_THEME_VERBOSE |
--json | Print the result as JSON on stdout. | — | — |
queek theme screenshot
queek theme screenshot food
queek theme screenshot --port 7840queek theme package
Zip your theme for submission.
Writes <slug>.zip containing the theme folder (never node_modules, .queek or .git). It runs the check first and tells you if errors would block the submission.
queek theme package [flags]| Flag | Description | Default | Env |
|---|---|---|---|
--path <value> | The theme project (or its theme folder). | . | QUEEK_THEME_PATH |
--output <value> | Where to write the zip. Defaults to <slug>.zip in the project. | — | — |
--vocabulary <value> | A pinned vocabulary file (default: the live copy). | — | — |
--offline | Use the bundled vocabulary snapshot; no network. | false | — |
--verbose | Print debug lines to stderr. | false | QUEEK_THEME_VERBOSE |
--json | Print the result as JSON on stdout. | — | — |
queek theme package
queek theme package --output dist/my-theme.zipqueek theme init
Start a new theme, the same as npm create @usequeek/theme.
Asks for anything not given as a flag (in a terminal), then writes a renamed skeleton whose check output is your to-do list.
queek theme init [dir] [flags]| Flag | Description | Default | Env |
|---|---|---|---|
--name <value> | Theme name (default: the folder name). | — | — |
--templates <value> | Businesses to make templates for, comma-separated (required with --yes). | — | — |
--primary <value> | The main template (default: the first). | — | — |
--categories <value> | Business categories (default: the templates'). | — | — |
--tags <value> | 1–6 tags for the look (required with --yes). | — | — |
--pages <value> | Extra pages: contact, faq, or none. | — | — |
--ai <value> | AI assistants: claude, gemini. | — | — |
--no-ai | Write no AI instructions. | false | — |
--pm <value> | Package manager: npm, pnpm, yarn or bun. | — | — |
--install / --no-install | Install dependencies. | true | — |
--git / --no-git | Run git init. | true | — |
--yes, -y | Never prompt; take the default for everything else. | false | — |
--dry-run | Print what would be written; write nothing. | false | — |
--force | Allow a folder that is not empty. | false | — |
--template <value> | Another starter: a giget source or a local folder. | — | — |
--vocabulary <value> | A pinned vocabulary file (default: the live copy). | — | — |
--offline | Use the bundled vocabulary snapshot; no network. | false | — |
queek theme init my-theme
queek theme init my-theme --templates laundry,foods --primary laundry --tags minimal --yes