Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.komerza.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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
Once installed, the komerza command is available globally.

​
Authentication

​
Login

komerza 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

komerza logout

​
Check who you’re logged in as

komerza whoami
Prints your account and the stores associated with it.

​
Cloning a Project

komerza clone [projectId]
Downloads a Builder project to your local machine. If you omit the project ID, you’ll get an interactive list to pick from. This creates:
  • A directory named after your project
  • A .komerza/config.json file tracking the project — commit this file
  • A .gitignore
Options:
FlagDescription
-d, --dir <name>Use a custom directory name instead of the project name

​
Local Development

komerza dev
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

komerza deploy
Builds the project and deploys it to production.
  1. Runs your build script from package.json
  2. Finds the build output (dist, out, build, .next/out, or public/dist)
  3. Uploads it and makes it live
The live store URL is printed on success.

​
Environment Variables

Manage env vars stored on your Builder project.
CommandDescription
komerza env pullFetches env vars and writes them to .env.local
komerza env pushUploads .env.local to the Builder, replacing all existing vars
komerza env listPrints 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)
Both are manual escape hatches. Most workflows only need dev and deploy. komerza pull will ask for confirmation if local files already exist. Use -f / --force to skip the prompt.

​
List projects

komerza 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:
FieldDescription
projectIdThe Builder project ID
storeIdThe associated store
nameProject display name
deploymentUrlUpdated after each successful deploy
Commit this file — it is required by most CLI commands.

​
File Size Limit

Files larger than 12 MB are not synced.