Skip to main content
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:
data-line-numbers=false
To view available commands and options:
data-line-numbers=false

​
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:

​
Options

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:
data-line-numbers=false
Using the Naturelle template:
data-line-numbers=false
Using a specific commit version:
data-line-numbers=false
Creating project without installing dependencies:
data-line-numbers=false
Agent/CI-friendly setup:
data-line-numbers=false
Non-interactive setup that also starts the dev server:
data-line-numbers=false

​
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
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.

​
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.12.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), 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), then copy the Storefront API values into .env.
  • Verify port 3456 is available on your system