Add auth status command

[gonzaloriestra]

WHY are these changes introduced?

Agents need a deterministic way to check whether Shopify CLI already has a usable Shopify account session before starting workflows that require auth. This PR adds that primitive first so follow-up guidance can point agents at a stable command.

WHAT is this pull request doing?

• Adds shopify auth status with human-readable output and --json for stable machine-readable status.
• Adds a cli-kit getAuthStatus() helper that checks stored sessions without starting a login flow.
• Updates generated command docs, the command snapshot, and tests.

How to test your changes?

shopify auth status

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
• The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add

[gonzaloriestra]

• Improve auth guidance for agents #7628
• Add auth status command #7629 👈 (View in Graphite)
• main

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

[gonzaloriestra]

/snapit

[ghost]

🫰✨ Thanks @gonzaloriestra! 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-20260525120835

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.

[ghost]

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/public/node/session.d.ts

@@ -33,6 +33,21 @@ interface ServiceAccountInfo {
 interface UnknownAccountInfo {
     type: 'UnknownAccount';
 }
+export type AuthStatusName = 'authenticated' | 'needs_refresh' | 'not_authenticated' | 'invalid';
+export interface AuthStatus {
+    status: AuthStatusName;
+    authenticated: boolean;
+    account?: {
+        userId: string;
+        alias?: string;
+    };
+    identityFqdn?: string;
+    expiresAt?: string;
+    agentGuidance: {
+        instruction: string;
+        nextCommand?: string;
+    };
+}
 /**
  * Type guard to check if an account is a UserAccount.
  *
@@ -47,6 +62,12 @@ export declare function isUserAccount(account: AccountInfo): account is UserAcco
  * @returns True if the account is a ServiceAccount.
  */
 export declare function isServiceAccount(account: AccountInfo): account is ServiceAccountInfo;
+/**
+ * Returns the current Shopify CLI authentication status without starting a login flow.
+ *
+ * @returns The current authentication status.
+ */
+export declare function getAuthStatus(): Promise<AuthStatus>;
 /**
  * Ensure that we have a valid session with no particular scopes.
  *