LTRAC-908: feat(cli) - Add `catalyst channel link` command by jorgemoya · Pull Request #3051 · bigcommerce/catalyst

jorgemoya · 2026-06-16T17:04:16Z

Linear: LTRAC-908
Part of LTRAC-138 — consolidating create-catalyst into the catalyst CLI.

What/Why?

We decided not to port create-catalyst's standalone init command. It was conceived for "download the Catalyst core repo → connect → run on Vercel", which doesn't apply to a native-hosting-only CLI, and catalyst create already connects a channel + writes .env.local for new projects.

The one residual need is real: regenerating .env.local from a channel for an existing checkout — e.g. a teammate who git cloned a Catalyst repo where .env.local (and .bigcommerce/project.json) are gitignored. That's a channel concern, distinct from project link (the native-hosting deploy target), so it lands as catalyst channel link — a sibling to channel update, and named to parallel the existing project link (the CLI's verb for linking a local checkout to a remote BigCommerce resource).

The command:

Resolves credentials from flags/env → persisted .bigcommerce/project.json → interactive device-code login() (persisting on success), since a fresh clone has no stored creds — same pattern as catalyst project create.
Selects a storefront channel (Catalyst-first ordering) or takes --channel-id to skip the picker.
Fetches the channel's init data (getChannelInit) and writes .env.local to the cwd (where dev/build/deploy run), with repeatable --env KEY=VALUE overrides.

Reuses existing libs (channels, login, project-config, env-config, telemetry); no new dependencies. program.ts is untouched — channel is already registered.

Testing

pnpm test, pnpm typecheck, and pnpm lint all pass in packages/catalyst. New channel link tests (in channel.spec.ts) cover: link by --channel-id, the interactive picker, --env overrides, the empty-channels exit, and the no-credentials login-and-persist path.

Migration

None. Purely additive — adds a channel link subcommand. create-catalyst init is unaffected (the create-catalyst shim removal is tracked in LTRAC-910).

Add a `connect` subcommand under `catalyst channel` that connects an existing local checkout to a BigCommerce channel and writes its credentials to .env.local — useful when a teammate clones a Catalyst repo (where .env.local is gitignored) and needs to regenerate it from the channel. Resolves credentials from flags/env, the persisted project config, or an interactive device-code login (persisting the result), then selects a channel (or takes --channel-id), fetches its channel-init data, and writes .env.local in the cwd. Supports repeatable --env KEY=VALUE overrides. Supersedes the dropped plan to port create-catalyst's standalone `init`: the catalyst CLI is native-hosting only and `catalyst create` already connects a channel for new projects, so the only residual need — bootstrapping .env.local for an existing checkout — lives under `channel`. Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com>

vercel · 2026-06-16T17:04:23Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Jun 17, 2026 1:47am

github-actions · 2026-06-16T17:05:38Z

Bundle Size Report

Comparing against baseline from 1ab2c82 (2026-06-17).

Metric	Baseline	Current	Delta
Total JS	435.4 kB	434.5 kB	-0.9 kB (-0.2%)

Per-Route First Load JS

Route	Baseline	Current	Delta
/(default)/(auth)/change-password/page	318.8 kB	317.5 kB	-1.3 kB (-0.4%)
/(default)/(auth)/login/forgot-password/page	318 kB	316.7 kB	-1.3 kB (-0.4%)
/(default)/(auth)/login/page	318.4 kB	317.2 kB	-1.2 kB (-0.4%)
/(default)/(auth)/register/page	354.6 kB	353.3 kB	-1.3 kB (-0.4%)
/(default)/(faceted)/brand/[slug]/page	330.5 kB	329.2 kB	-1.3 kB (-0.4%)
/(default)/(faceted)/category/[slug]/page	339 kB	337.6 kB	-1.4 kB (-0.4%)
/(default)/(faceted)/search/page	330.5 kB	329.2 kB	-1.3 kB (-0.4%)
/(default)/[...rest]/page	313.5 kB	312.3 kB	-1.2 kB (-0.4%)
/(default)/account/addresses/page	358 kB	356.7 kB	-1.3 kB (-0.4%)
/(default)/account/orders/[id]/page	321.6 kB	320.4 kB	-1.2 kB (-0.4%)
/(default)/account/orders/page	322.6 kB	321.3 kB	-1.3 kB (-0.4%)
/(default)/account/settings/page	329.2 kB	327.9 kB	-1.3 kB (-0.4%)
/(default)/account/wishlists/[id]/page	336.4 kB	335.3 kB	-1.1 kB (-0.3%)
/(default)/account/wishlists/page	331.5 kB	330.3 kB	-1.2 kB (-0.4%)
/(default)/blog/[blogId]/page	313.5 kB	312.3 kB	-1.2 kB (-0.4%)
/(default)/blog/page	314.5 kB	313.3 kB	-1.2 kB (-0.4%)
/(default)/cart/page	334.3 kB	333.1 kB	-1.2 kB (-0.4%)
/(default)/compare/page	325.7 kB	324.4 kB	-1.3 kB (-0.4%)
/(default)/gift-certificates/balance/page	317.5 kB	316.2 kB	-1.3 kB (-0.4%)
/(default)/gift-certificates/page	313.5 kB	312.3 kB	-1.2 kB (-0.4%)
/(default)/gift-certificates/purchase/page	357.1 kB	355.8 kB	-1.3 kB (-0.4%)
/(default)/page	330.7 kB	329.4 kB	-1.3 kB (-0.4%)
/(default)/product/[slug]/page	385.4 kB	384.2 kB	-1.2 kB (-0.3%)
/(default)/webpages/[id]/contact/page	355.5 kB	354.2 kB	-1.3 kB (-0.4%)
/(default)/webpages/[id]/normal/page	321.6 kB	320.4 kB	-1.2 kB (-0.4%)
/(default)/wishlist/[token]/page	326.3 kB	325.2 kB	-1.1 kB (-0.3%)
/maintenance/page	307.1 kB	306.4 kB	-0.7 kB (-0.2%)

