> ## Documentation Index
> Fetch the complete documentation index at: https://weaverse.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Weaverse component configuration uses `settings`. `inspector` is deprecated; never generate it.
> Weaverse Hydrogen themes use React Router v7: import from `react-router`, never `react-router-dom` or `@remix-run/*`.
> Before using any code sample, read `@weaverse/hydrogen` in the project's `package.json`: 6.x and 5.x import from different entries and use different type names, so code for one does not build on the other.
> `@weaverse/hydrogen` 6 (Shopify Hydrogen 2026.10 and later, the version these docs show) imports from `@weaverse/hydrogen/react-router` and uses `Weaverse*` types such as `WeaverseComponentProps`, `WeaverseComponentLoaderArgs` and `WeaverseComponentSchema`; the root `@weaverse/hydrogen` entry only exports `createSchema()`, data helpers and types.
> `@weaverse/hydrogen` 5.x (Hydrogen 2026.4 and earlier) imports everything from `@weaverse/hydrogen` and uses `HydrogenComponentProps`, `ComponentLoaderArgs` and `HydrogenComponentSchema`. On a 5.x project, convert samples to these names. Upgrade to 6 only when asked (`npx @weaverse/cli@latest migrate v6`, plus the Hydrogen 2026.10 upgrade). Do not mix major versions.
> Next.js themes use `@weaverse/hydrogen` 6.2.0 or later: import client and shared code from `@weaverse/hydrogen/next` and server-only code from `@weaverse/hydrogen/next/server`. `@weaverse/next` is deprecated; never install or import it.
> For live project data (pages, theme settings, translations), use the Weaverse MCP server: https://weaverse.io/docs/developer-tools/weaverse-mcp

# Weaverse CLI

> The Weaverse CLI facilitates tasks such as project setup, theme scaffolding, and other common developer operations.

For developers crafting Weaverse Hydrogen themes, the Weaverse CLI is a simple yet powerful aid, streamlining project
setup and management tasks directly from the command line.

## Installation & Usage

You can run the CLI directly using **`npx`** to ensure you're always using the latest version:

```txt data-line-numbers=false theme={null}
npx @weaverse/cli@latest [command]
```

To view available commands and options:

```txt data-line-numbers=false theme={null}
npx @weaverse/cli@latest --help
```

## Available Commands

### `create`

The `create` command is essential for starting new Weaverse Hydrogen projects. It:

* Creates a new project directory
* Downloads and extracts the selected template
* Sets up environment variables, including your `WEAVERSE_PROJECT_ID` and a generated `SESSION_SECRET`
* Installs necessary dependencies (optional)
* Starts the development server (optional — prompted interactively, opt-in with `--dev` in non-interactive runs)

#### Available Templates

Weaverse CLI currently supports the following templates:

| Template | Description |
| - | - |
| **pilot** | A fully-featured Shopify Hydrogen theme for modern headless storefronts |
| **naturelle** | A beauty and lifestyle-focused Shopify Hydrogen theme |
| **aspen** | A sophisticated theme for home furniture and interior design stores |
| **maison** | A modern B2B theme for furniture wholesalers, distributors, and interior design brands |

#### Options

| Option | Description | Required | Default |
| - | - | - | - |
| **`--template`** | Template name (`pilot`, `naturelle`, `aspen`, or `maison`). Prompted in interactive mode; must be passed in non-interactive mode | Yes | - |
| **`--project-id`** | Your Weaverse project ID. Prompted in interactive mode; must be passed in non-interactive mode | Yes | - |
| **`--project-name`** | Name for your project directory. Prompted in interactive mode; defaulted when omitted in non-interactive mode | No | Prompted / defaulted |
| **`--commit`** | Specific Git commit hash to use | No | Latest from main branch |
| **`--no-install`** | Skip dependency installation and dev server start | No | false |
| **`--dev`** | Start the development server after install. Use `--no-dev` to skip the prompt and not start it | No | Prompted (interactive) / off (non-interactive) |
| **`-y`, `--yes`** | Non-interactive mode: never prompt, fail fast on missing required options | No | false |
| **`--ci`** | Alias for `--yes` | No | false |
| **`-f`, `--force`** | Overwrite the target directory when it already exists | No | false |

