@zeyos/cli 0.1.1 → 0.2.0

package/README.md

@@ -52,6 +52,7 @@ Inspect the CLI-supported resource registry:
 
 ```bash
 zeyos resources
+zeyos doctor agent --json
 ```
 
 List tickets for automation:
@@ -65,11 +66,19 @@ zeyos list tickets \
   --json
 ```
 
+For larger or reusable filters, put the JSON in a file:
+
+```bash
+zeyos list tickets --filter-file ./filters/open-tickets.json --json
+```
+
 Create, update, and delete:
 
 ```bash
 zeyos create ticket --data '{"name":"Fix login bug","status":0,"priority":3,"visibility":0}' --json
+zeyos create ticket --data-file ./ticket.json --json
 zeyos update ticket 42 --data '{"status":4}' --json
+zeyos update ticket 42 --data-file ./ticket-update.json --json
 zeyos delete ticket 42
 ```
 

package/bin/zeyos.mjs

@@ -16,6 +16,7 @@
  *   update <resource>    Update a record
  *   delete <resource>    Delete a record
  *   resources            List available resource types
+ *   doctor agent         Check local CLI readiness for coding agents
  */
 
 // ── Version ───────────────────────────────────────────────────────────────────
@@ -23,45 +24,52 @@
 import { createRequire as _createRequire } from 'node:module';
 import { dirname as _dirname } from 'node:path';
 import { fileURLToPath as _fileURLToPath } from 'node:url';
+import { colors as _c } from '../lib/output.mjs';
 const _require = _createRequire(import.meta.url);
 const _VERSION = _require('../package.json').version;
 
 // ── Global help ───────────────────────────────────────────────────────────────
 
+// Section headers are bold and the `zeyos` binary / command names are cyan,
+// gated by USE_COLOR in output.mjs (so `zeyos --help | less` stays plain text).
+const _z = _c.cyan('zeyos');
 const HELP = `\
