@zeyos/cli 0.1.1 → 0.3.0

package/config/message.json

@@ -0,0 +1,20 @@
+{
+  "list": {
+    "fields": {
+      "ID": "ID",
+      "Date": "date",
+      "Mailbox": "mailbox",
+      "Subject": "subject",
+      "From": "sender_email",
+      "To": "to_email",
+      "Ticket": "ticket",
+      "Opportunity": "opportunity",
+      "Reference": "reference",
+      "Message-ID": "messageid"
+    }
+  },
+  "get": {
+    "fields": ["ID", "date", "mailbox", "subject", "sender", "sender_email", "sender_name", "to", "to_email", "to_name", "cc", "bcc", "ticket", "opportunity", "reference", "messageid", "contenttype", "text", "attachments", "senddate", "senderror", "creationdate", "lastmodified"],
+    "params": { "extdata": 1 }
+  }
+}

package/config/task.json

@@ -8,11 +8,13 @@
       "Priority": "priority",
       "Agent": "assigneduser.name",
       "Due": "duedate",
-      "Ticket": "ticket"
+      "Ticket": "ticket",
+      "Project": "project",
+      "Projected": "projectedeffort"
     }
   },
   "get": {
-    "fields": ["ID", "tasknum", "name", "description", "status", "priority", "duedate", "ticket", "creator", "created", "lastmodified"],
+    "fields": ["ID", "tasknum", "name", "description", "status", "priority", "datefrom", "duedate", "ticket", "project", "projectedeffort", "assigneduser", "creator", "creationdate", "lastmodified"],
     "params": { "extdata": 1 }
   }
 }

package/config/ticket.json

@@ -7,13 +7,14 @@
       "Status": "status",
       "Priority": "priority",
       "Account": "account.lastname",
+      "Project": "project",
       "Agent": "assigneduser.name",
       "Due": "duedate",
       "Modified": "lastmodified"
     }
   },
   "get": {
-    "fields": ["ID", "ticketnum", "name", "description", "status", "priority", "duedate", "created", "creator", "lastmodified"],
+    "fields": ["ID", "ticketnum", "name", "description", "status", "priority", "duedate", "account", "project", "assigneduser", "creator", "creationdate", "lastmodified"],
     "params": { "extdata": 1 }
   }
 }

package/lib/client.mjs

@@ -3,7 +3,7 @@
  * Also provides a helper that persists refreshed tokens back to the config file.
  */
 import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
-import { loadConfigWithSource, saveConfig, requireConfig } from './config.mjs';
+import { loadConfigWithSource, persistTokens, requireConfig, listProfiles } from './config.mjs';
 
 /** @typedef {import('./types.mjs').CliConfig} CliConfig */
 
@@ -12,10 +12,16 @@ import { loadConfigWithSource, saveConfig, requireConfig } from './config.mjs';
  * Throws a friendly error if required config keys are missing.
  *
  * @param {CliConfig} [overrides]  Extra config values (e.g. from CLI flags)
- * @returns {{ client: ReturnType<typeof createZeyosClient>, config: CliConfig, tokenStore: MemoryTokenStore, configSource: 'local'|'global'|null }}
+ * @param {{ profile?: string }} [opts]  Profile selector (from --profile / ZEYOS_PROFILE)
+ * @returns {{ client: ReturnType<typeof createZeyosClient>, config: CliConfig, tokenStore: MemoryTokenStore, configSource: import('./config.mjs').ConfigSource|null }}
  */
