@zeyos/cli 0.5.0 → 0.6.0

package/README.md

@@ -80,15 +80,25 @@ Inspect dynamic schema definitions:
 ```bash
 zeyos count customfields --json
 zeyos list customfields --fields ID,name,identifier,context,type --json
+zeyos count dunning --json
 ```
 
 Inspect actionsteps/time-entry evidence and ticket mail:
 
 ```bash
 zeyos list actionsteps --fields ID,name,status,date,duedate,effort,ticket,account --json
+zeyos sum actionsteps effort --filter '{"status":[1,3]}' --json
 zeyos list messages --fields ID,date,mailbox,subject,sender_email,to_email,ticket,reference --filter '{"ticket":42}' --json
 ```
 
+Filters accept common agent-generated shapes and normalize them to the native ZeyOS
+request form. Use `--query --json` to inspect the request without sending it:
+
+```bash
+zeyos list tickets --filter '{"status":{"$nin":[8,9,10]},"priority":[3,4]}' --query --json
+zeyos list accounts --filter '{"name__like":"Acme%","ID__in":[1,2,3]}' --query --json
+```
+
 Create, update, and delete:
 
 ```bash

package/bin/zeyos.mjs

@@ -10,6 +10,7 @@
  *   whoami               Show current user info
  *   list <resource>      List records
  *   count <resource>     Count records
+ *   sum <resource>       Sum a numeric field across matching records
  *   get <resource> <id>  Fetch a single record
  *   show <resource> <id> Alias for get
  *   create <resource>    Create a new record
@@ -42,6 +43,7 @@ ${_c.bold('Commands:')}
   ${_c.cyan('whoami')}               Show currently authenticated user
   ${_c.cyan('list')}   <resource>    List / query records
   ${_c.cyan('count')}  <resource>    Count records (with optional filter)
+  ${_c.cyan('sum')}    <resource> <field>  Sum a numeric field
   ${_c.cyan('get')}    <resource> <id>  Fetch a single record by ID
   ${_c.cyan('show')}   <resource> <id>  Alias for get
   ${_c.cyan('create')} <resource>    Create a new record
@@ -68,6 +70,7 @@ ${_c.bold('Examples:')}
   ${_z} list tickets --filter '{"status":1}' --sort -lastmodified
   ${_z} list tickets --filter-file ./filters/open-tickets.json
   ${_z} count tickets --filter '{"status":1}'
+  ${_z} sum actionsteps effort --filter '{"status":[1,3]}'
   ${_z} get ticket 42
   ${_z} get ticket 42 --all
   ${_z} create ticket --name "Fix login bug" --priority 3
@@ -105,6 +108,7 @@ const OPTIONS = {
   'sort':       { type: 'string' },
   'limit':      { type: 'string' },
   'offset':     { type: 'string' },
+  'page-size':  { type: 'string' },
   'expand':     { type: 'string' },
   'extdata':    { type: 'boolean' },
   'tags':       { type: 'boolean' },
@@ -127,6 +131,12 @@ const OPTIONS = {
   'from-current': { type: 'boolean' },
 };
 
+const COMMON_COMMAND_HELP = `\
+Global options:
+  --profile <name>     Use a named credential profile for this command
+  --no-color           Disable ANSI colors
+`;
+
 // ── Command registry ──────────────────────────────────────────────────────────
 // Maps every command and alias to the module that implements it.
 
@@ -136,6 +146,7 @@ const COMMANDS = {
   whoami:    '../commands/whoami.mjs',
   list:      '../commands/list.mjs',
   count:     '../commands/count.mjs',
+  sum:       '../commands/sum.mjs',
   get:       '../commands/get.mjs',
   show:      '../commands/get.mjs',
   create:    '../commands/create.mjs',
@@ -161,6 +172,7 @@ const COMMANDS = {
 // exception: they accept arbitrary `--<field>` flags, marked with `null` below.
 
 const ALWAYS_FLAGS = ['help', 'json', 'yaml', 'no-color', 'profile'];
+const LEADING_FLAGS = [...ALWAYS_FLAGS, 'version', 'query'];
 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'];
@@ -173,6 +185,7 @@ const COMMAND_FLAGS = {
   whoami:    ['show-token'],
   list:      ['fields', 'filter', 'filter-file', 'sort', 'limit', 'offset', 'extdata', 'expand', 'query'],
   count:     ['filter', 'filter-file', 'query'],
+  sum:       ['filter', 'filter-file', 'limit', 'offset', 'page-size', 'query'],
   get:       GET_FLAGS,
   show:      GET_FLAGS,
   create:    null,
@@ -192,6 +205,8 @@ const COMMAND_FLAGS = {
   profiles:  PROFILE_FLAGS,
 };
 
+const CREDENTIAL_MUTATION_COMMANDS = new Set(['login', 'logout', 'profile', 'profiles']);
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -208,20 +223,37 @@ async function main() {
     process.exit(0);
   }
 
-  const command = argv[0];
+  const lead = _splitLeadingFlags(argv);
+  if (lead.values.help && lead.argv.length === 0) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+  if (lead.values.version && lead.argv.length === 0) {
+    process.stdout.write(_VERSION + '\n');
+    process.exit(0);
+  }
+  if (lead.argv.length === 0) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
 
-  // A leading flag (e.g. `zeyos --invalid`) is not a command — surface it as a
-  // bad option rather than letting it masquerade as one.
+  const command = lead.argv[0];
   if (command.startsWith('-')) {
-    process.stderr.write(`Unknown option: "${command}".  Run 'zeyos --help' for usage.\n`);
-    process.exit(1);
+    _failLeadingOption(command);
   }
 
-  const rest    = argv.slice(1);
+  const rest    = lead.argv.slice(1);
+
+  if (process.env.ZEYOS_CREDENTIALS_READONLY && CREDENTIAL_MUTATION_COMMANDS.has(command)) {
+    process.stderr.write(`Credential command "${command}" is disabled because ZEYOS_CREDENTIALS_READONLY is set.\n`);
+    process.exit(1);
+  }
 
   // Parse remaining args permissively: known options are parsed normally and
   // unknown --key value flags are captured too (so create/update accept fields).
-  const { values, positional } = _parsePermissive(rest, OPTIONS);
+  const parsed = _parsePermissive(rest, OPTIONS);
+  const values = { ...lead.values, ...parsed.values };
+  const positional = parsed.positional;
 
   const modulePath = COMMANDS[command];
   if (!modulePath) {
@@ -232,7 +264,7 @@ async function main() {
   const mod = await import(modulePath);
 
   if (values.help) {
-    process.stdout.write(mod.USAGE ?? HELP);
+    process.stdout.write(_formatCommandHelp(mod.USAGE ?? HELP));
     process.exit(0);
   }
 
@@ -254,11 +286,121 @@ async function main() {
     }
   }
 
+  _validateKnownStringValues(values);
+
   await mod.run(values, positional);
 }
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
+/**
+ * Parse documented global flags that appear before the command name, e.g.
+ * `zeyos --profile dev whoami`. Command-specific flags remain after the
+ * command so the per-command allow-list can validate them.
+ */
+function _splitLeadingFlags(argv) {
+  const values = {};
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (arg === '--') {
+      return { values, argv: argv.slice(i + 1) };
+    }
+
+    if (arg.startsWith('--')) {
+      const eqIdx    = arg.indexOf('=');
+      const key      = eqIdx === -1 ? arg.slice(2) : arg.slice(2, eqIdx);
+      const inlineVal = eqIdx === -1 ? undefined : arg.slice(eqIdx + 1);
+      const opt      = OPTIONS[key];
+
+      if (!LEADING_FLAGS.includes(key)) {
+        _failLeadingOption(arg);
+      }
+
+      if (opt?.type === 'boolean') {
+        values[key] = true;
+        i++;
+        continue;
+      }
+
+      if (opt?.type === 'string') {
+        if (inlineVal !== undefined) {
+          values[key] = inlineVal;
+          i++;
+        } else {
+          const next = argv[i + 1];
+          if (next !== undefined && next.startsWith('--')) {
+            values[key] = '';
+            i++;
+          } else {
+            values[key] = next ?? '';
+            i += 2;
+          }
+        }
+        continue;
+      }
+    }
+
+    if (arg.startsWith('-') && arg.length === 2) {
+      const short = arg[1];
+      const match = Object.entries(OPTIONS).find(([, o]) => o.short === short);
+      if (!match || !LEADING_FLAGS.includes(match[0])) {
+        _failLeadingOption(arg);
+      }
+
+      const [key, opt] = match;
+      if (opt.type === 'boolean') {
+        values[key] = true;
+        i++;
+      } else {
+        const next = argv[i + 1];
+        if (next !== undefined && next.startsWith('--')) {
+          values[key] = '';
+          i++;
+        } else {
+          values[key] = next ?? '';
+          i += 2;
+        }
+      }
+      continue;
+    }
+
+    break;
+  }
+
+  return { values, argv: argv.slice(i) };
+}
+
+function _failLeadingOption(flag) {
+  process.stderr.write(`Unknown option: "${flag}".  Run 'zeyos --help' for usage.\n`);
+  process.exit(1);
+}
+
+function _formatCommandHelp(usage) {
+  if (usage === HELP || /--profile\s+<name>/.test(usage)) {
+    return usage;
+  }
+  if (/Global options:\n/.test(usage)) {
+    return usage.replace(
+      /Global options:\n/,
+      `Global options:\n  --profile <name>           Use a named credential profile for this command\n  --no-color                 Disable ANSI colors\n`
+    );
+  }
+  const trimmed = usage.endsWith('\n') ? usage : `${usage}\n`;
+  return `${trimmed}\n${COMMON_COMMAND_HELP}`;
+}
+
+function _validateKnownStringValues(values) {
+  for (const [key, value] of Object.entries(values)) {
+    if (OPTIONS[key]?.type === 'string' && value === '') {
+      process.stderr.write(`Option --${key} requires a value.\n`);
+      process.exit(1);
+    }
+  }
+}
+
 /**
  * Parse argv with known options; capture unknown --key value pairs too.
  * This lets create/update accept arbitrary --fieldName value flags.

package/commands/count.mjs

@@ -11,7 +11,7 @@
  */
 
 import { normalizeCountResult }    from '@zeyos/client';
-import { buildCliClient, callApi, maybeDryRun, parseJsonOptionOrFile, requireResource } from '../lib/command.mjs';
+import { buildCliClient, callApi, maybeDryRun, normalizeFilterOperators, parseJsonOptionOrFile, requireResource } from '../lib/command.mjs';
 import { outputMode, printJson, printYaml } from '../lib/output.mjs';
 
 export const USAGE = `\
