fix(cli): await the next-steps outro so post-command output prints below it

.changeset/slack-thread-fix-issue-bun-1-4-define.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Keep `--define CLI_VERSION` working when building with Bun 1.4.
+
+Bun 1.4 runs macros in a sealed transpiler context that `--define` globals no longer reach, so the version macro silently fell back to the checkout-derived dev version even when a release version was injected. The define check and dev classification now live in `version.ts` module scope, where define substitution still applies; the macro only derives the Git checkout fallback.

.changeset/slack-thread-fix-issue.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Stop the "Update available" notice from garbling the "Next steps" block.
+
+The next-steps outro animation moves the cursor back onto the header line for ~450ms, but several commands (`switch-env`, `auth logout`, `unlink`, `users create`, `apps create`, and others) did not await it. The command's promise resolved mid-animation, so the post-command update check printed its notice at the parked cursor position — overwriting the step lines and leaving a stray duplicate "Next steps" header. Every `outro(...)` call is now awaited, so output printed after a command lands below the finished block.

.claude/rules/versioning.md

@@ -16,10 +16,13 @@ import { CURRENT_VERSION, IS_DEV_BUILD } from "./version.ts";
  including CLI help, user-agent headers, and MCP client info.
 - Read `IS_DEV_BUILD` when behavior depends on whether the binary is a
  development build.
-- Keep checkout-derived version generation and dev classification in
- `version.macro.ts`; the compiled CLI must not execute Git or classify its
- version at runtime.
+- Keep checkout-derived version generation in `version.macro.ts`; the compiled
+ CLI must not execute Git at runtime.
+- Keep the `CLI_VERSION` define check and dev classification in `version.ts`
+ module scope, NOT in the macro: since Bun 1.4, macros run in a sealed
+ transpiler context that `--define` globals do not reach, while defines still
+ substitute identifiers in transpiled modules.
 
-The constants are evaluated while Bun transpiles or compiles the module, so
+The macro fallback is inlined while Bun transpiles or compiles the module, so
 release builds can use the injected `CLI_VERSION` while local builds retain
 their checkout metadata.

CLAUDE.md

@@ -60,4 +60,4 @@ These flags require Bun >= 1.3.13 — older versions silently ignore them and lo
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
 
-Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git or classifies the version at runtime. Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.
+Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.

packages/cli-core/src/commands/api/index.ts

@@ -167,9 +167,9 @@ export async function api(
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/apps/create.ts

@@ -41,9 +41,9 @@ export async function create(name: string, options: AppsOptions = {}): Promise<v
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro(nextSteps);
+await outro(nextSteps);
  }
  }
  }

packages/cli-core/src/commands/apps/list.ts

@@ -60,9 +60,9 @@ export async function list(options: AppsOptions = {}): Promise<void> {
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/auth/login.ts

@@ -140,7 +140,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
  return existingSession;
  }
@@ -151,7 +151,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  default: false,
  });
  if (!reauthenticate) {
- outro();
+await outro();
  throwUserAbort();
  }
  }
@@ -188,7 +188,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
 
  return userInfo;

packages/cli-core/src/commands/auth/logout.ts

@@ -26,5 +26,5 @@ export async function logout(): Promise<void> {
  );
  }
 
- outro(NEXT_STEPS.LOGOUT);
+await outro(NEXT_STEPS.LOGOUT);
 }

packages/cli-core/src/commands/config/push.ts

@@ -137,9 +137,9 @@ async function configPush(options: ConfigPushOptions, op: Operation): Promise<vo
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/deploy/index.ts

@@ -92,7 +92,7 @@ export async function deploy(_options: DeployOptions = {}) {
  throw error;
  }
  if (error instanceof DeployPausedError && isInsideGutter()) {
- outro("Paused");
+await outro("Paused");
  }
  if (error instanceof UserAbortError && isInsideGutter()) {
  pausedOutro(pausedOperationNotice());
@@ -103,7 +103,7 @@ export async function deploy(_options: DeployOptions = {}) {
  // Successful and paused paths call outro themselves. This balances the
  // intro gutter if an unexpected error escapes.
  if (isInsideGutter()) {
- outro("Failed");
+await outro("Failed");
  }
  }
 }
@@ -154,7 +154,7 @@ async function startNewDeploy(ctx: DeployContext): Promise<void> {
  const proceed = await confirmProceed();
  if (!proceed) {
  log.info("No changes were made.");
- outro("Cancelled");
+await outro("Cancelled");
  return;
  }
 
@@ -233,7 +233,7 @@ async function reconcileExistingDeploy(ctx: DeployContext): Promise<void> {
  log.blank();
  log.info("A production instance exists, but Clerk did not return a production domain yet.");
  log.info("Run `clerk deploy` again after the domain is available from the API.");
- outro("No deploy actions available");
+await outro("No deploy actions available");
  return;
  }
 
@@ -361,7 +361,7 @@ async function confirmProductionInstanceCreation(domain: string): Promise<boolea
 
  log.blank();
  log.info("No production instance was created.");
- outro("Cancelled");
+await outro("Cancelled");
  return false;
 }
 
@@ -639,7 +639,7 @@ async function finishDeploy(
  fallback: bold,
  body: `${applyPrefix(nextStepsBody(ctx.appId, productionInstanceId))}\n`,
  });
- outro("Success");
+await outro("Success");
 }
 
 export function registerDeploy(program: Program): void {

packages/cli-core/src/commands/doctor/index.ts

@@ -128,7 +128,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
  return;
  }
  }
@@ -139,7 +139,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
 }
 
 export function registerDoctor(program: Program): void {

packages/cli-core/src/commands/init/index.ts

@@ -160,7 +160,7 @@ export async function init(options: InitOptions = {}) {
  if (agent && strategy === "manual") {
  printBootstrapManualSetupInfo(ctx.framework);
  }
- outro("Done");
+await outro("Done");
  return;
  }
 
@@ -183,7 +183,7 @@ export async function init(options: InitOptions = {}) {
  printBootstrapNextSteps(bootstrap, strategy === "keyless");
  }
 
- outro("Done");
+await outro("Done");
 }
 
 /**

packages/cli-core/src/commands/link/index.ts

@@ -61,13 +61,13 @@ export async function link(options: LinkOptions = {}): Promise<void> {
  if (existing && agent) {
  printExistingStatus(existing, normalizedRemote);
  if (!targetsDifferentApp) {
- outro();
+await outro();
  return;
  }
  } else if (existing) {
  const shouldRelink = await handleExistingProfile(existing, normalizedRemote, options);
  if (!shouldRelink) {
- outro();
+await outro();
  return;
  }
  }

packages/cli-core/src/commands/open/index.ts

@@ -102,7 +102,7 @@ export async function openDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 /**
@@ -196,7 +196,7 @@ async function openKeylessDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 export function registerOpen(program: Program): void {

packages/cli-core/src/commands/switch-env/index.ts

@@ -48,12 +48,12 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  } else if (available.length <= 1) {
  log.info(`Current environment: ${current}`);
  log.info("Only one environment configured — nothing to switch to.");
- outro();
+await outro();
  return;
  } else {
  log.info(`Current environment: ${current}`);
  log.info(`Available environments: ${available.join(", ")}`);
- outro();
+await outro();
  return;
  }
  }
@@ -68,7 +68,7 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
 
  if (previousEnv === target) {
  log.data(`Already on ${target} environment.`);
- outro();
+await outro();
  return;
  }
 
@@ -81,10 +81,10 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  const token = await getToken();
  if (!token) {
  log.data(`No credentials found for ${target}.`);
- outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
+await outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
  return;
  }
- outro(NEXT_STEPS.SWITCH_ENV);
+await outro(NEXT_STEPS.SWITCH_ENV);
 }
 
 export function registerSwitchEnv(program: Program): void {

packages/cli-core/src/commands/switch-env/update-notice-race.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Repro for the garbled "Update available" output reported in Slack: the
+ * next-steps outro animation parks the cursor on the header line for ~450ms,
+ * so anything printed after the command's promise resolves (the postAction
+ * update notice) must not run until the animation has finished. If the command
+ * resolves early, the notice lands mid-block and overwrites the step lines.
+ *
+ * Unlike index.test.ts this file deliberately uses the REAL spinner/gradient
+ * modules on a forced-interactive TTY so the animation actually runs.
+ */
+import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
+import { log } from "../../lib/log.ts";
+import { setMode } from "../../mode.ts";
+import { useCaptureLog, configStubs, credentialStoreStubs } from "../../test/lib/stubs.ts";
+
+const MOCK_ENVS = ["production", "staging"];
+let mockCurrentEnv = "production";
+
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+}));
+
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: async () => "some-token",
+}));
+
+mock.module("../../lib/environment.ts", () => ({
+ getCurrentEnvName: () => mockCurrentEnv,
+ getAvailableEnvs: () => MOCK_ENVS,
+ isValidEnv: (name: string) => MOCK_ENVS.includes(name),
+ setCurrentEnv: (name: string) => {
+ mockCurrentEnv = name;
+ },
+}));
+
+const { switchEnv } = await import("./index.ts");
+
+const CURSOR_SHOW = "\x1b[?25h";
+const NOTICE = "⬆ Update available: 3.0.1 → 3.1.0";
+
+describe("switch-env update-notice race", () => {
+ const captured = useCaptureLog();
+ const ENV_KEYS = ["CI", "NO_COLOR", "FORCE_COLOR", "COLORTERM"] as const;
+ let savedTTY: boolean | undefined;
+ let savedEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ setMode("human"); // the runner has no TTY, but the bug only shows in human mode
+ mockCurrentEnv = "production";
+ savedTTY = process.stderr.isTTY;
+ savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+ Object.defineProperty(process.stderr, "isTTY", { value: true, configurable: true });
+ for (const k of ENV_KEYS) delete process.env[k];
+ process.env.COLORTERM = "truecolor";
+ });
+
+ afterEach(() => {
+ Object.defineProperty(process.stderr, "isTTY", { value: savedTTY, configurable: true });
+ for (const k of ENV_KEYS) {
+ if (savedEnv[k] == null) delete process.env[k];
+ else process.env[k] = savedEnv[k];
+ }
+ });
+
+ test("output printed after the command resolves lands below the finished animation", async () => {
+ await switchEnv("staging");
+ // The postAction hook prints the update notice as soon as the action's
+ // promise resolves — reproduce that exact ordering.
+ log.warn(NOTICE);
+ // On fixed code the animation completed before switchEnv() resolved, so
+ // this returns immediately; on a regression it waits (bounded) for the
+ // orphaned animation's trailing frames so the ordering assertion below
+ // fails with a precise message instead of a missing-cursor-restore -1.
+ const deadline = Date.now() + 2_000;
+ while (!captured.err.includes(CURSOR_SHOW) && Date.now() < deadline) {
+ await Bun.sleep(25);
+ }
+
+ const err = captured.err;
+ const cursorRestoredAt = err.lastIndexOf(CURSOR_SHOW);
+ const noticeAt = err.indexOf(NOTICE);
+ expect(cursorRestoredAt).toBeGreaterThanOrEqual(0);
+ expect(noticeAt).toBeGreaterThan(cursorRestoredAt);
+ }, 10_000);
+});

packages/cli-core/src/commands/unlink/index.ts