-export function buildClient(overrides = {}) {
-  const loaded = loadConfigWithSource();
+export function buildClient(overrides = {}, opts = {}) {
+  const loaded = loadConfigWithSource({ profile: opts.profile });
+  if (loaded.profile?.missing) {
+    const names = Object.keys(listProfiles().profiles);
+    const known = names.length ? `Known profiles: ${names.join(', ')}.` : 'No profiles defined yet — create one with `zeyos profile add <name>`.';
+    throw new Error(`Profile "${loaded.profile.name}" not found (selected via ${loaded.profile.origin}). ${known}`);
+  }
   const config = { ...loaded.config, ...overrides };
   requireConfig(['baseUrl', 'clientId', 'clientSecret', 'accessToken'], config);
 
@@ -43,25 +49,28 @@ export function buildClient(overrides = {}) {
 }
 
 /**
- * Persist any refreshed tokens back to the credential store.
+ * Persist any refreshed tokens back to the credential store the config came from
+ * (a named profile, the legacy local auth.json, or the legacy global file).
  * Call this after API operations to keep tokens up-to-date.
  *
  * @param {MemoryTokenStore} tokenStore
- * @param {'local'|'global'|null} scope
+ * @param {import('./config.mjs').ConfigSource|'local'|'global'|null} source
  */
-export async function syncTokens(tokenStore, scope = 'local') {
-  if (!scope) {
+export async function syncTokens(tokenStore, source = 'local') {
+  if (!source) {
     return;
   }
+  // Back-compat: a bare 'local'/'global' string still works.
+  const resolved = typeof source === 'string' ? { kind: source } : source;
   try {
     const ts = await tokenStore.get();
     if (ts?.accessToken) {
-      saveConfig({
+      persistTokens(resolved, {
         accessToken:           ts.accessToken,
         refreshToken:          ts.refreshToken,
         expiresAt:             ts.expiresAt,
         refreshTokenExpiresAt: ts.refreshTokenExpiresAt,
-      }, scope);
+      });
     }
   } catch {
     // non-critical

package/lib/command.mjs

@@ -1,7 +1,9 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { buildClient, syncTokens } from './client.mjs';
 import { collectFieldFlags } from './flags.mjs';
 import { resolveResource } from './resources.mjs';
-import { error, info, warn } from './output.mjs';
+import { error, info, warn, printQuery } from './output.mjs';
 
 export function fail(message) {
   error(message);
@@ -31,9 +33,9 @@ export function requireRecordId(id, usage) {
   }
 }
 
-export function buildCliClient() {
+export function buildCliClient(values = {}) {
   try {
-    return buildClient();
+    return buildClient({}, { profile: values.profile });
   } catch (err) {
     fail(err.message);
   }
@@ -49,6 +51,54 @@ export function parseJsonOption(value, flagName) {
   }
 }
 
+export function parseJsonFileOption(value, flagName) {
+  if (value == null || value === '') {
+    fail(`--${flagName} requires a file path.`);
+  }
+
+  const filePath = String(value);
+  const absolutePath = resolve(process.cwd(), filePath);
+  let text;
+
+  try {
+    text = readFileSync(absolutePath, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      fail(`--${flagName} file not found: ${filePath}`);
+    }
+    if (err?.code === 'EISDIR') {
+      fail(`--${flagName} points to a directory, not a JSON file: ${filePath}`);
+    }
+    fail(`Could not read --${flagName} file ${filePath}: ${err.message || err}`);
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    fail(`--${flagName} file must contain valid JSON: ${filePath} (${err.message || err})`);
+  }
+}
+
+export function parseJsonOptionOrFile(values, flagName, fileFlagName = `${flagName}-file`) {
+  const hasInline = Object.prototype.hasOwnProperty.call(values, flagName);
+  const hasFile = Object.prototype.hasOwnProperty.call(values, fileFlagName);
+
+  if (hasInline && hasFile) {
+    fail(`Use either --${flagName} or --${fileFlagName}, not both.`);
+  }
+  if (hasInline) {
+    if (values[flagName] === '') {
+      fail(`--${flagName} requires a JSON value. Use --${fileFlagName} <path> for file input.`);
+    }
+    return parseJsonOption(values[flagName], flagName);
+  }
+  if (hasFile) {
+    return parseJsonFileOption(values[fileFlagName], fileFlagName);
+  }
+
+  return undefined;
+}
+
 /** Cheap structural check: does this string look like an intended JSON object? */
 function looksLikeJsonObject(value) {
   return typeof value === 'string' && value.trim().startsWith('{');
@@ -90,7 +140,7 @@ function tryParseJsonObject(value) {
  * @returns {Record<string, unknown>}
  */
 export function buildRecordPayload(values, positionalData) {
-  const parsed = parseJsonOption(values.data, 'data');
+  const parsed = parseJsonOptionOrFile(values, 'data', 'data-file');
   const data = parsed === undefined ? {} : parsed;
 
   if (!data || typeof data !== 'object' || Array.isArray(data)) {
@@ -125,6 +175,31 @@ export function buildRecordPayload(values, positionalData) {
   fail('No fields provided.  Use --data or individual --<field> flags.');
 }
 
+/**
+ * Handle the global `--query` flag: instead of sending the request, ask the
+ * client to resolve the route + payload (dry run) and print them. Returns
+ * `true` when it handled a dry run, so the caller can `return` early.
+ *
+ * @param {ReturnType<typeof buildCliClient>} clientState
+ * @param {string} operationId
+ * @param {unknown} input - the same input the real call would receive
+ * @param {Record<string, unknown>} values - parsed CLI flags
+ * @returns {Promise<boolean>}
+ */
+export async function maybeDryRun(clientState, operationId, input, values) {
+  if (!values.query) return false;
+
+  const fn = requireApiMethod(clientState, operationId);
+  let descriptor;
+  try {
+    descriptor = await fn(input, { dryRun: true });
+  } catch (err) {
+    fail(`Could not build request: ${err.message}`);
+  }
+  printQuery(descriptor, values);
+  return true;
+}
+
 export function requireApiMethod(clientState, operationId) {
   const fn = clientState.client.api[operationId];
   if (typeof fn !== 'function') {

package/lib/config.mjs

@@ -1,52 +1,142 @@
 /**
- * Credential configuration — cascade:
- *   1. Environment variables  (ZEYOS_BASE_URL, ZEYOS_TOKEN, …)
- *   2. .zeyos/auth.json       (walk up from CWD, like .gitconfig)
- *   3. ~/.config/zeyos/credentials.json
+ * Credential configuration with named profiles.
  *
- * The auth file stores connection params AND tokens.
- * Add .zeyos/auth.json to .gitignore.
+ * A "profile" is a full credential set (baseUrl, clientId, clientSecret, tokens)
+ * stored under a name. Profiles live in a global registry; a project can pin which
+ * profile it uses. The legacy single-file layout still works unchanged.
+ *
+ * Resolution cascade (first match decides which credential set is the base):
+ *   1. --profile <name>            (CLI flag)            -> named profile
+ *   2. ZEYOS_PROFILE               (env var)             -> named profile
+ *   3. .zeyos/profile              (project pin, walked up) -> named profile
+ *   4. .zeyos/auth.json            (legacy local, walked up)
+ *   5. profiles.json "active"      (global active profile)
+ *   6. ~/.config/zeyos/credentials.json  (legacy global)
+ * Environment credential vars (ZEYOS_BASE_URL, ZEYOS_TOKEN, …) always field-merge
+ * on top of whichever base was chosen.
+ *
+ * Add .zeyos/auth.json and .zeyos/profile to .gitignore.
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 
 /** @typedef {import('./types.mjs').CliConfig} CliConfig */
+/** @typedef {{ kind: 'profile'|'local'|'global', name?: string, path?: string }} ConfigSource */
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
-const LOCAL_DIR   = '.zeyos';
-const LOCAL_FILE  = 'auth.json';
-const GLOBAL_DIR  = join(homedir(), '.config', 'zeyos');
-const GLOBAL_FILE = join(GLOBAL_DIR, 'credentials.json');
+const LOCAL_DIR    = '.zeyos';
+const LOCAL_FILE   = 'auth.json';
+const PIN_FILE     = 'profile';
+const GLOBAL_DIR   = join(homedir(), '.config', 'zeyos');
+const GLOBAL_FILE  = join(GLOBAL_DIR, 'credentials.json');
+const PROFILES_FILE = join(GLOBAL_DIR, 'profiles.json');
+
+/** Credential fields that make up a profile / auth file. */
+const CRED_KEYS = [
+  'baseUrl', 'instance', 'clientId', 'clientSecret',
+  'accessToken', 'refreshToken', 'expiresAt', 'refreshTokenExpiresAt'
+];
+const TOKEN_KEYS = ['accessToken', 'refreshToken', 'expiresAt', 'refreshTokenExpiresAt'];
 
 // ── Load ─────────────────────────────────────────────────────────────────────
 
 /**
  * Load the full config object using the cascade.
- * Returns a merged object; env vars always win over file values.
+ * @param {{ profile?: string }} [opts]
  */
-export function loadConfig() {
-  return loadConfigWithSource().config;
+export function loadConfig(opts = {}) {
+  return loadConfigWithSource(opts).config;
 }
 
 /**
- * Load config and identify the credential file scope that should receive
- * refreshed tokens. Local config overrides global config field-by-field, so a
- * partial local file cannot shadow global connection parameters.
+ * Load config and identify the credential store that should receive refreshed
+ * tokens (the `source`). Env credential vars field-merge on top of the resolved
+ * base so they always win.
+ *
+ * @param {{ profile?: string }} [opts]
+ * @returns {{ config: CliConfig, source: ConfigSource|null, profile: { name: string, origin: string }|null }}
  */
-export function loadConfigWithSource() {
-  const localPath = _findLocalPath();
-  const globalFile = _readGlobal();
-  const localFile = localPath ? _readJson(localPath) : {};
+export function loadConfigWithSource(opts = {}) {
   const env = _fromEnv();
+  const selection = resolveProfileSelection({ profileFlag: opts.profile });
+
+  let base = {};
+  let source = null;
+
+  if (selection.name) {
+    // An explicit/active profile was selected (flag, env, pin, or active pointer).
+    const prof = getProfile(selection.name);
+    base = prof ?? {};
+    source = { kind: 'profile', name: selection.name };
+    // selection.missing is surfaced via resolveProfileSelection consumers; base
+    // stays {} so requireConfig reports the missing fields.
+  } else {
+    // No named profile in play — fall back to the legacy single-file layout.
+    const localPath = _findLocalPath();
+    if (localPath) {
+      base = _readJson(localPath);
+      source = { kind: 'local', path: localPath };
+    } else if (existsSync(GLOBAL_FILE)) {
+      base = _readGlobal();
+      source = { kind: 'global' };
+    }
+  }
 
   return {
-    config: { ...globalFile, ...localFile, ...env },
-    source: localPath ? 'local' : (existsSync(GLOBAL_FILE) ? 'global' : null)
+    config: { ...base, ...env },
+    source,
+    profile: selection.name
+      ? { name: selection.name, origin: selection.origin, missing: Boolean(selection.missing) }
+      : null
   };
 }
 
+/**
+ * Decide which profile name applies, and where the decision came from.
+ * Order: flag > ZEYOS_PROFILE env > project pin (.zeyos/profile) > global active.
+ * `.zeyos/auth.json` (legacy local) deliberately sits BELOW the pin but is handled
+ * in loadConfigWithSource (it is not a named profile).
+ *
+ * @param {{ profileFlag?: string }} [opts]
+ * @returns {{ name: string|null, origin: 'flag'|'env'|'pin'|'active'|null, path?: string, missing?: boolean }}
+ */
+export function resolveProfileSelection(opts = {}) {
+  const flag = opts.profileFlag;
+  if (flag) return _withExistence({ name: flag, origin: 'flag' });
+
+  const envName = process.env.ZEYOS_PROFILE;
+  if (envName) return _withExistence({ name: envName, origin: 'env' });
+
+  const pin = readLocalPin();
+  // A pin only selects a named profile if there is NO legacy local auth.json that
+  // sits closer to the cwd (legacy projects keep working). When both exist at the
+  // same place the explicit pin wins.
+  if (pin) {
+    const localPath = _findLocalPath();
+    if (!localPath || _isSameOrShallower(pin.dir, localPath)) {
+      return _withExistence({ name: pin.name, origin: 'pin', path: pin.path });
+    }
+  }
+
+  // If a legacy local auth.json exists, it (not the global active profile) is the
+  // base — handled by the caller. Only fall through to the active profile when no
+  // local file shadows it.
+  if (_findLocalPath()) return { name: null, origin: null };
+
+  const active = getActiveProfileName();
+  if (active) return _withExistence({ name: active, origin: 'active' });
+
+  return { name: null, origin: null };
+}
+
+function _withExistence(sel) {
+  return { ...sel, missing: getProfile(sel.name) == null };
+}
+
+// ── Require ──────────────────────────────────────────────────────────────────
+
 /**
  * Require specific keys to be present; throws a human-friendly error if not.
  * @param {string[]} keys
@@ -67,12 +157,11 @@ export function requireConfig(keys, config) {
   throw new Error(`Missing required configuration:\n${messages.join('\n')}`);
 }
 
-// ── Save ─────────────────────────────────────────────────────────────────────
+// ── Save (legacy single-file) ─────────────────────────────────────────────────
 
 /**
- * Save (merge) config values into the nearest .zeyos/auth.json found while
- * walking up, or create one in the current directory.  Falls back to the
- * global file when `scope === 'global'`.
+ * Save (merge) config values into the nearest .zeyos/auth.json (or create one in
+ * the current directory), or the global credentials file when scope === 'global'.
  *
  * @param {CliConfig} updates
  * @param {'local'|'global'} scope
@@ -90,39 +179,163 @@ export function saveConfig(updates, scope = 'local') {
 
 /** Remove the stored tokens (leave connection params intact). */
 export function clearTokens(scope = 'local') {
-  const strip = o => {
-    const { accessToken, refreshToken, expiresAt, refreshTokenExpiresAt, ...rest } = o;
-    return rest;
-  };
   if (scope === 'global') {
-    _writeGlobal(strip(_readGlobal()));
+    _writeGlobal(_stripTokens(_readGlobal()));
     return;
   }
   const path = _findLocalPath();
-  if (path) _writeJson(path, strip(_readJson(path)));
+  if (path) _writeJson(path, _stripTokens(_readJson(path)));
+}
+
+/**
+ * Persist refreshed tokens back to wherever the active credentials came from.
+ * @param {ConfigSource|null} source
+ * @param {Partial<CliConfig>} tokens
+ */
+export function persistTokens(source, tokens) {
+  if (!source) return;
+  const slice = {};
+  for (const k of TOKEN_KEYS) if (k in tokens) slice[k] = tokens[k];
+  if (source.kind === 'profile') {
+    upsertProfile(source.name, slice);
+  } else if (source.kind === 'global') {
+    saveConfig(slice, 'global');
+  } else {
+    saveConfig(slice, 'local');
+  }
+}
+
+/** Clear tokens from whichever store the source points at. */
+export function clearTokensForSource(source) {
+  if (!source) return;
+  if (source.kind === 'profile') {
+    const prof = getProfile(source.name);
+    if (prof) upsertProfile(source.name, _stripTokens(prof), { replace: true });
+  } else if (source.kind === 'global') {
+    clearTokens('global');
+  } else {
+    clearTokens('local');
+  }
+}
+
+// ── Profiles ───────────────────────────────────────────────────────────────────
+
+/** Read the profiles registry: { active, profiles }. */
+export function readProfiles() {
+  const raw = existsSync(PROFILES_FILE) ? _readJson(PROFILES_FILE) : {};
+  return {
+    active: typeof raw.active === 'string' ? raw.active : null,
+    profiles: raw.profiles && typeof raw.profiles === 'object' ? raw.profiles : {}
+  };
+}
+
+/** List profile names with their (token-stripped-safe) creds and the active name. */
+export function listProfiles() {
+  const { active, profiles } = readProfiles();
+  return {
+    active,
+    profiles: Object.fromEntries(Object.entries(profiles).map(([name, creds]) => [name, { ...creds }]))
+  };
+}
+
+/** Return a single profile's credentials, or null. */
+export function getProfile(name) {
+  if (!name) return null;
+  const { profiles } = readProfiles();
+  return profiles[name] ? { ...profiles[name] } : null;
+}
+
+/**
+ * Create or update a profile (field merge by default).
+ * @param {string} name
+ * @param {Partial<CliConfig>} updates
+ * @param {{ replace?: boolean }} [opts]  replace: overwrite instead of merge
+ */
+export function upsertProfile(name, updates, opts = {}) {
+  if (!name) throw new Error('Profile name is required.');
+  const reg = readProfiles();
+  const current = opts.replace ? {} : (reg.profiles[name] || {});
+  reg.profiles[name] = _onlyCredKeys({ ...current, ...updates });
+  if (!reg.active) reg.active = name; // first profile becomes active
+  _writeProfiles(reg);
+}
+
+/** Delete a profile. Clears the active pointer if it referenced this profile. */
+export function removeProfile(name) {
+  const reg = readProfiles();
+  if (!(name in reg.profiles)) return false;
+  delete reg.profiles[name];
+  if (reg.active === name) {
+    reg.active = Object.keys(reg.profiles)[0] ?? null;
+  }
+  _writeProfiles(reg);
+  return true;
+}
+
+/** Set the global active profile. Throws if it does not exist. */
+export function setActiveProfile(name) {
+  const reg = readProfiles();
+  if (!(name in reg.profiles)) throw new Error(`No such profile: "${name}".`);
+  reg.active = name;
+  _writeProfiles(reg);
+}
+
+export function getActiveProfileName() {
+  return readProfiles().active;
+}
+
+// ── Project pin (.zeyos/profile) ─────────────────────────────────────────────
+
+/** Read the nearest project pin: { name, path, dir } or null. */
+export function readLocalPin() {
+  let dir = process.cwd();
+  for (let i = 0; i < 20; i++) {
+    const candidate = join(dir, LOCAL_DIR, PIN_FILE);
+    if (existsSync(candidate)) {
+      try {
+        const name = readFileSync(candidate, 'utf8').trim();
+        if (name) return { name, path: candidate, dir };
+      } catch { /* ignore unreadable pin */ }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
 }
 
-/** Return the path of the active local .zeyos/auth.json (if any). */
-export function localConfigPath() {
-  return _findLocalPath();
+/** Pin a profile for the current project (writes ./.zeyos/profile). */
+export function writeLocalPin(name, dir = process.cwd()) {
+  const path = join(dir, LOCAL_DIR, PIN_FILE);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${name}\n`, { mode: 0o600 });
+  return path;
 }
 
-/** Return the global credentials file path. */
-export function globalConfigPath() {
-  return GLOBAL_FILE;
+/** Remove the nearest project pin, if any. Returns the removed path or null. */
+export function clearLocalPin() {
+  const pin = readLocalPin();
+  if (pin) { unlinkSync(pin.path); return pin.path; }
+  return null;
 }
 
+// ── Paths (for messages) ───────────────────────────────────────────────────────
+
+export function localConfigPath() { return _findLocalPath(); }
+export function globalConfigPath() { return GLOBAL_FILE; }
+export function profilesConfigPath() { return PROFILES_FILE; }
+
 // ── Internals ────────────────────────────────────────────────────────────────
 
 function _fromEnv() {
   const e = process.env;
   const out = {};
-  if (e.ZEYOS_BASE_URL)              out.baseUrl             = e.ZEYOS_BASE_URL;
-  if (e.ZEYOS_INSTANCE)              out.instance            = e.ZEYOS_INSTANCE;
-  if (e.ZEYOS_CLIENT_ID)             out.clientId            = e.ZEYOS_CLIENT_ID;
-  if (e.ZEYOS_CLIENT_SECRET)         out.clientSecret        = e.ZEYOS_CLIENT_SECRET;
-  if (e.ZEYOS_TOKEN)                 out.accessToken         = e.ZEYOS_TOKEN;
-  if (e.ZEYOS_REFRESH_TOKEN)         out.refreshToken        = e.ZEYOS_REFRESH_TOKEN;
+  if (e.ZEYOS_BASE_URL)      out.baseUrl      = e.ZEYOS_BASE_URL;
+  if (e.ZEYOS_INSTANCE)      out.instance     = e.ZEYOS_INSTANCE;
+  if (e.ZEYOS_CLIENT_ID)     out.clientId     = e.ZEYOS_CLIENT_ID;
+  if (e.ZEYOS_CLIENT_SECRET) out.clientSecret = e.ZEYOS_CLIENT_SECRET;
+  if (e.ZEYOS_TOKEN)         out.accessToken  = e.ZEYOS_TOKEN;
+  if (e.ZEYOS_REFRESH_TOKEN) out.refreshToken = e.ZEYOS_REFRESH_TOKEN;
   return out;
 }
 
@@ -138,6 +351,23 @@ function _findLocalPath() {
   return null;
 }
 
+/** True when the pin directory is at or above the auth.json's directory. */
+function _isSameOrShallower(pinDir, localPath) {
+  const localDir = dirname(dirname(localPath)); // strip /.zeyos/auth.json
+  return pinDir.length <= localDir.length;
+}
+
+function _onlyCredKeys(obj) {
+  const out = {};
+  for (const k of CRED_KEYS) if (obj[k] != null) out[k] = obj[k];
+  return out;
+}
+
+function _stripTokens(o) {
+  const { accessToken, refreshToken, expiresAt, refreshTokenExpiresAt, ...rest } = o;
+  return rest;
+}
+
 function _readGlobal() {
   return existsSync(GLOBAL_FILE) ? _readJson(GLOBAL_FILE) : {};
 }
@@ -147,6 +377,11 @@ function _writeGlobal(data) {
   _writeJson(GLOBAL_FILE, data);
 }
 
+function _writeProfiles(reg) {
+  mkdirSync(GLOBAL_DIR, { recursive: true });
+  _writeJson(PROFILES_FILE, { active: reg.active ?? null, profiles: reg.profiles ?? {} });
+}
+
 function _readJson(path) {
   try {
     return JSON.parse(readFileSync(path, 'utf8'));

package/lib/flags.mjs

@@ -6,11 +6,11 @@
 // Global CLI flags that are never record fields. Any other --flag on
 // create/update is treated as a field on the record being written.
 const RESERVED_FLAGS = new Set([
-  'data', 'json', 'yaml', 'help', 'h',
-  'no-color', 'force', 'fields', 'filter', 'sort',
+  'data', 'data-file', 'json', 'yaml', 'help', 'h',
+  'no-color', 'force', 'fields', 'filter', 'filter-file', 'sort',
   'limit', 'offset', 'expand', 'base-url', 'client-id',
   'secret', 'scope', 'global', 'port', 'manual', 'show-token',
-  'extdata', 'tags', 'all', 'clean',
+  'extdata', 'tags', 'all', 'clean', 'query', 'profile',
 ]);
 
 /**