@@ -24,6 +24,8 @@ Arguments:
 
 Options:
   --filter <json>     JSON filter object  e.g. '{"status":1}'
+                      Arrays normalize to IN; $lt/$lte/$gt/$gte/$ne/$in/$nin and suffix
+                      keys like field__startswith/field__gt normalize to native operators
   --filter-file <path>
                       Read JSON filter object from a file
   --json              Output as JSON ({ "count": N })
@@ -47,7 +49,7 @@ export async function run(values, positional) {
 
   const filters = parseJsonOptionOrFile(values, 'filter', 'filter-file');
   if (filters !== undefined) {
-    body.filters = filters;
+    body.filters = normalizeFilterOperators(filters, { fieldAliases: res.filterAliases });
   }
 
   // ── Call API ───────────────────────────────────────────────────────────────

package/commands/doctor.mjs

@@ -21,6 +21,8 @@ const ENV_KEYS = {
   ZEYOS_CLIENT_SECRET: 'clientSecret',
   ZEYOS_TOKEN:         'accessToken',
   ZEYOS_REFRESH_TOKEN: 'refreshToken',
+  ZEYOS_NO_REFRESH:    'tokenOnly',
+  ZEYOS_CREDENTIALS_READONLY: 'credentialsReadonly',
 };
 
 export const USAGE = `\
@@ -82,8 +84,9 @@ function buildAgentReport() {
     clientSecret: Boolean(config.clientSecret),
     accessToken:  Boolean(config.accessToken),
     refreshToken: Boolean(config.refreshToken),
+    tokenOnly:    Boolean(process.env.ZEYOS_TOKEN) || isTruthyEnv(process.env.ZEYOS_NO_REFRESH),
   };
-  const ready = Boolean(effective.baseUrl && effective.clientId && effective.clientSecret && effective.accessToken);
+  const ready = Boolean(effective.baseUrl && effective.accessToken && (effective.tokenOnly || (effective.clientId && effective.clientSecret)));
   const resources = inspectResources();
 
   return {
@@ -117,6 +120,10 @@ function buildAgentReport() {
   };
 }
 
+function isTruthyEnv(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
 function inspectResources() {
   const names = listResources();
   const missing = [];

package/commands/list.mjs

@@ -26,6 +26,7 @@ import {
   callApi,
   fail,
   maybeDryRun,
+  normalizeFilterOperators,
   parseJsonOptionOrFile,
   requireApiMethod,
   requireResource
@@ -42,6 +43,8 @@ Arguments:
 Options:
   --fields <list>     Field selection (see formats below)
   --filter <json>     JSON filter object  e.g. '{"status":1}'
+                      Arrays normalize to IN; $lt/$lte/$gt/$gte/$ne/$in/$nin and suffix
+                      keys like field__startswith/field__gt normalize to native operators
   --filter-file <path>
                       Read JSON filter object from a file
   --sort <fields>     Sort expression  e.g. '-lastmodified'
@@ -86,7 +89,7 @@ export async function run(values, positional) {
 
   const filters = parseJsonOptionOrFile(values, 'filter', 'filter-file');
   if (filters !== undefined) {
-    body.filters = filters;
+    body.filters = normalizeFilterOperators(filters, { fieldAliases: res.filterAliases });
   }
 
   if (values.sort) body.sort = values.sort.split(',').map(s => s.trim()).filter(Boolean);

package/commands/sum.mjs

@@ -0,0 +1,112 @@
+/**
+ * zeyos sum <resource> <field>
+ *
+ * Page through records and sum one numeric field client-side.
+ */
+
+import { normalizeListResult } from '@zeyos/client';
+import {
+  buildCliClient,
+  callApi,
+  fail,
+  maybeDryRun,
+  normalizeFilterOperators,
+  parseJsonOptionOrFile,
+  requireResource
+} from '../lib/command.mjs';
+import { outputMode, printJson, printYaml } from '../lib/output.mjs';
+
+export const USAGE = `\
+Usage: zeyos sum <resource> <field> [options]
+
+Sum a numeric field across all records matching an optional filter.
+The CLI pages internally so agents do not need to list rows and write ad hoc scripts.
+
+Arguments:
+  resource            Resource name (e.g. actionsteps, transactions, payments)
+  field               Numeric field to sum (e.g. effort, amount, netamount)
+
+Options:
+  --filter <json>     JSON filter object  e.g. '{"status":[1,3]}'
+                      Arrays normalize to IN; $lt/$lte/$gt/$gte/$ne/$in/$nin and suffix
+                      keys like field__startswith/field__gt normalize to native operators
+  --filter-file <path>
+                      Read JSON filter object from a file
+  --page-size <n>     Records per API page (default: 50)
+  --limit <n>         Maximum records to inspect
+  --offset <n>        Initial offset (default: 0)
+  --json              Output as JSON ({ "sum": N, "count": N })
+  --yaml              Output as YAML
+  --query             Print the first page request without sending it
+  -h, --help          Show this help
+
+Examples:
+  zeyos sum actionsteps effort --filter '{"status":[1,3]}'
+  zeyos sum transactions netamount --filter '{"type":3}' --json
+`;
+
+export async function run(values, positional) {
+  const resourceName = positional[0];
+  const field = positional[1];
+  const res = requireResource(resourceName, 'zeyos sum <resource> <field>');
+  if (!field) fail('Missing field name.  Usage: zeyos sum <resource> <field>');
+
+  const pageSize = parsePositiveInt(values['page-size'] ?? '50', '--page-size');
+  const maxRows = values.limit == null ? Infinity : parsePositiveInt(values.limit, '--limit');
+  let offset = values.offset == null ? 0 : parseNonNegativeInt(values.offset, '--offset');
+
+  const body = { fields: [field], limit: Math.min(pageSize, maxRows), offset };
+  const filters = parseJsonOptionOrFile(values, 'filter', 'filter-file');
+  if (filters !== undefined) body.filters = normalizeFilterOperators(filters, { fieldAliases: res.filterAliases });
+
+  const clientState = buildCliClient(values);
+  if (await maybeDryRun(clientState, res.list, body, values)) return;
+
+  let sum = 0;
+  let count = 0;
+
+  while (count < maxRows) {
+    const remaining = maxRows - count;
+    const limit = Math.min(pageSize, remaining);
+    const pageBody = { ...body, limit, offset };
+    const result = await callApi(clientState, res.list, pageBody);
+    const rows = normalizeListResult(result).data;
+
+    for (const row of rows) {
+      sum += numericValue(row[field], field);
+      count += 1;
+      if (count >= maxRows) break;
+    }
+
+    if (rows.length < limit || rows.length === 0) break;
+    offset += rows.length;
+  }
+
+  const mode = outputMode(values);
+  if (mode === 'json') {
+    printJson({ sum, count, field });
+  } else if (mode === 'yaml') {
+    printYaml({ sum, count, field });
+  } else {
+    process.stdout.write(`${sum}\n`);
+  }
+}
+
+function numericValue(value, field) {
+  if (value == null || value === '') return 0;
+  const n = Number(value);
+  if (!Number.isFinite(n)) fail(`Field "${field}" contains a non-numeric value: ${JSON.stringify(value)}`);
+  return n;
+}
+
+function parsePositiveInt(value, flag) {
+  const n = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(n) || n <= 0) fail(`${flag} must be a positive integer.`);
+  return n;
+}
+
+function parseNonNegativeInt(value, flag) {
+  const n = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(n) || n < 0) fail(`${flag} must be a non-negative integer.`);
+  return n;
+}

package/lib/client.mjs

@@ -23,29 +23,47 @@ export function buildClient(overrides = {}, opts = {}) {
     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);
+  const tokenOnly = isTokenOnlyMode(config);
+  requireConfig(tokenOnly ? ['baseUrl', 'accessToken'] : ['baseUrl', 'clientId', 'clientSecret', 'accessToken'], config);
 
-  const tokenStore = new MemoryTokenStore({
-    accessToken:           config.accessToken,
-    refreshToken:          config.refreshToken,
-    expiresAt:             config.expiresAt,
-    refreshTokenExpiresAt: config.refreshTokenExpiresAt,
-  });
+  const tokenStore = new MemoryTokenStore(tokenOnly
+    ? { accessToken: config.accessToken }
+    : {
+        accessToken:           config.accessToken,
+        refreshToken:          config.refreshToken,
+        expiresAt:             config.expiresAt,
+        refreshTokenExpiresAt: config.refreshTokenExpiresAt,
+      });
 
-  const client = createZeyosClient({
-    platform: config.baseUrl,
-    auth: {
-      mode: 'oauth',
-      oauth: {
+  const oauth = tokenOnly
+    ? {
+        tokenStore,
+        autoRefresh: false,
+      }
+    : {
         clientId:     config.clientId,
         clientSecret: config.clientSecret,
         tokenStore,
         autoRefresh:  true,
-      },
+      };
+
+  const client = createZeyosClient({
+    platform: config.baseUrl,
+    auth: {
+      mode: 'oauth',
+      oauth,
     },
   });
 
-  return { client, config, tokenStore, configSource: loaded.source };
+  return { client, config, tokenStore, configSource: tokenOnly ? null : loaded.source, tokenOnly };
+}
+
+function isTruthyEnv(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function isTokenOnlyMode(config) {
+  return Boolean(process.env.ZEYOS_TOKEN) || (isTruthyEnv(process.env.ZEYOS_NO_REFRESH) && Boolean(config.accessToken));
 }
 
 /**

package/lib/command.mjs

@@ -99,6 +99,134 @@ export function parseJsonOptionOrFile(values, flagName, fileFlagName = `${flagNa
   return undefined;
 }
 
+const FILTER_OPERATOR_ALIASES = {
+  $lt: '<',
+  $lte: '<=',
+  $gt: '>',
+  $gte: '>=',
+  $ne: '!=',
+  $in: 'IN',
+  $nin: '!IN',
+  $notIn: '!IN',
+  lt: '<',
+  lte: '<=',
+  gt: '>',
+  gte: '>=',
+  ne: '!=',
+  in: 'IN',
+  nin: '!IN',
+  notIn: '!IN',
+  notin: '!IN'
+};
+
+const FILTER_SUFFIX_OPERATOR_ALIASES = {
+  lt: '<',
+  lte: '<=',
+  gt: '>',
+  gte: '>=',
+  ne: '!=',
+  in: 'IN',
+  nin: '!IN',
+  notin: '!IN'
+};
+
+const FILTER_PATTERN_SUFFIXES = new Set([
+  'startswith',
+  'istartswith',
+  'like',
+  'ilike',
+  'contains',
+  'icontains',
+  'regex',
+  'iregex'
+]);
+
+export function normalizeFilterOperators(value, options = {}) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeFilterOperators(item, options));
+  }
+  if (!value || typeof value !== 'object') return value;
+
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    const suffixFilter = parseFilterSuffix(key, child, options);
+    if (suffixFilter) {
+      mergeFieldFilter(out, suffixFilter.field, suffixFilter.operator, suffixFilter.value);
+      continue;
+    }
+
+    const normalizedKey = FILTER_OPERATOR_ALIASES[key] || key;
+    const outputKey = isFilterOperatorKey(normalizedKey)
+      ? normalizedKey
+      : normalizeFieldAlias(normalizedKey, options);
+    const normalizedChild = normalizeFilterOperators(child, options);
+    out[outputKey] = Array.isArray(normalizedChild) && !isFilterOperatorKey(outputKey)
+      ? { IN: normalizedChild }
+      : normalizedChild;
+  }
+  return out;
+}
+
+function isFilterOperatorKey(key) {
+  return ['<', '<=', '>', '>=', '!=', 'IN', '!IN', '~~*'].includes(key);
+}
+
+function normalizeFieldAlias(field, options = {}) {
+  return options.fieldAliases?.[field] || field;
+}
+
+function parseFilterSuffix(key, child, options) {
+  const separator = key.lastIndexOf('__');
+  if (separator <= 0) return null;
+
+  const rawField = key.slice(0, separator);
+  const suffix = key.slice(separator + 2).toLowerCase();
+  const field = normalizeFieldAlias(rawField, options);
+
+  if (Object.prototype.hasOwnProperty.call(FILTER_SUFFIX_OPERATOR_ALIASES, suffix)) {
+    return {
+      field,
+      operator: FILTER_SUFFIX_OPERATOR_ALIASES[suffix],
+      value: normalizeFilterOperators(child, options)
+    };
+  }
+
+  if (FILTER_PATTERN_SUFFIXES.has(suffix)) {
+    return {
+      field,
+      operator: '~~*',
+      value: patternValueForSuffix(suffix, child)
+    };
+  }
+
+  return null;
+}
+
+function patternValueForSuffix(suffix, child) {
+  const value = String(child ?? '');
+  if (suffix === 'startswith' || suffix === 'istartswith') return `${value}%`;
+  if (suffix === 'contains' || suffix === 'icontains') return `%${value}%`;
+  if (suffix === 'regex' || suffix === 'iregex') return regexLikeToSqlLike(value);
+  return value;
+}
+
+function regexLikeToSqlLike(value) {
+  return String(value)
+    .replace(/^\^/, '')
+    .replace(/\$$/, '')
+    .replace(/\\.\\*/g, '%')
+    .replace(/\.\*/g, '%');
+}
+
+function mergeFieldFilter(out, field, operator, value) {
+  const existing = out[field];
+  if (existing && typeof existing === 'object' && !Array.isArray(existing)) {
+    out[field] = { ...existing, [operator]: value };
+    return;
+  }
+  out[field] = { [operator]: value };
+}
+
 /** Cheap structural check: does this string look like an intended JSON object? */
 function looksLikeJsonObject(value) {
   return typeof value === 'string' && value.trim().startsWith('{');

package/lib/config.mjs

@@ -60,6 +60,9 @@ export function loadConfig(opts = {}) {
  */
 export function loadConfigWithSource(opts = {}) {
   const env = _fromEnv();
+  if (env.accessToken) {
+    return { config: env, source: null, profile: null };
+  }
   const selection = resolveProfileSelection({ profileFlag: opts.profile });
 
   let base = {};

package/lib/resource-config.mjs

@@ -73,7 +73,7 @@ export function loadResourceConfig(name) {
 export function getListFields(res, name, override) {
   // 1. CLI override
   if (override) {
-    return _parseFieldsOverride(override);
+    return _parseFieldsOverride(override, res?.fieldAliases);
   }
 
   // 2. Config file
@@ -181,7 +181,7 @@ export function getGetParams(name) {
  * Parse a --fields override string.
  * Supports: comma-separated, JSON object, JSON array.
  */
-function _parseFieldsOverride(raw) {
+function _parseFieldsOverride(raw, fieldAliases = {}) {
   const trimmed = raw.trim();
 
   // JSON object: {"Alias": "path", ...}
@@ -189,7 +189,7 @@ function _parseFieldsOverride(raw) {
     try {
       const obj = JSON.parse(trimmed);
       if (typeof obj === 'object' && obj !== null && !Array.isArray(obj)) {
-        const apiFields = _toFieldAliasMap(obj);
+        const apiFields = _toFieldAliasMap(obj, fieldAliases);
         return { apiFields, displayColumns: Object.keys(apiFields) };
       }
     } catch (e) {
@@ -205,7 +205,7 @@ function _parseFieldsOverride(raw) {
       if (Array.isArray(arr)) {
         const paths = arr.map(String);
         const apiFields = {};
-        for (const p of paths) apiFields[p] = p;
+        for (const p of paths) apiFields[p] = normalizeFieldAlias(p, fieldAliases);
         return { apiFields, displayColumns: paths };
       }
     } catch (e) {
@@ -217,7 +217,7 @@ function _parseFieldsOverride(raw) {
   // Comma-separated: "ID,name,status"
   const paths = trimmed.split(',').map(s => s.trim()).filter(Boolean);
   const apiFields = {};
-  for (const p of paths) apiFields[p] = p;
+  for (const p of paths) apiFields[p] = normalizeFieldAlias(p, fieldAliases);
   return { apiFields, displayColumns: paths };
 }
 
@@ -227,14 +227,18 @@ function _parseFieldsOverride(raw) {
  * @param {Record<string, JsonValue>} value
  * @returns {Record<string,string>}
  */
-function _toFieldAliasMap(value) {
+function _toFieldAliasMap(value, fieldAliases = {}) {
   const fields = {};
   for (const [alias, field] of Object.entries(value)) {
-    fields[String(alias)] = String(field);
+    fields[String(alias)] = normalizeFieldAlias(String(field), fieldAliases);
   }
   return fields;
 }
 
+function normalizeFieldAlias(field, fieldAliases = {}) {
+  return fieldAliases[field] || field;
+}
+
 // ── Internals ────────────────────────────────────────────────────────────────
 
 /**

package/lib/resources.mjs

@@ -45,6 +45,8 @@ const REGISTRY = {
     update: 'updateAccount',
     delete: 'deleteAccount',
     fields: ['ID', 'customernum', 'lastname', 'firstname', 'type', 'assigneduser', 'lastmodified'],
+    fieldAliases: { name: 'lastname' },
+    filterAliases: { name: 'lastname' },
   },
   contact: {
     list:   'listContacts',
@@ -54,6 +56,14 @@ const REGISTRY = {
     delete: 'deleteContact',
     fields: ['ID', 'firstname', 'lastname', 'email', 'phone', 'account'],
   },
+  address: {
+    list:   'listAddresses',
+    get:    'getAddress',
+    create: 'createAddress',
+    update: 'updateAddress',
+    delete: 'deleteAddress',
+    fields: ['ID', 'account', 'contact', 'type', 'default'],
+  },
   project: {
     list:   'listProjects',
     get:    'getProject',
@@ -112,6 +122,11 @@ const REGISTRY = {
     get:    'getGroup',
     fields: ['ID', 'name', 'description'],
   },
+  groupuser: {
+    list:   'listGroupsToUsers',
+    get:    'getGroupToUser',
+    fields: ['ID', 'group', 'user'],
+  },
   event: {
     list:   'listEvents',
     get:    'getEvent',
@@ -152,6 +167,62 @@ const REGISTRY = {
     delete: 'deleteCampaign',
     fields: ['ID', 'name', 'status', 'startdate', 'enddate'],
   },
+  mailinglist: {
+    list:   'listMailingLists',
+    get:    'getMailingList',
+    create: 'createMailingList',
+    update: 'updateMailingList',
+    delete: 'deleteMailingList',
+    fields: ['ID', 'name', 'description', 'status', 'lastmodified'],
+  },
+  mailingrecipient: {
+    list:   'listMailingRecipients',
+    get:    'getMailingRecipient',
+    create: 'createMailingRecipient',
+    update: 'updateMailingRecipient',
+    delete: 'deleteMailingRecipient',
+    fields: ['ID', 'message', 'mailinglist', 'campaign', 'email', 'recipientuser', 'recipientgroup'],
+  },
+  dunning: {
+    list:   'listDunningNotices',
+    get:    'getDunningNotice',
+    create: 'createDunningNotice',
+    update: 'updateDunningNotice',
+    delete: 'deleteDunningNotice',
+    fields: ['ID', 'dunningnum', 'type', 'status', 'date', 'duedate', 'account', 'recipient', 'fee'],
+  },
+  dunningtransaction: {
+    list:   'listDunningToTransactions',
+    get:    'getDunningToTransaction',
+    create: 'createDunningToTransaction',
+    update: 'updateDunningToTransaction',
+    delete: 'deleteDunningToTransaction',
+    fields: ['ID', 'dunning', 'transaction'],
+  },
+  pricelist: {
+    list:   'listPriceLists',
+    get:    'getPriceList',
+    create: 'createPriceList',
+    update: 'updatePriceList',
+    delete: 'deletePriceList',
+    fields: ['ID', 'name', 'type', 'discount', 'allaccounts'],
+  },
+  pricelistaccount: {
+    list:   'listPriceListsToAccounts',
+    get:    'getPriceListToAccount',
+    create: 'createPriceListToAccount',
+    update: 'updatePriceListToAccount',
+    delete: 'deletePriceListToAccount',
+    fields: ['ID', 'pricelist', 'account'],
+  },
+  price: {
+    list:   'listPrices',
+    get:    'getPrice',
+    create: 'createPrice',
+    update: 'updatePrice',
+    delete: 'deletePrice',
+    fields: ['ID', 'pricelist', 'item', 'price', 'rebate', 'discount'],
+  },
   customfield: {
     list:   'listCustomFields',
     get:    'getCustomField',
@@ -198,6 +269,7 @@ const ALIASES = {
   tasks:        'task',
   accounts:     'account',
   contacts:     'contact',
+  addresses:    'address',
   projects:     'project',
   appointments: 'appointment',
   documents:    'document',
@@ -208,11 +280,46 @@ const ALIASES = {
   items:        'item',
   users:        'user',
   groups:       'group',
+  groupuser:    'groupuser',
+  groupusers:   'groupuser',
+  groups2user:  'groupuser',
+  groups2users: 'groupuser',
+  'group-user': 'groupuser',
+  'group-users': 'groupuser',
+  'groups-to-user': 'groupuser',
+  'groups-to-users': 'groupuser',
   events:       'event',
   transactions: 'transaction',
   payments:     'payment',
   opportunities:'opportunity',
   campaigns:    'campaign',
+  mailinglists:  'mailinglist',
+  'mailing-list': 'mailinglist',
+  'mailing-lists': 'mailinglist',
+  mailingrecipients: 'mailingrecipient',
+  'mailing-recipient': 'mailingrecipient',
+  'mailing-recipients': 'mailingrecipient',
+  dunnings:      'dunning',
+  'dunning-notice': 'dunning',
+  'dunning-notices': 'dunning',
+  dunningnotice: 'dunning',
+  dunningnotices: 'dunning',
+  dunning2transaction: 'dunningtransaction',
+  dunning2transactions: 'dunningtransaction',
+  'dunning-transaction': 'dunningtransaction',
+  'dunning-transactions': 'dunningtransaction',
+  'dunning-to-transaction': 'dunningtransaction',
+  'dunning-to-transactions': 'dunningtransaction',
+  pricelists:    'pricelist',
+  'price-list':  'pricelist',
+  'price-lists': 'pricelist',
+  pricelistaccount: 'pricelistaccount',
+  pricelistaccounts: 'pricelistaccount',
+  pricelists2account: 'pricelistaccount',
+  pricelists2accounts: 'pricelistaccount',
+  'price-list-account': 'pricelistaccount',
+  'price-list-accounts': 'pricelistaccount',
+  prices:        'price',
   customfields:  'customfield',
   custom_fields: 'customfield',
   'custom-fields': 'customfield',

package/lib/types.mjs

@@ -18,7 +18,9 @@
  *   update?: string,
  *   delete?: string,
  *   fields: string[],
- *   idField?: string
+ *   idField?: string,
+ *   fieldAliases?: Record<string,string>,
+ *   filterAliases?: Record<string,string>
  * }} ResourceDef
  */
 

package/package.json

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