@dscodotco/theme-cli/docs/getting-started.md

A CLI tool for developing Shopify themes

# Getting Started with Theme CLI

This guide will help you get started with Theme CLI, a powerful tool for Shopify theme development.

## Prerequisites

- Node.js (v16 or higher)
- npm or yarn
- A Shopify store with admin API access
- Basic knowledge of Shopify theme development

## Installation

### Global Installation (Recommended)

```bash
npm install -g @dscodotco/theme-cli
```

or using yarn:

```bash
yarn global add @dscodotco/theme-cli
```

### Project Installation

```bash
npm install --save-dev @dscodotco/theme-cli
```

or using yarn:

```bash
yarn add --dev @dscodotco/theme-cli
```

## Quick Start

1. **Create a new theme project**

```bash
theme-cli init my-theme
cd my-theme
```

2. **Set up environment variables**

Create a `.env` file in your project root:

```env
SHOPIFY_STORE_NAME=your-store.myshopify.com
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_PASSWORD=your_api_password
SHOPIFY_THEME_ID=123456789
```

3. **Start the development server**

```bash
theme-cli dev
```

Your theme will be available at `http://localhost:3000`

## Basic Commands

### Initialize a New Theme

```bash
theme-cli init [name]
```

Options:
- `--template <name>` - Use a specific theme template (default: "blank")
- `--typescript` - Initialize with TypeScript support
- `--force` - Overwrite existing directory

### Development Server

```bash
theme-cli dev
```

Options:
- `--port <number>` - Specify port number (default: 3000)
- `--host <host>` - Specify host (default: localhost)
- `--https` - Enable HTTPS
- `--watch` - Enable file watching (default: true)

### Deploy Theme

```bash
theme-cli deploy
```

Options:
- `--env <environment>` - Deploy to specific environment
- `--backup` - Create backup before deploying
- `--force` - Skip confirmation prompt

## Project Structure

A typical theme project structure:

```
my-theme/
├── .env                 # Environment variables
├── package.json        # Project configuration
├── theme.config.js     # Theme CLI configuration
├── assets/            # Theme assets
│   ├── scripts/
│   └── styles/
├── config/            # Theme configuration
│   └── settings_schema.json
├── layout/           # Theme layouts
├── sections/         # Theme sections
├── snippets/         # Theme snippets
└── templates/        # Theme templates
    ├── index.liquid
    ├── product.liquid
    └── collection.liquid
```

## Configuration

### theme.config.js

```javascript
module.exports = {
  development: {
    store: process.env.SHOPIFY_STORE_NAME,
    themeId: process.env.SHOPIFY_THEME_ID,
    password: process.env.SHOPIFY_API_PASSWORD,
    ignore: [
      'settings_data.json',
      '.git',
      '.env'
    ],
    deployIgnore: [
      'settings_data.json',
      'node_modules',
      '.git',
      '.env'
    ]
  },
  production: {
    // Production-specific configuration
  }
};
```

### Package Scripts

Add these scripts to your `package.json`:

```json
{
  "scripts": {
    "dev": "theme-cli dev",
    "build": "theme-cli build",
    "deploy": "theme-cli deploy",
    "lint": "theme-cli lint",
    "test": "theme-cli test"
  }
}
```

## Development Workflow

1. **Start Development Server**
   ```bash
   npm run dev
   ```
   This will:
   - Start the development server
   - Watch for file changes
   - Enable hot reload
   - Provide API endpoints for theme data

2. **Make Changes**
   - Edit theme files in your preferred editor
   - Changes are automatically synced
   - View changes at `http://localhost:3000`

3. **Test Your Theme**
   ```bash
   npm run test
   ```
   This will:
   - Run theme linting
   - Check for common issues
   - Validate theme structure

4. **Deploy Your Theme**
   ```bash
   npm run deploy
   ```
   This will:
   - Build production assets
   - Upload theme files
   - Update theme settings

## Next Steps

- Read the [Core Concepts](./core-concepts.md) guide
- Explore the [API Reference](./api/README.md)
- Check out the [Tutorials](./tutorials/README.md)
- Learn about [Contributing](./development/contributing.md)

## Troubleshooting

If you encounter issues:

1. Check the [Troubleshooting Guide](./troubleshooting.md)
2. Verify your environment variables
3. Check your Shopify API access
4. Review the console for errors
5. Check the Theme CLI logs

## Support

- [GitHub Issues](https://github.com/dsco/theme-cli/issues)
- [Documentation](https://docs.dsco.dev/theme-cli)
- [Community Discord](https://discord.gg/dsco)

## License

MIT License - see [LICENSE](../LICENSE) for details