Catalyst CLI

Make sure to read the Overview documentation to understand the purpose of the CLI, how configuration variables work, etc. The Catalyst CLI supports the following commands:

Global options

These options can be used with any Catalyst CLI command.

version

Display detailed version information (CLI version, Node version, and platform).

Parameters

This command does not accept any parameters.

Example

$
pnpm catalyst version

create

Scaffold a new Catalyst storefront and connect it to your BigCommerce store. The CLI will prompt for any required values not passed as flags.

Parameters

Example

$
# Interactive setup (prompts for all required values)
$
pnpm catalyst create

$
# Self-hosted setup with explicit credentials
$
pnpm catalyst create --project-name my-store --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

$
# Native Hosting setup
$
pnpm catalyst create --project-name my-store --hosting commerce --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

auth login

Authenticate with BigCommerce via your browser. Uses an OAuth device code flow. The CLI displays a one-time code, opens your browser to the BigCommerce login page, and waits for you to authorize. After logging in, your credentials are stored in .bigcommerce/project.json.

If you are already logged in, the CLI will display your current credentials and suggest running catalyst auth logout to re-authenticate.

Parameters

Example

$
# Login via browser (recommended)
$
pnpm catalyst auth login

$
# Login with existing credentials (skips browser flow)
$
pnpm catalyst auth login --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

auth logout

Remove stored credentials for the current project.

Parameters

This command does not accept any parameters.

Example

$
pnpm catalyst auth logout

auth whoami

Verify your stored credentials and display information about the authenticated store and linked project.

Parameters

Example

$
pnpm catalyst auth whoami

Example output:

Logged in to My Store (abc123), connected to project my-project (43eba682-0c48-11f1-9bd5-827a48b0ce1e)

If no credentials are found, the command exits with a “not logged in” message.

start

Start a local preview of your Catalyst storefront using OpenNext/Cloudflare. Requires a successful catalyst build first.

Parameters

This command does not accept any parameters.

Example

$
pnpm catalyst start

build

Build your Catalyst project. If the project is configured for Native Hosting (Commerce Hosting), this runs the OpenNext/Cloudflare pipeline and a Wrangler dry-run to generate deployment artifacts. Otherwise, it falls back to next build.

Parameters

Example

$
pnpm catalyst build

deploy

Deploy your application to Cloudflare. By default, this also runs a build before deploying which can be skipped with the --prebuilt flag. Generates a bundle from .bigcommerce/dist, uploads it to BigCommerce, and creates a deployment. Requires a linked project (via project link) if not passing --project-uuid.

Parameters

Example

$
pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN>

logs tail

Tail live logs from your deployed application. Streams log output in real time using Server-Sent Events (SSE). The stream automatically reconnects on transient errors (up to 5 retries).

Parameters

The available formats are:

• default — [timestamp] [LEVEL] message
• short — message only
• request — [timestamp] [LEVEL] METHOD URL (status_code) message
• json — raw JSON output
• pretty — pretty-printed JSON

Example

$
pnpm catalyst logs tail

$
# Tail logs with request format
$
pnpm catalyst logs tail --format request

$
# Tail logs as raw JSON (useful for piping to other tools)
$
pnpm catalyst logs tail --format json

project create

Create a new BigCommerce infrastructure project and link it to your local Catalyst project. The project UUID is written to .bigcommerce/project.json.

Parameters

Example

$
# Create a project (prompts for project name)
$
pnpm catalyst project create

$
# Create a project and pass store hash and access token
$
pnpm catalyst project create --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

project link

Link your local Catalyst project to a BigCommerce infrastructure project. You can provide a project UUID directly, or use store credentials to fetch and select from available projects (or create a new one). The linked project UUID is written to .bigcommerce/project.json.

Parameters

Example

$
# Link using a project UUID directly
$
pnpm catalyst project link --project-uuid <UUID>

$
# Link by fetching projects (prompts to select or create)
$
pnpm catalyst project link --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

project list

List BigCommerce infrastructure projects for your store. The currently linked project is highlighted.

Parameters

Example

$
pnpm catalyst project list

$
# List projects by passing store hash and access token
$
pnpm catalyst project list --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>

project delete

Permanently delete a BigCommerce infrastructure project. This action is irreversible. If --project-uuid is not provided, the CLI fetches available projects and prompts you to select one. A confirmation prompt is shown before deletion unless --force is passed.

Parameters

Example

$
# Delete a project (prompts for selection and confirmation)
$
pnpm catalyst project delete

$
# Delete a specific project by UUID
$
pnpm catalyst project delete --project-uuid <UUID>

$
# Delete without confirmation prompt
$
pnpm catalyst project delete --project-uuid <UUID> --force

telemetry

View or change CLI telemetry collection status (enable, disable, or show current status). Enabling telemetry helps BigCommerce support diagnose and troubleshoot errors.

Parameters

Example

$
# Show telemetry status
$
pnpm catalyst telemetry

$
# Enable telemetry collection
$
pnpm catalyst telemetry enable

$
# Disable telemetry collection
$
pnpm catalyst telemetry --disable