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

# Komerza CLI

> Build and deploy Komerza storefronts from your local machine

## 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

```bash theme={null}
npm install -g @komerza/cli
```

Once installed, the `komerza` command is available globally.

## Authentication

### Login

```bash theme={null}
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

```bash theme={null}
komerza logout
```

### Check who you're logged in as

```bash theme={null}
komerza whoami
```

Prints your account and the stores associated with it.

***

## Cloning a Project

```bash theme={null}
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:**

| Flag               | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `-d, --dir <name>` | Use a custom directory name instead of the project name |

***

## Local Development

```bash theme={null}
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`

<Note>
  The dev server and file-watching run together in the same terminal process.
  Stop the server (Ctrl+C) to exit both.
</Note>

***

## Deploying

```bash theme={null}
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.

| 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

```bash theme={null}
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

```bash theme={null}
komerza projects
```

Lists all Builder projects linked to your account.

### Open in browser

```bash theme={null}
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 |

Commit this file — it is required by most CLI commands.

***

## File Size Limit

Files larger than **12 MB** are not synced.