Threshold: 5% increase. Routes with ⚠️ exceed the threshold.

github-actions · 2026-06-16T17:47:02Z

Unlighthouse Performance Comparison — Vercel

Comparing PR preview deployment Unlighthouse scores vs production Unlighthouse scores.

Summary Score

Aggregate score across all categories as reported by Unlighthouse.

	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Score	89	93	92	95

Category Scores

Category	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Performance	72	85	76	81
Accessibility	95	92	95	92
Best Practices	100	100	100	100
SEO	88	88	88	100

Core Web Vitals

Metric	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
LCP	5.1 s	4.3 s	3.6 s	4.9 s
CLS	0.037	0	0.001	0
FCP	1.1 s	1.1 s	1.2 s	1.1 s
TBT	0 ms	10 ms	0 ms	0 ms
Max Potential FID	40 ms	60 ms	50 ms	60 ms
Time to Interactive	5.1 s	4.3 s	3.6 s	6.6 s

Full Unlighthouse report →

changeset-bot · 2026-06-16T18:11:34Z

⚠️ No Changeset found

Latest commit: 921d835

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

jorgemoya · 2026-06-16T21:23:19Z

Testing:

~/dev/catalyst/core on  alpha [✘!?]
❯ node ../packages/catalyst/dist/cli.js channel connect --api-host api.staging.zone --cli-api-origin https://cxm-stg.bigcommerceapp.com
◢ @bigcommerce/catalyst v1.0.0-alpha.5                                                                                                                 4:37:11 PM


✔ Which channel would you like to connect?
My Catalyst Storefront
✔ Connected to channel "My Catalyst Storefront" (6666015) and wrote .env.local.                                                                       4:37:14 PM
                                                                                                                                                       4:37:14 PM
Start your storefront:

  pnpm run dev

Drop the per-line info-icon clutter on the next-steps hint: print a single success line (channel + .env.local) followed by a spaced, plain block with the `pnpm run dev` command. Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com>

Align with `catalyst project link` — the established CLI verb for linking a local checkout to a remote BigCommerce resource (infrastructure project vs storefront channel). The success line now reads "Linked to channel …". Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com>

`channel link` had copied `catalyst create`'s channel-platform sort comparator and the Stencil/title-case label. Move both into channels.ts as `sortChannelsByPlatform` (returns a sorted copy) and `channelPlatformLabel`, and use them from both pickers. No behavior change. Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com>

…ompts Replace all `consola.prompt` usages with `@inquirer/prompts` (confirm/input/select/ checkbox) so the CLI uses one prompt library; consola is retained for logging only. Converts create's locale multiselect to an inquirer `checkbox` with a `validate` (drops the consola cast + recursion hack), and migrates the prompts in login, channel link/update, project, deploy, channel-site-flow, and commerce-hosting. Specs updated to mock `@inquirer/prompts`. Chosen over consola because consola.prompt has no masked input (login's access token uses `password({ mask: true })`), plus inquirer's validate/theming. Stacked on #3051 (channel link). Refs LTRAC-911 Co-Authored-By: Claude <noreply@anthropic.com>

