# CLI Commands

> The **[Vitrin CLI](https://www.npmjs.com/package/@zidsa/vitrin-cli)** helps you authenticate, create, build, preview, and manage themes for Zid stores.  
> Each command is straightforward, with copy-ready examples below.
> 
---

## 🔑 Authentication

Authenticate your CLI with Zid Partner Dashboard.

```bash
$ vitrin login
```

Opens your browser for the OAuth flow and saves credentials locally.

**Example:**
```bash
$ vitrin login
Opening Zid Partner Dashboard in your default browser...
Listening for authentication callback on http://localhost:4444/auth/callback

✅ Authentication successful!
Token saved to ~/.vitrin/config.json
```
---

## 🎨 Theme Creation

Create a new theme from a template.

```bash
$ vitrin new <theme-name> [options]
```
**Options:**
- `-t`, `--template <template>` → Template to use (basic, minimal, advanced)

- `--no-git` → Skip Git initialization

**Example:**

```bash
$ vitrin new my-store-theme
Creating new theme: my-store-theme
Target directory: /Users/user/my-store-theme
✅ Theme created successfully!

Next steps:
  cd my-store-theme
  vitrin build
```

---

## Theme Push
Builds and pushes your theme to Zid servers, creating or updating the theme.

```bash
$ vitrin push [options]
```

**Options:**
- `-s`, `--store` `<email>` → Dev store email to install on
- `-a`, `--activate` → Activate theme after installation
- `-v`, `--version` `<version>` → Version number (default: from theme.json)
- `-c`, `--changelog` `<text>` → Version changelog

**Example:**
    
```bash
$ vitrin push --store dev@example.com --activate
✅ Theme pushed successfully!
Theme ID: abc123
Version: 1.0.0
```

---

## 🛠️ Building Themes

Build your theme into a distributable `.zip` package.


```bash
$ vitrin build [theme-path]
```

**Example:**


```bash
$ vitrin build
Validating theme structure...
✅ Theme structure is valid
Building theme package...
✅ Build complete: dist/theme.zip (2.4 MB)
```
---

## 👀 Preview on Dev Store

Preview your theme on a development store for testing.

```bash
$ vitrin preview [options]

```

**Options:**
- `-s`, `--store` `<store-id>` → Dev store email
- `--build` → Build theme before previewing


**Example:**

```bash
$ vitrin preview 123 --build
📦 Preparing theme preview for store 123
Building theme...
✅ Theme built successfully
Creating theme...
✅ Theme created: 45678
Creating version...
✅ Version 1.0.0 created
Uploading theme package...
✅ Upload complete
Installing on store...

🎉 Theme ready for preview!

Theme ID: 45678
Version: 90123
Installation: 11111

💡 To activate: vitrin activate 123 11111
```
---

## 📋 List Resources

List available themes or dev stores.

```bash
$ vitrin list [resource]
```

**Example:**


```bash
$ vitrin list stores
Fetching dev stores...

Dev Stores (3):

ID: 123
Name: Test Store 1
Email: test1@example.com
URL: https://test1.zidtest.com

ID: 456
Name: Test Store 2
Email: test2@example.com
URL: https://test2.zidtest.com
```

---

## 📦 Theme Installation

Install a specific theme version on a store.


```bash
$ vitrin install <store-id> <theme-id> <version-id>
```

**Example:**

```bash
$ vitrin install 123 45678 90123
Installing theme on store...
✅ Theme installed successfully!
Installation ID: 11111
```
---

## 🚀 Theme Activation

Activate an installed theme on a store.


```bash
$ vitrin activate <store-id> <installation-id>
```

**Example:**

```bash
$ vitrin activate 123 11111
Activating theme...
✅ Theme activated successfully!
```

---
## Temporary themes settings editing

Since we got a little too excited to share the new themes with you when the new theme editor is still cooking, here's a quick way to upload drafted settings while building the theme through the cli:
with your theme files, add the following:
```js
my-theme/
├── assets/
│   ├── styles.css
│   ├── scripts.js
│   └── images/
├── templates/
│   ├── home.jinja
│   ├── home.json # this 
│   ├── product.jinja
│   └── cart.jinja
├── layout.jinja
├── layout.json # this 
├── footer.jinja
├── footer.json # this 
├── header.jinja
├── header.json # this 
├── package.json
└── theme.json
```
in a .json file with the template name, you can add settings for the template that will be uploaded to the store during `preview`.
in `home.json` you can add the sections settings that you want reflected in the home page like so:
```
{
     "components": {
         "ar": [
             {
                 "template": "sections/....jinja",
                 "settings": ...,
             }
         ],
         "en": [
             ...
         ]
     }
}
```
checkout https://github.com/zidsa/soft-theme-vitrin/ for reference...
p.s. you can give you schema an LLM and ask it to give placeholder values
Sorry for the inconvenince, we promise to make it worthwhile ;)