@@ -45,7 +45,7 @@ export async function unlink(options: UnlinkOptions = {}): Promise<void> {
 
  await removeProfile(existing.path);
  log.data(`\nUnlinked ${cyan(label)} from ${dim(displayPath)}`);
- outro(NEXT_STEPS.UNLINK);
+await outro(NEXT_STEPS.UNLINK);
 }
 
 export function registerUnlink(program: Program): void {

.changeset/slack-thread-fix-issue-bun-1-4-define.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Keep `--define CLI_VERSION` working when building with Bun 1.4.
+
+Bun 1.4 runs macros in a sealed transpiler context that `--define` globals no longer reach, so the version macro silently fell back to the checkout-derived dev version even when a release version was injected. The define check and dev classification now live in `version.ts` module scope, where define substitution still applies; the macro only derives the Git checkout fallback.

.changeset/slack-thread-fix-issue.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Stop the "Update available" notice from garbling the "Next steps" block.
+
+The next-steps outro animation moves the cursor back onto the header line for ~450ms, but several commands (`switch-env`, `auth logout`, `unlink`, `users create`, `apps create`, and others) did not await it. The command's promise resolved mid-animation, so the post-command update check printed its notice at the parked cursor position — overwriting the step lines and leaving a stray duplicate "Next steps" header. Every `outro(...)` call is now awaited, so output printed after a command lands below the finished block.

.claude/rules/versioning.md

@@ -16,10 +16,13 @@ import { CURRENT_VERSION, IS_DEV_BUILD } from "./version.ts";
  including CLI help, user-agent headers, and MCP client info.
 - Read `IS_DEV_BUILD` when behavior depends on whether the binary is a
  development build.
-- Keep checkout-derived version generation and dev classification in
- `version.macro.ts`; the compiled CLI must not execute Git or classify its
- version at runtime.
+- Keep checkout-derived version generation in `version.macro.ts`; the compiled
+ CLI must not execute Git at runtime.
+- Keep the `CLI_VERSION` define check and dev classification in `version.ts`
+ module scope, NOT in the macro: since Bun 1.4, macros run in a sealed
+ transpiler context that `--define` globals do not reach, while defines still
+ substitute identifiers in transpiled modules.
 
-The constants are evaluated while Bun transpiles or compiles the module, so
+The macro fallback is inlined while Bun transpiles or compiles the module, so
 release builds can use the injected `CLI_VERSION` while local builds retain
 their checkout metadata.

CLAUDE.md

@@ -60,4 +60,4 @@ These flags require Bun >= 1.3.13 — older versions silently ignore them and lo
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
 
-Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git or classifies the version at runtime. Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.
+Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.

packages/cli-core/src/commands/api/index.ts

@@ -167,9 +167,9 @@ export async function api(
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/apps/create.ts

@@ -41,9 +41,9 @@ export async function create(name: string, options: AppsOptions = {}): Promise<v
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro(nextSteps);
+await outro(nextSteps);
  }
  }
  }

packages/cli-core/src/commands/apps/list.ts

@@ -60,9 +60,9 @@ export async function list(options: AppsOptions = {}): Promise<void> {
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/auth/login.ts

@@ -140,7 +140,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
  return existingSession;
  }
@@ -151,7 +151,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  default: false,
  });
  if (!reauthenticate) {
- outro();
+await outro();
  throwUserAbort();
  }
  }
@@ -188,7 +188,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
 
  return userInfo;

packages/cli-core/src/commands/auth/logout.ts

@@ -26,5 +26,5 @@ export async function logout(): Promise<void> {
  );
  }
 
- outro(NEXT_STEPS.LOGOUT);
+await outro(NEXT_STEPS.LOGOUT);
 }

packages/cli-core/src/commands/config/push.ts

@@ -137,9 +137,9 @@ async function configPush(options: ConfigPushOptions, op: Operation): Promise<vo
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/deploy/index.ts

@@ -92,7 +92,7 @@ export async function deploy(_options: DeployOptions = {}) {
  throw error;
  }
  if (error instanceof DeployPausedError && isInsideGutter()) {
- outro("Paused");
+await outro("Paused");
  }
  if (error instanceof UserAbortError && isInsideGutter()) {
  pausedOutro(pausedOperationNotice());
@@ -103,7 +103,7 @@ export async function deploy(_options: DeployOptions = {}) {
  // Successful and paused paths call outro themselves. This balances the
  // intro gutter if an unexpected error escapes.
  if (isInsideGutter()) {
- outro("Failed");
+await outro("Failed");
  }
  }
 }
@@ -154,7 +154,7 @@ async function startNewDeploy(ctx: DeployContext): Promise<void> {
  const proceed = await confirmProceed();
  if (!proceed) {
  log.info("No changes were made.");
- outro("Cancelled");
+await outro("Cancelled");
  return;
  }
 
@@ -233,7 +233,7 @@ async function reconcileExistingDeploy(ctx: DeployContext): Promise<void> {
  log.blank();
  log.info("A production instance exists, but Clerk did not return a production domain yet.");
  log.info("Run `clerk deploy` again after the domain is available from the API.");
- outro("No deploy actions available");
+await outro("No deploy actions available");
  return;
  }
 
@@ -361,7 +361,7 @@ async function confirmProductionInstanceCreation(domain: string): Promise<boolea
 
  log.blank();
  log.info("No production instance was created.");
- outro("Cancelled");
+await outro("Cancelled");
  return false;
 }
 
@@ -639,7 +639,7 @@ async function finishDeploy(
  fallback: bold,
  body: `${applyPrefix(nextStepsBody(ctx.appId, productionInstanceId))}\n`,
  });
- outro("Success");
+await outro("Success");
 }
 
 export function registerDeploy(program: Program): void {

packages/cli-core/src/commands/doctor/index.ts

@@ -128,7 +128,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
  return;
  }
  }
@@ -139,7 +139,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
 }
 
 export function registerDoctor(program: Program): void {

packages/cli-core/src/commands/init/index.ts

@@ -160,7 +160,7 @@ export async function init(options: InitOptions = {}) {
  if (agent && strategy === "manual") {
  printBootstrapManualSetupInfo(ctx.framework);
  }
- outro("Done");
+await outro("Done");
  return;
  }
 
@@ -183,7 +183,7 @@ export async function init(options: InitOptions = {}) {
  printBootstrapNextSteps(bootstrap, strategy === "keyless");
  }
 
- outro("Done");
+await outro("Done");
 }
 
 /**

packages/cli-core/src/commands/link/index.ts

@@ -61,13 +61,13 @@ export async function link(options: LinkOptions = {}): Promise<void> {
  if (existing && agent) {
  printExistingStatus(existing, normalizedRemote);
  if (!targetsDifferentApp) {
- outro();
+await outro();
  return;
  }
  } else if (existing) {
  const shouldRelink = await handleExistingProfile(existing, normalizedRemote, options);
  if (!shouldRelink) {
- outro();
+await outro();
  return;
  }
  }

packages/cli-core/src/commands/open/index.ts

@@ -102,7 +102,7 @@ export async function openDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 /**
@@ -196,7 +196,7 @@ async function openKeylessDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 export function registerOpen(program: Program): void {

packages/cli-core/src/commands/switch-env/index.ts

@@ -48,12 +48,12 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  } else if (available.length <= 1) {
  log.info(`Current environment: ${current}`);
  log.info("Only one environment configured — nothing to switch to.");
- outro();
+await outro();
  return;
  } else {
  log.info(`Current environment: ${current}`);
  log.info(`Available environments: ${available.join(", ")}`);
- outro();
+await outro();
  return;
  }
  }
@@ -68,7 +68,7 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
 
  if (previousEnv === target) {
  log.data(`Already on ${target} environment.`);
- outro();
+await outro();
  return;
  }
 
@@ -81,10 +81,10 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  const token = await getToken();
  if (!token) {
  log.data(`No credentials found for ${target}.`);
- outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
+await outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
  return;
  }
- outro(NEXT_STEPS.SWITCH_ENV);
+await outro(NEXT_STEPS.SWITCH_ENV);
 }
 
 export function registerSwitchEnv(program: Program): void {

packages/cli-core/src/commands/switch-env/update-notice-race.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Repro for the garbled "Update available" output reported in Slack: the
+ * next-steps outro animation parks the cursor on the header line for ~450ms,
+ * so anything printed after the command's promise resolves (the postAction
+ * update notice) must not run until the animation has finished. If the command
+ * resolves early, the notice lands mid-block and overwrites the step lines.
+ *
+ * Unlike index.test.ts this file deliberately uses the REAL spinner/gradient
+ * modules on a forced-interactive TTY so the animation actually runs.
+ */
+import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
+import { log } from "../../lib/log.ts";
+import { setMode } from "../../mode.ts";
+import { useCaptureLog, configStubs, credentialStoreStubs } from "../../test/lib/stubs.ts";
+
+const MOCK_ENVS = ["production", "staging"];
+let mockCurrentEnv = "production";
+
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+}));
+
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: async () => "some-token",
+}));
+
+mock.module("../../lib/environment.ts", () => ({
+ getCurrentEnvName: () => mockCurrentEnv,
+ getAvailableEnvs: () => MOCK_ENVS,
+ isValidEnv: (name: string) => MOCK_ENVS.includes(name),
+ setCurrentEnv: (name: string) => {
+ mockCurrentEnv = name;
+ },
+}));
+
+const { switchEnv } = await import("./index.ts");
+
+const CURSOR_SHOW = "\x1b[?25h";
+const NOTICE = "⬆ Update available: 3.0.1 → 3.1.0";
+
+describe("switch-env update-notice race", () => {
+ const captured = useCaptureLog();
+ const ENV_KEYS = ["CI", "NO_COLOR", "FORCE_COLOR", "COLORTERM"] as const;
+ let savedTTY: boolean | undefined;
+ let savedEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ setMode("human"); // the runner has no TTY, but the bug only shows in human mode
+ mockCurrentEnv = "production";
+ savedTTY = process.stderr.isTTY;
+ savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+ Object.defineProperty(process.stderr, "isTTY", { value: true, configurable: true });
+ for (const k of ENV_KEYS) delete process.env[k];
+ process.env.COLORTERM = "truecolor";
+ });
+
+ afterEach(() => {
+ Object.defineProperty(process.stderr, "isTTY", { value: savedTTY, configurable: true });
+ for (const k of ENV_KEYS) {
+ if (savedEnv[k] == null) delete process.env[k];
+ else process.env[k] = savedEnv[k];
+ }
+ });
+
+ test("output printed after the command resolves lands below the finished animation", async () => {
+ await switchEnv("staging");
+ // The postAction hook prints the update notice as soon as the action's
+ // promise resolves — reproduce that exact ordering.
+ log.warn(NOTICE);
+ // On fixed code the animation completed before switchEnv() resolved, so
+ // this returns immediately; on a regression it waits (bounded) for the
+ // orphaned animation's trailing frames so the ordering assertion below
+ // fails with a precise message instead of a missing-cursor-restore -1.
+ const deadline = Date.now() + 2_000;
+ while (!captured.err.includes(CURSOR_SHOW) && Date.now() < deadline) {
+ await Bun.sleep(25);
+ }
+
+ const err = captured.err;
+ const cursorRestoredAt = err.lastIndexOf(CURSOR_SHOW);
+ const noticeAt = err.indexOf(NOTICE);
+ expect(cursorRestoredAt).toBeGreaterThanOrEqual(0);
+ expect(noticeAt).toBeGreaterThan(cursorRestoredAt);
+ }, 10_000);
+});

packages/cli-core/src/commands/unlink/index.ts

