# Introduction

> The **[Vitrin CLI](https://www.npmjs.com/package/@zidsa/vitrin-cli)** is a command-line tool for Zid theme developers.  
> It helps you **develop, validate, and publish** themes to the Zid platform directly from your local environment.

![Vitrin_CLI.gif](https://api.apidog.com/api/v1/projects/613905/resources/360382/image-preview)

### With the CLI, you can:


<Columns>
    <Column>
    **✨ Visual Dashboard**
    - Quick access to all commands
    - Real-time build status tracking
    - Theme and authentication information at a glance
    </Column>
    <Column>
    **🔨 Build & Development**
    - Visual build progress with step-by-step feedback
    - Instant theme preview on dev stores
    </Column>
</Columns>

<Columns>
    <Column>
    **🎨 Theme Management**
    - Create, browse and select existing themes
    - One-click theme preview deployment
    - Automatic theme detection in current directory
    </Column>
    <Column>
    **🔐 Authentication & Settings**
    - Easy login/logout flow
    - Configure API endpoints
    - Persistent settings management
    </Column>
</Columns>

---

## Installing the CLI


:::highlight purple 📌
https://www.npmjs.com/package/@zidsa/vitrin-cli
:::

```bash
npm install -g @zidsa/vitrin-cli
```

---

## Quick Start


### Launch the interactive TUI (recommended)

```bash
vitrin
```

### Use CLI Commands Directly:

```bash
vitrin login        # Authenticate with Zid
vitrin new my-theme # Create a new theme
cd my-theme
vitrin push         # Push theme to Zid
```

---

## Configuration
### Environment Variables
- `VITRIN_API_URL` - API endpoint (default: https://api.zid.sa)
- `VITRIN_PARTNER_URL` - Partner dashboard URL (default: https://partner.zid.sa)
- `LOG_LEVEL` - Logging level (debug, info, error)

### Debug Mode
Run with detailed logging for troubleshooting:
```bash
LOG_LEVEL=debug vitrin preview 123

```


### File Structure
Expected theme structure:

```js
my-theme/
├── assets/
│   ├── styles.css
│   ├── scripts.js
│   └── images/
├── templates/
│   ├── home.jinja
│   ├── product.jinja
│   └── cart.jinja
├── layout.jinja
├── footer.jinja
├── header.jinja
├── package.json
└── theme.json
```

---

## Authentication
Authentication tokens are stored in `~/.vitrin/config.json`.

**To logout:**
```bash
rm ~/.vitrin/config.json
```
---

## Troubleshooting


:::warning[]
**Found a bug or unexpected behavior?**  
Please report issues on our GitHub tracker: [zidsa/vitrin-cli/issues](https://github.com/zidsa/vitrin-cli/issues)
:::

### Authentication Issues
```bash
# Check authentication status
vitrin list themes
# If you see "Authentication required", login again
vitrin login
```

### Build Failures

```bash
# Validate theme structure
vitrin build --validate
```

**Common causes:**
- Missing required directories (`assets/`, `templates/`)
- Invalid or missing `package.json`
- `.DS_Store` files (these are auto-cleaned during build)

### Preview Errors

```bash
# Run with debug logging

# MacOS
LOG_LEVEL=debug vitrin preview 123

# Windows 
$env:LOG_LEVEL="debug"; vitrin preview 123

```
**Common causes:**

- Expired authentication token → run `vitrin login`
- Invalid store ID → check using `vitrin list stores`
- Theme name conflict → CLI auto-generates a unique name

---

<TipGood>Explore Vitrin [CLI Commands](https://docs.zid.sa/cli-commands-1390556m0) page for detailed syntax and options for each command.</TipGood>