fix: tighten auth recovery guidance

Author: nicknisi

README.md

@@ -13,6 +13,10 @@ npm install -g workos
 workos install
 ```
 
+`npx workos@latest install` is recommended because it bypasses stale global shims and older shell-resolved binaries.
+If a global install reports `unknown command "install"`, run the npx command above or reinstall globally and clear your
+shell command cache.
+
 ## Features
 
 - **15 Framework Support:** Next.js, React Router, TanStack Start, React SPA, Vanilla JS, SvelteKit, Node.js (Express), Python (Django), Ruby (Rails), Go, .NET (ASP.NET Core), Kotlin (Spring Boot), Elixir (Phoenix), PHP (Laravel), PHP
@@ -93,7 +97,7 @@ When you run `workos install` without credentials, the CLI automatically provisi
 
 ```bash
 # Install with zero setup — environment provisioned automatically
-workos install
+npx workos@latest install
 
 # Check your environment
 workos env list
@@ -560,13 +564,13 @@ workos install [options]
 
 ```bash
 # Interactive (recommended)
-npx workos
+npx workos@latest install
 
 # Specify framework
-npx workos install --integration react-router
+npx workos@latest install --integration react-router
 
 # With visual dashboard (experimental)
-npx workos dashboard
+npx workos@latest dashboard
 
 # JSON output (explicit)
 workos org list --json --api-key sk_test_xxx
@@ -648,13 +652,13 @@ The CLI uses WorkOS Connect OAuth device flow for authentication:
 
 ```bash
 # Login (opens browser for authentication)
-workos auth login
+npx workos@latest auth login
 
 # Check current auth status
-workos auth status
+npx workos@latest auth status
 
 # Logout (clears stored credentials)
-workos auth logout
+npx workos@latest auth logout
 ```
 
 OAuth credentials are stored in the system keychain (with `~/.workos/credentials.json` fallback). Access tokens are not persisted long-term for security - users re-authenticate when tokens expire.
@@ -682,7 +686,7 @@ The installer collects anonymous usage telemetry to help improve the product:
 No code, credentials, or personal data is collected. Disable with:
 
 ```bash
-WORKOS_TELEMETRY=false npx workos
+WORKOS_TELEMETRY=false npx workos@latest install
 ```
 
 ## Logs

src/commands/auth-status.ts

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { getCredentials, isTokenExpired } from '../lib/credentials.js';
 import { getActiveEnvironment } from '../lib/config-store.js';
 import { isJsonMode, outputJson } from '../utils/output.js';
+import { formatWorkOSCommand } from '../utils/command-invocation.js';
 
 function formatTimeRemaining(ms: number): string {
   if (ms <= 0) return 'expired';
@@ -23,7 +24,7 @@ export async function runAuthStatus(): Promise<void> {
       return;
     }
     console.log(chalk.yellow('Not logged in'));
-    console.log(chalk.dim('Run `workos auth login` to authenticate'));
+    console.log(chalk.dim(`Run \`${formatWorkOSCommand('auth login')}\` to authenticate`));
     return;
   }
 

src/commands/claim.ts

@@ -13,6 +13,7 @@ import { createClaimNonce, UnclaimedEnvApiError } from '../lib/unclaimed-env-api
 import { logInfo, logError } from '../utils/debug.js';
 import { isJsonMode, outputJson, exitWithError } from '../utils/output.js';
 import { sleep } from '../lib/helper-functions.js';
+import { formatWorkOSCommand } from '../utils/command-invocation.js';
 
 const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 const POLL_INTERVAL_MS = 5_000; // 5 seconds
@@ -48,7 +49,7 @@ export async function runClaim(): Promise<void> {
         outputJson({ status: 'already_claimed', message: 'Environment already claimed!' });
       } else {
         clack.log.success('Environment already claimed!');
-        clack.log.info('Run `workos auth login` to connect your account.');
+        clack.log.info(`Run \`${formatWorkOSCommand('auth login')}\` to connect your account.`);
       }
       return;
     }