@@ -45,7 +45,7 @@ export async function unlink(options: UnlinkOptions = {}): Promise<void> {
 
  await removeProfile(existing.path);
  log.data(`\nUnlinked ${cyan(label)} from ${dim(displayPath)}`);
- outro(NEXT_STEPS.UNLINK);
+await outro(NEXT_STEPS.UNLINK);
 }
 
 export function registerUnlink(program: Program): void {

.changeset/slack-thread-fix-issue-bun-1-4-define.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Keep `--define CLI_VERSION` working when building with Bun 1.4.
+
+Bun 1.4 runs macros in a sealed transpiler context that `--define` globals no longer reach, so the version macro silently fell back to the checkout-derived dev version even when a release version was injected. The define check and dev classification now live in `version.ts` module scope, where define substitution still applies; the macro only derives the Git checkout fallback.

.changeset/slack-thread-fix-issue.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Stop the "Update available" notice from garbling the "Next steps" block.
+
+The next-steps outro animation moves the cursor back onto the header line for ~450ms, but several commands (`switch-env`, `auth logout`, `unlink`, `users create`, `apps create`, and others) did not await it. The command's promise resolved mid-animation, so the post-command update check printed its notice at the parked cursor position — overwriting the step lines and leaving a stray duplicate "Next steps" header. Every `outro(...)` call is now awaited, so output printed after a command lands below the finished block.

.claude/rules/versioning.md

@@ -16,10 +16,13 @@ import { CURRENT_VERSION, IS_DEV_BUILD } from "./version.ts";
  including CLI help, user-agent headers, and MCP client info.
 - Read `IS_DEV_BUILD` when behavior depends on whether the binary is a
  development build.
-- Keep checkout-derived version generation and dev classification in
- `version.macro.ts`; the compiled CLI must not execute Git or classify its
- version at runtime.
+- Keep checkout-derived version generation in `version.macro.ts`; the compiled
+ CLI must not execute Git at runtime.
+- Keep the `CLI_VERSION` define check and dev classification in `version.ts`
+ module scope, NOT in the macro: since Bun 1.4, macros run in a sealed
+ transpiler context that `--define` globals do not reach, while defines still
+ substitute identifiers in transpiled modules.
 
-The constants are evaluated while Bun transpiles or compiles the module, so
+The macro fallback is inlined while Bun transpiles or compiles the module, so
 release builds can use the injected `CLI_VERSION` while local builds retain
 their checkout metadata.

CLAUDE.md

@@ -60,4 +60,4 @@ These flags require Bun >= 1.3.13 — older versions silently ignore them and lo
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
 
-Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git or classifies the version at runtime. Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.
+Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.

packages/cli-core/src/commands/api/index.ts

@@ -167,9 +167,9 @@ export async function api(
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/apps/create.ts

@@ -41,9 +41,9 @@ export async function create(name: string, options: AppsOptions = {}): Promise<v
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro(nextSteps);
+await outro(nextSteps);
  }
  }
  }

packages/cli-core/src/commands/apps/list.ts

@@ -60,9 +60,9 @@ export async function list(options: AppsOptions = {}): Promise<void> {
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/auth/login.ts

@@ -140,7 +140,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
  return existingSession;
  }
@@ -151,7 +151,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  default: false,
  });
  if (!reauthenticate) {
- outro();
+await outro();
  throwUserAbort();
  }
  }
@@ -188,7 +188,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
 
  return userInfo;

packages/cli-core/src/commands/auth/logout.ts

@@ -26,5 +26,5 @@ export async function logout(): Promise<void> {
  );
  }
 
- outro(NEXT_STEPS.LOGOUT);
+await outro(NEXT_STEPS.LOGOUT);
 }

packages/cli-core/src/commands/config/push.ts

@@ -137,9 +137,9 @@ async function configPush(options: ConfigPushOptions, op: Operation): Promise<vo
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/deploy/index.ts

@@ -92,7 +92,7 @@ export async function deploy(_options: DeployOptions = {}) {
  throw error;
  }
  if (error instanceof DeployPausedError && isInsideGutter()) {
- outro("Paused");
+await outro("Paused");
  }
  if (error instanceof UserAbortError && isInsideGutter()) {
  pausedOutro(pausedOperationNotice());
@@ -103,7 +103,7 @@ export async function deploy(_options: DeployOptions = {}) {
  // Successful and paused paths call outro themselves. This balances the
  // intro gutter if an unexpected error escapes.
  if (isInsideGutter()) {
- outro("Failed");
+await outro("Failed");
  }
  }
 }
@@ -154,7 +154,7 @@ async function startNewDeploy(ctx: DeployContext): Promise<void> {
  const proceed = await confirmProceed();
  if (!proceed) {
  log.info("No changes were made.");
- outro("Cancelled");
+await outro("Cancelled");
  return;
  }
 
@@ -233,7 +233,7 @@ async function reconcileExistingDeploy(ctx: DeployContext): Promise<void> {
  log.blank();
  log.info("A production instance exists, but Clerk did not return a production domain yet.");
  log.info("Run `clerk deploy` again after the domain is available from the API.");
- outro("No deploy actions available");
+await outro("No deploy actions available");
  return;
  }
 
@@ -361,7 +361,7 @@ async function confirmProductionInstanceCreation(domain: string): Promise<boolea
 
  log.blank();
  log.info("No production instance was created.");
- outro("Cancelled");
+await outro("Cancelled");
  return false;
 }
 
@@ -639,7 +639,7 @@ async function finishDeploy(
  fallback: bold,
  body: `${applyPrefix(nextStepsBody(ctx.appId, productionInstanceId))}\n`,
  });
- outro("Success");
+await outro("Success");
 }
 
 export function registerDeploy(program: Program): void {

packages/cli-core/src/commands/doctor/index.ts

@@ -128,7 +128,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
  return;
  }
  }
@@ -139,7 +139,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
 }
 
 export function registerDoctor(program: Program): void {

packages/cli-core/src/commands/init/index.ts

@@ -160,7 +160,7 @@ export async function init(options: InitOptions = {}) {
  if (agent && strategy === "manual") {
  printBootstrapManualSetupInfo(ctx.framework);
  }
- outro("Done");
+await outro("Done");
  return;
  }
 
@@ -183,7 +183,7 @@ export async function init(options: InitOptions = {}) {
  printBootstrapNextSteps(bootstrap, strategy === "keyless");
  }
 
- outro("Done");
+await outro("Done");
 }
 
 /**

packages/cli-core/src/commands/link/index.ts

@@ -61,13 +61,13 @@ export async function link(options: LinkOptions = {}): Promise<void> {
  if (existing && agent) {
  printExistingStatus(existing, normalizedRemote);
  if (!targetsDifferentApp) {
- outro();
+await outro();
  return;
  }
  } else if (existing) {
  const shouldRelink = await handleExistingProfile(existing, normalizedRemote, options);
  if (!shouldRelink) {
- outro();
+await outro();
  return;
  }
  }

packages/cli-core/src/commands/open/index.ts

@@ -102,7 +102,7 @@ export async function openDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 /**
@@ -196,7 +196,7 @@ async function openKeylessDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 export function registerOpen(program: Program): void {

packages/cli-core/src/commands/switch-env/index.ts

@@ -48,12 +48,12 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  } else if (available.length <= 1) {
  log.info(`Current environment: ${current}`);
  log.info("Only one environment configured — nothing to switch to.");
- outro();
+await outro();
  return;
  } else {
  log.info(`Current environment: ${current}`);
  log.info(`Available environments: ${available.join(", ")}`);
- outro();
+await outro();
  return;
  }
  }
@@ -68,7 +68,7 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
 
  if (previousEnv === target) {
  log.data(`Already on ${target} environment.`);
- outro();
+await outro();
  return;
  }
 
@@ -81,10 +81,10 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  const token = await getToken();
  if (!token) {
  log.data(`No credentials found for ${target}.`);
- outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
+await outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
  return;
  }
- outro(NEXT_STEPS.SWITCH_ENV);
+await outro(NEXT_STEPS.SWITCH_ENV);
 }
 
 export function registerSwitchEnv(program: Program): void {

packages/cli-core/src/commands/switch-env/update-notice-race.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Repro for the garbled "Update available" output reported in Slack: the
+ * next-steps outro animation parks the cursor on the header line for ~450ms,
+ * so anything printed after the command's promise resolves (the postAction
+ * update notice) must not run until the animation has finished. If the command
+ * resolves early, the notice lands mid-block and overwrites the step lines.
+ *
+ * Unlike index.test.ts this file deliberately uses the REAL spinner/gradient
+ * modules on a forced-interactive TTY so the animation actually runs.
+ */
+import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
+import { log } from "../../lib/log.ts";
+import { setMode } from "../../mode.ts";
+import { useCaptureLog, configStubs, credentialStoreStubs } from "../../test/lib/stubs.ts";
+
+const MOCK_ENVS = ["production", "staging"];
+let mockCurrentEnv = "production";
+
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+}));
+
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: async () => "some-token",
+}));
+
+mock.module("../../lib/environment.ts", () => ({
+ getCurrentEnvName: () => mockCurrentEnv,
+ getAvailableEnvs: () => MOCK_ENVS,
+ isValidEnv: (name: string) => MOCK_ENVS.includes(name),
+ setCurrentEnv: (name: string) => {
+ mockCurrentEnv = name;
+ },
+}));
+
+const { switchEnv } = await import("./index.ts");
+
+const CURSOR_SHOW = "\x1b[?25h";
+const NOTICE = "⬆ Update available: 3.0.1 → 3.1.0";
+
+describe("switch-env update-notice race", () => {
+ const captured = useCaptureLog();
+ const ENV_KEYS = ["CI", "NO_COLOR", "FORCE_COLOR", "COLORTERM"] as const;
+ let savedTTY: boolean | undefined;
+ let savedEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ setMode("human"); // the runner has no TTY, but the bug only shows in human mode
+ mockCurrentEnv = "production";
+ savedTTY = process.stderr.isTTY;
+ savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+ Object.defineProperty(process.stderr, "isTTY", { value: true, configurable: true });
+ for (const k of ENV_KEYS) delete process.env[k];
+ process.env.COLORTERM = "truecolor";
+ });
+
+ afterEach(() => {
+ Object.defineProperty(process.stderr, "isTTY", { value: savedTTY, configurable: true });
+ for (const k of ENV_KEYS) {
+ if (savedEnv[k] == null) delete process.env[k];
+ else process.env[k] = savedEnv[k];
+ }
+ });
+
+ test("output printed after the command resolves lands below the finished animation", async () => {
+ await switchEnv("staging");
+ // The postAction hook prints the update notice as soon as the action's
+ // promise resolves — reproduce that exact ordering.
+ log.warn(NOTICE);
+ // On fixed code the animation completed before switchEnv() resolved, so
+ // this returns immediately; on a regression it waits (bounded) for the
+ // orphaned animation's trailing frames so the ordering assertion below
+ // fails with a precise message instead of a missing-cursor-restore -1.
+ const deadline = Date.now() + 2_000;
+ while (!captured.err.includes(CURSOR_SHOW) && Date.now() < deadline) {
+ await Bun.sleep(25);
+ }
+
+ const err = captured.err;
+ const cursorRestoredAt = err.lastIndexOf(CURSOR_SHOW);
+ const noticeAt = err.indexOf(NOTICE);
+ expect(cursorRestoredAt).toBeGreaterThanOrEqual(0);
+ expect(noticeAt).toBeGreaterThan(cursorRestoredAt);
+ }, 10_000);
+});

packages/cli-core/src/commands/unlink/index.ts

