Vitrin CLI in depth: from login to preview, push and troubleshooting

What the CLI gives you

Vitrin CLI is Zid's command-line tool for theme developers. It lets you develop, validate and publish themes from your local environment, and it's published on npm as @zidsa/vitrin-cli.

npm install -g @zidsa/vitrin-cli

vitrin   # Launch the interactive TUI (recommended)

The interactive TUI is what the docs recommend: a dashboard with quick access to commands, real-time build status, and theme and authentication info. It lets you create, browse and select themes, deploy a preview in one click, and detects the theme in the current directory automatically. Everything is also available as direct commands, which is what this guide covers.

• 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 or error).

Sign in: vitrin login

vitrin login opens the Partner Dashboard in your browser for the OAuth flow, then saves your credentials locally. While it waits, the CLI listens for the callback on http://localhost:4444/auth/callback:

$ 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

• The token is stored in ~/.vitrin/config.json. To log out, run vitrin logout (in version 1.3.0), or delete the file as the docs describe: rm ~/.vitrin/config.json.
• To check you're still authenticated, run vitrin list themes. If you see "Authentication required", run vitrin login again.

Create a theme: vitrin new

vitrin new <theme-name> [options] creates a new theme. In version 1.3.0 on npm it clones the official Growth theme template from zidsa/growth-theme by default, -e or --from-existing <path> registers a directory you already have as a Vitrin theme instead of cloning, and --no-git skips Git initialization. The -t or --template option (basic, minimal or advanced) listed on the docs commands page isn't in version 1.3.0. Once it's created, the CLI suggests you cd into the folder and run vitrin push. This is the structure the CLI expects, per the docs introduction page:

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

The Architecture page in the docs adds sections/, components/, the translation file locale/ar/LC_MESSAGES/messages.po, and layout.schema.json, header.schema.json and footer.schema.json. Treat the CLI's tree as the minimum.

Preview on a development store

List your development stores to get the store ID, then preview on it. With --build, the CLI builds the theme, creates it, creates a version, uploads the package and installs it on the store, then prints three IDs:

vitrin list stores
vitrin preview 123 --build

# From the preview output:
# Theme ID: 45678
# Version: 90123
# Installation: 11111

Preview ends with the theme installed but not active, and the CLI suggests the activation command. To install a specific version yourself, use vitrin install with the store, theme and version IDs, then activate with the installation ID:

vitrin install <store-id> <theme-id> <version-id>
vitrin activate <store-id> <installation-id>

# Example
vitrin activate 123 11111

Build and push: vitrin build and vitrin push

vitrin build [theme-path] validates the structure and packages the theme as a distributable .zip. The docs example shows dist/theme.zip; in version 1.3.0 the file is named after the theme folder plus a timestamp (for example my-theme-1714492800000.zip), and -o or --output <path> sets the output directory. vitrin push builds the theme and pushes it to Zid's servers, creating or updating it:

vitrin build
vitrin build --validate

vitrin push --store 123 --activate

• -s or --store <id>: the development store ID to install on (the docs page says email; version 1.3.0 takes the store ID).
• -a or --activate: activate the theme after installation.
• -v or --version <version>: version number (default: from theme.json).
• -c or --changelog <text>: version changelog.
• -n or --new-version (version 1.3.0): creates a new theme version; by default push updates the latest version in place.

A good practice is to pass --changelog on every push, and an explicit --version whenever you create a new version, so each version is easy to trace. Keep in mind that push doesn't submit your theme for Theme Market review; that's a separate step: Submit to Publish under My Themes → Themes Management in the Partner Dashboard, or vitrin status --target pending_review in version 1.3.0. Our pre-submission checklist article covers the steps.

Common errors and fixes

• Authentication required: the token is missing or expired. Run vitrin login.
• Build fails: run vitrin build --validate. Common causes are missing assets/ or templates/ directories, or an invalid or missing package.json. .DS_Store files are cleaned automatically during the build.
• Preview fails: an expired token (run vitrin login), an invalid store ID (check with vitrin list stores), or a theme name conflict, which the CLI resolves by generating a unique name.
• Undefined-variable errors in the preview: since December 2025 these are shown in the development preview. Add fallbacks, handle optional values and use safeget.

For more detail, run the preview with debug logging:

# macOS
LOG_LEVEL=debug vitrin preview 123

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