@@ -84,7 +85,7 @@ export async function runClaim(): Promise<void> {
         if (check.alreadyClaimed) {
           spinner.stop('Environment claimed!');
           markEnvironmentClaimed();
-          clack.log.info('Run `workos auth login` to connect your account.');
+          clack.log.info(`Run \`${formatWorkOSCommand('auth login')}\` to connect your account.`);
           return;
         }
         consecutiveFailures = 0;
@@ -95,7 +96,7 @@ export async function runClaim(): Promise<void> {
           // when the environment is claimed. Safe to promote to sandbox.
           spinner.stop('Claim token is invalid or expired.');
           markEnvironmentClaimed();
-          clack.log.warn('Run `workos auth login` to set up your environment.');
+          clack.log.warn(`Run \`${formatWorkOSCommand('auth login')}\` to set up your environment.`);
           return;
         }
         consecutiveFailures++;

src/commands/login.ts

@@ -8,6 +8,7 @@ import { logInfo, logError } from '../utils/debug.js';
 import { fetchStagingCredentials } from '../lib/staging-api.js';
 import { getConfig, saveConfig } from '../lib/config-store.js';
 import type { CliConfig } from '../lib/config-store.js';
+import { formatWorkOSCommand } from '../utils/command-invocation.js';
 
 /**
  * Parse JWT payload
@@ -110,7 +111,7 @@ export async function runLogin(): Promise<void> {
   if (getAccessToken()) {
     const creds = getCredentials();
     console.log(chalk.green(`Already logged in as ${creds?.email ?? 'unknown'}`));
-    console.log(chalk.dim('Run `workos auth logout` to log out'));
+    console.log(chalk.dim(`Run \`${formatWorkOSCommand('auth logout')}\` to log out`));
     return;
   }
 
@@ -124,7 +125,7 @@ export async function runLogin(): Promise<void> {
         updateTokens(result.accessToken, result.expiresAt, result.refreshToken);
         logInfo('[login] Session refreshed via refresh token');
         console.log(chalk.green(`Already logged in as ${existingCreds.email ?? 'unknown'}`));
-        console.log(chalk.dim('Run `workos auth logout` to log out'));
+        console.log(chalk.dim(`Run \`${formatWorkOSCommand('auth logout')}\` to log out`));
         return;
       }
     } catch {

src/doctor/checks/ai-analysis.ts

@@ -4,6 +4,7 @@ import { getCredentials, isTokenExpired, updateTokens, diagnoseCredentials } fro
 import { refreshAccessToken } from '../../lib/token-refresh-client.js';
 import { buildDoctorPrompt, type AnalysisContext } from '../agent-prompt.js';
 import type { AiAnalysis, AiFinding } from '../types.js';
+import { formatWorkOSCommand } from '../../utils/command-invocation.js';
 
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 
@@ -61,10 +62,11 @@ async function callModel(prompt: string, model: string): Promise<string> {
   if (!creds) throw new Error('Not authenticated');
 
   if (isTokenExpired(creds)) {
-    if (!creds.refreshToken) throw new Error('Session expired — run `workos auth login` to re-authenticate');
+    if (!creds.refreshToken)
+      throw new Error(`Session expired — run \`${formatWorkOSCommand('auth login')}\` to re-authenticate`);
     const result = await refreshAccessToken(getAuthkitDomain(), getCliAuthClientId());
     if (!result.success || !result.accessToken || !result.expiresAt) {
-      throw new Error('Session expired — run `workos auth login` to re-authenticate');
+      throw new Error(`Session expired — run \`${formatWorkOSCommand('auth login')}\` to re-authenticate`);
     }
     updateTokens(result.accessToken, result.expiresAt, result.refreshToken);
     creds = getCredentials()!;
@@ -111,7 +113,7 @@ export async function checkAiAnalysis(context: AnalysisContext, options: { skipA
       process.stderr.write(`    ${line}\n`);
     }
     process.stderr.write('\n');
-    return skippedResult('Not authenticated — run `workos auth login` for AI-powered analysis');
+    return skippedResult(`Not authenticated — run \`${formatWorkOSCommand('auth login')}\` for AI-powered analysis`);
   }
 
   const startTime = Date.now();

src/lib/agent-interface.ts

@@ -11,6 +11,7 @@ import { analytics } from '../utils/analytics.js';
 import { INSTALLER_INTERACTION_EVENT_NAME } from './constants.js';
 import { LINTING_TOOLS } from './safe-tools.js';
 import { getLlmGatewayUrlFromHost } from '../utils/urls.js';
+import { formatWorkOSCommand } from '../utils/command-invocation.js';
 import { getConfig } from './settings.js';
 import { getCredentials, hasCredentials } from './credentials.js';
 import { ensureValidToken } from './token-refresh.js';
@@ -383,12 +384,12 @@ export async function initializeAgent(config: AgentConfig, options: InstallerOpt
       } else if (!options.skipAuth && !options.local) {
         // Check/refresh authentication for production (unless skipping auth)
         if (!hasCredentials()) {
-          throw new Error('Not authenticated. Run `workos auth login` to authenticate.');
+          throw new Error(`Not authenticated. Run \`${formatWorkOSCommand('auth login')}\` to authenticate.`);
         }
 
         const creds = getCredentials();
         if (!creds) {
-          throw new Error('Not authenticated. Run `workos auth login` to authenticate.');
+          throw new Error(`Not authenticated. Run \`${formatWorkOSCommand('auth login')}\` to authenticate.`);
         }
 
         // Check if we have refresh token capability and proxy is not disabled
@@ -409,7 +410,7 @@ export async function initializeAgent(config: AgentConfig, options: InstallerOpt
               onRefreshExpired: () => {
                 logError('[agent-interface] Session expired, refresh token invalid');
                 options.emitter?.emit('error', {
-                  message: 'Session expired. Run `workos auth login` to re-authenticate.',
+                  message: `Session expired. Run \`${formatWorkOSCommand('auth login')}\` to re-authenticate.`,
                 });
               },
             },
@@ -426,9 +427,9 @@ export async function initializeAgent(config: AgentConfig, options: InstallerOpt
           // No refresh token OR proxy disabled - fall back to old behavior (5 min limit)
           if (!creds.refreshToken) {
             logWarn('[agent-interface] No refresh token available, session limited to 5 minutes');
-            logWarn('[agent-interface] Run `workos auth login` to enable extended sessions');
+            logWarn(`[agent-interface] Run \`${formatWorkOSCommand('auth login')}\` to enable extended sessions`);
             options.emitter?.emit('status', {
-              message: 'Note: Run `workos auth login` to enable extended sessions',
+              message: `Note: Run \`${formatWorkOSCommand('auth login')}\` to enable extended sessions`,
             });
           } else {
             logWarn('[agent-interface] Proxy disabled via INSTALLER_DISABLE_PROXY');

src/lib/credential-proxy.ts

@@ -10,6 +10,7 @@ import { logInfo, logError, logWarn } from '../utils/debug.js';
 import { getCredentials, updateTokens, type Credentials } from './credentials.js';
 import { analytics } from '../utils/analytics.js';
 import { refreshAccessToken } from './token-refresh-client.js';
+import { formatWorkOSCommand } from '../utils/command-invocation.js';
 
 export interface RefreshConfig {
   /** AuthKit domain for refresh endpoint */
@@ -286,7 +287,7 @@ async function handleRequest(
     res.end(
       JSON.stringify({
         error: 'credentials_unavailable',
-        message: 'Not authenticated. Run `workos auth login` first.',
+        message: `Not authenticated. Run \`${formatWorkOSCommand('auth login')}\` first.`,
       }),
     );
     return;

src/lib/device-auth.ts

@@ -44,6 +44,7 @@ interface TokenResponse {
 
 interface AuthErrorResponse {
   error: string;
+  error_description?: string;
 }
 
 export class DeviceAuthError extends Error {
@@ -126,10 +127,13 @@ export async function pollForToken(
   const startTime = Date.now();
   let pollInterval = (options.interval || DEFAULT_POLL_INTERVAL_SECONDS) * 1000;
   const tokenUrl = `${options.authkitDomain}/oauth2/token`;
+  let pollCount = 0;
+  let lastPollSummary = 'no token response received';
 
   logInfo('[device-auth] Starting token polling, timeout:', timeoutMs);
   while (Date.now() - startTime < timeoutMs) {
     await sleep(pollInterval);
+    pollCount++;
     options.onPoll?.();
 
     let res: Response;
@@ -159,19 +163,23 @@ export async function pollForToken(
     let data;
     try {
       data = await res.json();
-    } catch {
-      logError('[device-auth] Invalid JSON response from auth server');
-      throw new DeviceAuthError('Invalid response from auth server');
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logError('[device-auth] Invalid JSON response from auth server:', message);
+      throw new DeviceAuthError(`Invalid response from auth server: ${message}`);
     }
 
-    logInfo('[device-auth] Token poll response:', res.status, (data as AuthErrorResponse)?.error ?? 'success');
+    const errorData = data as AuthErrorResponse;
+    const elapsedMs = Date.now() - startTime;
+    lastPollSummary = res.ok
+      ? `${res.status} success`
+      : `${res.status} ${errorData.error ?? 'unknown_error'}${errorData.error_description ? ` (${errorData.error_description})` : ''}`;
+    logInfo('[device-auth] Token poll response:', `attempt=${pollCount}`, `elapsedMs=${elapsedMs}`, lastPollSummary);
     if (res.ok) {
       logInfo('[device-auth] Token received successfully');
       return parseTokenResponse(data as TokenResponse);
     }
 
-    const errorData = data as AuthErrorResponse;
-
     if (errorData.error === 'authorization_pending') {
       continue;
     }
@@ -187,8 +195,10 @@ export async function pollForToken(
     throw new DeviceAuthError(`Token error: ${errorData.error}`);
   }
 
-  logError('[device-auth] Authentication timed out');
-  throw new DeviceAuthError(`Authentication timed out after ${Math.round(timeoutMs / 1000)} seconds`);
+  logError('[device-auth] Authentication timed out, last poll:', lastPollSummary);
+  throw new DeviceAuthError(
+    `Authentication timed out after ${Math.round(timeoutMs / 1000)} seconds (last token response: ${lastPollSummary})`,
+  );
 }
 
 function parseTokenResponse(data: TokenResponse): DeviceAuthResult {

src/lib/ensure-auth.ts

@@ -9,6 +9,7 @@ import { runLogin } from '../commands/login.js';
 import { logInfo } from '../utils/debug.js';
 import { isNonInteractiveEnvironment } from '../utils/environment.js';
 import { exitWithAuthRequired } from '../utils/exit-codes.js';
+import { formatWorkOSCommand } from '../utils/command-invocation.js';
 
 export interface EnsureAuthResult {
   /** Whether auth is now valid */
@@ -78,7 +79,7 @@ export async function ensureAuthenticated(): Promise<EnsureAuthResult> {
         clearCredentials();
         if (isNonInteractiveEnvironment()) {
           exitWithAuthRequired(
-            'Session expired. Run `workos auth login` in an interactive terminal to re-authenticate.',
+            `Session expired. Run \`${formatWorkOSCommand('auth login')}\` in an interactive terminal to re-authenticate.`,
           );
         }
         logInfo('[ensure-auth] Refresh token expired, triggering login');
@@ -91,7 +92,7 @@ export async function ensureAuthenticated(): Promise<EnsureAuthResult> {
       // Network or server error - keep credentials intact for retry
       if (isNonInteractiveEnvironment()) {
         exitWithAuthRequired(
-          `Authentication refresh failed (${refreshResult.errorType}). Run \`workos auth login\` in an interactive terminal.`,
+          `Authentication refresh failed (${refreshResult.errorType}). Run \`${formatWorkOSCommand('auth login')}\` in an interactive terminal.`,
         );
       }
       logInfo(`[ensure-auth] Refresh failed (${refreshResult.errorType}), triggering login`);
@@ -105,7 +106,9 @@ export async function ensureAuthenticated(): Promise<EnsureAuthResult> {
   // Case 4: No refresh token available — clear stale creds, must login
   clearCredentials();
   if (isNonInteractiveEnvironment()) {
-    exitWithAuthRequired('Session expired. Run `workos auth login` in an interactive terminal to re-authenticate.');
+    exitWithAuthRequired(
+      `Session expired. Run \`${formatWorkOSCommand('auth login')}\` in an interactive terminal to re-authenticate.`,
+    );
   }
   logInfo('[ensure-auth] No refresh token, triggering login');
   await runLogin();

src/lib/token-refresh-client.ts

@@ -4,6 +4,7 @@
 
 import { logInfo, logError } from '../utils/debug.js';
 import { getCredentials } from './credentials.js';
+import { formatWorkOSCommand } from '../utils/command-invocation.js';
 
 export interface RefreshResult {
   success: boolean;
@@ -73,7 +74,7 @@ export async function refreshAccessToken(authkitDomain: string, clientId: string
       if (errorData.error === 'invalid_grant') {
         return {
           success: false,
-          error: 'Session expired. Run `workos auth login` to re-authenticate.',
+          error: `Session expired. Run \`${formatWorkOSCommand('auth login')}\` to re-authenticate.`,
           errorType: 'invalid_grant',
         };
       }