@@ -45,7 +45,7 @@ export async function unlink(options: UnlinkOptions = {}): Promise<void> {
 
  await removeProfile(existing.path);
  log.data(`\nUnlinked ${cyan(label)} from ${dim(displayPath)}`);
- outro(NEXT_STEPS.UNLINK);
+await outro(NEXT_STEPS.UNLINK);
 }
 
 export function registerUnlink(program: Program): void {

.changeset/slack-thread-fix-issue-bun-1-4-define.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Keep `--define CLI_VERSION` working when building with Bun 1.4.
+
+Bun 1.4 runs macros in a sealed transpiler context that `--define` globals no longer reach, so the version macro silently fell back to the checkout-derived dev version even when a release version was injected. The define check and dev classification now live in `version.ts` module scope, where define substitution still applies; the macro only derives the Git checkout fallback.

.changeset/slack-thread-fix-issue.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Stop the "Update available" notice from garbling the "Next steps" block.
+
+The next-steps outro animation moves the cursor back onto the header line for ~450ms, but several commands (`switch-env`, `auth logout`, `unlink`, `users create`, `apps create`, and others) did not await it. The command's promise resolved mid-animation, so the post-command update check printed its notice at the parked cursor position — overwriting the step lines and leaving a stray duplicate "Next steps" header. Every `outro(...)` call is now awaited, so output printed after a command lands below the finished block.

.claude/rules/versioning.md

@@ -16,10 +16,13 @@ import { CURRENT_VERSION, IS_DEV_BUILD } from "./version.ts";
  including CLI help, user-agent headers, and MCP client info.
 - Read `IS_DEV_BUILD` when behavior depends on whether the binary is a
  development build.
-- Keep checkout-derived version generation and dev classification in
- `version.macro.ts`; the compiled CLI must not execute Git or classify its
- version at runtime.
+- Keep checkout-derived version generation in `version.macro.ts`; the compiled
+ CLI must not execute Git at runtime.
+- Keep the `CLI_VERSION` define check and dev classification in `version.ts`
+ module scope, NOT in the macro: since Bun 1.4, macros run in a sealed
+ transpiler context that `--define` globals do not reach, while defines still
+ substitute identifiers in transpiled modules.
 
-The constants are evaluated while Bun transpiles or compiles the module, so
+The macro fallback is inlined while Bun transpiles or compiles the module, so
 release builds can use the injected `CLI_VERSION` while local builds retain
 their checkout metadata.

CLAUDE.md

@@ -60,4 +60,4 @@ These flags require Bun >= 1.3.13 — older versions silently ignore them and lo
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
 
-Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git or classifies the version at runtime. Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.
+Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.

packages/cli-core/src/commands/api/index.ts

@@ -167,9 +167,9 @@ export async function api(
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/apps/create.ts

@@ -41,9 +41,9 @@ export async function create(name: string, options: AppsOptions = {}): Promise<v
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro(nextSteps);
+await outro(nextSteps);
  }
  }
  }

packages/cli-core/src/commands/apps/list.ts

@@ -60,9 +60,9 @@ export async function list(options: AppsOptions = {}): Promise<void> {
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/auth/login.ts

@@ -140,7 +140,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
  return existingSession;
  }
@@ -151,7 +151,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  default: false,
  });
  if (!reauthenticate) {
- outro();
+await outro();
  throwUserAbort();
  }
  }
@@ -188,7 +188,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
 
  return userInfo;

packages/cli-core/src/commands/auth/logout.ts

@@ -26,5 +26,5 @@ export async function logout(): Promise<void> {
  );
  }
 
- outro(NEXT_STEPS.LOGOUT);
+await outro(NEXT_STEPS.LOGOUT);
 }

packages/cli-core/src/commands/config/push.ts

@@ -137,9 +137,9 @@ async function configPush(options: ConfigPushOptions, op: Operation): Promise<vo
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/deploy/index.ts

@@ -92,7 +92,7 @@ export async function deploy(_options: DeployOptions = {}) {
  throw error;
  }
  if (error instanceof DeployPausedError && isInsideGutter()) {
- outro("Paused");
+await outro("Paused");
  }
  if (error instanceof UserAbortError && isInsideGutter()) {
  pausedOutro(pausedOperationNotice());
@@ -103,7 +103,7 @@ export async function deploy(_options: DeployOptions = {}) {
  // Successful and paused paths call outro themselves. This balances the
  // intro gutter if an unexpected error escapes.
  if (isInsideGutter()) {
- outro("Failed");
+await outro("Failed");
  }
  }
 }
@@ -154,7 +154,7 @@ async function startNewDeploy(ctx: DeployContext): Promise<void> {
  const proceed = await confirmProceed();
  if (!proceed) {
  log.info("No changes were made.");
- outro("Cancelled");
+await outro("Cancelled");
  return;
  }
 
@@ -233,7 +233,7 @@ async function reconcileExistingDeploy(ctx: DeployContext): Promise<void> {
  log.blank();
  log.info("A production instance exists, but Clerk did not return a production domain yet.");
  log.info("Run `clerk deploy` again after the domain is available from the API.");
- outro("No deploy actions available");
+await outro("No deploy actions available");
  return;
  }
 
@@ -361,7 +361,7 @@ async function confirmProductionInstanceCreation(domain: string): Promise<boolea
 
  log.blank();
  log.info("No production instance was created.");
- outro("Cancelled");
+await outro("Cancelled");
  return false;
 }
 
@@ -639,7 +639,7 @@ async function finishDeploy(
  fallback: bold,
  body: `${applyPrefix(nextStepsBody(ctx.appId, productionInstanceId))}\n`,
  });
- outro("Success");
+await outro("Success");
 }
 
 export function registerDeploy(program: Program): void {

packages/cli-core/src/commands/doctor/index.ts

@@ -128,7 +128,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
  return;
  }
  }
@@ -139,7 +139,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
 }
 
 export function registerDoctor(program: Program): void {

packages/cli-core/src/commands/init/index.ts

@@ -160,7 +160,7 @@ export async function init(options: InitOptions = {}) {
  if (agent && strategy === "manual") {
  printBootstrapManualSetupInfo(ctx.framework);
  }
- outro("Done");
+await outro("Done");
  return;
  }
 
@@ -183,7 +183,7 @@ export async function init(options: InitOptions = {}) {
  printBootstrapNextSteps(bootstrap, strategy === "keyless");
  }
 
- outro("Done");
+await outro("Done");
 }
 
 /**

packages/cli-core/src/commands/link/index.ts

@@ -61,13 +61,13 @@ export async function link(options: LinkOptions = {}): Promise<void> {
  if (existing && agent) {
  printExistingStatus(existing, normalizedRemote);
  if (!targetsDifferentApp) {
- outro();
+await outro();
  return;
  }
  } else if (existing) {
  const shouldRelink = await handleExistingProfile(existing, normalizedRemote, options);
  if (!shouldRelink) {
- outro();
+await outro();
  return;
  }
  }

packages/cli-core/src/commands/open/index.ts

@@ -102,7 +102,7 @@ export async function openDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 /**
@@ -196,7 +196,7 @@ async function openKeylessDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 export function registerOpen(program: Program): void {

packages/cli-core/src/commands/switch-env/index.ts

@@ -48,12 +48,12 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  } else if (available.length <= 1) {
  log.info(`Current environment: ${current}`);
  log.info("Only one environment configured — nothing to switch to.");
- outro();
+await outro();
  return;
  } else {
  log.info(`Current environment: ${current}`);
  log.info(`Available environments: ${available.join(", ")}`);
- outro();
+await outro();
  return;
  }
  }
@@ -68,7 +68,7 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
 
  if (previousEnv === target) {
  log.data(`Already on ${target} environment.`);
- outro();
+await outro();
  return;
  }
 
@@ -81,10 +81,10 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  const token = await getToken();
  if (!token) {
  log.data(`No credentials found for ${target}.`);
- outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
+await outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
  return;
  }
- outro(NEXT_STEPS.SWITCH_ENV);
+await outro(NEXT_STEPS.SWITCH_ENV);
 }
 
 export function registerSwitchEnv(program: Program): void {

packages/cli-core/src/commands/switch-env/update-notice-race.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Repro for the garbled "Update available" output reported in Slack: the
+ * next-steps outro animation parks the cursor on the header line for ~450ms,
+ * so anything printed after the command's promise resolves (the postAction
+ * update notice) must not run until the animation has finished. If the command
+ * resolves early, the notice lands mid-block and overwrites the step lines.
+ *
+ * Unlike index.test.ts this file deliberately uses the REAL spinner/gradient
+ * modules on a forced-interactive TTY so the animation actually runs.
+ */
+import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
+import { log } from "../../lib/log.ts";
+import { setMode } from "../../mode.ts";
+import { useCaptureLog, configStubs, credentialStoreStubs } from "../../test/lib/stubs.ts";
+
+const MOCK_ENVS = ["production", "staging"];
+let mockCurrentEnv = "production";
+
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+}));
+
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: async () => "some-token",
+}));
+
+mock.module("../../lib/environment.ts", () => ({
+ getCurrentEnvName: () => mockCurrentEnv,
+ getAvailableEnvs: () => MOCK_ENVS,
+ isValidEnv: (name: string) => MOCK_ENVS.includes(name),
+ setCurrentEnv: (name: string) => {
+ mockCurrentEnv = name;
+ },
+}));
+
+const { switchEnv } = await import("./index.ts");
+
+const CURSOR_SHOW = "\x1b[?25h";
+const NOTICE = "⬆ Update available: 3.0.1 → 3.1.0";
+
+describe("switch-env update-notice race", () => {
+ const captured = useCaptureLog();
+ const ENV_KEYS = ["CI", "NO_COLOR", "FORCE_COLOR", "COLORTERM"] as const;
+ let savedTTY: boolean | undefined;
+ let savedEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ setMode("human"); // the runner has no TTY, but the bug only shows in human mode
+ mockCurrentEnv = "production";
+ savedTTY = process.stderr.isTTY;
+ savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+ Object.defineProperty(process.stderr, "isTTY", { value: true, configurable: true });
+ for (const k of ENV_KEYS) delete process.env[k];
+ process.env.COLORTERM = "truecolor";
+ });
+
+ afterEach(() => {
+ Object.defineProperty(process.stderr, "isTTY", { value: savedTTY, configurable: true });
+ for (const k of ENV_KEYS) {
+ if (savedEnv[k] == null) delete process.env[k];
+ else process.env[k] = savedEnv[k];
+ }
+ });
+
+ test("output printed after the command resolves lands below the finished animation", async () => {
+ await switchEnv("staging");
+ // The postAction hook prints the update notice as soon as the action's
+ // promise resolves — reproduce that exact ordering.
+ log.warn(NOTICE);
+ // On fixed code the animation completed before switchEnv() resolved, so
+ // this returns immediately; on a regression it waits (bounded) for the
+ // orphaned animation's trailing frames so the ordering assertion below
+ // fails with a precise message instead of a missing-cursor-restore -1.
+ const deadline = Date.now() + 2_000;
+ while (!captured.err.includes(CURSOR_SHOW) && Date.now() < deadline) {
+ await Bun.sleep(25);
+ }
+
+ const err = captured.err;
+ const cursorRestoredAt = err.lastIndexOf(CURSOR_SHOW);
+ const noticeAt = err.indexOf(NOTICE);
+ expect(cursorRestoredAt).toBeGreaterThanOrEqual(0);
+ expect(noticeAt).toBeGreaterThan(cursorRestoredAt);
+ }, 10_000);
+});

packages/cli-core/src/commands/unlink/index.ts

