feat!: move login/logout to auth subcommand, add auth status (#84)

* feat!: move login/logout to auth subcommand, add auth status

BREAKING CHANGE: `workos login` and `workos logout` are now
`workos auth login` and `workos auth logout`.

New `workos auth status` command shows current auth state:
- Logged in email/userId
- Token expiry (time remaining or how long ago it expired)
- Refresh token presence
- Active environment name and type
- Supports --json for machine-readable output

All error messages referencing `workos login` updated to
`workos auth login`.

* chore: formatting and linting fixes

* feat: add credential audit log for debugging auth loss

Writes timestamped entries to ~/.workos/audit.log for every credential
mutation: SAVE_CREDENTIALS, CLEAR_CREDENTIALS, UPDATE_TOKENS, and
GET_CREDENTIALS (when returning null). Logs only non-sensitive metadata:
email, userId, token expiry, refresh token presence, storage backend,
and caller stack frame. Never logs tokens or API keys.

Disabled automatically in test environments (VITEST).

* fix: guard keyring operations behind insecure storage flag

When forceInsecureStorage is true, all keyring read/write/delete
operations are now no-ops. Previously, deleteFromKeyring() would
still hit the real system keychain even in insecure-storage mode,
meaning tests using setInsecureStorage(true) could wipe real
credentials from the keychain.

This was the root cause of credentials mysteriously vanishing
after running tests.

* Revert "fix: guard keyring operations behind insecure storage flag"

This reverts commit e8b74d1.

* Revert "feat: add credential audit log for debugging auth loss"

This reverts commit 2d78cf5.

* docs: update README auth commands to use auth subcommand

* fix: use plain colored output for auth status instead of clack

* fix: add blank line after update notice to separate from command output

* fix: use plain colored output for login already-authenticated messages

* fix: suppress update notice in JSON mode to keep stdout clean

* fix: review fixes — isJsonMode guard, missed string ref, double newline

- bin.ts: use isJsonMode() instead of hasJsonFlag to suppress update
  notice in all JSON contexts (including non-TTY auto-detection)
- ensure-auth.ts: fix missed workos login → workos auth login at line 94
- version-check.ts: fix double blank line (console.log already adds \n)
- Update CLAUDE.md, DEVELOPMENT.md, SKILL.md references

Author: nicknisi

CLAUDE.md

@@ -12,7 +12,7 @@ WorkOS CLI for installing AuthKit integrations and managing WorkOS resources (or
 ## Non-TTY Behavior
 
 - **Output**: Auto-switches to JSON when piped or `--json` flag. `WORKOS_FORCE_TTY=1` overrides.
-- **Auth**: Exits code 4 instead of opening browser. Requires prior `workos login` or `WORKOS_API_KEY` env var.
+- **Auth**: Exits code 4 instead of opening browser. Requires prior `workos auth login` or `WORKOS_API_KEY` env var.
 - **Errors**: Structured JSON to stderr: `{ "error": { "code": "...", "message": "..." } }`
 - **Exit codes**: 0=success, 1=error, 2=cancelled, 4=auth required (follows `gh` CLI convention)
 - **Headless flags**: `--no-branch`, `--no-commit`, `--create-pr`, `--no-git-check`

DEVELOPMENT.md

@@ -26,8 +26,9 @@ src/
 │   ├── user.ts               # workos user (get/list/update/delete)
 │   ├── install.ts            # workos install
 │   ├── install-skill.ts      # workos install-skill
-│   ├── login.ts              # workos login
-│   └── logout.ts             # workos logout
+│   ├── auth-status.ts        # workos auth status
+│   ├── login.ts              # workos auth login
+│   └── logout.ts             # workos auth logout
 ├── dashboard/                # Ink/React TUI components
 ├── nextjs/                   # Next.js installer agent
 ├── react/                    # React SPA installer agent

README.md

@@ -470,10 +470,13 @@ The CLI uses WorkOS Connect OAuth device flow for authentication:
 
 ```bash
 # Login (opens browser for authentication)
-workos login
+workos auth login
+
+# Check current auth status
+workos auth status
 
 # Logout (clears stored credentials)
-workos logout
+workos 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.

skills/workos-management/SKILL.md

@@ -5,7 +5,7 @@ description: Manage WorkOS resources (orgs, users, roles, SSO, directories, webh
 
 # WorkOS Management Commands
 
-Use these commands to manage WorkOS resources directly from the terminal. The CLI must be authenticated via `workos login` or `WORKOS_API_KEY` env var.
+Use these commands to manage WorkOS resources directly from the terminal. The CLI must be authenticated via `workos auth login` or `WORKOS_API_KEY` env var.
 
 All commands support `--json` for structured output. Use `--json` when you need to parse output (e.g., extract an ID).
 

src/bin.ts

@@ -28,7 +28,7 @@ if (!satisfies(process.version, NODE_VERSION_RANGE)) {
 }
 
 import { isNonInteractiveEnvironment } from './utils/environment.js';
-import { resolveOutputMode, setOutputMode, outputJson, exitWithError } from './utils/output.js';
+import { resolveOutputMode, setOutputMode, isJsonMode, outputJson, exitWithError } from './utils/output.js';
 import clack from './utils/clack.js';
 import { registerSubcommand } from './utils/register-subcommand.js';
 
@@ -177,8 +177,8 @@ const installerOptions = {
   },
 };
 
-// Check for updates (blocks up to 500ms)
-await checkForUpdates();
+// Check for updates (blocks up to 500ms, skip in JSON mode to keep stdout clean)
+if (!isJsonMode()) await checkForUpdates();
 
 yargs(rawArgs)
   .env('WORKOS_INSTALLER')
@@ -188,16 +188,43 @@ yargs(rawArgs)
     describe: 'Output results as JSON (auto-enabled in non-TTY)',
     global: true,
   })
-  .command('login', 'Authenticate with WorkOS via browser-based OAuth', insecureStorageOption, async (argv) => {
-    await applyInsecureStorage(argv.insecureStorage);
-    const { runLogin } = await import('./commands/login.js');
-    await runLogin();
-    process.exit(0);
-  })
-  .command('logout', 'Remove stored WorkOS credentials and tokens', insecureStorageOption, async (argv) => {
-    await applyInsecureStorage(argv.insecureStorage);
-    const { runLogout } = await import('./commands/logout.js');
-    await runLogout();
+  .command('auth', 'Manage authentication (login, logout, status)', (yargs) => {
+    yargs.options(insecureStorageOption);
+    registerSubcommand(
+      yargs,
+      'login',
+      'Authenticate with WorkOS via browser-based OAuth',
+      (y) => y,
+      async (argv) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { runLogin } = await import('./commands/login.js');
+        await runLogin();
+        process.exit(0);
+      },
+    );
+    registerSubcommand(
+      yargs,
+      'logout',
+      'Remove stored WorkOS credentials and tokens',
+      (y) => y,
+      async (argv) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { runLogout } = await import('./commands/logout.js');
+        await runLogout();
+      },
+    );
+    registerSubcommand(
+      yargs,
+      'status',
+      'Show current authentication status',
+      (y) => y,
+      async (argv) => {
+        await applyInsecureStorage(argv.insecureStorage);
+        const { runAuthStatus } = await import('./commands/auth-status.js');
+        await runAuthStatus();
+      },
+    );
+    return yargs.demandCommand(1, 'Please specify an auth subcommand').strict();
   })
   .command(
     'install-skill',

src/commands/auth-status.ts

@@ -0,0 +1,60 @@
+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';
+
+function formatTimeRemaining(ms: number): string {
+  if (ms <= 0) return 'expired';
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  if (hours > 0) return `${hours}h ${minutes % 60}m`;
+  if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
+  return `${seconds}s`;
+}
+
+export async function runAuthStatus(): Promise<void> {
+  const creds = getCredentials();
+  const activeEnv = getActiveEnvironment();
+
+  if (!creds) {
+    if (isJsonMode()) {
+      outputJson({ authenticated: false });
+      return;
+    }
+    console.log(chalk.yellow('Not logged in'));
+    console.log(chalk.dim('Run `workos auth login` to authenticate'));
+    return;
+  }
+
+  const expired = isTokenExpired(creds);
+  const timeRemaining = creds.expiresAt - Date.now();
+
+  if (isJsonMode()) {
+    outputJson({
+      authenticated: true,
+      email: creds.email ?? null,
+      userId: creds.userId,
+      tokenExpired: expired,
+      tokenExpiresAt: new Date(creds.expiresAt).toISOString(),
+      tokenExpiresIn: expired ? null : formatTimeRemaining(timeRemaining),
+      hasRefreshToken: !!creds.refreshToken,
+      activeEnvironment: activeEnv ? { name: activeEnv.name, type: activeEnv.type } : null,
+    });
+    return;
+  }
+
+  console.log(chalk.green(`Logged in as ${creds.email ?? creds.userId}`));
+
+  if (expired) {
+    console.log(chalk.yellow(`Token expired ${formatTimeRemaining(-timeRemaining)} ago`));
+  } else {
+    console.log(chalk.dim(`Token expires in ${formatTimeRemaining(timeRemaining)}`));
+  }
+
+  console.log(chalk.dim(`Refresh token: ${creds.refreshToken ? 'present' : 'absent'}`));
+
+  if (activeEnv) {
+    console.log(chalk.dim(`Environment: ${activeEnv.name} (${activeEnv.type})`));
+  }
+}

src/commands/login.ts

@@ -1,4 +1,5 @@
 import open from 'opn';
+import chalk from 'chalk';
 import clack from '../utils/clack.js';
 import { saveCredentials, getCredentials, getAccessToken, isTokenExpired, updateTokens } from '../lib/credentials.js';
 import { getCliAuthClientId, getAuthkitDomain } from '../lib/settings.js';
@@ -76,8 +77,8 @@ export async function runLogin(): Promise<void> {
   // Check if already logged in with valid token
   if (getAccessToken()) {
     const creds = getCredentials();
-    clack.log.info(`Already logged in as ${creds?.email ?? 'unknown'}`);
-    clack.log.info('Run `workos logout` to log out');
+    console.log(chalk.green(`Already logged in as ${creds?.email ?? 'unknown'}`));
+    console.log(chalk.dim('Run `workos auth logout` to log out'));
     return;
   }
 
@@ -90,8 +91,8 @@ export async function runLogin(): Promise<void> {
       if (result.accessToken && result.expiresAt) {
         updateTokens(result.accessToken, result.expiresAt, result.refreshToken);
         logInfo('[login] Session refreshed via refresh token');
-        clack.log.info(`Already logged in as ${existingCreds.email ?? 'unknown'}`);
-        clack.log.info('Run `workos logout` to log out');
+        console.log(chalk.green(`Already logged in as ${existingCreds.email ?? 'unknown'}`));
+        console.log(chalk.dim('Run `workos auth logout` to log out'));
         return;
       }
     } catch {

src/doctor/checks/ai-analysis.ts

@@ -61,10 +61,10 @@ 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 login` to re-authenticate');
+    if (!creds.refreshToken) throw new Error('Session expired — run `workos 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 login` to re-authenticate');
+      throw new Error('Session expired — run `workos auth login` to re-authenticate');
     }
     updateTokens(result.accessToken, result.expiresAt, result.refreshToken);
     creds = getCredentials()!;
@@ -111,7 +111,7 @@ export async function checkAiAnalysis(context: AnalysisContext, options: { skipA
       process.stderr.write(`    ${line}\n`);
     }
     process.stderr.write('\n');
-    return skippedResult('Not authenticated — run `workos login` for AI-powered analysis');
+    return skippedResult('Not authenticated — run `workos auth login` for AI-powered analysis');
   }
 
   const startTime = Date.now();

src/lib/adapters/cli-adapter.ts

@@ -406,7 +406,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 logout && workos install');
+      clack.log.info('Try running: workos auth logout && workos install');
     }
     if (message.includes('ENOENT') || message.includes('not found')) {
       clack.log.info('Ensure you are in a project directory');

src/lib/agent-interface.ts

@@ -360,12 +360,12 @@ export async function initializeAgent(config: AgentConfig, options: InstallerOpt
       // Check/refresh authentication for production (unless skipping auth)
       if (!options.skipAuth && !options.local) {
         if (!hasCredentials()) {
-          throw new Error('Not authenticated. Run `workos login` to authenticate.');
+          throw new Error('Not authenticated. Run `workos auth login` to authenticate.');
         }
 
         const creds = getCredentials();
         if (!creds) {
-          throw new Error('Not authenticated. Run `workos login` to authenticate.');
+          throw new Error('Not authenticated. Run `workos auth login` to authenticate.');
         }
 
         // Check if we have refresh token capability and proxy is not disabled
@@ -386,7 +386,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 login` to re-authenticate.',
+                  message: 'Session expired. Run `workos auth login` to re-authenticate.',
                 });
               },
             },
@@ -403,9 +403,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 login` to enable extended sessions');
+            logWarn('[agent-interface] Run `workos auth login` to enable extended sessions');
             options.emitter?.emit('status', {
-              message: 'Note: Run `workos login` to enable extended sessions',
+              message: 'Note: Run `workos auth login` to enable extended sessions',
             });
           } else {
             logWarn('[agent-interface] Proxy disabled via INSTALLER_DISABLE_PROXY');