@zeyos/cli 0.1.1 → 0.3.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,33 @@ 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
+```
+
+Inspect dynamic schema definitions:
+
+```bash
+zeyos count customfields --json
+zeyos list customfields --fields ID,name,identifier,context,type --json
+```
+
+Inspect actionsteps/time-entry evidence and ticket mail:
+
+```bash
+zeyos list actionsteps --fields ID,name,status,date,duedate,effort,ticket,account --json
+zeyos list messages --fields ID,date,mailbox,subject,sender_email,to_email,ticket,reference --filter '{"ticket":42}' --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
 ```
 
@@ -82,6 +105,6 @@ zeyos delete ticket 42
 
 ## Coverage Boundary
 
-The CLI intentionally covers a curated registry instead of the full API surface. Use `zeyos resources` to see the supported set.
+The CLI intentionally covers a curated registry instead of the full API surface. It includes operational resources such as tickets, tasks, messages, and actionsteps; use `zeyos resources` to see the supported set.
 
 When you need unsupported resources or low-level request control, switch to [`@zeyos/client`](../docs/02-javascript-client/01-getting-started.md) and follow the escalation guidance in [CLI Coverage and Escalation](../docs/04-agent-workflows/03-cli-coverage-and-escalation.md).

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,54 @@
 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.cyan('profile')} <command>    Manage credential profiles / switch instances
+
+${_c.bold('Global options:')}
   --json               Output as JSON
   --yaml               Output as YAML
+  --query              Print the API route + JSON payload without sending it
+  --profile <name>     Use a named credential profile for this command
   --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 +83,8 @@ const OPTIONS = {
   'json':       { type: 'boolean' },
   'yaml':       { type: 'boolean' },
   'no-color':   { type: 'boolean' },
+  'query':      { type: 'boolean' },
+  'profile':    { type: 'string' },
   // login
   'base-url':   { type: 'string' },
   'client-id':  { type: 'string' },
@@ -88,6 +100,7 @@ const OPTIONS = {
   // list
   'fields':     { type: 'string' },
   'filter':     { type: 'string' },
+  'filter-file': { type: 'string' },
   'sort':       { type: 'string' },
   'limit':      { type: 'string' },
   'offset':     { type: 'string' },
@@ -100,12 +113,15 @@ const OPTIONS = {
   'show-token': { type: 'boolean' },
   // create / update
   'data':       { type: 'string' },
+  'data-file':  { type: 'string' },
   // delete
   // (--force is already declared above)
   // skills install
   'target':     { type: 'string' },
   'dir':        { type: 'string' },
   'no-logo':    { type: 'boolean' },
+  // profile
+  'from-current': { type: 'boolean' },
 };
 
 // ── Command registry ──────────────────────────────────────────────────────────
@@ -128,8 +144,46 @@ 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',
+  profile:   '../commands/profile.mjs',
+  profiles:  '../commands/profile.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', 'profile'];
+const SKILLS_FLAGS = ['target', 'dir', 'global', 'local', 'force', 'yes', 'no-logo'];
+const PROFILE_FLAGS = ['base-url', 'client-id', 'secret', 'local', 'from-current'];
+const DELETE_FLAGS = ['force', 'query'];
+const GET_FLAGS    = ['fields', 'extdata', 'tags', 'expand', 'all', 'query'];
+
+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,
+  profile:   PROFILE_FLAGS,
+  profiles:  PROFILE_FLAGS,
 };
 
 // ── Main ──────────────────────────────────────────────────────────────────────
@@ -149,6 +203,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 +230,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 +354,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(values);
+  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) {
@@ -43,9 +48,11 @@ export async function run(values, positional) {
   // (optional) JSON body some callers pass positionally instead of via --data.
   const data = buildRecordPayload(values, positional[1]);
 
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
 
   // ── 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(values);
+
+  // ── 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';
+}