@@ -45,7 +45,7 @@ export async function unlink(options: UnlinkOptions = {}): Promise<void> {
 
  await removeProfile(existing.path);
  log.data(`\nUnlinked ${cyan(label)} from ${dim(displayPath)}`);
- outro(NEXT_STEPS.UNLINK);
+await outro(NEXT_STEPS.UNLINK);
 }
 
 export function registerUnlink(program: Program): void {

.changeset/slack-thread-fix-issue-bun-1-4-define.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Keep `--define CLI_VERSION` working when building with Bun 1.4.
+
+Bun 1.4 runs macros in a sealed transpiler context that `--define` globals no longer reach, so the version macro silently fell back to the checkout-derived dev version even when a release version was injected. The define check and dev classification now live in `version.ts` module scope, where define substitution still applies; the macro only derives the Git checkout fallback.

.changeset/slack-thread-fix-issue.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Stop the "Update available" notice from garbling the "Next steps" block.
+
+The next-steps outro animation moves the cursor back onto the header line for ~450ms, but several commands (`switch-env`, `auth logout`, `unlink`, `users create`, `apps create`, and others) did not await it. The command's promise resolved mid-animation, so the post-command update check printed its notice at the parked cursor position — overwriting the step lines and leaving a stray duplicate "Next steps" header. Every `outro(...)` call is now awaited, so output printed after a command lands below the finished block.

.claude/rules/versioning.md

@@ -16,10 +16,13 @@ import { CURRENT_VERSION, IS_DEV_BUILD } from "./version.ts";
  including CLI help, user-agent headers, and MCP client info.
 - Read `IS_DEV_BUILD` when behavior depends on whether the binary is a
  development build.
-- Keep checkout-derived version generation and dev classification in
- `version.macro.ts`; the compiled CLI must not execute Git or classify its
- version at runtime.
+- Keep checkout-derived version generation in `version.macro.ts`; the compiled
+ CLI must not execute Git at runtime.
+- Keep the `CLI_VERSION` define check and dev classification in `version.ts`
+ module scope, NOT in the macro: since Bun 1.4, macros run in a sealed
+ transpiler context that `--define` globals do not reach, while defines still
+ substitute identifiers in transpiled modules.
 
-The constants are evaluated while Bun transpiles or compiles the module, so
+The macro fallback is inlined while Bun transpiles or compiles the module, so
 release builds can use the injected `CLI_VERSION` while local builds retain
 their checkout metadata.

CLAUDE.md

@@ -60,4 +60,4 @@ These flags require Bun >= 1.3.13 — older versions silently ignore them and lo
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
 
-Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git or classifies the version at runtime. Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.
+Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.

packages/cli-core/src/commands/api/index.ts

@@ -167,9 +167,9 @@ export async function api(
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/apps/create.ts

@@ -41,9 +41,9 @@ export async function create(name: string, options: AppsOptions = {}): Promise<v
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro(nextSteps);
+await outro(nextSteps);
  }
  }
  }

packages/cli-core/src/commands/apps/list.ts

@@ -60,9 +60,9 @@ export async function list(options: AppsOptions = {}): Promise<void> {
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/auth/login.ts

@@ -140,7 +140,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
  return existingSession;
  }
@@ -151,7 +151,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  default: false,
  });
  if (!reauthenticate) {
- outro();
+await outro();
  throwUserAbort();
  }
  }
@@ -188,7 +188,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
 
  return userInfo;

packages/cli-core/src/commands/auth/logout.ts

@@ -26,5 +26,5 @@ export async function logout(): Promise<void> {
  );
  }
 
- outro(NEXT_STEPS.LOGOUT);
+await outro(NEXT_STEPS.LOGOUT);
 }

packages/cli-core/src/commands/config/push.ts

@@ -137,9 +137,9 @@ async function configPush(options: ConfigPushOptions, op: Operation): Promise<vo
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/deploy/index.ts

@@ -92,7 +92,7 @@ export async function deploy(_options: DeployOptions = {}) {
  throw error;
  }
  if (error instanceof DeployPausedError && isInsideGutter()) {
- outro("Paused");
+await outro("Paused");
  }
  if (error instanceof UserAbortError && isInsideGutter()) {
  pausedOutro(pausedOperationNotice());
@@ -103,7 +103,7 @@ export async function deploy(_options: DeployOptions = {}) {
  // Successful and paused paths call outro themselves. This balances the
  // intro gutter if an unexpected error escapes.
  if (isInsideGutter()) {
- outro("Failed");
+await outro("Failed");
  }
  }
 }
@@ -154,7 +154,7 @@ async function startNewDeploy(ctx: DeployContext): Promise<void> {
  const proceed = await confirmProceed();
  if (!proceed) {
  log.info("No changes were made.");
- outro("Cancelled");
+await outro("Cancelled");
  return;
  }
 
@@ -233,7 +233,7 @@ async function reconcileExistingDeploy(ctx: DeployContext): Promise<void> {
  log.blank();
  log.info("A production instance exists, but Clerk did not return a production domain yet.");
  log.info("Run `clerk deploy` again after the domain is available from the API.");
- outro("No deploy actions available");
+await outro("No deploy actions available");
  return;
  }
 
@@ -361,7 +361,7 @@ async function confirmProductionInstanceCreation(domain: string): Promise<boolea
 
  log.blank();
  log.info("No production instance was created.");
- outro("Cancelled");
+await outro("Cancelled");
  return false;
 }
 
@@ -639,7 +639,7 @@ async function finishDeploy(
  fallback: bold,
  body: `${applyPrefix(nextStepsBody(ctx.appId, productionInstanceId))}\n`,
  });
- outro("Success");
+await outro("Success");
 }
 
 export function registerDeploy(program: Program): void {

packages/cli-core/src/commands/doctor/index.ts

@@ -128,7 +128,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
  return;
  }
  }
@@ -139,7 +139,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
 }
 
 export function registerDoctor(program: Program): void {

packages/cli-core/src/commands/init/index.ts

@@ -160,7 +160,7 @@ export async function init(options: InitOptions = {}) {
  if (agent && strategy === "manual") {
  printBootstrapManualSetupInfo(ctx.framework);
  }
- outro("Done");
+await outro("Done");
  return;
  }
 
@@ -183,7 +183,7 @@ export async function init(options: InitOptions = {}) {
  printBootstrapNextSteps(bootstrap, strategy === "keyless");
  }
 
- outro("Done");
+await outro("Done");
 }
 
 /**

packages/cli-core/src/commands/link/index.ts

@@ -61,13 +61,13 @@ export async function link(options: LinkOptions = {}): Promise<void> {
  if (existing && agent) {
  printExistingStatus(existing, normalizedRemote);
  if (!targetsDifferentApp) {
- outro();
+await outro();
  return;
  }
  } else if (existing) {
  const shouldRelink = await handleExistingProfile(existing, normalizedRemote, options);
  if (!shouldRelink) {
- outro();
+await outro();
  return;
  }
  }

packages/cli-core/src/commands/open/index.ts

@@ -102,7 +102,7 @@ export async function openDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 /**
@@ -196,7 +196,7 @@ async function openKeylessDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 export function registerOpen(program: Program): void {

packages/cli-core/src/commands/switch-env/index.ts

@@ -48,12 +48,12 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  } else if (available.length <= 1) {
  log.info(`Current environment: ${current}`);
  log.info("Only one environment configured — nothing to switch to.");
- outro();
+await outro();
  return;
  } else {
  log.info(`Current environment: ${current}`);
  log.info(`Available environments: ${available.join(", ")}`);
- outro();
+await outro();
  return;
  }
  }
@@ -68,7 +68,7 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
 
  if (previousEnv === target) {
  log.data(`Already on ${target} environment.`);
- outro();
+await outro();
  return;
  }
 
@@ -81,10 +81,10 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  const token = await getToken();
  if (!token) {
  log.data(`No credentials found for ${target}.`);
- outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
+await outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
  return;
  }
- outro(NEXT_STEPS.SWITCH_ENV);
+await outro(NEXT_STEPS.SWITCH_ENV);
 }
 
 export function registerSwitchEnv(program: Program): void {

packages/cli-core/src/commands/switch-env/update-notice-race.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Repro for the garbled "Update available" output reported in Slack: the
+ * next-steps outro animation parks the cursor on the header line for ~450ms,
+ * so anything printed after the command's promise resolves (the postAction
+ * update notice) must not run until the animation has finished. If the command
+ * resolves early, the notice lands mid-block and overwrites the step lines.
+ *
+ * Unlike index.test.ts this file deliberately uses the REAL spinner/gradient
+ * modules on a forced-interactive TTY so the animation actually runs.
+ */
+import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
+import { log } from "../../lib/log.ts";
+import { setMode } from "../../mode.ts";
+import { useCaptureLog, configStubs, credentialStoreStubs } from "../../test/lib/stubs.ts";
+
+const MOCK_ENVS = ["production", "staging"];
+let mockCurrentEnv = "production";
+
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+}));
+
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: async () => "some-token",
+}));
+
+mock.module("../../lib/environment.ts", () => ({
+ getCurrentEnvName: () => mockCurrentEnv,
+ getAvailableEnvs: () => MOCK_ENVS,
+ isValidEnv: (name: string) => MOCK_ENVS.includes(name),
+ setCurrentEnv: (name: string) => {
+ mockCurrentEnv = name;
+ },
+}));
+
+const { switchEnv } = await import("./index.ts");
+
+const CURSOR_SHOW = "\x1b[?25h";
+const NOTICE = "⬆ Update available: 3.0.1 → 3.1.0";
+
+describe("switch-env update-notice race", () => {
+ const captured = useCaptureLog();
+ const ENV_KEYS = ["CI", "NO_COLOR", "FORCE_COLOR", "COLORTERM"] as const;
+ let savedTTY: boolean | undefined;
+ let savedEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ setMode("human"); // the runner has no TTY, but the bug only shows in human mode
+ mockCurrentEnv = "production";
+ savedTTY = process.stderr.isTTY;
+ savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+ Object.defineProperty(process.stderr, "isTTY", { value: true, configurable: true });
+ for (const k of ENV_KEYS) delete process.env[k];
+ process.env.COLORTERM = "truecolor";
+ });
+
+ afterEach(() => {
+ Object.defineProperty(process.stderr, "isTTY", { value: savedTTY, configurable: true });
+ for (const k of ENV_KEYS) {
+ if (savedEnv[k] == null) delete process.env[k];
+ else process.env[k] = savedEnv[k];
+ }
+ });
+
+ test("output printed after the command resolves lands below the finished animation", async () => {
+ await switchEnv("staging");
+ // The postAction hook prints the update notice as soon as the action's
+ // promise resolves — reproduce that exact ordering.
+ log.warn(NOTICE);
+ // On fixed code the animation completed before switchEnv() resolved, so
+ // this returns immediately; on a regression it waits (bounded) for the
+ // orphaned animation's trailing frames so the ordering assertion below
+ // fails with a precise message instead of a missing-cursor-restore -1.
+ const deadline = Date.now() + 2_000;
+ while (!captured.err.includes(CURSOR_SHOW) && Date.now() < deadline) {
+ await Bun.sleep(25);
+ }
+
+ const err = captured.err;
+ const cursorRestoredAt = err.lastIndexOf(CURSOR_SHOW);
+ const noticeAt = err.indexOf(NOTICE);
+ expect(cursorRestoredAt).toBeGreaterThanOrEqual(0);
+ expect(noticeAt).toBeGreaterThan(cursorRestoredAt);
+ }, 10_000);
+});

packages/cli-core/src/commands/unlink/index.ts

