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:

version

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

Parameters

This command does not accept any parameters.

Example

$
pnpm catalyst version

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. Runs either the Next.js build or the Catalyst (OpenNext/Cloudflare) build pipeline depending on the configured framework. For the Catalyst framework, also runs a Wrangler dry-run to generate deployment artifacts.

Parameters

Example

$
pnpm catalyst build

$
# Include framework and project UUID
$
pnpm catalyst build --framework catalyst --project-uuid <UUID>

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 previous 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>

project create

Create a BigCommerce infrastructure project.

Parameters

Example

$
# Create a project
$
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).

Parameters

Example

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

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

project list

List BigCommerce infrastructure projects for your store.

Parameters

Example

$
# List your projects
$
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>

telemetry

View or change CLI telemetry collection status (enable, disable, or show current status).

Parameters

Example

$
# Show telemetry status
$
pnpm catalyst telemetry

$
# Enable telemetry collection
$
pnpm catalyst telemetry enable

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