@shopify/cli-hydrogen 7.1.2 → 8.0.0

package/dist/commands/hydrogen/dev-vite.js

@@ -1,21 +1,22 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { muteDevLogs, enhanceH2Logs } from '../../lib/log.js';
-import { commonFlags, overrideFlag, flagsToCamelObject } from '../../lib/flags.js';
+import { setH2OVerbose, isH2Verbose, muteDevLogs, enhanceH2Logs } from '../../lib/log.js';
+import { commonFlags, overrideFlag, flagsToCamelObject, DEFAULT_INSPECTOR_PORT, DEFAULT_APP_PORT } from '../../lib/flags.js';
 import Command from '@shopify/cli-kit/node/base-command';
 import colors from '@shopify/cli-kit/node/colors';
-import { renderInfo } from '@shopify/cli-kit/node/ui';
+import { collectLog } from '@shopify/cli-kit/node/output';
+import { renderSuccess } from '@shopify/cli-kit/node/ui';
 import { AbortError } from '@shopify/cli-kit/node/error';
 import { Flags } from '@oclif/core';
 import { spawnCodegenProcess } from '../../lib/codegen.js';
 import { getAllEnvironmentVariables } from '../../lib/environment-variables.js';
-import { getConfig } from '../../lib/shopify-config.js';
-import { checkRemixVersions } from '../../lib/remix-version-check.js';
 import { displayDevUpgradeNotice } from './upgrade.js';
 import { prepareDiffDirectory } from '../../lib/template-diff.js';
-import { setH2OPluginContext } from '../../lib/vite/shared.js';
-import { getGraphiQLUrl } from '../../lib/graphiql-url.js';
-import { getDebugBannerLine } from '../../lib/mini-oxygen/workerd.js';
+import { getDevConfigInBackground, TUNNEL_DOMAIN, startTunnelAndPushConfig, getUtilityBannerlines, getDebugBannerLine, isMockShop, notifyIssueWithTunnelAndMockShop } from '../../lib/dev-shared.js';
+import { getCliCommand } from '../../lib/shell.js';
+import { findPort } from '../../lib/find-port.js';
+import { logRequestLine } from '../../lib/mini-oxygen/common.js';
+import { findHydrogenPlugin, findOxygenPlugin } from '../../lib/vite-config.js';
 
 class DevVite extends Command {
   static description = "Runs Hydrogen storefront in an Oxygen worker for development.";
@@ -28,8 +29,7 @@ class DevVite extends Command {
     ...commonFlags.codegen,
     "disable-virtual-routes": Flags.boolean({
       description: "Disable rendering fallback routes when a route file doesn't exist.",
-      env: "SHOPIFY_HYDROGEN_FLAG_DISABLE_VIRTUAL_ROUTES",
-      default: false
+      env: "SHOPIFY_HYDROGEN_FLAG_DISABLE_VIRTUAL_ROUTES"
     }),
     ...commonFlags.debug,
     ...commonFlags.inspectorPort,
@@ -38,28 +38,34 @@ class DevVite extends Command {
       default: false,
       required: false
     }),
+    ...commonFlags.env,
     ...commonFlags.envBranch,
     "disable-version-check": Flags.boolean({
       description: "Skip the version check when running `hydrogen dev`",
       default: false,
       required: false
     }),
-    ...commonFlags.diff
+    ...commonFlags.diff,
+    ...commonFlags.customerAccountPush,
+    ...commonFlags.verbose
   };