@@ -45,7 +45,7 @@ export async function unlink(options: UnlinkOptions = {}): Promise<void> {
 
  await removeProfile(existing.path);
  log.data(`\nUnlinked ${cyan(label)} from ${dim(displayPath)}`);
- outro(NEXT_STEPS.UNLINK);
+await outro(NEXT_STEPS.UNLINK);
 }
 
 export function registerUnlink(program: Program): void {

.changeset/slack-thread-fix-issue-bun-1-4-define.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Keep `--define CLI_VERSION` working when building with Bun 1.4.
+
+Bun 1.4 runs macros in a sealed transpiler context that `--define` globals no longer reach, so the version macro silently fell back to the checkout-derived dev version even when a release version was injected. The define check and dev classification now live in `version.ts` module scope, where define substitution still applies; the macro only derives the Git checkout fallback.

.changeset/slack-thread-fix-issue.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Stop the "Update available" notice from garbling the "Next steps" block.
+
+The next-steps outro animation moves the cursor back onto the header line for ~450ms, but several commands (`switch-env`, `auth logout`, `unlink`, `users create`, `apps create`, and others) did not await it. The command's promise resolved mid-animation, so the post-command update check printed its notice at the parked cursor position — overwriting the step lines and leaving a stray duplicate "Next steps" header. Every `outro(...)` call is now awaited, so output printed after a command lands below the finished block.

.claude/rules/versioning.md

@@ -16,10 +16,13 @@ import { CURRENT_VERSION, IS_DEV_BUILD } from "./version.ts";
  including CLI help, user-agent headers, and MCP client info.
 - Read `IS_DEV_BUILD` when behavior depends on whether the binary is a
  development build.
-- Keep checkout-derived version generation and dev classification in
- `version.macro.ts`; the compiled CLI must not execute Git or classify its
- version at runtime.
+- Keep checkout-derived version generation in `version.macro.ts`; the compiled
+ CLI must not execute Git at runtime.
+- Keep the `CLI_VERSION` define check and dev classification in `version.ts`
+ module scope, NOT in the macro: since Bun 1.4, macros run in a sealed
+ transpiler context that `--define` globals do not reach, while defines still
+ substitute identifiers in transpiled modules.
 
-The constants are evaluated while Bun transpiles or compiles the module, so
+The macro fallback is inlined while Bun transpiles or compiles the module, so
 release builds can use the injected `CLI_VERSION` while local builds retain
 their checkout metadata.

CLAUDE.md

@@ -60,4 +60,4 @@ These flags require Bun >= 1.3.13 — older versions silently ignore them and lo
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
 
-Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git or classifies the version at runtime. Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.
+Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.

packages/cli-core/src/commands/api/index.ts

@@ -167,9 +167,9 @@ export async function api(
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/apps/create.ts

@@ -41,9 +41,9 @@ export async function create(name: string, options: AppsOptions = {}): Promise<v
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro(nextSteps);
+await outro(nextSteps);
  }
  }
  }

packages/cli-core/src/commands/apps/list.ts

@@ -60,9 +60,9 @@ export async function list(options: AppsOptions = {}): Promise<void> {
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/auth/login.ts

@@ -140,7 +140,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
  return existingSession;
  }
@@ -151,7 +151,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  default: false,
  });
  if (!reauthenticate) {
- outro();
+await outro();
  throwUserAbort();
  }
  }
@@ -188,7 +188,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
 
  return userInfo;

packages/cli-core/src/commands/auth/logout.ts

@@ -26,5 +26,5 @@ export async function logout(): Promise<void> {
  );
  }
 
- outro(NEXT_STEPS.LOGOUT);
+await outro(NEXT_STEPS.LOGOUT);
 }

packages/cli-core/src/commands/config/push.ts

@@ -137,9 +137,9 @@ async function configPush(options: ConfigPushOptions, op: Operation): Promise<vo
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/deploy/index.ts

@@ -92,7 +92,7 @@ export async function deploy(_options: DeployOptions = {}) {
  throw error;
  }
  if (error instanceof DeployPausedError && isInsideGutter()) {
- outro("Paused");
+await outro("Paused");
  }
  if (error instanceof UserAbortError && isInsideGutter()) {
  pausedOutro(pausedOperationNotice());
@@ -103,7 +103,7 @@ export async function deploy(_options: DeployOptions = {}) {
  // Successful and paused paths call outro themselves. This balances the
  // intro gutter if an unexpected error escapes.
  if (isInsideGutter()) {
- outro("Failed");
+await outro("Failed");
  }
  }
 }
@@ -154,7 +154,7 @@ async function startNewDeploy(ctx: DeployContext): Promise<void> {
  const proceed = await confirmProceed();
  if (!proceed) {
  log.info("No changes were made.");
- outro("Cancelled");
+await outro("Cancelled");
  return;
  }
 
@@ -233,7 +233,7 @@ async function reconcileExistingDeploy(ctx: DeployContext): Promise<void> {
  log.blank();
  log.info("A production instance exists, but Clerk did not return a production domain yet.");
  log.info("Run `clerk deploy` again after the domain is available from the API.");
- outro("No deploy actions available");
+await outro("No deploy actions available");
  return;
  }
 
@@ -361,7 +361,7 @@ async function confirmProductionInstanceCreation(domain: string): Promise<boolea
 
  log.blank();
  log.info("No production instance was created.");
- outro("Cancelled");
+await outro("Cancelled");
  return false;
 }
 
@@ -639,7 +639,7 @@ async function finishDeploy(
  fallback: bold,
  body: `${applyPrefix(nextStepsBody(ctx.appId, productionInstanceId))}\n`,
  });
- outro("Success");
+await outro("Success");
 }
 
 export function registerDeploy(program: Program): void {

packages/cli-core/src/commands/doctor/index.ts

@@ -128,7 +128,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
  return;
  }
  }
@@ -139,7 +139,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
 }
 
 export function registerDoctor(program: Program): void {

packages/cli-core/src/commands/init/index.ts

@@ -160,7 +160,7 @@ export async function init(options: InitOptions = {}) {
  if (agent && strategy === "manual") {
  printBootstrapManualSetupInfo(ctx.framework);
  }
- outro("Done");
+await outro("Done");
  return;
  }
 
@@ -183,7 +183,7 @@ export async function init(options: InitOptions = {}) {
  printBootstrapNextSteps(bootstrap, strategy === "keyless");
  }
 
- outro("Done");
+await outro("Done");
 }
 
 /**

packages/cli-core/src/commands/link/index.ts

@@ -61,13 +61,13 @@ export async function link(options: LinkOptions = {}): Promise<void> {
  if (existing && agent) {
  printExistingStatus(existing, normalizedRemote);
  if (!targetsDifferentApp) {
- outro();
+await outro();
  return;
  }
  } else if (existing) {
  const shouldRelink = await handleExistingProfile(existing, normalizedRemote, options);
  if (!shouldRelink) {
- outro();
+await outro();
  return;
  }
  }

packages/cli-core/src/commands/open/index.ts

@@ -102,7 +102,7 @@ export async function openDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 /**
@@ -196,7 +196,7 @@ async function openKeylessDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 export function registerOpen(program: Program): void {

packages/cli-core/src/commands/switch-env/index.ts

@@ -48,12 +48,12 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  } else if (available.length <= 1) {
  log.info(`Current environment: ${current}`);
  log.info("Only one environment configured — nothing to switch to.");
- outro();
+await outro();
  return;
  } else {
  log.info(`Current environment: ${current}`);
  log.info(`Available environments: ${available.join(", ")}`);
- outro();
+await outro();
  return;
  }
  }
@@ -68,7 +68,7 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
 
  if (previousEnv === target) {
  log.data(`Already on ${target} environment.`);
- outro();
+await outro();
  return;
  }
 
@@ -81,10 +81,10 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  const token = await getToken();
  if (!token) {
  log.data(`No credentials found for ${target}.`);
- outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
+await outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
  return;
  }
- outro(NEXT_STEPS.SWITCH_ENV);
+await outro(NEXT_STEPS.SWITCH_ENV);
 }
 
 export function registerSwitchEnv(program: Program): void {

packages/cli-core/src/commands/switch-env/update-notice-race.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Repro for the garbled "Update available" output reported in Slack: the
+ * next-steps outro animation parks the cursor on the header line for ~450ms,
+ * so anything printed after the command's promise resolves (the postAction
+ * update notice) must not run until the animation has finished. If the command
+ * resolves early, the notice lands mid-block and overwrites the step lines.
+ *
+ * Unlike index.test.ts this file deliberately uses the REAL spinner/gradient
+ * modules on a forced-interactive TTY so the animation actually runs.
+ */
+import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
+import { log } from "../../lib/log.ts";
+import { setMode } from "../../mode.ts";
+import { useCaptureLog, configStubs, credentialStoreStubs } from "../../test/lib/stubs.ts";
+
+const MOCK_ENVS = ["production", "staging"];
+let mockCurrentEnv = "production";
+
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+}));
+
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: async () => "some-token",
+}));
+
+mock.module("../../lib/environment.ts", () => ({
+ getCurrentEnvName: () => mockCurrentEnv,
+ getAvailableEnvs: () => MOCK_ENVS,
+ isValidEnv: (name: string) => MOCK_ENVS.includes(name),
+ setCurrentEnv: (name: string) => {
+ mockCurrentEnv = name;
+ },
+}));
+
+const { switchEnv } = await import("./index.ts");
+
+const CURSOR_SHOW = "\x1b[?25h";
+const NOTICE = "⬆ Update available: 3.0.1 → 3.1.0";
+
+describe("switch-env update-notice race", () => {
+ const captured = useCaptureLog();
+ const ENV_KEYS = ["CI", "NO_COLOR", "FORCE_COLOR", "COLORTERM"] as const;
+ let savedTTY: boolean | undefined;
+ let savedEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ setMode("human"); // the runner has no TTY, but the bug only shows in human mode
+ mockCurrentEnv = "production";
+ savedTTY = process.stderr.isTTY;
+ savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+ Object.defineProperty(process.stderr, "isTTY", { value: true, configurable: true });
+ for (const k of ENV_KEYS) delete process.env[k];
+ process.env.COLORTERM = "truecolor";
+ });
+
+ afterEach(() => {
+ Object.defineProperty(process.stderr, "isTTY", { value: savedTTY, configurable: true });
+ for (const k of ENV_KEYS) {
+ if (savedEnv[k] == null) delete process.env[k];
+ else process.env[k] = savedEnv[k];
+ }
+ });
+
+ test("output printed after the command resolves lands below the finished animation", async () => {
+ await switchEnv("staging");
+ // The postAction hook prints the update notice as soon as the action's
+ // promise resolves — reproduce that exact ordering.
+ log.warn(NOTICE);
+ // On fixed code the animation completed before switchEnv() resolved, so
+ // this returns immediately; on a regression it waits (bounded) for the
+ // orphaned animation's trailing frames so the ordering assertion below
+ // fails with a precise message instead of a missing-cursor-restore -1.
+ const deadline = Date.now() + 2_000;
+ while (!captured.err.includes(CURSOR_SHOW) && Date.now() < deadline) {
+ await Bun.sleep(25);
+ }
+
+ const err = captured.err;
+ const cursorRestoredAt = err.lastIndexOf(CURSOR_SHOW);
+ const noticeAt = err.indexOf(NOTICE);
+ expect(cursorRestoredAt).toBeGreaterThanOrEqual(0);
+ expect(noticeAt).toBeGreaterThan(cursorRestoredAt);
+ }, 10_000);
+});

packages/cli-core/src/commands/unlink/index.ts

