fix: improve installer auth recovery

README.md

@@ -5,14 +5,18 @@ WorkOS CLI for installing AuthKit integrations and managing WorkOS resources.
 ## Installation
 
 ```bash
-# Run directly with npx (recommended)
-npx workos
+# Run the installer directly with npx (recommended)
+npx workos@latest install
 
 # Or install globally
 npm install -g workos
-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/adapters/cli-adapter.spec.ts

@@ -244,5 +244,27 @@ describe('CLIAdapter', () => {
  expect(output).toContain('Something went wrong');
  consoleSpy.mockRestore();
  });
+
+ it('keeps npx in auth recovery hints when launched through npm exec', async () => {
+ const originalNpmCommand = process.env.npm_command;
+ process.env.npm_command = 'exec';
+
+ try {
+ await adapter.start();
+ const clack = await import('../../utils/clack.js');
+
+ emitter.emit('error', { message: 'authentication failed', stack: undefined });
+
+ expect(clack.default.log.info).toHaveBeenCalledWith(
+ 'Try running: npx workos@latest auth logout && npx workos@latest install',
+ );
+ } finally {
+ if (originalNpmCommand === undefined) {
+ delete process.env.npm_command;
+ } else {
+ process.env.npm_command = originalNpmCommand;
+ }
+ }
+ });
  });
 });

src/lib/adapters/cli-adapter.ts

@@ -5,6 +5,7 @@ import chalk from 'chalk';
 import { getConfig } from '../settings.js';
 import { ProgressTracker } from '../progress-tracker.js';
 import { renderCompletionSummary } from '../../utils/summary-box.js';
+import { formatWorkOSCommand } from '../../utils/command-invocation.js';
 
 /**
  * CLI adapter that renders wizard events via clack.
@@ -427,7 +428,7 @@ export class CLIAdapter implements InstallerAdapter {
 
  // Add actionable hints for common errors
  if (message.includes('authentication') || message.includes('auth')) {
- clack.log.info('Try running: workos auth logout && workos install');
+ clack.log.info(`Try running: ${formatWorkOSCommand('auth logout')} && ${formatWorkOSCommand('install')}`);
  }
  if (message.includes('ENOENT') || message.includes('not found')) {
  clack.log.info('Ensure you are in a project directory');

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';
@@ -395,12 +396,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
@@ -421,7 +422,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.`,
  });
  },
  },
@@ -441,9 +442,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 {
@@ -54,6 +55,8 @@ export class DeviceAuthError extends Error {
 }
 
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const POLL_REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_SCOPES = ['openid', 'email', 'staging-environment:credentials:read', 'offline_access'];
 
 function sleep(ms: number): Promise<void> {
@@ -122,15 +125,20 @@ export async function pollForToken(
 ): Promise<DeviceAuthResult> {
  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
  const startTime = Date.now();
- let pollInterval = options.interval * 1000;
+ 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;
+ const controller = new AbortController();
+ const timeout = setTimeout(() => controller.abort(), POLL_REQUEST_TIMEOUT_MS);
  try {
  res = await fetch(tokenUrl, {
  method: 'POST',
@@ -140,28 +148,38 @@ export async function pollForToken(
  device_code: deviceCode,
  client_id: options.clientId,
  }),
+ signal: controller.signal,
  });
- } catch {
- logInfo('[device-auth] Token poll network error, retrying');
+ } catch (error) {
+ logInfo(
+ '[device-auth] Token poll network error, retrying:',
+ error instanceof Error ? error.message : String(error),
+ );
  continue;
+ } finally {
+ clearTimeout(timeout);
  }
 
  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;
  }
@@ -177,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 5 minutes');
+ 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 {