+  static hidden = true;
   async run() {
     const { flags } = await this.parse(DevVite);
     let directory = flags.path ? path.resolve(flags.path) : process.cwd();
     if (flags.diff) {
       directory = await prepareDiffDirectory(directory, true);
     }
-    await runDev({
+    await runViteDev({
       ...flagsToCamelObject(flags),
+      customerAccountPush: flags["customer-account-push__unstable"],
       path: directory,
-      isLocalDev: flags.diff
+      isLocalDev: flags.diff,
+      cliConfig: this.config
     });
   }
 }
-async function runDev({
+async function runViteDev({
   entry: ssrEntry,
   port: appPort,
   path: appPath,
@@ -68,92 +74,155 @@ async function runDev({
   codegenConfigPath,
   disableVirtualRoutes,
   envBranch,
+  env: envHandle,
   debug = false,
   disableVersionCheck = false,
   inspectorPort,
-  isLocalDev = false
+  isLocalDev = false,
+  customerAccountPush: customerAccountPushFlag = false,
+  cliConfig,
+  verbose
 }) {
   if (!process.env.NODE_ENV)
     process.env.NODE_ENV = "development";
-  muteDevLogs();
+  if (verbose)
+    setH2OVerbose();
+  if (!isH2Verbose())
+    muteDevLogs();
   const root = appPath ?? process.cwd();
-  const envPromise = getConfig(root).then(({ shop, storefront }) => {
-    const fetchRemote = !!shop && !!storefront?.id;
-    return getAllEnvironmentVariables({ root, fetchRemote, envBranch });
-  });
+  const cliCommandPromise = getCliCommand(root);
+  const backgroundPromise = getDevConfigInBackground(
+    root,
+    customerAccountPushFlag
+  );
+  const envPromise = backgroundPromise.then(
+    ({ fetchRemote, localVariables: localVariables2 }) => getAllEnvironmentVariables({
+      root,
+      envBranch,
+      envHandle,
+      fetchRemote,
+      localVariables: localVariables2
+    })
+  );
+  if (debug && !inspectorPort) {
+    inspectorPort = await findPort(DEFAULT_INSPECTOR_PORT);
+  }
   const vite = await import('vite');
   const fs = isLocalDev ? { allow: [root, fileURLToPath(new URL("../../../../", import.meta.url))] } : void 0;
+  const customLogger = vite.createLogger();
+  if (process.env.SHOPIFY_UNIT_TEST) {
+    customLogger.info = (msg) => collectLog("info", msg);
+    customLogger.warn = (msg) => collectLog("warn", msg);
+    customLogger.error = (msg) => collectLog("error", msg);
+  }
   const viteServer = await vite.createServer({
     root,
+    customLogger,
+    clearScreen: false,
     server: { fs, host: host ? true : void 0 },
-    ...setH2OPluginContext({
-      cliOptions: {
-        debug,
-        ssrEntry,
-        envPromise,
-        inspectorPort,
-        disableVirtualRoutes
+    plugins: [
+      {
+        name: "hydrogen:cli",
+        configResolved(config) {
+          findHydrogenPlugin(config)?.api?.registerPluginOptions({
+            disableVirtualRoutes
+          });
+          findOxygenPlugin(config)?.api?.registerPluginOptions({
+            debug,
+            entry: ssrEntry,
+            envPromise: envPromise.then(({ allVariables }) => allVariables),
+            inspectorPort,
+            logRequestLine
+          });
+        },
+        configureServer: (viteDevServer) => {
+          if (customerAccountPushFlag) {
+            viteDevServer.middlewares.use((req, res, next) => {
+              const host2 = req.headers.host;
+              if (host2?.includes(TUNNEL_DOMAIN.ORIGINAL)) {
+                req.headers.host = host2.replace(
+                  TUNNEL_DOMAIN.ORIGINAL,
+                  TUNNEL_DOMAIN.REBRANDED
+                );
+              }
+              next();
+            });
+          }
+        }
       }
-    })
+    ]
   });
-  process.once("SIGTERM", async () => {
-    try {
-      await viteServer.close();
-    } finally {
-      process.exit();
-    }
-  });
-  if (!viteServer.config.plugins.find((plugin) => plugin.name === "hydrogen:main")) {
+  const h2Plugin = findHydrogenPlugin(viteServer.config);
+  if (!h2Plugin) {
     await viteServer.close();
     throw new AbortError(
       "Hydrogen plugin not found.",
       "Add `hydrogen()` plugin to your Vite config."
     );
   }
+  const h2PluginOptions = h2Plugin.api?.getPluginOptions?.();
   const codegenProcess = useCodegen ? spawnCodegenProcess({
     rootDirectory: root,
-    configFilePath: codegenConfigPath
+    configFilePath: codegenConfigPath,
+    appDirectory: h2PluginOptions?.remixConfig?.appDirectory
   }) : void 0;
   process.on("unhandledRejection", (err) => {
     console.log("Unhandled Rejection: ", err);
   });
-  const publicPort = appPort ?? viteServer.config.server.port ?? 3e3;
-  await viteServer.listen(publicPort);
+  const publicPort = appPort ?? viteServer.config.server.port ?? DEFAULT_APP_PORT;
+  const [tunnel, cliCommand] = await Promise.all([
+    backgroundPromise.then(
+      ({ customerAccountPush, storefrontId }) => customerAccountPush ? startTunnelAndPushConfig(root, cliConfig, publicPort, storefrontId) : void 0
+    ),
+    cliCommandPromise,
+    viteServer.listen(publicPort)
+  ]);
   const publicUrl = new URL(
     viteServer.resolvedUrls.local[0] ?? viteServer.resolvedUrls.network[0]
   );
-  enhanceH2Logs({ rootDirectory: root, host: publicUrl.toString() });
-  await envPromise;
+  const finalHost = tunnel?.host || publicUrl.toString() || publicUrl.origin;
+  enhanceH2Logs({
+    rootDirectory: root,
+    host: finalHost,
+    cliCommand
+  });
+  const { logInjectedVariables, localVariables } = await envPromise;
+  logInjectedVariables();
   console.log("");
   viteServer.printUrls();
   viteServer.bindCLIShortcuts({ print: true });
   console.log("\n");
-  const infoLines = [];
-  if (!disableVirtualRoutes) {
-    infoLines.push(
-      `${colors.dim("View GraphiQL API browser:")} ${getGraphiQLUrl({
-        host: publicUrl.origin
-      })}`,
-      `
-${colors.dim("View server network requests:")} ${publicUrl.origin}/subrequest-profiler`
-    );
+  const customSections = [];
+  if (!h2PluginOptions?.disableVirtualRoutes) {
+    customSections.push({ body: getUtilityBannerlines(finalHost) });
   }
-  if (debug) {
-    infoLines.push({ warn: getDebugBannerLine(inspectorPort) });
-  }
-  if (infoLines.length > 0) {
-    renderInfo({ body: infoLines });
+  if (debug && inspectorPort) {
+    customSections.push({
+      body: { warn: getDebugBannerLine(inspectorPort) }
+    });
   }
-  checkRemixVersions();
+  const { storefrontTitle } = await backgroundPromise;
+  renderSuccess({
+    body: [
+      `View ${storefrontTitle ? colors.cyan(storefrontTitle) : "Hydrogen"} app:`,
+      { link: { url: finalHost } }
+    ],
+    customSections
+  });
   if (!disableVersionCheck) {
     displayDevUpgradeNotice({ targetPath: root });
   }
+  if (customerAccountPushFlag && isMockShop(localVariables)) {
+    notifyIssueWithTunnelAndMockShop(cliCommand);
+  }
   return {
+    getUrl: () => finalHost,
     async close() {
-      codegenProcess?.kill(0);
-      await viteServer.close();
+      codegenProcess?.removeAllListeners("close");
+      codegenProcess?.kill("SIGINT");
+      await Promise.allSettled([viteServer.close(), tunnel?.cleanup?.()]);
     }
   };
 }
 
-export { DevVite as default, runDev };
+export { DevVite as default, runViteDev };

package/dist/commands/hydrogen/dev.js

@@ -1,30 +1,33 @@
-import path from 'node:path';
 import fs from 'node:fs/promises';
 import { outputInfo, outputDebug } from '@shopify/cli-kit/node/output';
 import { fileExists } from '@shopify/cli-kit/node/fs';
 import { renderFatalError } from '@shopify/cli-kit/node/ui';
-import colors from '@shopify/cli-kit/node/colors';
+import { resolvePath, relativePath } from '@shopify/cli-kit/node/path';
 import { copyPublicFiles } from './build.js';
 import { getProjectPaths, assertOxygenChecks, handleRemixImportFail, getRemixConfig } from '../../lib/remix-config.js';
-import { muteDevLogs, createRemixLogger, enhanceH2Logs } from '../../lib/log.js';
-import { commonFlags, deprecated, flagsToCamelObject } from '../../lib/flags.js';
+import { setH2OVerbose, isH2Verbose, muteDevLogs, createRemixLogger, enhanceH2Logs } from '../../lib/log.js';
+import { commonFlags, deprecated, flagsToCamelObject, DEFAULT_APP_PORT } from '../../lib/flags.js';
 import Command from '@shopify/cli-kit/node/base-command';
 import { Flags } from '@oclif/core';
 import { buildAssetsUrl, startMiniOxygen } from '../../lib/mini-oxygen/index.js';
 import { addVirtualRoutes } from '../../lib/virtual-routes.js';
 import { spawnCodegenProcess } from '../../lib/codegen.js';
 import { getAllEnvironmentVariables } from '../../lib/environment-variables.js';
-import { getConfig } from '../../lib/shopify-config.js';
 import { setupLiveReload } from '../../lib/live-reload.js';
 import { checkRemixVersions } from '../../lib/remix-version-check.js';
-import { getGraphiQLUrl } from '../../lib/graphiql-url.js';
 import { displayDevUpgradeNotice } from './upgrade.js';
 import { findPort } from '../../lib/find-port.js';
-import { prepareDiffDirectory } from '../../lib/template-diff.js';
+import { prepareDiffDirectory, copyShopifyConfig } from '../../lib/template-diff.js';
+import { getDevConfigInBackground, startTunnelAndPushConfig, isMockShop, notifyIssueWithTunnelAndMockShop } from '../../lib/dev-shared.js';
+import { getCliCommand } from '../../lib/shell.js';
+import { hasViteConfig } from '../../lib/vite-config.js';
 
 const LOG_REBUILDING = "\u{1F9F1} Rebuilding...";
 const LOG_REBUILT = "\u{1F680} Rebuilt";
 class Dev extends Command {
+  static descriptionWithMarkdown = `Runs a Hydrogen storefront in a local runtime that emulates an Oxygen worker for development.
+
+  If your project is [linked](https://shopify.dev/docs/api/shopify-cli/hydrogen/hydrogen-link) to a Hydrogen storefront, then its environment variables will be loaded with the runtime.`;
   static description = "Runs Hydrogen storefront in an Oxygen worker for development.";
   static flags = {
     ...commonFlags.path,
@@ -40,24 +43,43 @@ class Dev extends Command {
     }),
     ...commonFlags.debug,
     ...commonFlags.inspectorPort,
+    ...commonFlags.env,
     ...commonFlags.envBranch,
     "disable-version-check": Flags.boolean({
       description: "Skip the version check when running `hydrogen dev`",
       default: false,
       required: false
     }),
-    ...commonFlags.diff
+    ...commonFlags.diff,
+    ...commonFlags.customerAccountPush,
+    ...commonFlags.verbose
   };
   async run() {
     const { flags } = await this.parse(Dev);
-    let directory = flags.path ? path.resolve(flags.path) : process.cwd();
+    const originalDirectory = flags.path ? resolvePath(flags.path) : process.cwd();
+    let directory = originalDirectory;
     if (flags.diff) {
       directory = await prepareDiffDirectory(directory, true);
     }
-    await runDev({
+    const devParams = {
       ...flagsToCamelObject(flags),
-      path: directory
-    });
+      customerAccountPush: flags["customer-account-push__unstable"],
+      path: directory,
+      cliConfig: this.config
+    };
+    const { close } = await hasViteConfig(directory ?? process.cwd()) ? await import('./dev-vite.js').then(
+      ({ runViteDev }) => runViteDev(devParams)
+    ) : await runDev(devParams);
+    let closingPromise;
+    const processExit = process.exit;
+    process.exit = async (code) => {
+      closingPromise ??= close();
+      await closingPromise;
+      return processExit(code);
+    };
+    if (flags.diff) {
+      await copyShopifyConfig(directory, originalDirectory);
+    }
   }
 }
 async function runDev({
@@ -67,17 +89,26 @@ async function runDev({
   legacyRuntime = false,
   codegenConfigPath,
   disableVirtualRoutes,
+  env: envHandle,
   envBranch,
   debug = false,
   sourcemap = true,
   disableVersionCheck = false,
-  inspectorPort
+  inspectorPort,
+  customerAccountPush: customerAccountPushFlag = false,
+  shouldLiveReload = true,
+  cliConfig,
+  verbose
 }) {
   if (!process.env.NODE_ENV)
     process.env.NODE_ENV = "development";
-  muteDevLogs();
+  if (verbose)
+    setH2OVerbose();
+  if (!isH2Verbose())
+    muteDevLogs();
   const { root, publicPath, buildPathClient, buildPathWorkerFile } = getProjectPaths(appPath);
-  const copyingFiles = copyPublicFiles(publicPath, buildPathClient);
+  const copyFilesPromise = copyPublicFiles(publicPath, buildPathClient);
+  const cliCommandPromise = getCliCommand(root);
   const reloadConfig = async () => {
     const config = await getRemixConfig(root);
     return disableVirtualRoutes ? config : addVirtualRoutes(config).catch((error) => {
@@ -88,23 +119,42 @@ async function runDev({
     });
   };
   const getFilePaths = (file) => {
-    const fileRelative = path.relative(root, file);
-    return [fileRelative, path.resolve(root, fileRelative)];
+    const fileRelative = relativePath(root, file);
+    return [fileRelative, resolvePath(root, fileRelative)];
   };
   const serverBundleExists = () => fileExists(buildPathWorkerFile);
-  inspectorPort = debug ? await findPort(inspectorPort) : inspectorPort;
-  appPort = legacyRuntime ? appPort : await findPort(appPort);
+  if (!appPort) {
+    appPort = await findPort(DEFAULT_APP_PORT);
+  }
   const assetsPort = legacyRuntime ? 0 : await findPort(appPort + 100);
   if (assetsPort) {
-    process.env.HYDROGEN_ASSET_BASE_URL = buildAssetsUrl(assetsPort);
+    process.env.HYDROGEN_ASSET_BASE_URL = await buildAssetsUrl(assetsPort);
   }
-  const [remixConfig, { shop, storefront }] = await Promise.all([
-    reloadConfig(),
-    getConfig(root)
-  ]);
+  const backgroundPromise = getDevConfigInBackground(
+    root,
+    customerAccountPushFlag
+  );
+  const tunnelPromise = cliConfig && backgroundPromise.then(({ customerAccountPush, storefrontId }) => {
+    if (customerAccountPush) {
+      return startTunnelAndPushConfig(
+        root,
+        cliConfig,
+        appPort,
+        storefrontId
+      );
+    }
+  });
+  const remixConfig = await reloadConfig();
   assertOxygenChecks(remixConfig);
-  const fetchRemote = !!shop && !!storefront?.id;
-  const envPromise = getAllEnvironmentVariables({ root, fetchRemote, envBranch });
+  const envPromise = backgroundPromise.then(
+    ({ fetchRemote, localVariables }) => getAllEnvironmentVariables({
+      root,
+      fetchRemote,
+      envBranch,
+      envHandle,
+      localVariables
+    })
+  );
   const [{ watch }, { createFileWatchCache }] = await Promise.all([
     import('@remix-run/dev/dist/compiler/watch.js'),
     import('@remix-run/dev/dist/compiler/fileWatchCache.js')
@@ -112,43 +162,37 @@ async function runDev({
   let isInitialBuild = true;
   let initialBuildDurationMs = 0;
   let initialBuildStartTimeMs = Date.now();
-  const liveReload = await setupLiveReload(remixConfig.dev?.port ?? 8002) ;
+  const liveReload = shouldLiveReload ? await setupLiveReload(remixConfig.dev?.port ?? 8002) : void 0;
   let miniOxygen;
   let codegenProcess;
   async function safeStartMiniOxygen() {
     if (miniOxygen)
       return;
+    const { allVariables, localVariables, logInjectedVariables } = await envPromise;
     miniOxygen = await startMiniOxygen(
       {
         root,
         debug,
+        appPort,
         assetsPort,
         inspectorPort,
-        port: appPort,
         watch: !liveReload,
         buildPathWorkerFile,
         buildPathClient,
-        env: await envPromise
+        env: allVariables
       },
       legacyRuntime
     );
-    enhanceH2Logs({ host: miniOxygen.listeningAt, ...remixConfig });
+    logInjectedVariables();
+    const host = (await tunnelPromise)?.host ?? miniOxygen.listeningAt;
+    const cliCommand = await cliCommandPromise;
+    enhanceH2Logs({ host, cliCommand, ...remixConfig });
+    const { storefrontTitle } = await backgroundPromise;
     miniOxygen.showBanner({
-      appName: storefront ? colors.cyan(storefront?.title) : void 0,
+      appName: storefrontTitle,
       headlinePrefix: initialBuildDurationMs > 0 ? `Initial build: ${initialBuildDurationMs}ms
 ` : "",
-      extraLines: [
-        colors.dim(
-          `
-View GraphiQL API browser: ${getGraphiQLUrl({
-            host: miniOxygen.listeningAt
-          })}`
-        ),
-        colors.dim(
-          `
-View server network requests: ${miniOxygen.listeningAt}/subrequest-profiler`
-        )
-      ]
+      host
     });
     if (useCodegen) {
       codegenProcess = spawnCodegenProcess({
@@ -160,6 +204,9 @@ View server network requests: ${miniOxygen.listeningAt}/subrequest-profiler`
     if (!disableVersionCheck) {
       displayDevUpgradeNotice({ targetPath: appPath });
     }
+    if (customerAccountPushFlag && isMockShop(localVariables)) {
+      notifyIssueWithTunnelAndMockShop(cliCommand);
+    }
   }
   const fileWatchCache = createFileWatchCache();
   let skipRebuildLogs = false;
@@ -185,7 +232,7 @@ View server network requests: ${miniOxygen.listeningAt}/subrequest-profiler`
       onBuildManifest: liveReload?.onBuildManifest,
       async onBuildFinish(context, duration, succeeded) {
         if (isInitialBuild) {
-          await copyingFiles;
+          await copyFilesPromise;
           initialBuildDurationMs = Date.now() - initialBuildStartTimeMs;
           isInitialBuild = false;
         } else if (!skipRebuildLogs) {
@@ -230,12 +277,16 @@ View server network requests: ${miniOxygen.listeningAt}/subrequest-profiler`
 \u{1F4C4} File changed: ${relative}`);
         if (relative.endsWith(".env")) {
           skipRebuildLogs = true;
+          const { fetchRemote } = await backgroundPromise;
+          const { allVariables, logInjectedVariables } = await getAllEnvironmentVariables({
+            root,
+            fetchRemote,
+            envBranch,
+            envHandle
+          });
+          logInjectedVariables();
           await miniOxygen.reload({
-            env: await getAllEnvironmentVariables({
-              root,
-              fetchRemote,
-              envBranch
-            })
+            env: allVariables
           });
         }
         if (absolute.startsWith(publicPath)) {
@@ -257,9 +308,15 @@ View server network requests: ${miniOxygen.listeningAt}/subrequest-profiler`
     }
   );
   return {
+    getUrl: () => miniOxygen.listeningAt,
     async close() {
-      codegenProcess?.kill(0);
-      await Promise.all([closeWatcher(), miniOxygen?.close()]);
+      codegenProcess?.removeAllListeners("close");
+      codegenProcess?.kill("SIGINT");
+      await Promise.allSettled([
+        closeWatcher(),
+        miniOxygen?.close(),
+        Promise.resolve(tunnelPromise).then((tunnel) => tunnel?.cleanup?.())
+      ]);
     }
   };
 }

package/dist/commands/hydrogen/env/list.js

@@ -1,16 +1,17 @@
 import Command from '@shopify/cli-kit/node/base-command';
 import { renderConfirmationPrompt } from '@shopify/cli-kit/node/ui';
 import { pluralize } from '@shopify/cli-kit/common/string';
-import colors from '@shopify/cli-kit/node/colors';
-import { outputNewline, outputInfo, outputContent } from '@shopify/cli-kit/node/output';
+import { outputInfo, outputNewline, outputContent } from '@shopify/cli-kit/node/output';
 import { linkStorefront } from '../link.js';
 import { commonFlags } from '../../../lib/flags.js';
 import { getStorefrontEnvironments } from '../../../lib/graphql/admin/list-environments.js';
+import { createEnvironmentCliChoiceLabel } from '../../../lib/common.js';
 import { renderMissingLink, renderMissingStorefront } from '../../../lib/render-errors.js';
 import { login } from '../../../lib/auth.js';
 import { getCliCommand } from '../../../lib/shell.js';
 
 class EnvList extends Command {
+  static descriptionWithMarkdown = "Lists all environments available on the linked Hydrogen storefront.";
   static description = "List the environments on your linked Hydrogen storefront.";
   static flags = {
     ...commonFlags.path
@@ -60,25 +61,23 @@ async function runEnvList({ path: root = process.cwd() }) {
     1
   );
   storefront.environments.push(previewEnvironment[0]);
-  outputNewline();
   outputInfo(
     pluralizedEnvironments({
       environments: storefront.environments,
       storefrontTitle: configStorefront.title
     }).toString()
   );
-  storefront.environments.forEach(({ name, branch, type, url }) => {
+  storefront.environments.forEach(({ name, handle, branch, type, url }) => {
     outputNewline();
     const environmentUrl = type === "PRODUCTION" ? storefront.productionUrl : url;
     outputInfo(
-      outputContent`${colors.whiteBright(name)}${branch ? ` ${colors.dim(`(Branch: ${branch})`)}` : ""}`.value
+      outputContent`${createEnvironmentCliChoiceLabel(name, handle, branch)}`.value
     );
     if (environmentUrl) {
-      outputInfo(
-        outputContent`    ${colors.whiteBright(environmentUrl)}`.value
-      );
+      outputInfo(outputContent`    ${environmentUrl}`.value);
     }
   });
+  outputNewline();
 }
 const pluralizedEnvironments = ({
   environments,

package/dist/commands/hydrogen/env/pull.js

@@ -9,13 +9,17 @@ import colors from '@shopify/cli-kit/node/colors';
 import { commonFlags, flagsToCamelObject } from '../../../lib/flags.js';
 import { login } from '../../../lib/auth.js';
 import { getCliCommand } from '../../../lib/shell.js';
+import { findEnvironmentOrThrow, findEnvironmentByBranchOrThrow } from '../../../lib/common.js';
 import { renderMissingLink, renderMissingStorefront } from '../../../lib/render-errors.js';
 import { linkStorefront } from '../link.js';
+import { getStorefrontEnvironments } from '../../../lib/graphql/admin/list-environments.js';
 import { getStorefrontEnvVariables } from '../../../lib/graphql/admin/pull-variables.js';
 
 class EnvPull extends Command {
+  static descriptionWithMarkdown = "Pulls environment variables from the linked Hydrogen storefront and writes them to an `.env` file.";
   static description = "Populate your .env with variables from your Hydrogen storefront.";
   static flags = {
+    ...commonFlags.env,
     ...commonFlags.envBranch,
     ...commonFlags.path,
     ...commonFlags.force
@@ -26,6 +30,7 @@ class EnvPull extends Command {
   }
 }
 async function runEnvPull({
+  env: envHandle,
   envBranch,
   path: root = process.cwd(),
   force
@@ -49,10 +54,21 @@ async function runEnvPull({
   }
   if (!config.storefront?.id)
     return;
+  if (envHandle || envBranch) {
+    const environments = (await getStorefrontEnvironments(session, config.storefront.id))?.environments || [];
+    if (envHandle) {
+      findEnvironmentOrThrow(environments, envHandle);
+    } else if (envBranch) {
+      envHandle = findEnvironmentByBranchOrThrow(
+        environments,
+        envBranch
+      ).handle;
+    }
+  }
   const storefront = await getStorefrontEnvVariables(
     session,
     config.storefront.id,
-    envBranch
+    envHandle
   );
   if (!storefront) {
     renderMissingStorefront({