Add auth-alias flag

[isaacroldan]

WHY are these changes introduced?

App and theme workflows need a way to run commands with a stored Shopify account alias without switching the user's persisted current CLI session.

WHAT is this pull request doing?

• Adds a shared authAliasFlag in cli-kit.
• Opts the flag into AppCommand, ThemeCommand, and organization list only.
• Parses --auth-alias centrally in BaseCommand, resolves the alias to a command-scoped session, and uses that session during authentication without mutating the current session.
• Refreshes generated manifests, CLI README, dev docs, and adds a changeset.

How to test your changes?

pnpm vitest run packages/cli/src/cli/commands/auth/login.test.ts packages/cli-kit/src/private/node/session.test.ts packages/cli-kit/src/public/node/session.test.ts packages/cli-kit/src/public/node/base-command.test.ts packages/theme/src/cli/utilities/theme-command.test.ts

pnpm nx run cli-kit:type-check --output-style=stream
pnpm nx run app:type-check --output-style=stream
pnpm nx run theme:type-check --output-style=stream
pnpm nx run cli:type-check --output-style=stream
pnpm nx run cli-kit:lint --output-style=stream
pnpm nx run app:lint --output-style=stream
pnpm nx run theme:lint --output-style=stream
pnpm nx run cli:lint --output-style=stream
git diff --check
pnpm refresh-manifests
pnpm refresh-readme
pnpm build-dev-docs

Manual smoke:

pnpm shopify organization list --auth-alias <alias>
pnpm shopify app info --auth-alias <alias>
pnpm shopify theme list --auth-alias <alias> --store <store.myshopify.com>

Post-release steps

None.

[isaacroldan]

• Add auth-alias flag #8026 👈 (View in Graphite)
• Stop tracking generated docs interfaces #8025
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[isaacroldan]

/snapit

[github-actions]

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

Test the snapshot by installing your package globally:

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

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.

[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

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/private/node/session.d.ts

@@ -90,6 +90,7 @@ export declare function setLastSeenUserIdAfterAuth(id: string): void;
  */
 export declare function getLastSeenAuthMethod(): Promise<AuthMethod>;
 export declare function setLastSeenAuthMethod(method: AuthMethod): void;
+export declare function setCommandSessionId(sessionId: string | undefined): void;
 export interface EnsureAuthenticatedAdditionalOptions {
     noPrompt?: boolean;
     forceRefresh?: boolean;

packages/cli-kit/dist/public/node/base-command.d.ts

@@ -16,6 +16,7 @@ declare abstract class BaseCommand extends Command {
     protected parse<TFlags extends FlagOutput & {
         path?: string;
         verbose?: boolean;
+        'auth-alias'?: string;
     }, TGlobalFlags extends FlagOutput, TArgs extends ArgOutput>(options?: Input<TFlags, TGlobalFlags, TArgs>, argv?: string[]): Promise<ParserOutput<TFlags, TGlobalFlags, TArgs> & {
         argv: string[];
     }>;

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

@@ -39,6 +39,9 @@ export declare const globalFlags: {
 export declare const jsonFlag: {
     json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
 };
+export declare const authAliasFlag: {
+    'auth-alias': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
 /**
  * Builds a  flag that only accepts a valid port number. The flag parses its
  * value as an integer and rejects anything that isn't a whole number between 1 and

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

@@ -22,6 +22,19 @@ export type AccountInfo = UserAccountInfo | ServiceAccountInfo | UnknownAccountI
  * @param userId - User identifier to report on the command analytics event.
  */
 export declare function setLastSeenUserId(userId: string): void;
+/**
+ * Finds a stored Shopify account session by alias without changing the current session.
+ *
+ * @param alias - The account alias to find.
+ * @returns The matching session ID, or undefined if no session matches.
+ */
+export declare function findSessionIdByAlias(alias: string): Promise<string | undefined>;
+/**
+ * Selects a stored Shopify account session by alias for the current command process.
+ *
+ * @param alias - The account alias to select. Passing undefined clears the command selection.
+ */
+export declare function setCurrentSessionAlias(alias?: string): Promise<void>;
 interface UserAccountInfo {
     type: 'UserAccount';
     email: string;