Overview
The Komerza CLI lets you develop storefronts locally instead of inside the browser-based Builder. It keeps your local files in sync with your Builder project in real time, and lets you deploy directly to production from the terminal.
The typical workflow is: clone → dev → deploy.
Installation
npm install -g @komerza/cli
komerza command is available globally.
Authentication
Login
Opens a browser window to authenticate with your Komerza account. Credentials are stored securely in your OS keychain — no tokens to copy and paste.
Logout
Check who you’re logged in as
Prints your account and the stores associated with it.
Cloning a Project
komerza clone [projectId]
- A directory named after your project
- A
.komerza/config.json file tracking the project — commit this file
- A
.gitignore
Options:
| Flag | Description |
|---|
-d, --dir <name> | Use a custom directory name instead of the project name |
Local Development
Starts your local dev server and watches for file changes. Any saved file is automatically synced to the Builder within 1.5 seconds.
- Detects your package manager (
npm, pnpm, yarn, or bun) automatically
- Requires a
"dev" script in package.json
The dev server and file-watching run together in the same terminal process.
Stop the server (Ctrl+C) to exit both.
Deploying
Builds the project and deploys it to production.
- Runs your
build script from package.json
- Finds the build output (
dist, out, build, .next/out, or public/dist)
- Uploads it and makes it live
The live store URL is printed on success.
Environment Variables
Manage env vars stored on your Builder project.
| Command | Description |
|---|
komerza env pull | Fetches env vars and writes them to .env.local |
komerza env push | Uploads .env.local to the Builder, replacing all existing vars |
komerza env list | Prints all env vars currently set on the project |
Other Commands
Manual sync
komerza push # push local files to the Builder
komerza pull # pull files from the Builder (overwrites local)
dev and deploy.
komerza pull will ask for confirmation if local files already exist. Use -f / --force to skip the prompt.
List projects
Lists all Builder projects linked to your account.
Open in browser
komerza open # opens the live store
komerza open --builder # opens the Builder editor
Config File
.komerza/config.json is created when you run komerza clone. It stores:
| Field | Description |
|---|
projectId | The Builder project ID |
storeId | The associated store |
name | Project display name |
deploymentUrl | Updated after each successful deploy |
File Size Limit
Files larger than 12 MB are not synced.
