# Theme Commands

All theme-related commands are grouped under `finqu theme`. Use them to connect a local project to a theme, sync assets,
and run the recommended local preview workflow with the [Theme Development Kit](/apis-and-tools/theme-dev/overview).

## Typical Workflow

1. Sign in with `finqu sign-in`.
2. Connect the project to a theme with `finqu theme configure`.
3. Pull the latest theme assets with `finqu theme download`.
4. Preview changes locally with `finqu theme dev`.
5. Push changes back with `finqu theme deploy`.

## Working With Theme Files

`finqu theme download`, `finqu theme deploy`, and `finqu theme delete` accept `[sources...]` paths so you can target
individual files or directories such as `assets/main.css` or `sections/header.liquid`.

If you omit `[sources...]`, `download` and `deploy` operate on the entire theme. Configuration is stored in `.env` by
default, or in the file you pass with `--config`.

---

## Connect a Theme

### `finqu theme configure`

Interactively selects a theme and stores the connection details in your configuration file.

```bash
finqu theme configure
```

This command walks you through choosing a theme and saving the resolved store and theme values to `.env`. For details,
see [Configuration](./configuration).

---

## Sync Assets

### `finqu theme download`

Downloads theme assets from the connected theme.

```bash
finqu theme download [sources...]
```

When no sources are provided, the CLI downloads the full theme into your local directory.

### `finqu theme deploy`

Uploads local assets to the connected theme.

```bash
finqu theme deploy [sources...]
```

| Option         | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| `--clean`      | Remove remote theme assets that are not present locally             |
| `--force`      | Include restricted paths such as `config/` and `.draft` directories |
| `--no-compile` | Skip asset compilation on the server after upload                   |

When no sources are provided, the CLI uploads the full local theme.

> **Note:** By default, `config/settings_data.json` and `config/.draft` are protected so local deploys do not overwrite
> settings edited in the Finqu admin. Use `--force` only when you intentionally want to include them.

### `finqu theme delete`

Deletes assets from the connected theme.

```bash
finqu theme delete [sources...]
```

| Option         | Description                                         |
| -------------- | --------------------------------------------------- |
| `--no-compile` | Skip asset compilation on the server after deletion |

Provide one or more asset paths to remove.

### Examples

```bash
# Download the entire theme
finqu theme download

# Download selected files or directories
finqu theme download assets/main.css sections/header.liquid
finqu theme download assets/

# Deploy the entire local theme
finqu theme deploy

# Deploy selected files
finqu theme deploy assets/main.css sections/header.liquid

# Deploy and remove remote files that no longer exist locally
finqu theme deploy --clean

# Include protected config files
finqu theme deploy --force

# Delete selected assets
finqu theme delete assets/old-script.js sections/removed-section.liquid
```

---

## Local Development

### `finqu theme dev` [#finqu-theme-dev]

Starts the recommended local development workflow using `finqu-theme-dev`.

```bash
finqu theme dev
```

| Option                | Description          | Default |
| --------------------- | -------------------- | ------- |
| `-p, --port <number>` | Port to listen on    | `3000`  |
| `-d, --dir <path>`    | Theme directory path |         |

What this command does:

1. Confirms that `finqu-theme-dev` is installed and available on your `PATH`.
2. Checks whether `finqu-theme-dev` has already been authenticated.
3. Starts `finqu-theme-dev auth` automatically if credentials are missing.
4. Launches the local preview server with `finqu-theme-dev serve`.

`finqu-theme-dev` keeps its own credentials in `~/.finqu-theme-dev/credentials.json` and uses a channel API key. That is
separate from the OAuth token managed by `finqu sign-in`.

### Examples

```bash
# Start the local development server
finqu theme dev

# Custom port and theme directory
finqu theme dev --port 8080 --dir ./theme
```

---

## Theme Structure

A typical Finqu theme looks like this:

```text
theme-name/
├── assets/              # CSS, JavaScript, images, and fonts
├── blocks/              # Reusable blocks
├── config/
│   └── settings_data.json   # Theme settings (protected during deploy)
├── layout/              # Layout templates
├── locales/             # Translation files
├── sections/            # Page sections
├── snippets/            # Code snippets
├── templates/           # Page templates
└── .env                 # CLI configuration file
```

## Next Steps

- [Theme Development Kit](/apis-and-tools/theme-dev/overview) - Recommended local theme preview and development
- [CLI Overview](./overview) - General CLI documentation
- [Configuration](./configuration) - Configuration reference
- [Troubleshooting](./troubleshooting) - Common issues and solutions