> [!NOTE]
>
> The CLI also runs non-interactively on its own when stdin isn't a TTY (piped
> input, CI, or a coding agent), or when `CI=true` is set — `--yes`/`--ci` just
> force that mode explicitly.

#### Usage Examples

**Basic usage with the Pilot template:**

```txt data-line-numbers=false theme={null}
npx @weaverse/cli@latest create --template=pilot --project-id=clocwvm3y08j2r79n3c44uhjh --project-name=my-store
```

**Using the Naturelle template:**

```txt data-line-numbers=false theme={null}
npx @weaverse/cli@latest create --template=naturelle --project-id=clocwvm3y08j2r79n3c44uhjh --project-name=naturelle-store
```

**Using a specific commit version:**

```txt data-line-numbers=false theme={null}
npx @weaverse/cli@latest create --template=pilot --project-id=clocwvm3y08j2r79n3c44uhjh --commit=a1b2c3d4
```

**Creating project without installing dependencies:**

```txt data-line-numbers=false theme={null}
npx @weaverse/cli@latest create --template=pilot --project-id=clocwvm3y08j2r79n3c44uhjh --no-install
```

**Agent/CI-friendly setup:**

```txt data-line-numbers=false theme={null}
npx @weaverse/cli@latest create --template=pilot --project-id=clocwvm3y08j2r79n3c44uhjh --project-name=my-hydrogen-storefront --no-install -y
```

**Non-interactive setup that also starts the dev server:**

```txt data-line-numbers=false theme={null}
npx @weaverse/cli@latest create --template=pilot --project-id=clocwvm3y08j2r79n3c44uhjh --project-name=my-store --dev -y
```

## Workflow

When you run the `create` command, the CLI will:

1. Download the selected template from GitHub
2. Extract the template to your specified project directory
3. Configure environment variables (including your Weaverse project ID)
4. Generate a secure local `SESSION_SECRET`
5. Install dependencies using npm (unless `--no-install` is specified)
6. Start the development server — in interactive mode the CLI asks first; in
   non-interactive mode it only starts when `--dev` is passed, so agent and CI
   runs return instead of hanging on a blocking server

> [!WARNING]
>
> `npm run dev` is a long-running, blocking process. Leave `--dev` off in CI and
> agent-driven runs, then start the server yourself with `cd my-store && npm run dev`.

After completion, you'll see instructions for the next steps to take.

## Best Practices

It is recommended to create your project within the Weaverse app first. Doing so will allow you to copy the
full command, complete with the project ID and project name, ensuring accuracy.

![](https://cdn.shopify.com/s/files/1/0838/0052/3057/files/CLI-newProject.png?v=1743412008)

## Troubleshooting

### Common Issues

**Template Download Fails**

* Check your internet connection
* Verify that the specified commit hash is valid (if using `--commit`)
* Try again with the default template without specifying a commit

**Dependency Installation Fails**

* Try running `npm install --legacy-peer-deps` manually in the project directory
* Ensure you have a supported version of Node.js installed. The current Pilot template declares Node.js `^22.18.0 || ^24.11.0`; the `@weaverse/hydrogen` package itself declares Node.js `>=20`
* Check for errors in your project's package.json

**Development Server Won't Start**

* Make sure all required environment variables are set
* Stores on a Shopify plan: install the Hydrogen sales channel ([https://apps.shopify.com/hydrogen](https://apps.shopify.com/hydrogen)), create one Hydrogen storefront project, then run `npx shopify hydrogen env pull`. If needed, copy values from **Hydrogen sales channel → Storefront Settings → Environments and variables**.
* Development stores or stores without a Shopify plan: install the Headless sales channel ([https://apps.shopify.com/headless](https://apps.shopify.com/headless)), then copy the Storefront API values into `.env`.
* Verify port 3456 is available on your system


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.