@@ -45,7 +45,7 @@ export async function unlink(options: UnlinkOptions = {}): Promise<void> {
 
  await removeProfile(existing.path);
  log.data(`\nUnlinked ${cyan(label)} from ${dim(displayPath)}`);
- outro(NEXT_STEPS.UNLINK);
+await outro(NEXT_STEPS.UNLINK);
 }
 
 export function registerUnlink(program: Program): void {

.changeset/slack-thread-fix-issue-bun-1-4-define.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Keep `--define CLI_VERSION` working when building with Bun 1.4.
+
+Bun 1.4 runs macros in a sealed transpiler context that `--define` globals no longer reach, so the version macro silently fell back to the checkout-derived dev version even when a release version was injected. The define check and dev classification now live in `version.ts` module scope, where define substitution still applies; the macro only derives the Git checkout fallback.

.changeset/slack-thread-fix-issue.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Stop the "Update available" notice from garbling the "Next steps" block.
+
+The next-steps outro animation moves the cursor back onto the header line for ~450ms, but several commands (`switch-env`, `auth logout`, `unlink`, `users create`, `apps create`, and others) did not await it. The command's promise resolved mid-animation, so the post-command update check printed its notice at the parked cursor position — overwriting the step lines and leaving a stray duplicate "Next steps" header. Every `outro(...)` call is now awaited, so output printed after a command lands below the finished block.

.claude/rules/versioning.md

@@ -16,10 +16,13 @@ import { CURRENT_VERSION, IS_DEV_BUILD } from "./version.ts";
  including CLI help, user-agent headers, and MCP client info.
 - Read `IS_DEV_BUILD` when behavior depends on whether the binary is a
  development build.
-- Keep checkout-derived version generation and dev classification in
- `version.macro.ts`; the compiled CLI must not execute Git or classify its
- version at runtime.
+- Keep checkout-derived version generation in `version.macro.ts`; the compiled
+ CLI must not execute Git at runtime.
+- Keep the `CLI_VERSION` define check and dev classification in `version.ts`
+ module scope, NOT in the macro: since Bun 1.4, macros run in a sealed
+ transpiler context that `--define` globals do not reach, while defines still
+ substitute identifiers in transpiled modules.
 
-The constants are evaluated while Bun transpiles or compiles the module, so
+The macro fallback is inlined while Bun transpiles or compiles the module, so
 release builds can use the injected `CLI_VERSION` while local builds retain
 their checkout metadata.

CLAUDE.md

@@ -60,4 +60,4 @@ These flags require Bun >= 1.3.13 — older versions silently ignore them and lo
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
 
-Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git or classifies the version at runtime. Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.
+Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.

packages/cli-core/src/commands/api/index.ts

@@ -167,9 +167,9 @@ export async function api(
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/apps/create.ts

@@ -41,9 +41,9 @@ export async function create(name: string, options: AppsOptions = {}): Promise<v
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro(nextSteps);
+await outro(nextSteps);
  }
  }
  }

packages/cli-core/src/commands/apps/list.ts

@@ -60,9 +60,9 @@ export async function list(options: AppsOptions = {}): Promise<void> {
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/auth/login.ts

@@ -140,7 +140,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
  return existingSession;
  }
@@ -151,7 +151,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  default: false,
  });
  if (!reauthenticate) {
- outro();
+await outro();
  throwUserAbort();
  }
  }
@@ -188,7 +188,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
 
  return userInfo;

packages/cli-core/src/commands/auth/logout.ts

@@ -26,5 +26,5 @@ export async function logout(): Promise<void> {
  );
  }
 
- outro(NEXT_STEPS.LOGOUT);
+await outro(NEXT_STEPS.LOGOUT);
 }

packages/cli-core/src/commands/config/push.ts

@@ -137,9 +137,9 @@ async function configPush(options: ConfigPushOptions, op: Operation): Promise<vo
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/deploy/index.ts

@@ -92,7 +92,7 @@ export async function deploy(_options: DeployOptions = {}) {
  throw error;
  }
  if (error instanceof DeployPausedError && isInsideGutter()) {
- outro("Paused");
+await outro("Paused");
  }
  if (error instanceof UserAbortError && isInsideGutter()) {
  pausedOutro(pausedOperationNotice());
@@ -103,7 +103,7 @@ export async function deploy(_options: DeployOptions = {}) {
  // Successful and paused paths call outro themselves. This balances the
  // intro gutter if an unexpected error escapes.
  if (isInsideGutter()) {
- outro("Failed");
+await outro("Failed");
  }
  }
 }
@@ -154,7 +154,7 @@ async function startNewDeploy(ctx: DeployContext): Promise<void> {
  const proceed = await confirmProceed();
  if (!proceed) {
  log.info("No changes were made.");
- outro("Cancelled");
+await outro("Cancelled");
  return;
  }
 
@@ -233,7 +233,7 @@ async function reconcileExistingDeploy(ctx: DeployContext): Promise<void> {
  log.blank();
  log.info("A production instance exists, but Clerk did not return a production domain yet.");
  log.info("Run `clerk deploy` again after the domain is available from the API.");
- outro("No deploy actions available");
+await outro("No deploy actions available");
  return;
  }
 
@@ -361,7 +361,7 @@ async function confirmProductionInstanceCreation(domain: string): Promise<boolea
 
  log.blank();
  log.info("No production instance was created.");
- outro("Cancelled");
+await outro("Cancelled");
  return false;
 }
 
@@ -639,7 +639,7 @@ async function finishDeploy(
  fallback: bold,
  body: `${applyPrefix(nextStepsBody(ctx.appId, productionInstanceId))}\n`,
  });
- outro("Success");
+await outro("Success");
 }
 
 export function registerDeploy(program: Program): void {

packages/cli-core/src/commands/doctor/index.ts

@@ -128,7 +128,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
  return;
  }
  }
@@ -139,7 +139,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
 }
 
 export function registerDoctor(program: Program): void {

packages/cli-core/src/commands/init/index.ts

@@ -160,7 +160,7 @@ export async function init(options: InitOptions = {}) {
  if (agent && strategy === "manual") {
  printBootstrapManualSetupInfo(ctx.framework);
  }
- outro("Done");
+await outro("Done");
  return;
  }
 
@@ -183,7 +183,7 @@ export async function init(options: InitOptions = {}) {
  printBootstrapNextSteps(bootstrap, strategy === "keyless");
  }
 
- outro("Done");
+await outro("Done");
 }
 
 /**

packages/cli-core/src/commands/link/index.ts

@@ -61,13 +61,13 @@ export async function link(options: LinkOptions = {}): Promise<void> {
  if (existing && agent) {
  printExistingStatus(existing, normalizedRemote);
  if (!targetsDifferentApp) {
- outro();
+await outro();
  return;
  }
  } else if (existing) {
  const shouldRelink = await handleExistingProfile(existing, normalizedRemote, options);
  if (!shouldRelink) {
- outro();
+await outro();
  return;
  }
  }

packages/cli-core/src/commands/open/index.ts

@@ -102,7 +102,7 @@ export async function openDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 /**
@@ -196,7 +196,7 @@ async function openKeylessDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 export function registerOpen(program: Program): void {

packages/cli-core/src/commands/switch-env/index.ts

@@ -48,12 +48,12 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  } else if (available.length <= 1) {
  log.info(`Current environment: ${current}`);
  log.info("Only one environment configured — nothing to switch to.");
- outro();
+await outro();
  return;
  } else {
  log.info(`Current environment: ${current}`);
  log.info(`Available environments: ${available.join(", ")}`);
- outro();
+await outro();
  return;
  }
  }
@@ -68,7 +68,7 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
 
  if (previousEnv === target) {
  log.data(`Already on ${target} environment.`);
- outro();
+await outro();
  return;
  }
 
@@ -81,10 +81,10 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  const token = await getToken();
  if (!token) {
  log.data(`No credentials found for ${target}.`);
- outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
+await outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
  return;
  }
- outro(NEXT_STEPS.SWITCH_ENV);
+await outro(NEXT_STEPS.SWITCH_ENV);
 }
 
 export function registerSwitchEnv(program: Program): void {

packages/cli-core/src/commands/switch-env/update-notice-race.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Repro for the garbled "Update available" output reported in Slack: the
+ * next-steps outro animation parks the cursor on the header line for ~450ms,
+ * so anything printed after the command's promise resolves (the postAction
+ * update notice) must not run until the animation has finished. If the command
+ * resolves early, the notice lands mid-block and overwrites the step lines.
+ *
+ * Unlike index.test.ts this file deliberately uses the REAL spinner/gradient
+ * modules on a forced-interactive TTY so the animation actually runs.
+ */
+import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
+import { log } from "../../lib/log.ts";
+import { setMode } from "../../mode.ts";
+import { useCaptureLog, configStubs, credentialStoreStubs } from "../../test/lib/stubs.ts";
+
+const MOCK_ENVS = ["production", "staging"];
+let mockCurrentEnv = "production";
+
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+}));
+
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: async () => "some-token",
+}));
+
+mock.module("../../lib/environment.ts", () => ({
+ getCurrentEnvName: () => mockCurrentEnv,
+ getAvailableEnvs: () => MOCK_ENVS,
+ isValidEnv: (name: string) => MOCK_ENVS.includes(name),
+ setCurrentEnv: (name: string) => {
+ mockCurrentEnv = name;
+ },
+}));
+
+const { switchEnv } = await import("./index.ts");
+
+const CURSOR_SHOW = "\x1b[?25h";
+const NOTICE = "⬆ Update available: 3.0.1 → 3.1.0";
+
+describe("switch-env update-notice race", () => {
+ const captured = useCaptureLog();
+ const ENV_KEYS = ["CI", "NO_COLOR", "FORCE_COLOR", "COLORTERM"] as const;
+ let savedTTY: boolean | undefined;
+ let savedEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ setMode("human"); // the runner has no TTY, but the bug only shows in human mode
+ mockCurrentEnv = "production";
+ savedTTY = process.stderr.isTTY;
+ savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+ Object.defineProperty(process.stderr, "isTTY", { value: true, configurable: true });
+ for (const k of ENV_KEYS) delete process.env[k];
+ process.env.COLORTERM = "truecolor";
+ });
+
+ afterEach(() => {
+ Object.defineProperty(process.stderr, "isTTY", { value: savedTTY, configurable: true });
+ for (const k of ENV_KEYS) {
+ if (savedEnv[k] == null) delete process.env[k];
+ else process.env[k] = savedEnv[k];
+ }
+ });
+
+ test("output printed after the command resolves lands below the finished animation", async () => {
+ await switchEnv("staging");
+ // The postAction hook prints the update notice as soon as the action's
+ // promise resolves — reproduce that exact ordering.
+ log.warn(NOTICE);
+ // On fixed code the animation completed before switchEnv() resolved, so
+ // this returns immediately; on a regression it waits (bounded) for the
+ // orphaned animation's trailing frames so the ordering assertion below
+ // fails with a precise message instead of a missing-cursor-restore -1.
+ const deadline = Date.now() + 2_000;
+ while (!captured.err.includes(CURSOR_SHOW) && Date.now() < deadline) {
+ await Bun.sleep(25);
+ }
+
+ const err = captured.err;
+ const cursorRestoredAt = err.lastIndexOf(CURSOR_SHOW);
+ const noticeAt = err.indexOf(NOTICE);
+ expect(cursorRestoredAt).toBeGreaterThanOrEqual(0);
+ expect(noticeAt).toBeGreaterThan(cursorRestoredAt);
+ }, 10_000);
+});

packages/cli-core/src/commands/unlink/index.ts

