Changelog

--api-host is now a first-class, persistable config value

The Catalyst CLI’s API host is now resolved with the same precedence as its other credentials, and can be persisted in .bigcommerce/project.json.

• CATALYST_API_HOST replaces BIGCOMMERCE_API_HOST — the CLI no longer reads BIGCOMMERCE_API_HOST. Set CATALYST_API_HOST instead.
• Persistable in project.json — set apiHost in .bigcommerce/project.json to persist a non-default host, the same way store hash, access token, and project UUID are stored.
• Resolution order — --api-host flag > CATALYST_API_HOST environment variable > .bigcommerce/project.json apiHost > default api.bigcommerce.com.

Breaking change: if you set BIGCOMMERCE_API_HOST in your environment or CI, rename it to CATALYST_API_HOST.

For details, see the Catalyst CLI reference and the Native Hosting configuration guide.

Create a channel with catalyst channel create

The Catalyst CLI adds a channel create command that creates a new Catalyst storefront channel on your store — the same flow catalyst create uses while scaffolding, now available on an existing project without starting over.

• Interactive by default — logs you in through the browser device-code flow when you aren’t authenticated, checks store eligibility, then prompts for the channel name, default language, additional languages, and whether to install sample data
• Non-interactive mode — pass --name, --locale, --additional-locales, and --sample-data / --no-sample-data to skip the prompts
• Optional linking — after creation, choose to link the new channel to your project, or pass --link to write its credentials to .env.local without prompting

For details, see the Catalyst CLI reference.

Gather bug report diagnostics with catalyst debug

The Catalyst CLI adds a debug command that prints a diagnostic report to include when filing a bug report.

• What it reports — CLI version, runtime (Node version, platform, OS), the project’s package manager, project state (linked/transformed/fully-set-up, presence of middleware.ts, proxy.ts, the OpenNext dependency), resolved config sources, telemetry status and correlation ID, and which key files exist
• Secrets are never printed — credentials and environment variables are reported by name and source only, never by value
• --json — output the report as JSON for copy/paste or piping

For details, see the Catalyst CLI reference.

Claim a cross-store domain with catalyst domains claim

The Catalyst CLI adds a domains claim command that takes ownership of a custom domain currently in use on another store.

• Ownership verification — when catalyst domains add finds a domain already bound to a different store, it now prints a TXT record to publish with your DNS provider
• domains claim <domain> — after publishing the record, run this to release the domain from the other store and bind it to your project. If verification hasn’t completed yet, the command reprints the TXT record so you can retry
• --wait — poll until the claimed domain finishes verifying

For details, see the Catalyst CLI reference.

Move a domain between projects with catalyst domains transfer

The Catalyst CLI adds a domains transfer command that moves a custom domain to another project in the same store — the same-store counterpart to domains claim.

• domains transfer <domain> — when a domain is already bound to another project in your store, catalyst domains add now points you at this command instead of surfacing a raw API error
• --to-project-uuid <uuid> — target a specific destination project, or omit it to pick one interactively from your store’s projects
• --wait — poll until the transferred domain finishes verifying

For details, see the Catalyst CLI reference.

--env-path is now scoped to build and deploy

The Catalyst CLI’s --env-path option and auto-loaded env files are now scoped to the catalyst build and catalyst deploy commands — the only commands that need storefront environment variables for the build.

• --env-path is no longer a global option — it’s now a flag on build and deploy only. No other command reads env files.
• Auto-loading now includes .env — build and deploy auto-load both .env.local and .env from the current directory when --env-path isn’t passed (.env.local takes precedence, and neither overrides variables already set in your shell). Previously only .env.local was auto-loaded, and only from the top-level CLI, not build or deploy specifically.

Breaking change: if you relied on env vars auto-loading for a command other than build/deploy, set them in your shell environment or pass the relevant flags instead.

For details, see the Catalyst CLI reference.

Build with a specific Wrangler version

The Catalyst CLI now accepts a --wrangler-version option on catalyst build and catalyst deploy, so you can build against a Wrangler version other than the CLI’s pinned default.

• --wrangler-version <version> — build with the given Wrangler version or dist-tag (for example, 4.24.3 or latest). When omitted, the pinned default is used, unchanged.
• Ignored with --prebuilt — deploy --prebuilt skips the build, so the flag has no effect there.

For details, see the Catalyst CLI reference.

GraphQL Schema Updates

New types and fields across the Storefront GraphQL schemas.

Storefront GraphQL

• New updateCartLocale field on the CartMutations type
• New updateCompanyUser field on the CompanyMutations type
• New LocaleInvalidError type
• New variantEntityId field on the OrderDigitalLineItem type
• New productAttributeEntityId and productAttributeValueEntityId fields on the OrderLineItemProductOption type
• New variantEntityId field on the OrderPhysicalLineItem type
• New UpdateCartLocaleDataInput type
• New UpdateCartLocaleError type
• New UpdateCartLocaleInput type
• New UpdateCartLocaleResult type
• New UpdateCompanyUserError type
• New UpdateCompanyUserInput type
• New UpdateCompanyUserResult type

For schema details, browse the Storefront GraphQL API reference.