@zeyos/cli 0.3.0 → 0.5.0

package/README.md

@@ -47,6 +47,9 @@ zeyos whoami --json
 ```
 
 `whoami` does not print access tokens by default. Use `zeyos whoami --show-token --json` only when you intentionally need to pass a token to another local tool.
+If a stored refresh token has expired, interactive `whoami` offers to re-authenticate
+and then retries the user lookup. In `--json`/`--yaml` or non-interactive runs, it
+prints a diagnostic plus the matching `zeyos login --force` command instead.
 
 Inspect the CLI-supported resource registry:
 

package/bin/zeyos.mjs

@@ -6,7 +6,7 @@
  *
  * Commands:
  *   login                Authenticate with ZeyOS
- *   logout               Revoke session and clear tokens
+ *   logout               Revoke session and clear stored credentials
  *   whoami               Show current user info
  *   list <resource>      List records
  *   count <resource>     Count records
@@ -38,7 +38,7 @@ Usage: ${_z} <command> [options] [args…]
 
 ${_c.bold('Commands:')}
   ${_c.cyan('login')}                Authenticate with a ZeyOS instance
-  ${_c.cyan('logout')}               Revoke session and clear stored tokens
+  ${_c.cyan('logout')}               Revoke session and clear stored credentials
   ${_c.cyan('whoami')}               Show currently authenticated user
   ${_c.cyan('list')}   <resource>    List / query records
   ${_c.cyan('count')}  <resource>    Count records (with optional filter)
@@ -51,6 +51,7 @@ ${_c.bold('Commands:')}
   ${_c.cyan('describe')} <resource>  Show a resource's fields, types and enums
   ${_c.cyan('doctor')} agent         Check local CLI readiness for coding agents
   ${_c.cyan('skills')} <command>     List / show / install ZeyOS agent skills
+  ${_c.cyan('okf')} <command>        List / show / check / export the OKF knowledge bundle
   ${_c.cyan('profile')} <command>    Manage credential profiles / switch instances
 
 ${_c.bold('Global options:')}
@@ -120,6 +121,8 @@ const OPTIONS = {
   'target':     { type: 'string' },
   'dir':        { type: 'string' },
   'no-logo':    { type: 'boolean' },
+  // okf
+  'out':        { type: 'string' },
   // profile
   'from-current': { type: 'boolean' },
 };
@@ -147,6 +150,7 @@ const COMMANDS = {
   doctor:    '../commands/doctor.mjs',
   skills:    '../commands/skills.mjs',
   skill:     '../commands/skills.mjs',
+  okf:       '../commands/okf.mjs',
   profile:   '../commands/profile.mjs',
   profiles:  '../commands/profile.mjs',
 };
@@ -158,6 +162,7 @@ const COMMANDS = {
 
 const ALWAYS_FLAGS = ['help', 'json', 'yaml', 'no-color', 'profile'];
 const SKILLS_FLAGS = ['target', 'dir', 'global', 'local', 'force', 'yes', 'no-logo'];
+const OKF_FLAGS    = ['dir', 'out', 'force', 'no-logo'];
 const PROFILE_FLAGS = ['base-url', 'client-id', 'secret', 'local', 'from-current'];
 const DELETE_FLAGS = ['force', 'query'];
 const GET_FLAGS    = ['fields', 'extdata', 'tags', 'expand', 'all', 'query'];
@@ -182,6 +187,7 @@ const COMMAND_FLAGS = {
   doctor:    [],
   skills:    SKILLS_FLAGS,
   skill:     SKILLS_FLAGS,
+  okf:       OKF_FLAGS,
   profile:   PROFILE_FLAGS,
   profiles:  PROFILE_FLAGS,
 };

package/commands/login.mjs

@@ -49,6 +49,10 @@ export async function run(values) {
   const profileName = values.profile || null;
   const scope = values.global ? 'global' : 'local';
   const port  = values.port ? Number(values.port) : DEFAULT_CALLBACK_PORT;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    error('--port must be an integer between 1 and 65535.');
+    process.exit(1);
+  }
   const redirectUri = callbackUri(port);
 
   // Persist either into a named profile or the legacy local/global credential file.

package/commands/logout.mjs

@@ -1,22 +1,28 @@
 /**
  * zeyos logout
  *
- * Revokes the current access token (best-effort) and removes stored tokens
- * from the credential file.  Connection params (baseUrl, clientId, clientSecret)
- * are kept so a subsequent `zeyos login` works without re-entering them.
+ * Revokes the current access token (best-effort) and clears the selected
+ * stored session. Local legacy credentials are cleared completely so a
+ * subsequent `zeyos login` starts from fresh connection parameters.
  *
  * Options:
  *   --global    Clear the global credentials file
  */
 
 import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
-import { loadConfigWithSource, clearTokens, clearTokensForSource } from '../lib/config.mjs';
-import { success, warn, info }                 from '../lib/output.mjs';
+import {
+  loadConfigWithSource,
+  loadGlobalConfig,
+  clearTokensForSource,
+  clearLocalCredentialsForSource,
+  listProfiles
+} from '../lib/config.mjs';
+import { success, warn, info, error }          from '../lib/output.mjs';
 
 export const USAGE = `\
 Usage: zeyos logout [options]
 