@@ -45,7 +45,7 @@ export async function unlink(options: UnlinkOptions = {}): Promise<void> {
 
  await removeProfile(existing.path);
  log.data(`\nUnlinked ${cyan(label)} from ${dim(displayPath)}`);
- outro(NEXT_STEPS.UNLINK);
+await outro(NEXT_STEPS.UNLINK);
 }
 
 export function registerUnlink(program: Program): void {

.changeset/slack-thread-fix-issue-bun-1-4-define.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Keep `--define CLI_VERSION` working when building with Bun 1.4.
+
+Bun 1.4 runs macros in a sealed transpiler context that `--define` globals no longer reach, so the version macro silently fell back to the checkout-derived dev version even when a release version was injected. The define check and dev classification now live in `version.ts` module scope, where define substitution still applies; the macro only derives the Git checkout fallback.

.changeset/slack-thread-fix-issue.md

@@ -0,0 +1,7 @@
+---
+"clerk": patch
+---
+
+Stop the "Update available" notice from garbling the "Next steps" block.
+
+The next-steps outro animation moves the cursor back onto the header line for ~450ms, but several commands (`switch-env`, `auth logout`, `unlink`, `users create`, `apps create`, and others) did not await it. The command's promise resolved mid-animation, so the post-command update check printed its notice at the parked cursor position — overwriting the step lines and leaving a stray duplicate "Next steps" header. Every `outro(...)` call is now awaited, so output printed after a command lands below the finished block.

.claude/rules/versioning.md

@@ -16,10 +16,13 @@ import { CURRENT_VERSION, IS_DEV_BUILD } from "./version.ts";
  including CLI help, user-agent headers, and MCP client info.
 - Read `IS_DEV_BUILD` when behavior depends on whether the binary is a
  development build.
-- Keep checkout-derived version generation and dev classification in
- `version.macro.ts`; the compiled CLI must not execute Git or classify its
- version at runtime.
+- Keep checkout-derived version generation in `version.macro.ts`; the compiled
+ CLI must not execute Git at runtime.
+- Keep the `CLI_VERSION` define check and dev classification in `version.ts`
+ module scope, NOT in the macro: since Bun 1.4, macros run in a sealed
+ transpiler context that `--define` globals do not reach, while defines still
+ substitute identifiers in transpiled modules.
 
-The constants are evaluated while Bun transpiles or compiles the module, so
+The macro fallback is inlined while Bun transpiles or compiles the module, so
 release builds can use the injected `CLI_VERSION` while local builds retain
 their checkout metadata.

CLAUDE.md

@@ -60,4 +60,4 @@ These flags require Bun >= 1.3.13 — older versions silently ignore them and lo
 
 The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
 
-Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git or classifies the version at runtime. Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.
+Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.

packages/cli-core/src/commands/api/index.ts

@@ -167,9 +167,9 @@ export async function api(
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/apps/create.ts

@@ -41,9 +41,9 @@ export async function create(name: string, options: AppsOptions = {}): Promise<v
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro(nextSteps);
+await outro(nextSteps);
  }
  }
  }

packages/cli-core/src/commands/apps/list.ts

@@ -60,9 +60,9 @@ export async function list(options: AppsOptions = {}): Promise<void> {
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/auth/login.ts

@@ -140,7 +140,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
  return existingSession;
  }
@@ -151,7 +151,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  default: false,
  });
  if (!reauthenticate) {
- outro();
+await outro();
  throwUserAbort();
  }
  }
@@ -188,7 +188,7 @@ export async function login(options: LoginOptions = {}): Promise<UserInfo> {
  if (showNextSteps) {
  await outro(await loginNextSteps(claimResult));
  } else {
- outro("Done");
+await outro("Done");
  }
 
  return userInfo;

packages/cli-core/src/commands/auth/logout.ts

@@ -26,5 +26,5 @@ export async function logout(): Promise<void> {
  );
  }
 
- outro(NEXT_STEPS.LOGOUT);
+await outro(NEXT_STEPS.LOGOUT);
 }

packages/cli-core/src/commands/config/push.ts

@@ -137,9 +137,9 @@ async function configPush(options: ConfigPushOptions, op: Operation): Promise<vo
  if (closeStatus === "paused") {
  pausedOutro();
  } else if (closeStatus === "failed") {
- outro("Failed");
+await outro("Failed");
  } else if (closeStatus === "success") {
- outro();
+await outro();
  }
  }
  }

packages/cli-core/src/commands/deploy/index.ts

@@ -92,7 +92,7 @@ export async function deploy(_options: DeployOptions = {}) {
  throw error;
  }
  if (error instanceof DeployPausedError && isInsideGutter()) {
- outro("Paused");
+await outro("Paused");
  }
  if (error instanceof UserAbortError && isInsideGutter()) {
  pausedOutro(pausedOperationNotice());
@@ -103,7 +103,7 @@ export async function deploy(_options: DeployOptions = {}) {
  // Successful and paused paths call outro themselves. This balances the
  // intro gutter if an unexpected error escapes.
  if (isInsideGutter()) {
- outro("Failed");
+await outro("Failed");
  }
  }
 }
@@ -154,7 +154,7 @@ async function startNewDeploy(ctx: DeployContext): Promise<void> {
  const proceed = await confirmProceed();
  if (!proceed) {
  log.info("No changes were made.");
- outro("Cancelled");
+await outro("Cancelled");
  return;
  }
 
@@ -233,7 +233,7 @@ async function reconcileExistingDeploy(ctx: DeployContext): Promise<void> {
  log.blank();
  log.info("A production instance exists, but Clerk did not return a production domain yet.");
  log.info("Run `clerk deploy` again after the domain is available from the API.");
- outro("No deploy actions available");
+await outro("No deploy actions available");
  return;
  }
 
@@ -361,7 +361,7 @@ async function confirmProductionInstanceCreation(domain: string): Promise<boolea
 
  log.blank();
  log.info("No production instance was created.");
- outro("Cancelled");
+await outro("Cancelled");
  return false;
 }
 
@@ -639,7 +639,7 @@ async function finishDeploy(
  fallback: bold,
  body: `${applyPrefix(nextStepsBody(ctx.appId, productionInstanceId))}\n`,
  });
- outro("Success");
+await outro("Success");
 }
 
 export function registerDeploy(program: Program): void {

packages/cli-core/src/commands/doctor/index.ts

@@ -128,7 +128,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
  return;
  }
  }
@@ -139,7 +139,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<void> {
  code: ERROR_CODE.DOCTOR_FAILED,
  });
  }
- outro("All checks passing");
+await outro("All checks passing");
 }
 
 export function registerDoctor(program: Program): void {

packages/cli-core/src/commands/init/index.ts

@@ -160,7 +160,7 @@ export async function init(options: InitOptions = {}) {
  if (agent && strategy === "manual") {
  printBootstrapManualSetupInfo(ctx.framework);
  }
- outro("Done");
+await outro("Done");
  return;
  }
 
@@ -183,7 +183,7 @@ export async function init(options: InitOptions = {}) {
  printBootstrapNextSteps(bootstrap, strategy === "keyless");
  }
 
- outro("Done");
+await outro("Done");
 }
 
 /**

packages/cli-core/src/commands/link/index.ts

@@ -61,13 +61,13 @@ export async function link(options: LinkOptions = {}): Promise<void> {
  if (existing && agent) {
  printExistingStatus(existing, normalizedRemote);
  if (!targetsDifferentApp) {
- outro();
+await outro();
  return;
  }
  } else if (existing) {
  const shouldRelink = await handleExistingProfile(existing, normalizedRemote, options);
  if (!shouldRelink) {
- outro();
+await outro();
  return;
  }
  }

packages/cli-core/src/commands/open/index.ts

@@ -102,7 +102,7 @@ export async function openDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 /**
@@ -196,7 +196,7 @@ async function openKeylessDashboard(
  );
  }
 
- outro();
+await outro();
 }
 
 export function registerOpen(program: Program): void {

packages/cli-core/src/commands/switch-env/index.ts

@@ -48,12 +48,12 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  } else if (available.length <= 1) {
  log.info(`Current environment: ${current}`);
  log.info("Only one environment configured — nothing to switch to.");
- outro();
+await outro();
  return;
  } else {
  log.info(`Current environment: ${current}`);
  log.info(`Available environments: ${available.join(", ")}`);
- outro();
+await outro();
  return;
  }
  }
@@ -68,7 +68,7 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
 
  if (previousEnv === target) {
  log.data(`Already on ${target} environment.`);
- outro();
+await outro();
  return;
  }
 
@@ -81,10 +81,10 @@ export async function switchEnv(environmentArg: string | undefined): Promise<voi
  const token = await getToken();
  if (!token) {
  log.data(`No credentials found for ${target}.`);
- outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
+await outro(NEXT_STEPS.SWITCH_ENV_NO_TOKEN);
  return;
  }
- outro(NEXT_STEPS.SWITCH_ENV);
+await outro(NEXT_STEPS.SWITCH_ENV);
 }
 
 export function registerSwitchEnv(program: Program): void {

packages/cli-core/src/commands/switch-env/update-notice-race.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Repro for the garbled "Update available" output reported in Slack: the
+ * next-steps outro animation parks the cursor on the header line for ~450ms,
+ * so anything printed after the command's promise resolves (the postAction
+ * update notice) must not run until the animation has finished. If the command
+ * resolves early, the notice lands mid-block and overwrites the step lines.
+ *
+ * Unlike index.test.ts this file deliberately uses the REAL spinner/gradient
+ * modules on a forced-interactive TTY so the animation actually runs.
+ */
+import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
+import { log } from "../../lib/log.ts";
+import { setMode } from "../../mode.ts";
+import { useCaptureLog, configStubs, credentialStoreStubs } from "../../test/lib/stubs.ts";
+
+const MOCK_ENVS = ["production", "staging"];
+let mockCurrentEnv = "production";
+
+mock.module("../../lib/config.ts", () => ({
+ ...configStubs,
+}));
+
+mock.module("../../lib/credential-store.ts", () => ({
+ ...credentialStoreStubs,
+ getToken: async () => "some-token",
+}));
+
+mock.module("../../lib/environment.ts", () => ({
+ getCurrentEnvName: () => mockCurrentEnv,
+ getAvailableEnvs: () => MOCK_ENVS,
+ isValidEnv: (name: string) => MOCK_ENVS.includes(name),
+ setCurrentEnv: (name: string) => {
+ mockCurrentEnv = name;
+ },
+}));
+
+const { switchEnv } = await import("./index.ts");
+
+const CURSOR_SHOW = "\x1b[?25h";
+const NOTICE = "⬆ Update available: 3.0.1 → 3.1.0";
+
+describe("switch-env update-notice race", () => {
+ const captured = useCaptureLog();
+ const ENV_KEYS = ["CI", "NO_COLOR", "FORCE_COLOR", "COLORTERM"] as const;
+ let savedTTY: boolean | undefined;
+ let savedEnv: Record<string, string | undefined>;
+
+ beforeEach(() => {
+ setMode("human"); // the runner has no TTY, but the bug only shows in human mode
+ mockCurrentEnv = "production";
+ savedTTY = process.stderr.isTTY;
+ savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+ Object.defineProperty(process.stderr, "isTTY", { value: true, configurable: true });
+ for (const k of ENV_KEYS) delete process.env[k];
+ process.env.COLORTERM = "truecolor";
+ });
+
+ afterEach(() => {
+ Object.defineProperty(process.stderr, "isTTY", { value: savedTTY, configurable: true });
+ for (const k of ENV_KEYS) {
+ if (savedEnv[k] == null) delete process.env[k];
+ else process.env[k] = savedEnv[k];
+ }
+ });
+
+ test("output printed after the command resolves lands below the finished animation", async () => {
+ await switchEnv("staging");
+ // The postAction hook prints the update notice as soon as the action's
+ // promise resolves — reproduce that exact ordering.
+ log.warn(NOTICE);
+ // On fixed code the animation completed before switchEnv() resolved, so
+ // this returns immediately; on a regression it waits (bounded) for the
+ // orphaned animation's trailing frames so the ordering assertion below
+ // fails with a precise message instead of a missing-cursor-restore -1.
+ const deadline = Date.now() + 2_000;
+ while (!captured.err.includes(CURSOR_SHOW) && Date.now() < deadline) {
+ await Bun.sleep(25);
+ }
+
+ const err = captured.err;
+ const cursorRestoredAt = err.lastIndexOf(CURSOR_SHOW);
+ const noticeAt = err.indexOf(NOTICE);
+ expect(cursorRestoredAt).toBeGreaterThanOrEqual(0);
+ expect(noticeAt).toBeGreaterThan(cursorRestoredAt);
+ }, 10_000);
+});

packages/cli-core/src/commands/unlink/index.ts

@@ -45,7 +45,7 @@ export async function unlink(options: UnlinkOptions = {}): Promise<void> {
 
  await removeProfile(existing.path);
  log.data(`\nUnlinked ${cyan(label)} from ${dim(displayPath)}`);
- outro(NEXT_STEPS.UNLINK);
+await outro(NEXT_STEPS.UNLINK);
 }
 
 export function registerUnlink(program: Program): void {