Add typed JSON output to upgrade

[gonzaloriestra]

WHY are these changes introduced?

Fixes https://github.com/shop/issues-develop/issues/23676.

shopify upgrade needs a structured result for scripts and agents.

WHAT is this pull request doing?

Add --json with a strict, discoverable result schema for global upgrades, local dependency installations, and skips. Use canonical success/skipped outcomes and kebab-case skip reasons; send package-manager diagnostics through stderr events.

Global results include the verified installed version and changed. Local results include the absolute project directory, updated package names, and nullable available version. Their changed is null because installed local versions and dependency changes are not verified. Preserve existing terminal output and automatic upgrade behavior.

How to manually test your changes?

pnpm shopify upgrade --help
pnpm shopify upgrade --json-schema
pnpm shopify upgrade --json --no-input
pnpm shopify upgrade

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• Added a minor changeset for the new JSON flag.

[gonzaloriestra]

/snapit

[github-actions]

🫰✨ Thanks @gonzaloriestra! Your snapshot has been published to npm.

Built from 3b3c59947ed10182c8d6d8d07fd89d4258b784a3. Workflow run.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20261002100254

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

[gonzaloriestra]

/snapit

[github-actions]

🫰✨ Thanks @gonzaloriestra! Your snapshot has been published to npm.

Built from e0d720de01bf379f88c1a8c1299bf52d7194a258. Workflow run.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20261006134446

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

[isaacroldan]

One issue with the package manager output in JSON mode.

---

🤖 Generated by the review-pr skill

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/public/node/upgrade/output.d.ts

import { Writable } from 'node:stream';
/**
 * Keeps package-manager output off the result channel in JSON mode.
 *
 * @returns Streams for package-manager diagnostics, or the original terminal streams.
 */
export declare function upgradeOutputStreams(): {
    stdout: Writable;
    stderr: Writable;
};
/**
 * Runs a global upgrade with terminal input and format-appropriate diagnostics.
 *
 * @param command - The package-manager executable.
 * @param args - The install arguments.
 */
export declare function execUpgradeCommand(command: string, args: string[]): Promise<void>;

packages/cli-kit/dist/public/node/upgrade/result.d.ts

import { type UpgradeResult } from './types.js';
/**
 * Presents the upgrade result without changing progress or package-manager output.
 *
 * @param result - The completed upgrade outcome.
 * @param format - The output format selected by the caller.
 */
export declare function presentUpgradeResult(result: UpgradeResult, format: 'json' | 'text'): void;

packages/cli-kit/dist/public/node/upgrade/types.d.ts

import { type InferJsonOutputSchema } from '../json-output-schema.js';
import { zod } from '../schema.js';
export declare const upgradeJsonOutputSchema: import("../json-output-schema.js").JsonOutputSchema<zod.ZodUnion<[zod.ZodObject<{
    status: zod.ZodLiteral<"success">;
    changed: zod.ZodBoolean;
    scope: zod.ZodLiteral<"global">;
    previousVersion: zod.ZodString;
    version: zod.ZodString;
    packageManager: zod.ZodEnum<["npm", "pnpm", "yarn", "bun", "homebrew"]>;
}, "strict", zod.ZodTypeAny, {
    status: "success";
    version: string;
    scope: "global";
    changed: boolean;
    previousVersion: string;
    packageManager: "yarn" | "npm" | "pnpm" | "bun" | "homebrew";
}, {
    status: "success";
    version: string;
    scope: "global";
    changed: boolean;
    previousVersion: string;
    packageManager: "yarn" | "npm" | "pnpm" | "bun" | "homebrew";
}>, zod.ZodObject<{
    status: zod.ZodLiteral<"success">;
    changed: zod.ZodNull;
    scope: zod.ZodLiteral<"local">;
    directory: zod.ZodEffects<zod.ZodEffects<zod.ZodString, string, string>, string, string>;
    previousVersion: zod.ZodString;
    availableVersion: zod.ZodNullable<zod.ZodString>;
    packages: zod.ZodArray<zod.ZodString, "many">;
}, "strict", zod.ZodTypeAny, {
    status: "success";
    directory: string;
    scope: "local";
    changed: null;
    previousVersion: string;
    availableVersion: string | null;
    packages: string[];
}, {
    status: "success";
    directory: string;
    scope: "local";
    changed: null;
    previousVersion: string;
    availableVersion: string | null;
    packages: string[];
}>, zod.ZodObject<{
    status: zod.ZodLiteral<"skipped">;
    reason: zod.ZodEnum<["development", "local-autoupgrade", "dependency-not-found"]>;
    scope: zod.ZodEnum<["global", "local"]>;
}, "strict", zod.ZodTypeAny, {
    status: "skipped";
    scope: "local" | "global";
    reason: "development" | "local-autoupgrade" | "dependency-not-found";
}, {
    status: "skipped";
    scope: "local" | "global";
    reason: "development" | "local-autoupgrade" | "dependency-not-found";
}>]>>;
export type UpgradeResult = InferJsonOutputSchema<typeof upgradeJsonOutputSchema>;

Existing type declarations

packages/cli-kit/dist/public/node/upgrade.d.ts

@@ -1,4 +1,5 @@
 import { getAutoUpgradeEnabled, setAutoUpgradeEnabled } from '../../private/node/conf-store.js';
+import type { UpgradeResult } from './upgrade/types.js';
 export { getAutoUpgradeEnabled, setAutoUpgradeEnabled };
 /**
  * Utility function for generating an install command for the user to run
@@ -27,6 +28,13 @@ export interface RunCLIUpgradeOptions {
  * @throws AbortError if the package manager or command cannot be determined.
  */
 export declare function runCLIUpgrade(options?: RunCLIUpgradeOptions): Promise<void>;
+/**
+ * Upgrades the CLI and returns the outcome independently of final presentation.
+ *
+ * @param options - Whether the upgrade was triggered automatically.
+ * @returns The verified global version, local dependency update, or skip reason.
+ */
+export declare function upgradeCLI(options?: RunCLIUpgradeOptions): Promise<UpgradeResult>;
 /**
  * Returns the version to auto-upgrade to, or undefined if auto-upgrade should be skipped.
  * Auto-upgrade is enabled by default and can be disabled via `setAutoUpgradeEnabled(false)`.

[isaacroldan]

/snapit

[github-actions]

🫰✨ Thanks @isaacroldan! Your snapshot has been published to npm.

Built from 99214b716d7f08b97af116a4d312288ab0651d08. Workflow run.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20261009090327

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.