-Revoke the current session and clear stored tokens.
+Revoke the current session and clear stored credentials.
 
 Options:
   --profile <name>  Log out of a specific profile
@@ -25,9 +31,29 @@ Options:
 `;
 
 export async function run(values) {
-  const { config, source } = loadConfigWithSource({ profile: values.profile });
+  let config;
+  let source;
+
+  if (values.global) {
+    config = loadGlobalConfig();
+    source = { kind: 'global' };
+  } else {
+    const loaded = loadConfigWithSource({ profile: values.profile });
+    if (loaded.profile?.missing) {
+      const names = Object.keys(listProfiles().profiles);
+      const known = names.length ? `Known profiles: ${names.join(', ')}.` : 'No profiles defined yet.';
+      error(`Profile "${loaded.profile.name}" not found (selected via ${loaded.profile.origin}). ${known}`);
+      process.exit(1);
+    }
+    config = loaded.config;
+    source = loaded.source;
+  }
 
   if (!config.accessToken) {
+    if (source?.kind === 'local' && clearLocalCredentialsForSource(source)) {
+      success('Logged out (local credentials).');
+      return;
+    }
     warn('Not currently logged in.');
     return;
   }
@@ -58,8 +84,8 @@ export async function run(values) {
     }
   }
 
-  if (values.global) {
-    clearTokens('global');
+  if (source?.kind === 'local') {
+    clearLocalCredentialsForSource(source);
   } else {
     clearTokensForSource(source);
   }

package/commands/okf.mjs

@@ -0,0 +1,192 @@
+/**
+ * zeyos okf <list|show|check|build|export>
+ *
+ * Work with the Open Knowledge Format (OKF v0.1) bundle that ships with
+ * @zeyos/client (under okf/): a directory of Markdown concept docs describing the
+ * ZeyOS data model (entities, schema, foreign keys, enums, indexes, operations)
+ * plus curated metrics, playbooks, and query concepts. Consumers — coding agents,
+ * viewers, search — read it; this command lists/shows/validates the shipped bundle
+ * and can synthesize or export one.
+ */
+
+import { readFileSync, existsSync, cpSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+import { loadOkfBundle, validateOkfFiles, buildOkf, OKF_VERSION } from '@zeyos/client';
+import { outputMode, printJson, printYaml, printTable, colors, success, error, info, warn } from '../lib/output.mjs';
+
+const require = createRequire(import.meta.url);
+
+export const USAGE = `\
+Usage: zeyos okf <command> [options]
+
+Commands:
+  list                       List concepts in the OKF bundle (type, id, title)
+  show <concept>             Print a concept doc (e.g. "tickets" or "entities/tickets")
+  check                      Validate the bundle for OKF v0.1 conformance
+  build [--out <dir>]        Synthesize an OKF bundle from the client's schema
+  export [--out <dir>]       Copy the shipped okf/ bundle into a directory
+
+Options:
+  --dir <path>               Read from an explicit bundle directory (list/show/check)
+  --out <path>               Write to this directory (build/export; default ./okf)
+  --force                    Overwrite an existing target (export)
+  --json                     Output as JSON
+  --yaml                     Output as YAML
+  -h, --help                 Show this help
+
+Examples:
+  zeyos okf list
+  zeyos okf show tickets
+  zeyos okf check
+  zeyos okf export --out ./vendor/okf
+  zeyos okf build --out ./okf-live`;
+
+// Locate the okf/ bundle shipped inside the @zeyos/client package (mirrors the
+// skills command's findAgentsDir).
+function findOkfDir() {
+  let entry;
+  try {
+    entry = require.resolve('@zeyos/client');
+  } catch {
+    return null;
+  }
+  let dir = path.dirname(entry);
+  for (let i = 0; i < 6; i++) {
+    const candidate = path.join(dir, 'okf');
+    if (existsSync(path.join(candidate, 'index.md'))) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function expandHome(p) {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(homedir(), p.slice(2));
+  return p;
+}
+
+function displayPath(abs) {
+  const rel = path.relative(process.cwd(), abs);
+  if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) return rel;
+  const home = homedir();
+  if (abs === home || abs.startsWith(home + path.sep)) return '~' + abs.slice(home.length);
+  return abs;
+}
+
+function resolveInputDir(values) {
+  if (values.dir) return path.resolve(expandHome(values.dir));
+  const found = findOkfDir();
+  if (!found) {
+    error('Could not locate the bundled OKF bundle (the @zeyos/client okf/ directory). Pass --dir <path>.');
+    process.exit(1);
+  }
+  return found;
+}
+
+function conceptsToRows(concepts) {
+  return Object.entries(concepts)
+    .map(([id, { frontmatter }]) => ({ type: frontmatter.type || '(none)', concept: id, title: frontmatter.title || '' }))
+    .sort((a, b) => a.concept.localeCompare(b.concept));
+}
+
+async function runList(values) {
+  const dir = resolveInputDir(values);
+  const { version, concepts } = await loadOkfBundle(dir);
+  const rows = conceptsToRows(concepts);
+  const mode = outputMode(values);
+  if (mode === 'json') return printJson({ version, concepts: rows });
+  if (mode === 'yaml') return printYaml({ version, concepts: rows });
+  printTable(rows, ['type', 'concept', 'title']);
+  info(`OKF v${version || OKF_VERSION} — ${rows.length} concepts in ${displayPath(dir)}. Show one with: zeyos okf show <concept>`);
+}
+
+function runShow(values, name) {
+  const dir = resolveInputDir(values);
+  const candidates = [name, `${name}.md`, `entities/${name}.md`, path.join(dir, name), path.join(dir, `${name}.md`), path.join(dir, 'entities', `${name}.md`)];
+  for (const candidate of candidates) {
+    const abs = path.isAbsolute(candidate) ? candidate : path.join(dir, candidate);
+    if (existsSync(abs)) {
+      process.stdout.write(readFileSync(abs, 'utf8'));
+      return;
+    }
+  }
+  error(`Unknown concept "${name}". Run "zeyos okf list".`);
+  process.exit(1);
+}
+
+async function runCheck(values) {
+  const dir = resolveInputDir(values);
+  const { files } = await loadOkfBundle(dir);
+  const result = validateOkfFiles(files);
+  const mode = outputMode(values);
+  if (mode === 'json') { printJson(result); process.exit(result.valid ? 0 : 1); }
+  if (mode === 'yaml') { printYaml(result); process.exit(result.valid ? 0 : 1); }
+  if (result.valid) {
+    success(`OKF bundle is conformant: ${result.conceptCount} concepts, 0 errors (${displayPath(dir)}).`);
+    return;
+  }
+  for (const err of result.errors) error(`${err.path}: ${err.message}`);
+  error(`OKF bundle is NOT conformant: ${result.errors.length} error(s).`);
+  process.exit(1);
+}
+
+function writeBundle(outDir, files) {
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(outDir, rel);
+    mkdirSync(path.dirname(abs), { recursive: true });
+    writeFileSync(abs, content, 'utf8');
+  }
+}
+
+function runBuild(values) {
+  const outDir = path.resolve(expandHome(values.out || 'okf'));
+  const files = buildOkf();
+  writeBundle(outDir, files);
+  const mode = outputMode(values);
+  const summary = { out: outDir, files: Object.keys(files).length };
+  if (mode === 'json') return printJson(summary);
+  if (mode === 'yaml') return printYaml(summary);
+  success(`Synthesized ${summary.files} OKF files → ${displayPath(outDir)}`);
+  info('This is the runtime projection from the client schema (structural only). The shipped okf/ bundle adds curated metrics, playbooks, and notes.');
+}
+
+function runExport(values) {
+  const dir = resolveInputDir(values);
+  const outDir = path.resolve(expandHome(values.out || 'okf'));
+  if (existsSync(outDir) && !values.force) {
+    if (path.resolve(dir) === outDir) {
+      warn(`Source and target are the same (${displayPath(outDir)}); nothing to do.`);
+      return;
+    }
+    error(`Target ${displayPath(outDir)} already exists. Use --force to overwrite.`);
+    process.exit(1);
+  }
+  cpSync(dir, outDir, { recursive: true });
+  const mode = outputMode(values);
+  const summary = { from: dir, out: outDir };
+  if (mode === 'json') return printJson(summary);
+  if (mode === 'yaml') return printYaml(summary);
+  success(`Exported OKF bundle → ${displayPath(outDir)}`);
+}
+
+export async function run(values, positional = []) {
+  const sub = positional[0] || 'list';
+  const rest = positional.slice(1);
+  switch (sub) {
+    case 'list': return runList(values);
+    case 'show':
+      if (!rest[0]) { error('Usage: zeyos okf show <concept>'); process.exit(1); }
+      return runShow(values, rest[0]);
+    case 'check': return runCheck(values);
+    case 'build': return runBuild(values);
+    case 'export': return runExport(values);
+    default:
+      error(`Unknown okf command "${sub}".\n\n${USAGE}`);
+      process.exit(1);
+  }
+}

package/commands/profile.mjs

@@ -14,6 +14,7 @@
  * the credentials currently in effect (including tokens) into the new profile.
  */
 
+import { createInterface } from 'node:readline';
 import {
   listProfiles, getProfile, upsertProfile, removeProfile,
   setActiveProfile, writeLocalPin, readLocalPin,
@@ -31,7 +32,7 @@ Commands:
   current                    Show which profile is in effect, and why
   use <name>                 Make <name> the active profile (global)
   use <name> --local         Pin <name> to the current project (.zeyos/profile)
-  add <name> [options]       Create or update a profile
+  add [<name>] [options]     Create or update a profile; prompts when run without connection options
   remove <name>              Delete a profile
 
 Add options:
@@ -45,6 +46,7 @@ Global options:
   -h, --help                 Show this help
 
 Examples:
+  zeyos profile add                         # prompt for name and connection params
   zeyos profile add dev  --base-url https://zeyos.cms-it.de/dev
   zeyos profile add prod --from-current
   zeyos profile use prod
@@ -147,30 +149,42 @@ function cmdUse(values, name) {
 
 // ── add ────────────────────────────────────────────────────────────────────────
 
-function cmdAdd(values, name) {
-  if (!name) fail('Usage: zeyos profile add <name> [--base-url <url>] [--client-id <id>] [--secret <secret>] | --from-current');
+async function cmdAdd(values, name) {
+  let promptSession = null;
+  const ask = (question, opts) => {
+    promptSession ??= createPromptSession();
+    return promptSession.ask(question, opts);
+  };
 
-  let updates = {};
-  if (values['from-current']) {
-    const cfg = loadConfigWithSource().config; // whatever is in effect right now
-    for (const k of ['baseUrl', 'instance', 'clientId', 'clientSecret', 'accessToken', 'refreshToken', 'expiresAt', 'refreshTokenExpiresAt']) {
-      if (cfg[k] != null) updates[k] = cfg[k];
-    }
-    if (!updates.baseUrl) fail('Nothing to snapshot: no credentials are currently in effect.');
-  } else {
-    if (values['base-url'])  updates.baseUrl      = values['base-url'];
-    if (values['client-id']) updates.clientId     = values['client-id'];
-    if (values.secret)       updates.clientSecret = values.secret;
-    if (Object.keys(updates).length === 0) {
-      fail('Provide at least --base-url (and ideally --client-id/--secret), or use --from-current.');
+  try {
+    const profileName = name || await ask('Profile name');
+    if (!profileName) fail('Profile name is required.');
+
+    let updates = {};
+    if (values['from-current']) {
+      const cfg = loadConfigWithSource().config; // whatever is in effect right now
+      for (const k of ['baseUrl', 'instance', 'clientId', 'clientSecret', 'accessToken', 'refreshToken', 'expiresAt', 'refreshTokenExpiresAt']) {
+        if (cfg[k] != null) updates[k] = cfg[k];
+      }
+      if (!updates.baseUrl) fail('Nothing to snapshot: no credentials are currently in effect.');
+    } else {
+      if (values['base-url'])  updates.baseUrl      = values['base-url'];
+      if (values['client-id']) updates.clientId     = values['client-id'];
+      if (values.secret)       updates.clientSecret = values.secret;
+
+      if (Object.keys(updates).length === 0) {
+        updates = await promptProfileCredentials(profileName, ask);
+      }
     }
-  }
 
-  const existed = Boolean(getProfile(name));
-  upsertProfile(name, updates);
-  success(`${existed ? 'Updated' : 'Created'} profile "${name}".`);
-  if (!updates.accessToken) {
-    info(`Finish authenticating with:  zeyos login --profile ${name}`);
+    const existed = Boolean(getProfile(profileName));
+    upsertProfile(profileName, updates);
+    success(`${existed ? 'Updated' : 'Created'} profile "${profileName}".`);
+    if (!updates.accessToken) {
+      info(`Finish authenticating with:  zeyos login --profile ${profileName}`);
+    }
+  } finally {
+    promptSession?.close();
   }
 }
 
@@ -209,3 +223,84 @@ function fail(message) {
   error(message);
   process.exit(1);
 }
+
+async function promptProfileCredentials(name, ask) {
+  const existing = getProfile(name) || {};
+
+  info(`Creating profile "${name}".`);
+  info('This stores the platform and OAuth app credentials; tokens are added by login.');
+  console.error('');
+
+  const baseUrl = await ask('ZeyOS platform URL', { currentValue: existing.baseUrl });
+  const clientId = await ask('Application ID', { currentValue: existing.clientId });
+  const clientSecret = await ask('Application secret', { currentValue: existing.clientSecret, secret: true });
+
+  if (!baseUrl || !clientId || !clientSecret) {
+    fail('ZeyOS URL, application ID and secret are all required.');
+  }
+
+  return { baseUrl, clientId, clientSecret };
+}
+
+function createPromptSession() {
+  const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: process.stdin.isTTY && process.stderr.isTTY });
+  const originalWrite = rl._writeToOutput.bind(rl);
+  let hiddenPrompt = null;
+  let closed = false;
+  const queuedLines = [];
+  const waitingResolvers = [];
+
+  rl.on('line', (line) => {
+    const resolve = waitingResolvers.shift();
+    if (resolve) {
+      resolve(line);
+    } else {
+      queuedLines.push(line);
+    }
+  });
+
+  rl.on('close', () => {
+    closed = true;
+    let resolve;
+    while ((resolve = waitingResolvers.shift())) {
+      resolve('');
+    }
+  });
+
+  rl._writeToOutput = (value) => {
+    if (!hiddenPrompt || String(value).includes(hiddenPrompt) || value === '\n' || value === '\r\n') {
+      originalWrite(value);
+    }
+  };
+
+  const readLine = () => {
+    if (queuedLines.length) {
+      return Promise.resolve(queuedLines.shift());
+    }
+    if (closed) {
+      return Promise.resolve('');
+    }
+    return new Promise(resolve => {
+      waitingResolvers.push(resolve);
+    });
+  };
+
+  return {
+    ask(question, opts = {}) {
+      const currentValue = opts.currentValue || '';
+      const defaultLabel = opts.secret && currentValue ? 'stored, press Enter to keep' : currentValue;
+      const prompt = defaultLabel ? `${question} [${defaultLabel}]` : question;
+      hiddenPrompt = opts.secret && process.stdin.isTTY && process.stderr.isTTY ? prompt : null;
+      process.stderr.write(`${prompt}: `);
+
+      return readLine()
+        .then(answer => {
+          hiddenPrompt = null;
+          return answer.trim() || currentValue || '';
+        });
+    },
+    close() {
+      rl.close();
+    }
+  };
+}

package/commands/whoami.mjs

@@ -9,8 +9,11 @@
  *   --show-token Include the current access token in output
  */
 
+import { createInterface } from 'node:readline';
 import { buildClient, syncTokens } from '../lib/client.mjs';
+import { globalConfigPath, profilesConfigPath } from '../lib/config.mjs';
 import { outputMode, printJson, printYaml, printRecord, formatDate, error } from '../lib/output.mjs';
+import { run as runLogin } from './login.mjs';
 
 export const USAGE = `\
 Usage: zeyos whoami [options]