-Usage: zeyos <command> [options] [args…]
-
-Commands:
-  login                Authenticate with a ZeyOS instance
-  logout               Revoke session and clear stored tokens
-  whoami               Show currently authenticated user
-  list   <resource>    List / query records
-  count  <resource>    Count records (with optional filter)
-  get    <resource> <id>  Fetch a single record by ID
-  show   <resource> <id>  Alias for get
-  create <resource>    Create a new record
-  update <resource> <id>  Update an existing record
-  delete <resource> <id>  Delete a record
-  resources            List all available resource types
-  describe <resource>  Show a resource's fields, types and enums
-  skills <command>     List / show / install ZeyOS agent skills
-
-Global options:
+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('whoami')}               Show currently authenticated user
+  ${_c.cyan('list')}   <resource>    List / query records
+  ${_c.cyan('count')}  <resource>    Count records (with optional filter)
+  ${_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
+  ${_c.cyan('update')} <resource> <id>  Update an existing record
+  ${_c.cyan('delete')} <resource> <id>  Delete a record
+  ${_c.cyan('resources')}            List all available resource types
+  ${_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.bold('Global options:')}
   --json               Output as JSON
   --yaml               Output as YAML
+  --query              Print the API route + JSON payload without sending it
   --no-color           Disable ANSI colors
   -h, --help           Show help for a command
   -v, --version        Print the CLI version and exit
 
-Examples:
-  zeyos login --base-url https://cloud.zeyos.com/demo --client-id myapp --secret "$ZEYOS_CLIENT_SECRET"
-  zeyos list tickets --filter '{"status":1}' --sort -lastmodified
-  zeyos count tickets --filter '{"status":1}'
-  zeyos get ticket 42
-  zeyos get ticket 42 --all
-  zeyos create ticket --name "Fix login bug" --priority 3
-  zeyos update ticket 42 --status 2
-  zeyos delete ticket 42 --force
+${_c.bold('Examples:')}
+  ${_z} login --base-url https://cloud.zeyos.com/demo --client-id myapp --secret "$ZEYOS_CLIENT_SECRET"
+  ${_z} list tickets --filter '{"status":1}' --sort -lastmodified
+  ${_z} list tickets --filter-file ./filters/open-tickets.json
+  ${_z} count tickets --filter '{"status":1}'
+  ${_z} get ticket 42
+  ${_z} get ticket 42 --all
+  ${_z} create ticket --name "Fix login bug" --priority 3
+  ${_z} update ticket 42 --status 2
+  ${_z} delete ticket 42 --force
 `;
 
 // ── Argument definitions ──────────────────────────────────────────────────────
@@ -73,6 +81,7 @@ const OPTIONS = {
   'json':       { type: 'boolean' },
   'yaml':       { type: 'boolean' },
   'no-color':   { type: 'boolean' },
+  'query':      { type: 'boolean' },
   // login
   'base-url':   { type: 'string' },
   'client-id':  { type: 'string' },
@@ -88,6 +97,7 @@ const OPTIONS = {
   // list
   'fields':     { type: 'string' },
   'filter':     { type: 'string' },
+  'filter-file': { type: 'string' },
   'sort':       { type: 'string' },
   'limit':      { type: 'string' },
   'offset':     { type: 'string' },
@@ -100,6 +110,7 @@ const OPTIONS = {
   'show-token': { type: 'boolean' },
   // create / update
   'data':       { type: 'string' },
+  'data-file':  { type: 'string' },
   // delete
   // (--force is already declared above)
   // skills install
@@ -128,10 +139,43 @@ const COMMANDS = {
   resources: '../commands/resources.mjs',
   resource:  '../commands/resources.mjs',
   describe:  '../commands/describe.mjs',
+  doctor:    '../commands/doctor.mjs',
   skills:    '../commands/skills.mjs',
   skill:     '../commands/skills.mjs',
 };
 
+// ── Per-command flag allow-lists ────────────────────────────────────────────────
+// Unknown flags are rejected (e.g. `zeyos list --invalid`) so typos surface
+// immediately instead of being silently ignored. `create`/`update` are the
+// exception: they accept arbitrary `--<field>` flags, marked with `null` below.
+
+const ALWAYS_FLAGS = ['help', 'json', 'yaml', 'no-color'];
+const SKILLS_FLAGS = ['target', 'dir', 'global', 'local', 'force', 'yes', 'no-logo'];
+const DELETE_FLAGS = ['force', 'query'];
+const GET_FLAGS    = ['fields', 'extdata', 'tags', 'expand', 'all', 'query'];
+
+const COMMAND_FLAGS = {
+  login:     ['base-url', 'client-id', 'secret', 'scope', 'port', 'global', 'force', 'clean', 'manual'],
+  logout:    ['global'],
+  whoami:    ['show-token'],
+  list:      ['fields', 'filter', 'filter-file', 'sort', 'limit', 'offset', 'extdata', 'expand', 'query'],
+  count:     ['filter', 'filter-file', 'query'],
+  get:       GET_FLAGS,
+  show:      GET_FLAGS,
+  create:    null,
+  update:    null,
+  edit:      null,
+  delete:    DELETE_FLAGS,
+  rm:        DELETE_FLAGS,
+  remove:    DELETE_FLAGS,
+  resources: [],
+  resource:  [],
+  describe:  [],
+  doctor:    [],
+  skills:    SKILLS_FLAGS,
+  skill:     SKILLS_FLAGS,
+};
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -149,6 +193,14 @@ async function main() {
   }
 
   const command = argv[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.
+  if (command.startsWith('-')) {
+    process.stderr.write(`Unknown option: "${command}".  Run 'zeyos --help' for usage.\n`);
+    process.exit(1);
+  }
+
   const rest    = argv.slice(1);
 
   // Parse remaining args permissively: known options are parsed normally and
@@ -168,6 +220,24 @@ async function main() {
     process.exit(0);
   }
 
+  // Reject unknown flags so typos / unsupported options fail loudly instead of
+  // being silently ignored. `create`/`update` opt out (COMMAND_FLAGS = null)
+  // because they accept arbitrary `--<field>` flags as record data.
+  const allowed = COMMAND_FLAGS[command];
+  if (allowed) {
+    const allowedSet = new Set([...ALWAYS_FLAGS, ...allowed]);
+    const unknown = Object.keys(values).filter((key) => !allowedSet.has(key));
+    if (unknown.length > 0) {
+      const flag = unknown[0];
+      const hint = _suggestFlag(flag, [...allowedSet]);
+      process.stderr.write(
+        `Unknown option: --${flag}${hint ? `  (did you mean --${hint}?)` : ''}\n\n` +
+          `Run 'zeyos ${command} --help' for available options.\n`
+      );
+      process.exit(1);
+    }
+  }
+
   await mod.run(values, positional);
 }
 
@@ -274,6 +344,38 @@ function _parsePermissive(argv, options) {
   return { values, positional };
 }
 
+/** Suggest the closest allowed flag for an unknown one, if it's a near miss. */
+function _suggestFlag(input, candidates) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const candidate of candidates) {
+    const dist = _levenshtein(input, candidate);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = candidate;
+    }
+  }
+  // Only suggest a reasonably close match (avoid nonsense "did you mean").
+  return bestDist <= Math.max(2, Math.floor(input.length / 2)) ? best : null;
+}
+
+/** Levenshtein edit distance between two short strings. */
+function _levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => i);
+  for (let j = 1; j <= n; j++) {
+    let prev = dp[0];
+    dp[0] = j;
+    for (let i = 1; i <= m; i++) {
+      const tmp = dp[i];
+      dp[i] = a[i - 1] === b[j - 1] ? prev : 1 + Math.min(prev, dp[i], dp[i - 1]);
+      prev = tmp;
+    }
+  }
+  return dp[m];
+}
+
 main().catch(err => {
   process.stderr.write(`Fatal: ${err.message}\n`);
   process.exit(1);

package/commands/count.mjs

@@ -4,13 +4,14 @@
  * Return the count of records matching an optional filter.
  *
  * Options:
- *   --filter <json>   JSON filter object  e.g. '{"status":1}'
- *   --json            Output as JSON
- *   --yaml            Output as YAML
+ *   --filter <json>       JSON filter object  e.g. '{"status":1}'
+ *   --filter-file <path>  Read JSON filter object from a file
+ *   --json                Output as JSON
+ *   --yaml                Output as YAML
  */
 
 import { normalizeCountResult }    from '@zeyos/client';
-import { buildCliClient, callApi, parseJsonOption, requireResource } from '../lib/command.mjs';
+import { buildCliClient, callApi, maybeDryRun, parseJsonOptionOrFile, requireResource } from '../lib/command.mjs';
 import { outputMode, printJson, printYaml } from '../lib/output.mjs';
 
 export const USAGE = `\
@@ -23,29 +24,36 @@ Arguments:
 
 Options:
   --filter <json>     JSON filter object  e.g. '{"status":1}'
+  --filter-file <path>
+                      Read JSON filter object from a file
   --json              Output as JSON ({ "count": N })
   --yaml              Output as YAML
+  --query             Print the request route + JSON body without sending it
   -h, --help          Show this help
 
 Examples:
   zeyos count tickets
   zeyos count tickets --filter '{"status":1}'
+  zeyos count tickets --filter-file ./filters/open-tickets.json
   zeyos count accounts --json
 `;
 
 export async function run(values, positional) {
   const resourceName = positional[0];
   const res = requireResource(resourceName, 'zeyos count <resource>');
-  const clientState = buildCliClient();
 
   // ── Build request body ─────────────────────────────────────────────────────
   const body = { count: true };
 
-  if (values.filter) {
-    body.filters = parseJsonOption(values.filter, 'filter');
+  const filters = parseJsonOptionOrFile(values, 'filter', 'filter-file');
+  if (filters !== undefined) {
+    body.filters = filters;
   }
 
   // ── Call API ───────────────────────────────────────────────────────────────
+  const clientState = buildCliClient();
+  if (await maybeDryRun(clientState, res.list, body, values)) return;
+
   const result = await callApi(clientState, res.list, body);
 
   const count = normalizeCountResult(result);

package/commands/create.mjs

@@ -3,15 +3,17 @@
  *
  * Create a new record.  Field values can be supplied either as:
  *   - a JSON blob via --data '{"name":"foo","status":1}'
+ *   - a JSON file via --data-file ./ticket.json
  *   - individual --<field> <value> flags (converted automatically)
  *
  * Options:
- *   --data <json>    Full record as JSON object
- *   --json           Output created record as JSON
- *   --yaml           Output created record as YAML
+ *   --data <json>       Full record as JSON object
+ *   --data-file <path>  Read full record JSON object from a file
+ *   --json              Output created record as JSON
+ *   --yaml              Output created record as YAML
  */
 
-import { buildCliClient, buildRecordPayload, callApi, requireResource } from '../lib/command.mjs';
+import { buildCliClient, buildRecordPayload, callApi, maybeDryRun, requireResource } from '../lib/command.mjs';
 import { outputMode, printJson, printYaml, printRecord, success } from '../lib/output.mjs';
 
 export const USAGE = `\
@@ -24,14 +26,17 @@ Arguments:
 
 Options:
   --data <json>       Record fields as a JSON object
+  --data-file <path>  Read record fields as a JSON object from a file
   --<field> <value>   Set individual fields  e.g. --name "My Ticket" --status 1
   --json              Output created record as JSON
   --yaml              Output created record as YAML
+  --query             Print the request route + JSON body without sending it
   -h, --help          Show this help
 
 Examples:
   zeyos create ticket --name "Fix login bug" --status 0 --priority 2
   zeyos create account --data '{"lastname":"Acme Corp","email":"info@acme.com"}'
+  zeyos create ticket --data-file ./ticket.json
 `;
 
 export async function run(values, positional) {
@@ -46,6 +51,8 @@ export async function run(values, positional) {
   const clientState = buildCliClient();
 
   // ── Call API ───────────────────────────────────────────────────────────────
+  if (await maybeDryRun(clientState, res.create, data, values)) return;
+
   const record = await callApi(clientState, res.create, data);
 
   const mode = outputMode(values);

package/commands/delete.mjs

@@ -8,7 +8,7 @@
  */
 
 import { createInterface }         from 'node:readline';
-import { buildCliClient, callApi, requireRecordId, requireResource } from '../lib/command.mjs';
+import { buildCliClient, callApi, maybeDryRun, requireRecordId, requireResource } from '../lib/command.mjs';
 import { success, warn }           from '../lib/output.mjs';
 
 export const USAGE = `\
@@ -22,6 +22,7 @@ Arguments:
 
 Options:
   --force             Skip confirmation prompt
+  --query             Print the request route + JSON body without sending it
   -h, --help          Show this help
 
 Examples:
@@ -36,6 +37,12 @@ export async function run(values, positional) {
   const res = requireResource(resourceName, 'zeyos delete <resource> <id>', 'delete', 'deletion');
   requireRecordId(id, 'zeyos delete <resource> <id>');
 
+  const clientState = buildCliClient();
+
+  // ── Dry run ────────────────────────────────────────────────────────────────
+  // Show the request without prompting or deleting anything.
+  if (await maybeDryRun(clientState, res.delete, { ID: id }, values)) return;
+
   // ── Confirmation ───────────────────────────────────────────────────────────
   if (!values.force) {
     const confirmed = await _confirm(`Delete ${resourceName} #${id}? [y/N] `);
@@ -45,8 +52,6 @@ export async function run(values, positional) {
     }
   }
 
-  const clientState = buildCliClient();
-
   // ── Call API ───────────────────────────────────────────────────────────────
   await callApi(clientState, res.delete, { ID: id }, {
     notFoundMessage: `${resourceName} #${id} not found.`

package/commands/describe.mjs

@@ -82,12 +82,19 @@ export function run(values, positional = []) {
     return;
   }
 
+  // Keep the join-critical flags (→ fk, indexed, enum) in the table, but keep
+  // the `enum:` note SHORT so the long value list never blows out the column.
+  // The full enum values are printed below the table (see `enumDetails`), so FK
+  // and index flags stay legible in-line and the enum codes remain discoverable.
+  const enumDetails = [];
   const rows = Object.entries(def.fields).map(([name, field]) => {
     const notes = [];
     if (field.fk) notes.push(`→ ${field.fk}`);
     if (field.indexed) notes.push('indexed');
     if (field.enum) {
-      notes.push('enum: ' + Object.entries(field.enum).map(([k, v]) => `${k}=${v}`).join(' '));
+      const count = Object.keys(field.enum).length;
+      notes.push(`enum (${count})`);
+      enumDetails.push({ name, values: field.enum });
     }
     return { field: name, type: field.type, notes: notes.join('  ') };
   });
@@ -96,6 +103,20 @@ export function run(values, positional = []) {
 
   process.stdout.write(`\n  ${c.bold(def.name)} ${c.dim(`(${def.type}, ${rows.length} fields)`)}\n`);
   printTable(rows, ['field', 'type', 'notes']);
+
+  // Full enum values, one field per block, below the table. Each `code = LABEL`
+  // pair is on its own line so even long enums (e.g. ticket status) stay readable.
+  if (enumDetails.length > 0) {
+    process.stdout.write(`  ${c.bold('enums')}\n`);
+    for (const { name, values } of enumDetails) {
+      process.stdout.write(`    ${c.cyan(name)}\n`);
+      for (const [code, label] of Object.entries(values)) {
+        process.stdout.write(`      ${c.dim(code.padStart(2))}  ${label}\n`);
+      }
+    }
+    process.stdout.write('\n');
+  }
+
   if (operations.length > 0) {
     process.stdout.write(`  ${c.bold('operations')}  ${c.dim(operations.join(', '))}\n\n`);
   }

package/commands/doctor.mjs

@@ -0,0 +1,186 @@
+/**
+ * zeyos doctor agent
+ *
+ * Offline diagnostic for coding agents before they rely on the CLI.
+ */
+
+import { createRequire } from 'node:module';
+import { existsSync, readdirSync } from 'node:fs';
+import { loadConfigWithSource, localConfigPath, globalConfigPath } from '../lib/config.mjs';
+import { loadResourceConfig } from '../lib/resource-config.mjs';
+import { listResources, resolveResource } from '../lib/resources.mjs';
+import { colors as c, error, outputMode, printJson, printYaml } from '../lib/output.mjs';
+
+const require = createRequire(import.meta.url);
+const VERSION = require('../package.json').version;
+
+const ENV_KEYS = {
+  ZEYOS_BASE_URL:      'baseUrl',
+  ZEYOS_INSTANCE:      'instance',
+  ZEYOS_CLIENT_ID:     'clientId',
+  ZEYOS_CLIENT_SECRET: 'clientSecret',
+  ZEYOS_TOKEN:         'accessToken',
+  ZEYOS_REFRESH_TOKEN: 'refreshToken',
+};
+
+export const USAGE = `\
+Usage: zeyos doctor agent [options]
+
+Check local CLI readiness for coding agents. Runs offline and never prints
+tokens or client secrets.
+
+Options:
+  --json              Output as JSON
+  --yaml              Output as YAML
+  -h, --help          Show this help
+
+Examples:
+  zeyos doctor agent
+  zeyos doctor agent --json
+`;
+
+export function run(values, positional = []) {
+  const subject = positional[0];
+  if (subject !== 'agent') {
+    error('Unknown doctor target. Usage: zeyos doctor agent');
+    process.exit(1);
+  }
+
+  const report = buildAgentReport();
+  const mode = outputMode(values);
+
+  if (mode === 'json') {
+    printJson(report);
+    return;
+  }
+  if (mode === 'yaml') {
+    printYaml(report);
+    return;
+  }
+
+  printAgentReport(report);
+}
+
+function buildAgentReport() {
+  const localPath = localConfigPath();
+  const globalPath = globalConfigPath();
+  const envVariables = Object.keys(ENV_KEYS).filter((key) => process.env[key]);
+  let loaded = { config: {}, source: null };
+  let configError = null;
+
+  try {
+    loaded = loadConfigWithSource();
+  } catch (err) {
+    configError = err.message || String(err);
+  }
+
+  const config = loaded.config;
+  const effective = {
+    baseUrl:      Boolean(config.baseUrl),
+    instance:     Boolean(config.instance),
+    clientId:     Boolean(config.clientId),
+    clientSecret: Boolean(config.clientSecret),
+    accessToken:  Boolean(config.accessToken),
+    refreshToken: Boolean(config.refreshToken),
+  };
+  const ready = Boolean(effective.baseUrl && effective.clientId && effective.clientSecret && effective.accessToken);
+  const resources = inspectResources();
+
+  return {
+    ok: ready && !configError && resources.ok,
+    cli: {
+      version: VERSION,
+    },
+    connection: {
+      baseUrl: config.baseUrl ?? null,
+      instance: config.instance ?? null,
+    },
+    auth: {
+      ready,
+      source: envVariables.length > 0 ? 'env' : loaded.source,
+      env: {
+        present: envVariables.length > 0,
+        variables: envVariables,
+      },
+      local: {
+        present: Boolean(localPath),
+        path: localPath,
+      },
+      global: {
+        present: existsSync(globalPath),
+        path: globalPath,
+      },
+      effective,
+      error: configError,
+    },
+    resources,
+  };
+}
+
+function inspectResources() {
+  const names = listResources();
+  const missing = [];
+  const configErrors = [];
+
+  for (const name of names) {
+    if (!resolveResource(name)) {
+      missing.push(name);
+      continue;
+    }
+
+    try {
+      loadResourceConfig(name);
+    } catch (err) {
+      configErrors.push(err.message || String(err));
+    }
+  }
+
+  return {
+    ok: names.length > 0 && missing.length === 0 && configErrors.length === 0,
+    count: names.length,
+    shippedConfigCount: countShippedResourceConfigs(),
+    missing,
+    configErrors,
+  };
+}
+
+function countShippedResourceConfigs() {
+  try {
+    return readdirSync(new URL('../config/', import.meta.url))
+      .filter((name) => name.endsWith('.json'))
+      .length;
+  } catch {
+    return 0;
+  }
+}
+
+function printAgentReport(report) {
+  process.stdout.write('\n');
+  process.stdout.write(`  ${c.bold('ZeyOS CLI doctor: agent')}\n\n`);
+  process.stdout.write(`  CLI version        ${report.cli.version}\n`);
+  process.stdout.write(`  Base URL           ${report.connection.baseUrl ?? '(not set)'}\n`);
+  process.stdout.write(`  Instance           ${report.connection.instance ?? '(not set)'}\n`);
+  process.stdout.write(`  Auth ready         ${yesNo(report.auth.ready)}\n`);
+  process.stdout.write(`  Auth source        ${report.auth.source ?? '(none)'}\n`);
+  process.stdout.write(`  Env config         ${report.auth.env.present ? report.auth.env.variables.join(', ') : '(none)'}\n`);
+  process.stdout.write(`  Local config       ${report.auth.local.present ? report.auth.local.path : '(none)'}\n`);
+  process.stdout.write(`  Global config      ${report.auth.global.present ? report.auth.global.path : '(none)'}\n`);
+  process.stdout.write(`  Resource registry  ${report.resources.ok ? 'ok' : 'problem'} (${report.resources.count} resources, ${report.resources.shippedConfigCount} shipped configs)\n`);
+
+  if (report.auth.error) {
+    process.stdout.write(`\n  ${c.bold('Auth config error')}\n`);
+    process.stdout.write(`  ${report.auth.error}\n`);
+  }
+  if (report.resources.configErrors.length > 0) {
+    process.stdout.write(`\n  ${c.bold('Resource config errors')}\n`);
+    for (const message of report.resources.configErrors) {
+      process.stdout.write(`  ${message}\n`);
+    }
+  }
+
+  process.stdout.write('\n');
+}
+
+function yesNo(value) {
+  return value ? 'yes' : 'no';
+}

package/commands/get.mjs

@@ -17,11 +17,12 @@
 import { loadConfig }                    from '../lib/config.mjs';
 import { canonicalName }                 from '../lib/resources.mjs';
 import { getGetFields, getGetParams }    from '../lib/resource-config.mjs';
-import { outputMode, printJson, printYaml, printRecord, buildDateFormatters } from '../lib/output.mjs';
+import { outputMode, printJson, printYaml, printRecord, buildDateFormatters, buildEnumFormatters } from '../lib/output.mjs';
 import {
   buildCliClient,
   callApi,
   fail,
+  maybeDryRun,
   requireRecordId,
   requireResource
 } from '../lib/command.mjs';
@@ -44,6 +45,7 @@ Options:
   --all               Fetch all data (extdata + tags + all fields)
   --json              Output as JSON
   --yaml              Output as YAML
+  --query             Print the request route + JSON body without sending it
   -h, --help          Show this help
 
 Fields format:
@@ -98,6 +100,8 @@ export async function run(values, positional) {
   }
 
   // ── Call API ───────────────────────────────────────────────────────────────
+  if (await maybeDryRun(clientState, res.get, params, values)) return;
+
   const record = await callApi(clientState, res.get, params, {
     notFoundMessage: `${resourceName} #${id} not found.`
   });
@@ -121,7 +125,16 @@ export async function run(values, positional) {
     const cfg = loadConfig();
     const dateFormat = cfg.dateFormat ?? 'YYYY-MM-DD';
     const displayKeys = fields ?? Object.keys(record);
-    const formatters = buildDateFormatters(displayKeys, dateFormat);
-    printRecord(record, displayKeys, fieldLabels, formatters);
+    const dateFormatters = buildDateFormatters(displayKeys, dateFormat);
+
+    // QW-3: schema-driven enum/ID coloring in the single-record view too.
+    // Enum values are colored by their resolved label keyword; ID/FK fields are
+    // dimmed. Date formatters win for date columns. No-op when color is off.
+    const schema = clientState.client.schema;
+    const schemaKey = schema?.resourceForOperation?.(res.get);
+    const fieldDefs = schemaKey ? schema.describe(schemaKey)?.fields : undefined;
+    const enumFormatters = fieldDefs ? buildEnumFormatters(displayKeys, fieldDefs) : {};
+
+    printRecord(record, displayKeys, fieldLabels, { ...enumFormatters, ...dateFormatters });
   }
 }

package/commands/list.mjs

@@ -6,6 +6,7 @@
  * Options:
  *   --fields <list>        Field selection (comma-separated or JSON object)
  *   --filter <json>        JSON filter object  e.g. '{"status":1}'
+ *   --filter-file <path>   Read JSON filter object from a file
  *   --sort <field>         Sort field, prefix with - for descending  e.g. '-lastmodified'
  *   --limit <n>            Max records to fetch  (default: 50)
  *   --offset <n>           Skip first N records  (default: 0)
@@ -19,12 +20,13 @@ import { normalizeListResult }            from '@zeyos/client';
 import { loadConfig }                    from '../lib/config.mjs';
 import { canonicalName }                 from '../lib/resources.mjs';
 import { getListFields }                 from '../lib/resource-config.mjs';
-import { outputMode, printJson, printYaml, printTable, buildDateFormatters, warn, info } from '../lib/output.mjs';
+import { outputMode, printJson, printYaml, printTable, buildDateFormatters, buildEnumFormatters, info } from '../lib/output.mjs';
 import {
   buildCliClient,
   callApi,
   fail,
-  parseJsonOption,
+  maybeDryRun,
+  parseJsonOptionOrFile,
   requireApiMethod,
   requireResource
 } from '../lib/command.mjs';
@@ -40,6 +42,8 @@ Arguments:
 Options:
   --fields <list>     Field selection (see formats below)
   --filter <json>     JSON filter object  e.g. '{"status":1}'
+  --filter-file <path>
+                      Read JSON filter object from a file
   --sort <fields>     Sort expression  e.g. '-lastmodified'
   --limit <n>         Max records (default: 50)
   --offset <n>        Skip first N records (default: 0)
@@ -47,6 +51,7 @@ Options:
   --expand <list>     Expand JSON/binary columns (e.g. binfile, items)
   --json              Output as JSON
   --yaml              Output as YAML
+  --query             Print the request route + JSON body without sending it
   -h, --help          Show this help
 
 Fields format:
@@ -57,6 +62,7 @@ Fields format:
 Examples:
   zeyos list tickets
   zeyos list tickets --filter '{"status":1}' --sort -lastmodified
+  zeyos list tickets --filter-file ./filters/open-tickets.json
   zeyos list tickets --fields ID,name,status --limit 10
   zeyos list accounts --fields '{"Name": "lastname", "City": "contact.city"}'
   zeyos list tickets --extdata
@@ -68,7 +74,6 @@ export async function run(values, positional) {
   const res = requireResource(resourceName, 'zeyos list <resource>');
 
   const resName = canonicalName(resourceName);
-  const clientState = buildCliClient();
 
   // ── Resolve field config ──────────────────────────────────────────────────
   const { apiFields, displayColumns } = getListFields(res, resName, values.fields);
@@ -79,8 +84,9 @@ export async function run(values, positional) {
   // Pass configured fields to the API for server-side field selection
   if (apiFields) body.fields = apiFields;
 
-  if (values.filter) {
-    body.filters = parseJsonOption(values.filter, 'filter');
+  const filters = parseJsonOptionOrFile(values, 'filter', 'filter-file');
+  if (filters !== undefined) {
+    body.filters = filters;
   }
 
   if (values.sort) body.sort = values.sort.split(',').map(s => s.trim()).filter(Boolean);
@@ -110,6 +116,9 @@ export async function run(values, positional) {
   }
 
   // ── Call API ───────────────────────────────────────────────────────────────
+  const clientState = buildCliClient();
+  if (await maybeDryRun(clientState, res.list, body, values)) return;
+
   const fn = requireApiMethod(clientState, res.list);
   let records = await callApi(clientState, res.list, body);
 
@@ -125,13 +134,27 @@ export async function run(values, positional) {
   } else if (mode === 'yaml') {
     printYaml(records);
   } else if (records.length === 0) {
-    warn(`No ${resourceName} found.`);
+    // QW-7: an empty result is a neutral fact, not a warning — use the info `·`
+    // glyph rather than the `⚠` glyph (which reads as an error).
+    info(`No ${resourceName} match.`);
     return;
   } else {
     const cfg = loadConfig();
     const dateFormat = cfg.dateFormat ?? 'YYYY-MM-DD';
-    const formatters = buildDateFormatters(displayColumns, dateFormat, apiFields);
-    printTable(records, displayColumns, {}, formatters);
+    const dateFormatters = buildDateFormatters(displayColumns, dateFormat, apiFields);
+
+    // QW-3: schema-driven enum/ID coloring. Resolve the resource's field defs
+    // (enums, FKs) via the same schema source `describe` uses, then color enum
+    // values by label keyword and dim ID/FK columns. No-op when color is off.
+    // Date formatters win for date columns (a column is never both).
+    const schema = clientState.client.schema;
+    const schemaKey = schema?.resourceForOperation?.(res.list);
+    const fieldDefs = schemaKey ? schema.describe(schemaKey)?.fields : undefined;
+    const enumFormatters = fieldDefs
+      ? buildEnumFormatters(displayColumns, fieldDefs, apiFields)
+      : {};
+
+    printTable(records, displayColumns, {}, { ...enumFormatters, ...dateFormatters });
   }
 
   // ── Pagination / truncation hint ──────────────────────────────────────────
@@ -149,14 +172,14 @@ export async function run(values, positional) {
       const countResult = await fn(countBody);
       const total = countResult?.count ?? null;
       if (total !== null && total > records.length) {
-        info(`Showing ${from}–${to} of ${total}  (default --limit ${limit} truncated this — pass --limit, --offset ${to} for the next page, or use \`zeyos count ${resourceName}\` for the total).`);
+        info(`→ Showing ${from}–${to} of ${total}  (default --limit ${limit} truncated this — pass --limit, --offset ${to} for the next page, or use \`zeyos count ${resourceName}\` for the total).`);
       } else if (total !== null) {
-        info(`Showing ${from}–${to} of ${total}  (--offset ${to} for next page)`);
+        info(`→ Showing ${from}–${to} of ${total}  (--offset ${to} for next page)`);
       }
     } catch {
       // Non-critical — skip pagination info
     }
   } else if (offset > 0) {
-    info(`Showing ${from}–${to} of ${to}`);
+    info(`→ Showing ${from}–${to} of ${to}`);
   }
 }

package/commands/skills.mjs

@@ -177,7 +177,7 @@ async function resolveTarget(values) {
   } else if (interactive) {
     agent = await promptAgent();
   } else {
-    agent = detectAgent() || AGENTS[0];
+    agent = detectAgent() || AGENTS.find((a) => a.key === 'agents');
   }
 
   // (b) Install globally or just for this project?
@@ -225,7 +225,8 @@ function promptMenu(question, items, defaultIndex = 0) {
 
 async function promptAgent() {
   const detected = detectAgent();
-  const defaultIndex = detected ? AGENTS.indexOf(detected) : 0;
+  const agentsIdx = AGENTS.findIndex((a) => a.key === 'agents');
+  const defaultIndex = detected ? AGENTS.indexOf(detected) : agentsIdx;
   const items = AGENTS.map((a) => ({
     label: a.label,
     hint: a === detected ? `${a.local}  (detected here)` : a.local,

package/commands/update.mjs

@@ -4,15 +4,17 @@
  * Update an existing record.  Works like `create` but requires an ID.
  *
  * Options:
- *   --data <json>    Fields to update as a JSON object
- *   --json           Output updated record as JSON
- *   --yaml           Output updated record as YAML
+ *   --data <json>       Fields to update as a JSON object
+ *   --data-file <path>  Read fields to update as a JSON object from a file
+ *   --json              Output updated record as JSON
+ *   --yaml              Output updated record as YAML
  */
 
 import {
   buildCliClient,
   buildRecordPayload,
   callApi,
+  maybeDryRun,
   requireRecordId,
   requireResource
 } from '../lib/command.mjs';
@@ -29,14 +31,17 @@ Arguments:
 
 Options:
   --data <json>       Fields to update as a JSON object
+  --data-file <path>  Read fields to update as a JSON object from a file
   --<field> <value>   Set individual fields  e.g. --status 2
   --json              Output updated record as JSON
   --yaml              Output updated record as YAML
+  --query             Print the request route + JSON body without sending it
   -h, --help          Show this help
 
 Examples:
   zeyos update ticket 42 --status 3
   zeyos update account 7 --data '{"email":"new@example.com"}'
+  zeyos update ticket 42 --data-file ./ticket-update.json
 `;
 
 export async function run(values, positional) {
@@ -54,6 +59,8 @@ export async function run(values, positional) {
   const clientState = buildCliClient();
 
   // ── Call API ───────────────────────────────────────────────────────────────
+  if (await maybeDryRun(clientState, res.update, { ID: id, body: data }, values)) return;
+
   const record = await callApi(clientState, res.update, { ID: id, body: data }, {
     notFoundMessage: `${resourceName} #${id} not found.`
   });

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);
@@ -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/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',
 ]);
 
 /**

package/lib/output.mjs

@@ -20,6 +20,7 @@ const c = {
   red:    s => USE_COLOR ? `\x1b[31m${s}\x1b[0m` : s,
   yellow: s => USE_COLOR ? `\x1b[33m${s}\x1b[0m` : s,
   cyan:   s => USE_COLOR ? `\x1b[36m${s}\x1b[0m` : s,
+  gray:   s => USE_COLOR ? `\x1b[90m${s}\x1b[0m` : s, // bright-black: dim IDs / muted cells
 };
 
 export { c as colors };
@@ -39,6 +40,33 @@ export function printJson(data) {
   process.stdout.write(JSON.stringify(data, null, 2) + '\n');
 }
 
+// ── Query (dry run) ─────────────────────────────────────────────────────────────
+
+/**
+ * Print a dry-run request descriptor (from `--query`): the resolved HTTP route
+ * and the JSON payload that *would* be sent, without performing the request.
+ *
+ * @param {{method:string,url:string,body?:unknown,bodyType?:string}} descriptor
+ * @param {Record<string, unknown>} [values] - parsed CLI flags (for --json/--yaml)
+ */
+export function printQuery(descriptor, values = {}) {
+  if (values.json) { printJson(descriptor); return; }
+  if (values.yaml) { printYaml(descriptor); return; }
+
+  const { method, url, body, bodyType } = descriptor;
+  process.stdout.write(`${c.bold(method)} ${url}\n`);
+  if (bodyType) {
+    const contentType = bodyType === 'form' ? 'application/x-www-form-urlencoded' : 'application/json';
+    process.stdout.write(c.dim(`Content-Type: ${contentType}`) + '\n');
+  }
+  process.stdout.write('\n');
+  if (body === undefined || body === null) {
+    process.stdout.write(c.dim('(no request body)') + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(body, null, 2) + '\n');
+  }
+}
+
 // ── YAML ──────────────────────────────────────────────────────────────────────
 
 export function printYaml(data) {
@@ -129,14 +157,54 @@ export function printTable(rows, columns, labels = {}, formatters = {}) {
     Math.max(headers[i].length, ...data.map(row => _visibleLength(row[i])))
   );
 
-  const headerRow = headers.map((h, i) => _pad(c.bold(h), widths[i])).join('  ');
+  // QW-2: detect numeric columns (every non-empty cell is a plain number,
+  // ignoring ANSI) so we can right-align them — header included.
+  const numeric = columns.map((_, i) => {
+    let sawValue = false;
+    for (const row of data) {
+      const plain = row[i].replace(/\x1b\[[0-9;]*m/g, '');
+      if (plain === '' || plain === '—') continue; // blank / em-dash placeholder
+      sawValue = true;
+      if (!/^-?\d+(\.\d+)?$/.test(plain)) return false;
+    }
+    return sawValue;
+  });
+
+  // QW-1: when stdout is a TTY, shrink the widest column(s) until the row fits
+  // the terminal. Non-TTY (piped) output stays full-width so `| grep`/`| awk`
+  // see complete cell text. Budget = columns − 2 leading spaces − 2 per gutter.
+  if (process.stdout.isTTY) {
+    const term = process.stdout.columns;
+    if (term && term > 0) {
+      const MIN_COL = 8;
+      const gutters = (widths.length - 1) * 2;
+      const budget = term - 2 - gutters;
+      // Repeatedly trim the single widest column above the floor until it fits.
+      let total = widths.reduce((a, b) => a + b, 0);
+      while (total > budget) {
+        let widest = -1;
+        for (let i = 0; i < widths.length; i++) {
+          if (widths[i] > MIN_COL && (widest === -1 || widths[i] > widths[widest])) widest = i;
+        }
+        if (widest === -1) break; // every column already at the floor
+        widths[widest]--;
+        total--;
+      }
+    }
+  }
+
+  const align = (str, i) => (numeric[i] ? _padLeft(str, widths[i]) : _pad(_truncate(str, widths[i]), widths[i]));
+
+  const headerRow = headers.map((h, i) =>
+    numeric[i] ? _padLeft(c.bold(h), widths[i]) : _pad(_truncate(c.bold(h), widths[i]), widths[i])
+  ).join('  ');
   const separator = widths.map(w => '─'.repeat(w)).join('  ');
 
   process.stdout.write('\n');
   process.stdout.write('  ' + headerRow + '\n');
   process.stdout.write('  ' + c.dim(separator) + '\n');
   for (const row of data) {
-    process.stdout.write('  ' + row.map((v, i) => _pad(v, widths[i])).join('  ') + '\n');
+    process.stdout.write('  ' + row.map((v, i) => align(v, i)).join('  ') + '\n');
   }
   process.stdout.write('\n');
 }
@@ -163,10 +231,15 @@ export function printRecord(record, keys, labels = {}, formatters = {}) {
 
     if (formatters[key]) {
       display = String(formatters[key](val, record));
-    } else if (val === null) {
+    } else if (val === null || val === '') {
+      // QW-6: render null AND empty string as a dim em-dash, not a blank gap.
       display = c.dim('—');
+    } else if (Array.isArray(val)) {
+      // QW-6: empty array → dim em-dash; otherwise compact JSON.
+      display = val.length === 0 ? c.dim('—') : JSON.stringify(val);
     } else if (typeof val === 'object') {
-      display = JSON.stringify(val);
+      // QW-6: empty object → dim em-dash; otherwise compact JSON.
+      display = Object.keys(val).length === 0 ? c.dim('—') : JSON.stringify(val);
     } else {
       display = String(val);
     }
@@ -269,6 +342,77 @@ export function buildDateFormatters(columns, dateFormat = 'YYYY-MM-DD', aliasToP
   return formatters;
 }
 
+// ── Semantic enum / ID coloring (QW-3) ─────────────────────────────────────────
+
+/**
+ * Pick a colorizer for an enum LABEL by keyword.
+ *
+ * Enum codes are resource-specific (ticket status 1 = AWAITINGACCEPTANCE but
+ * transaction status 1 = COMPLETED), so color is derived from the label text —
+ * never from the numeric code. Returns `null` when no keyword matches, so the
+ * caller renders the value plain rather than guessing.
+ *
+ * @param {string} label
+ * @returns {((s:string)=>string)|null}
+ */
+function _enumColorForLabel(label) {
+  const L = String(label).toUpperCase();
+  // Positive / terminal-success states → green.
+  if (/COMPLETED|BOOKED|ACTIVE|DONE|ACCEPTED|PAID/.test(L)) return c.green;
+  // Failure / negative states → red.
+  if (/CANCELLED|CANCELED|FAILED|REJECTED|DELETED|OVERDUE/.test(L)) return c.red;
+  // Priority extremes.
+  if (/HIGHEST|HIGH/.test(L)) return c.red;
+  if (/LOWEST|LOW/.test(L)) return c.dim;
+  return null;
+}
+
+/** A field name that denotes a record identifier / foreign key → render dim. */
+function _isIdField(name) {
+  const lower = String(name).toLowerCase();
+  return lower === 'id' || lower.endsWith('id');
+}
+
+/**
+ * Build value formatters that colorize enum + ID columns, schema-driven.
+ *
+ * For each display column, the API field path (via `aliasToPath`) is reduced to
+ * its leaf column name and looked up in `fieldDefs` (a resource's
+ * `schema.describe(resource).fields` map). Columns whose field has an `enum` are
+ * colored by label keyword; ID/FK columns are dimmed. Columns with no resolvable
+ * enum label are left plain. No-ops entirely when color is disabled.
+ *
+ * @param {string[]} columns - display column keys
+ * @param {Record<string, {enum?:Record<string,string>, fk?:string}>} [fieldDefs]
+ * @param {Record<string,string>} [aliasToPath] - alias → API field path
+ * @returns {Record<string, ValueFormatter>}
+ */
+export function buildEnumFormatters(columns, fieldDefs = {}, aliasToPath) {
+  const formatters = {};
+  if (!USE_COLOR) return formatters; // color-gated: nothing to do when plain.
+
+  for (const col of columns) {
+    const fieldPath = aliasToPath?.[col] ?? col;
+    // Dot-notation joins (contact.city) can't be mapped to a base column reliably.
+    if (fieldPath.includes('.')) continue;
+    const def = fieldDefs[fieldPath];
+
+    if (def?.enum) {
+      const enumMap = def.enum;
+      formatters[col] = (val) => {
+        if (val == null || val === '') return c.dim('—');
+        const label = enumMap[String(val)];
+        if (label == null) return String(val); // unknown code → plain, never guess
+        const paint = _enumColorForLabel(label);
+        return paint ? paint(String(val)) : String(val);
+      };
+    } else if (_isIdField(fieldPath) || def?.fk) {
+      formatters[col] = (val) => (val == null || val === '' ? c.dim('—') : c.gray(String(val)));
+    }
+  }
+  return formatters;
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 /** String length ignoring ANSI escape codes. */
@@ -282,3 +426,49 @@ function _pad(str, len) {
   if (visible >= len) return str;
   return str + ' '.repeat(len - visible);
 }
+
+/** Left-pad a string to a visible width (right-align), ANSI-aware. */
+function _padLeft(str, len) {
+  const visible = _visibleLength(str);
+  if (visible >= len) return str;
+  return ' '.repeat(len - visible) + str;
+}
+
+/**
+ * Truncate a string to a max visible width, appending '…', ANSI-aware.
+ * Preserves any trailing reset so colored cells don't bleed. Strings already
+ * within the budget are returned untouched.
+ *
+ * @param {string} str
+ * @param {number} max - max visible width (including the ellipsis)
+ * @returns {string}
+ */
+function _truncate(str, max) {
+  if (max <= 0) return '';
+  if (_visibleLength(str) <= max) return str;
+
+  // Walk the string copying characters, skipping over ANSI sequences (which
+  // have zero visible width), until we've kept (max - 1) visible chars; then
+  // append the ellipsis and any trailing reset.
+  const keep = max - 1;
+  let out = '';
+  let visible = 0;
+  let i = 0;
+  let hadColor = false;
+  while (i < str.length && visible < keep) {
+    const ansi = str.slice(i).match(/^\x1b\[[0-9;]*m/);
+    if (ansi) {
+      out += ansi[0];
+      hadColor = true;
+      i += ansi[0].length;
+      continue;
+    }
+    out += str[i];
+    visible++;
+    i++;
+  }
+  out += '…';
+  // Re-apply a reset if the original was colored so the ellipsis/padding stay clean.
+  if (hadColor) out += '\x1b[0m';
+  return out;
+}

package/package.json

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