…rompts` (#3054) * LTRAC-911: ref(cli) - Standardize interactive prompts on @inquirer/prompts Replace all `consola.prompt` usages with `@inquirer/prompts` (confirm/input/select/ checkbox) so the CLI uses one prompt library; consola is retained for logging only. Converts create's locale multiselect to an inquirer `checkbox` with a `validate` (drops the consola cast + recursion hack), and migrates the prompts in login, channel link/update, project, deploy, channel-site-flow, and commerce-hosting. Specs updated to mock `@inquirer/prompts`. Chosen over consola because consola.prompt has no masked input (login's access token uses `password({ mask: true })`), plus inquirer's validate/theming. Stacked on #3051 (channel link). Refs LTRAC-911 Co-Authored-By: Claude <noreply@anthropic.com> * LTRAC-911: style(cli) - Standardize spacing on prompts and command output Stray blank lines came from leading/trailing newlines and `consola.log('')` calls, which the fancy reporter timestamps as their own log line. Collapse multi-line "Next steps" output into a single `consola.log` call (one timestamp, predictable spacing) and drop the manual blank-line separators after prompts. `project list` now joins its project blocks into one log call so each blank separator isn't timestamped. Refs LTRAC-911 Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

* LTRAC-908: feat(cli) - Add `catalyst channel connect` command Add a `connect` subcommand under `catalyst channel` that connects an existing local checkout to a BigCommerce channel and writes its credentials to .env.local — useful when a teammate clones a Catalyst repo (where .env.local is gitignored) and needs to regenerate it from the channel. Resolves credentials from flags/env, the persisted project config, or an interactive device-code login (persisting the result), then selects a channel (or takes --channel-id), fetches its channel-init data, and writes .env.local in the cwd. Supports repeatable --env KEY=VALUE overrides. Supersedes the dropped plan to port create-catalyst's standalone `init`: the catalyst CLI is native-hosting only and `catalyst create` already connects a channel for new projects, so the only residual need — bootstrapping .env.local for an existing checkout — lives under `channel`. Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com> * LTRAC-908: ref(cli) - Clean up `channel connect` success output Drop the per-line info-icon clutter on the next-steps hint: print a single success line (channel + .env.local) followed by a spaced, plain block with the `pnpm run dev` command. Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com> * LTRAC-908: ref(cli) - Rename `channel connect` to `channel link` Align with `catalyst project link` — the established CLI verb for linking a local checkout to a remote BigCommerce resource (infrastructure project vs storefront channel). The success line now reads "Linked to channel …". Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com> * LTRAC-908: ref(cli) - Extract shared channel sort/label helpers `channel link` had copied `catalyst create`'s channel-platform sort comparator and the Stencil/title-case label. Move both into channels.ts as `sortChannelsByPlatform` (returns a sorted copy) and `channelPlatformLabel`, and use them from both pickers. No behavior change. Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

…rompts` (#3054) * LTRAC-911: ref(cli) - Standardize interactive prompts on @inquirer/prompts Replace all `consola.prompt` usages with `@inquirer/prompts` (confirm/input/select/ checkbox) so the CLI uses one prompt library; consola is retained for logging only. Converts create's locale multiselect to an inquirer `checkbox` with a `validate` (drops the consola cast + recursion hack), and migrates the prompts in login, channel link/update, project, deploy, channel-site-flow, and commerce-hosting. Specs updated to mock `@inquirer/prompts`. Chosen over consola because consola.prompt has no masked input (login's access token uses `password({ mask: true })`), plus inquirer's validate/theming. Stacked on #3051 (channel link). Refs LTRAC-911 Co-Authored-By: Claude <noreply@anthropic.com> * LTRAC-911: style(cli) - Standardize spacing on prompts and command output Stray blank lines came from leading/trailing newlines and `consola.log('')` calls, which the fancy reporter timestamps as their own log line. Collapse multi-line "Next steps" output into a single `consola.log` call (one timestamp, predictable spacing) and drop the manual blank-line separators after prompts. `project list` now joins its project blocks into one log call so each blank separator isn't timestamped. Refs LTRAC-911 Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

* LTRAC-908: feat(cli) - Add `catalyst channel connect` command Add a `connect` subcommand under `catalyst channel` that connects an existing local checkout to a BigCommerce channel and writes its credentials to .env.local — useful when a teammate clones a Catalyst repo (where .env.local is gitignored) and needs to regenerate it from the channel. Resolves credentials from flags/env, the persisted project config, or an interactive device-code login (persisting the result), then selects a channel (or takes --channel-id), fetches its channel-init data, and writes .env.local in the cwd. Supports repeatable --env KEY=VALUE overrides. Supersedes the dropped plan to port create-catalyst's standalone `init`: the catalyst CLI is native-hosting only and `catalyst create` already connects a channel for new projects, so the only residual need — bootstrapping .env.local for an existing checkout — lives under `channel`. Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com> * LTRAC-908: ref(cli) - Clean up `channel connect` success output Drop the per-line info-icon clutter on the next-steps hint: print a single success line (channel + .env.local) followed by a spaced, plain block with the `pnpm run dev` command. Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com> * LTRAC-908: ref(cli) - Rename `channel connect` to `channel link` Align with `catalyst project link` — the established CLI verb for linking a local checkout to a remote BigCommerce resource (infrastructure project vs storefront channel). The success line now reads "Linked to channel …". Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com> * LTRAC-908: ref(cli) - Extract shared channel sort/label helpers `channel link` had copied `catalyst create`'s channel-platform sort comparator and the Stencil/title-case label. Move both into channels.ts as `sortChannelsByPlatform` (returns a sorted copy) and `channelPlatformLabel`, and use them from both pickers. No behavior change. Refs LTRAC-908 Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

…rompts` (#3054) * LTRAC-911: ref(cli) - Standardize interactive prompts on @inquirer/prompts Replace all `consola.prompt` usages with `@inquirer/prompts` (confirm/input/select/ checkbox) so the CLI uses one prompt library; consola is retained for logging only. Converts create's locale multiselect to an inquirer `checkbox` with a `validate` (drops the consola cast + recursion hack), and migrates the prompts in login, channel link/update, project, deploy, channel-site-flow, and commerce-hosting. Specs updated to mock `@inquirer/prompts`. Chosen over consola because consola.prompt has no masked input (login's access token uses `password({ mask: true })`), plus inquirer's validate/theming. Stacked on #3051 (channel link). Refs LTRAC-911 Co-Authored-By: Claude <noreply@anthropic.com> * LTRAC-911: style(cli) - Standardize spacing on prompts and command output Stray blank lines came from leading/trailing newlines and `consola.log('')` calls, which the fancy reporter timestamps as their own log line. Collapse multi-line "Next steps" output into a single `consola.log` call (one timestamp, predictable spacing) and drop the manual blank-line separators after prompts. `project list` now joins its project blocks into one log call so each blank separator isn't timestamped. Refs LTRAC-911 Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

vercel Bot deployed to Preview June 16, 2026 17:04 View deployment

vercel Bot deployed to Preview June 16, 2026 18:12 View deployment

jorgemoya force-pushed the jorgemoya/ltrac-908-add-catalyst-channel-connect-to-bootstrap-envlocal-from-a branch from 3c47b7d to 85103b8 Compare June 16, 2026 21:14

vercel Bot deployed to Preview June 16, 2026 21:29 View deployment

jorgemoya changed the title ~~LTRAC-908: feat(cli) - Add catalyst channel connect command~~ LTRAC-908: feat(cli) - Add catalyst channel link command Jun 16, 2026

vercel Bot deployed to Preview June 16, 2026 21:45 View deployment

vercel Bot deployed to Preview June 17, 2026 01:47 View deployment

jorgemoya marked this pull request as ready for review June 17, 2026 13:32

jorgemoya requested a review from a team as a code owner June 17, 2026 13:32

jorgemoya mentioned this pull request Jun 17, 2026

LTRAC-911: ref(cli) - Standardize interactive prompts on @inquirer/prompts #3054

Merged

chanceaclark approved these changes Jun 22, 2026

View reviewed changes

jorgemoya merged commit abe4a66 into alpha Jun 22, 2026
23 checks passed

jorgemoya deleted the jorgemoya/ltrac-908-add-catalyst-channel-connect-to-bootstrap-envlocal-from-a branch June 22, 2026 16:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

LTRAC-908: feat(cli) - Add `catalyst channel link` command#3051

LTRAC-908: feat(cli) - Add `catalyst channel link` command#3051
jorgemoya merged 4 commits into
alphafrom
jorgemoya/ltrac-908-add-catalyst-channel-connect-to-bootstrap-envlocal-from-a

jorgemoya commented Jun 16, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 16, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 16, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 16, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 16, 2026 •

edited

Loading

Uh oh!

jorgemoya commented Jun 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

jorgemoya commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why?

Testing

Migration

Uh oh!

vercel Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Report

Per-Route First Load JS

Uh oh!

github-actions Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlighthouse Performance Comparison — Vercel

Summary Score

Category Scores

Core Web Vitals

Uh oh!

changeset-bot Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

jorgemoya commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jorgemoya commented Jun 16, 2026 •

edited

Loading

vercel Bot commented Jun 16, 2026 •

edited

Loading

github-actions Bot commented Jun 16, 2026 •

edited

Loading

github-actions Bot commented Jun 16, 2026 •

edited

Loading

changeset-bot Bot commented Jun 16, 2026 •

edited

Loading

jorgemoya commented Jun 16, 2026 •

edited

Loading