@@ -25,35 +28,23 @@ Options:
 `;
 
 export async function run(values) {
-  let client, config, tokenStore, configSource;
-  try {
-    ({ client, config, tokenStore, configSource } = buildClient({}, { profile: values.profile }));
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
-  }
+  let state = _buildClientState(values);
 
   let userInfo;
   try {
-    userInfo = await client.oauth2.getUserInfo();
-    await syncTokens(tokenStore, configSource);
+    userInfo = await _fetchUserInfo(state);
   } catch (err) {
-    const status = err?.status;
-    if (status === 502 || status === 503 || status === 504) {
-      error(`ZeyOS instance is temporarily unavailable (HTTP ${status}). The server at ${config.baseUrl} may be down or restarting — this is server-side, not your credentials.`);
-    } else if (status === 401) {
-      error('Your session has expired or is invalid. Re-authenticate with: zeyos login --force');
-    } else {
-      error(`Failed to fetch user info: ${err.message}`);
-    }
-    process.exit(1);
+    const handled = await _handleFetchError(err, state, values);
+    if (!handled) process.exit(1);
+    state = handled.state;
+    userInfo = handled.userInfo;
   }
 
   const mode = outputMode(values);
 
   const output = { ...userInfo };
   if (values['show-token']) {
-    const tokenSet = await tokenStore.get();
+    const tokenSet = await state.tokenStore.get();
     if (tokenSet?.accessToken) output.accessToken = tokenSet.accessToken;
   }
 
@@ -63,7 +54,7 @@ export async function run(values) {
     printYaml(output);
   } else {
     // Pretty key-value record with custom formatters
-    const dateFormat = config.dateFormat ?? 'YYYY-MM-DD HH:mm';
+    const dateFormat = state.config.dateFormat ?? 'YYYY-MM-DD HH:mm';
     const keys = Object.keys(output);
     const formatters = {};
 
@@ -86,6 +77,56 @@ export async function run(values) {
   }
 }
 
+function _buildClientState(values) {
+  try {
+    const state = buildClient({}, { profile: values.profile });
+    return {
+      client: state.client,
+      config: state.config,
+      tokenStore: state.tokenStore,
+      configSource: state.configSource
+    };
+  } catch (err) {
+    error(err.message);
+    process.exit(1);
+  }
+}
+
+async function _fetchUserInfo(state) {
+  const userInfo = await state.client.oauth2.getUserInfo();
+  await syncTokens(state.tokenStore, state.configSource);
+  return userInfo;
+}
+
+async function _handleFetchError(err, state, values) {
+  const status = err?.status;
+  if (status === 502 || status === 503 || status === 504) {
+    error(`ZeyOS instance is temporarily unavailable (HTTP ${status}). The server at ${state.config.baseUrl} may be down or restarting — this is server-side, not your credentials.`);
+    return null;
+  }
+
+  const authFailure = _authFailureSummary(err);
+  if (!authFailure) {
+    error(`Failed to fetch user info: ${err.message}`);
+    return null;
+  }
+
+  error(_formatAuthFailure(authFailure, err, state.config, state.configSource, values));
+  const reauthenticated = await _maybeReauthenticate(state.configSource, values);
+  if (!reauthenticated) return null;
+
+  const nextState = _buildClientState(values);
+  try {
+    return {
+      state: nextState,
+      userInfo: await _fetchUserInfo(nextState)
+    };
+  } catch (retryErr) {
+    error(`Re-authentication completed, but fetching user info still failed: ${retryErr.message}`);
+    return null;
+  }
+}
+
 /**
  * Format an array of objects as a multi-line list.
  * Each item is shown as "name (rw)" or "name (ro)" on its own line.
@@ -105,3 +146,145 @@ function _formatObjectList(items, nameKey, writableKey) {
     })
     .join('\n');
 }
+
+function _isInvalidRefreshTokenError(err) {
+  const detail = `${err?.message ?? ''}\n${_stringifyErrorBody(err?.body)}`;
+  return [400, 401, 403].includes(err?.status) &&
+    /refresh[_ -]?token|invalid_grant/i.test(detail) &&
+    /invalid|expired|forbidden|invalid_grant/i.test(detail);
+}
+
+function _authFailureSummary(err) {
+  if (_isInvalidRefreshTokenError(err)) {
+    return 'Your stored refresh token is invalid or expired.';
+  }
+  if (err?.status === 401) {
+    return 'Your session has expired or is invalid.';
+  }
+  return null;
+}
+
+function _formatAuthFailure(summary, err, config, source, values) {
+  const lines = [
+    summary,
+    `Platform URL: ${config.baseUrl ?? '(not configured)'}`,
+    `Credential source: ${_describeConfigSource(source)}`
+  ];
+
+  if (err?.url) {
+    lines.push(`OAuth endpoint: ${err.url}`);
+  }
+  if (err?.status) {
+    lines.push(`HTTP status: ${err.status}${err.statusText ? ` ${err.statusText}` : ''}`);
+  }
+
+  const detail = _authErrorDetail(err);
+  if (detail) {
+    lines.push(`OAuth error: ${detail}`);
+  }
+
+  lines.push(`Next step: ${_loginCommand(source, values)}`);
+  if (process.env.ZEYOS_TOKEN || process.env.ZEYOS_REFRESH_TOKEN) {
+    lines.push('Note: ZEYOS_TOKEN or ZEYOS_REFRESH_TOKEN is set and overrides stored credentials; update or unset it before retrying.');
+  }
+  return lines.join('\n');
+}
+
+function _describeConfigSource(source) {
+  if (!source) {
+    return 'environment variables';
+  }
+  if (source.kind === 'profile') {
+    return `profile "${source.name}" (${profilesConfigPath()})`;
+  }
+  if (source.kind === 'global') {
+    return `global credentials (${globalConfigPath()})`;
+  }
+  if (source.kind === 'local') {
+    return `local file ${source.path ?? '.zeyos/auth.json'}`;
+  }
+  return source.kind ?? 'unknown';
+}
+
+function _loginCommand(source, values) {
+  const profile = values.profile ?? (source?.kind === 'profile' ? source.name : null);
+  if (profile) {
+    return `zeyos login --profile ${_quoteArg(profile)} --force`;
+  }
+  if (source?.kind === 'global') {
+    return 'zeyos login --global --force';
+  }
+  return 'zeyos login --force';
+}
+
+async function _maybeReauthenticate(source, values) {
+  if (!_canPromptForReauthentication(source, values)) {
+    return false;
+  }
+
+  const command = _loginCommand(source, values);
+  const confirmed = await _confirm(`Re-authenticate now (${command})? [y/N] `);
+  if (!confirmed) return false;
+
+  await runLogin(_loginValues(source, values));
+  return true;
+}
+
+function _canPromptForReauthentication(source, values) {
+  return Boolean(source) &&
+    !values.json &&
+    !values.yaml &&
+    process.stdin.isTTY &&
+    process.stderr.isTTY &&
+    !process.env.ZEYOS_TOKEN &&
+    !process.env.ZEYOS_REFRESH_TOKEN;
+}
+
+function _loginValues(source, values) {
+  return {
+    ...values,
+    force: true,
+    profile: values.profile ?? (source?.kind === 'profile' ? source.name : undefined),
+    global: source?.kind === 'global' ? true : values.global
+  };
+}
+
+function _confirm(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise(resolve => {
+    rl.question(prompt, answer => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+function _authErrorDetail(err) {
+  const body = _stringifyErrorBody(err?.body).trim();
+  if (body) {
+    return body;
+  }
+  return String(err?.message ?? '').trim();
+}
+
+function _stringifyErrorBody(body) {
+  if (body == null) {
+    return '';
+  }
+  if (typeof body === 'string') {
+    return body;
+  }
+  try {
+    return JSON.stringify(body);
+  } catch {
+    return String(body);
+  }
+}
+
+function _quoteArg(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(text)) {
+    return text;
+  }
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}

package/lib/config.mjs

@@ -187,6 +187,21 @@ export function clearTokens(scope = 'local') {
   if (path) _writeJson(path, _stripTokens(_readJson(path)));
 }
 
+/** Remove all credential/session fields from the resolved legacy local auth file. */
+export function clearLocalCredentialsForSource(source) {
+  if (!source || source.kind !== 'local') return false;
+  const path = source.path ?? _findLocalPath();
+  if (!path) return false;
+
+  const current = _readJson(path);
+  const hadCredentials = CRED_KEYS.some((key) => Object.prototype.hasOwnProperty.call(current, key));
+  if (!hadCredentials) return false;
+
+  const next = _stripCredentials(current);
+  _writeJson(path, next);
+  return true;
+}
+
 /**
  * Persist refreshed tokens back to wherever the active credentials came from.
  * @param {ConfigSource|null} source
@@ -325,6 +340,11 @@ export function localConfigPath() { return _findLocalPath(); }
 export function globalConfigPath() { return GLOBAL_FILE; }
 export function profilesConfigPath() { return PROFILES_FILE; }
 
+/** Read the legacy global credentials file directly, without applying the cascade. */
+export function loadGlobalConfig() {
+  return _readGlobal();
+}
+
 // ── Internals ────────────────────────────────────────────────────────────────
 
 function _fromEnv() {
@@ -368,6 +388,14 @@ function _stripTokens(o) {
   return rest;
 }
 
+function _stripCredentials(o) {
+  const out = { ...o };
+  for (const key of CRED_KEYS) {
+    delete out[key];
+  }
+  return out;
+}
+
 function _readGlobal() {
   return existsSync(GLOBAL_FILE) ? _readJson(GLOBAL_FILE) : {};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Command-line interface for the ZeyOS API",
   "type": "module",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "node": ">=18.3"
   },
   "dependencies": {
-    "@zeyos/client": "^0.3.0"
+    "@zeyos/client": "^0.5.0"
   },
   "scripts": {
     "test": "node --test test/offline.mjs"