@zeyos/cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZeyOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# ZeyOS CLI
+
+The CLI is the default interface for coding agents and shell automation that work against the curated ZeyOS resource registry.
+
+The authoritative documentation lives in the repository-level docs:
+
+- [Coding Agents](../docs/04-agent-workflows/00-coding-agents.md)
+- [Agent Quickstart](../docs/04-agent-workflows/01-agent-quickstart.md)
+- [CLI Getting Started](../docs/03-cli/01-getting-started.md)
+- [Commands Reference](../docs/03-cli/02-commands.md)
+- [Configuration](../docs/03-cli/03-configuration.md)
+
+## Install
+
+From the repository root:
+
+```bash
+npm install
+npm link cli/
+zeyos --help
+```
+
+Or install the package directly:
+
+```bash
+npm install -g @zeyos/cli
+```
+
+## Quick Start
+
+Authenticate:
+
+```bash
+export ZEYOS_CLIENT_SECRET="..."
+zeyos login \
+  --base-url https://cloud.zeyos.com/demo \
+  --client-id myapp \
+  --secret "$ZEYOS_CLIENT_SECRET"
+```
+
+For interactive use, omit `--secret`; the CLI prompts without echoing the secret to the terminal.
+
+Verify the current user:
+
+```bash
+zeyos whoami --json
+```
+
+`whoami` does not print access tokens by default. Use `zeyos whoami --show-token --json` only when you intentionally need to pass a token to another local tool.
+
+Inspect the CLI-supported resource registry:
+
+```bash
+zeyos resources
+```
+
+List tickets for automation:
+
+```bash
+zeyos list tickets \
+  --fields ID,ticketnum,name,status,priority,lastmodified \
+  --filter '{"visibility":0}' \
+  --sort -lastmodified \
+  --limit 20 \
+  --json
+```
+
+Create, update, and delete:
+
+```bash
+zeyos create ticket --data '{"name":"Fix login bug","status":0,"priority":3,"visibility":0}' --json
+zeyos update ticket 42 --data '{"status":4}' --json
+zeyos delete ticket 42
+```
+
+## Configuration
+
+- Local credentials: `.zeyos/auth.json`
+- Global credentials: `~/.config/zeyos/credentials.json`
+- Project resource overrides: `.zeyos/api/<resource>.json`
+- Global resource overrides: `~/.zeyos/api/<resource>.json`
+
+## Coverage Boundary
+
+The CLI intentionally covers a curated registry instead of the full API surface. 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

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * ZeyOS CLI — entry point
+ *
+ * Usage: zeyos <command> [options] [args…]
+ *
+ * Commands:
+ *   login                Authenticate with ZeyOS
+ *   logout               Revoke session and clear tokens
+ *   whoami               Show current user info
+ *   list <resource>      List records
+ *   count <resource>     Count records
+ *   get <resource> <id>  Fetch a single record
+ *   show <resource> <id> Alias for get
+ *   create <resource>    Create a new record
+ *   update <resource>    Update a record
+ *   delete <resource>    Delete a record
+ *   resources            List available resource types
+ */
+
+// ── Version ───────────────────────────────────────────────────────────────────
+
+import { createRequire as _createRequire } from 'node:module';
+import { dirname as _dirname } from 'node:path';
+import { fileURLToPath as _fileURLToPath } from 'node:url';
+const _require = _createRequire(import.meta.url);
+const _VERSION = _require('../package.json').version;
+
+// ── Global help ───────────────────────────────────────────────────────────────
+
+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:
+  --json               Output as JSON
+  --yaml               Output as YAML
+  --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
+`;
+
+// ── Argument definitions ──────────────────────────────────────────────────────
+
+const OPTIONS = {
+  // Global
+  'help':       { type: 'boolean', short: 'h' },
+  'version':    { type: 'boolean', short: 'v' },
+  'json':       { type: 'boolean' },
+  'yaml':       { type: 'boolean' },
+  'no-color':   { type: 'boolean' },
+  // login
+  'base-url':   { type: 'string' },
+  'client-id':  { type: 'string' },
+  'secret':     { type: 'string' },
+  'scope':      { type: 'string' },
+  'port':       { type: 'string' },
+  'global':     { type: 'boolean' },
+  'local':      { type: 'boolean' },
+  'force':      { type: 'boolean' },
+  'clean':      { type: 'boolean' },
+  'manual':     { type: 'boolean' },
+  'yes':        { type: 'boolean', short: 'y' },
+  // list
+  'fields':     { type: 'string' },
+  'filter':     { type: 'string' },
+  'sort':       { type: 'string' },
+  'limit':      { type: 'string' },
+  'offset':     { type: 'string' },
+  'expand':     { type: 'string' },
+  'extdata':    { type: 'boolean' },
+  'tags':       { type: 'boolean' },
+  // get
+  'all':        { type: 'boolean' },
+  // whoami
+  'show-token': { type: 'boolean' },
+  // create / update
+  'data':       { type: 'string' },
+  // delete
+  // (--force is already declared above)
+  // skills install
+  'target':     { type: 'string' },
+  'dir':        { type: 'string' },
+  'no-logo':    { type: 'boolean' },
+};
+
+// ── Command registry ──────────────────────────────────────────────────────────
+// Maps every command and alias to the module that implements it.
+
+const COMMANDS = {
+  login:     '../commands/login.mjs',
+  logout:    '../commands/logout.mjs',
+  whoami:    '../commands/whoami.mjs',
+  list:      '../commands/list.mjs',
+  count:     '../commands/count.mjs',
+  get:       '../commands/get.mjs',
+  show:      '../commands/get.mjs',
+  create:    '../commands/create.mjs',
+  update:    '../commands/update.mjs',
+  edit:      '../commands/update.mjs',
+  delete:    '../commands/delete.mjs',
+  rm:        '../commands/delete.mjs',
+  remove:    '../commands/delete.mjs',
+  resources: '../commands/resources.mjs',
+  resource:  '../commands/resources.mjs',
+  describe:  '../commands/describe.mjs',
+  skills:    '../commands/skills.mjs',
+  skill:     '../commands/skills.mjs',
+};
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  // Strip 'node' and script path from argv
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+
+  if (argv[0] === '--version' || argv[0] === '-v') {
+    process.stdout.write(_VERSION + '\n');
+    process.exit(0);
+  }
+
+  const command = argv[0];
+  const rest    = argv.slice(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 modulePath = COMMANDS[command];
+  if (!modulePath) {
+    process.stderr.write(`Unknown command: "${command}"\n\n${HELP}`);
+    process.exit(1);
+  }
+
+  const mod = await import(modulePath);
+
+  if (values.help) {
+    process.stdout.write(mod.USAGE ?? HELP);
+    process.exit(0);
+  }
+
+  await mod.run(values, positional);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Parse argv with known options; capture unknown --key value pairs too.
+ * This lets create/update accept arbitrary --fieldName value flags.
+ *
+ * Supports both `--key value` and `--key=value` forms.
+ */
+function _parsePermissive(argv, options) {
+  const values     = {};
+  const positional = [];
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (arg === '--') {
+      // Everything after -- is positional
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+
+    if (arg.startsWith('--')) {
+      // Split --key=value form into key + inline value
+      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 (opt?.type === 'boolean') {
+        // --key=value is unusual for booleans; treat as true and ignore =value
+        values[key] = true;
+        i++;
+        continue;
+      }
+
+      if (opt?.type === 'string') {
+        if (inlineVal !== undefined) {
+          // --key=value form
+          values[key] = inlineVal;
+          i++;
+        } else {
+          const next = argv[i + 1];
+          // Don't consume the next token as the value if it looks like a flag
+          // (starts with '--'), unless it's a negative number like -3 or -3.5.
+          if (next !== undefined && next.startsWith('--')) {
+            values[key] = '';
+            i++;
+          } else {
+            values[key] = next ?? '';
+            i += 2;
+          }
+        }
+        continue;
+      }
+
+      // Unknown option — treat as string
+      if (inlineVal !== undefined) {
+        // --key=value form for unknown option
+        values[key] = inlineVal;
+        i++;
+      } else if (i + 1 < argv.length && (!argv[i + 1].startsWith('-') || /^-\d/.test(argv[i + 1]))) {
+        values[key] = argv[i + 1];
+        i += 2;
+      } else {
+        values[key] = true;
+        i++;
+      }
+      continue;
+    }
+
+    if (arg.startsWith('-') && arg.length === 2) {
+      // Short option
+      const short = arg[1];
+      const match = Object.entries(options).find(([, o]) => o.short === short);
+      if (match) {
+        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;
+          }
+        }
+      } else {
+        i++;
+      }
+      continue;
+    }
+
+    positional.push(arg);
+    i++;
+  }
+
+  return { values, positional };
+}
+
+main().catch(err => {
+  process.stderr.write(`Fatal: ${err.message}\n`);
+  process.exit(1);
+});

package/commands/count.mjs

@@ -0,0 +1,63 @@
+/**
+ * zeyos count <resource>
+ *
+ * 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
+ */
+
+import { normalizeCountResult }    from '@zeyos/client';
+import { buildCliClient, callApi, parseJsonOption, requireResource } from '../lib/command.mjs';
+import { outputMode, printJson, printYaml } from '../lib/output.mjs';
+
+export const USAGE = `\
+Usage: zeyos count <resource> [options]
+
+Return the number of records matching an optional filter.
+
+Arguments:
+  resource            Resource name (e.g. tickets, accounts, tasks)
+
+Options:
+  --filter <json>     JSON filter object  e.g. '{"status":1}'
+  --json              Output as JSON ({ "count": N })
+  --yaml              Output as YAML
+  -h, --help          Show this help
+
+Examples:
+  zeyos count tickets
+  zeyos count tickets --filter '{"status":1}'
+  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');
+  }
+
+  // ── Call API ───────────────────────────────────────────────────────────────
+  const result = await callApi(clientState, res.list, body);
+
+  const count = normalizeCountResult(result);
+
+  // ── Output ─────────────────────────────────────────────────────────────────
+  const mode = outputMode(values);
+
+  if (mode === 'json') {
+    printJson({ count });
+  } else if (mode === 'yaml') {
+    printYaml({ count });
+  } else {
+    process.stdout.write(`${count}\n`);
+  }
+}

package/commands/create.mjs

@@ -0,0 +1,62 @@
+/**
+ * zeyos create <resource> [--data <json>] [--field value …]
+ *
+ * Create a new record.  Field values can be supplied either as:
+ *   - a JSON blob via --data '{"name":"foo","status":1}'
+ *   - 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
+ */
+
+import { buildCliClient, buildRecordPayload, callApi, requireResource } from '../lib/command.mjs';
+import { outputMode, printJson, printYaml, printRecord, success } from '../lib/output.mjs';
+
+export const USAGE = `\
+Usage: zeyos create <resource> [options]
+
+Create a new record.
+
+Arguments:
+  resource            Resource name (e.g. ticket, account)
+
+Options:
+  --data <json>       Record fields as a JSON object
+  --<field> <value>   Set individual fields  e.g. --name "My Ticket" --status 1
+  --json              Output created record as JSON
+  --yaml              Output created record as YAML
+  -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"}'
+`;
+
+export async function run(values, positional) {
+  const resourceName = positional[0];
+  const res = requireResource(resourceName, 'zeyos create <resource>', 'create', 'creation');
+
+  // ── Build data payload ─────────────────────────────────────────────────────
+  // Validate input before requiring credentials.  positional[1] is the
+  // (optional) JSON body some callers pass positionally instead of via --data.
+  const data = buildRecordPayload(values, positional[1]);
+
+  const clientState = buildCliClient();
+
+  // ── Call API ───────────────────────────────────────────────────────────────
+  const record = await callApi(clientState, res.create, data);
+
+  const mode = outputMode(values);
+
+  if (mode === 'json') {
+    printJson(record);
+  } else if (mode === 'yaml') {
+    printYaml(record);
+  } else {
+    const id = record?.ID ?? record?.id ?? '?';
+    success(`Created ${resourceName} #${id}.`);
+    if (record) printRecord(record, res.fields);
+  }
+}

package/commands/delete.mjs

@@ -0,0 +1,68 @@
+/**
+ * zeyos delete <resource> <id>
+ *
+ * Delete a record by ID.
+ *
+ * Options:
+ *   --force    Skip confirmation prompt
+ */
+
+import { createInterface }         from 'node:readline';
+import { buildCliClient, callApi, requireRecordId, requireResource } from '../lib/command.mjs';
+import { success, warn }           from '../lib/output.mjs';
+
+export const USAGE = `\
+Usage: zeyos delete <resource> <id> [options]
+
+Delete a record by ID.
+
+Arguments:
+  resource            Resource name (e.g. ticket, account)
+  id                  Record ID
+
+Options:
+  --force             Skip confirmation prompt
+  -h, --help          Show this help
+
+Examples:
+  zeyos delete ticket 42
+  zeyos delete account 7 --force
+`;
+
+export async function run(values, positional) {
+  const resourceName = positional[0];
+  const id           = positional[1];
+
+  const res = requireResource(resourceName, 'zeyos delete <resource> <id>', 'delete', 'deletion');
+  requireRecordId(id, 'zeyos delete <resource> <id>');
+
+  // ── Confirmation ───────────────────────────────────────────────────────────
+  if (!values.force) {
+    const confirmed = await _confirm(`Delete ${resourceName} #${id}? [y/N] `);
+    if (!confirmed) {
+      warn('Aborted.');
+      return;
+    }
+  }
+
+  const clientState = buildCliClient();
+
+  // ── Call API ───────────────────────────────────────────────────────────────
+  await callApi(clientState, res.delete, { ID: id }, {
+    notFoundMessage: `${resourceName} #${id} not found.`
+  });
+
+  success(`Deleted ${resourceName} #${id}.`);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function _confirm(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise(resolve => {
+    rl.question(prompt, answer => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}

package/commands/describe.mjs

@@ -0,0 +1,102 @@
+/**
+ * zeyos describe <resource>
+ *
+ * Print a resource's schema — fields, types, foreign keys, enums — straight
+ * from the generated schema. Works offline (no login required), so an agent
+ * can discover the data model before making any call.
+ */
+
+import { createZeyosClient } from '@zeyos/client';
+import { resolveResource } from '../lib/resources.mjs';
+import { colors as c, outputMode, printJson, printYaml, printTable, error } from '../lib/output.mjs';
+
+export const USAGE = `\
+Usage: zeyos describe <resource> [options]
+
+Show the fields, types, foreign keys and enum values for a resource.
+Runs offline — no authentication required.
+
+Arguments:
+  resource            Resource name (e.g. ticket, tickets, account)
+
+Options:
+  --json              Output as JSON
+  --yaml              Output as YAML
+  -h, --help          Show this help
+
+Examples:
+  zeyos describe tickets
+  zeyos describe accounts --json
+`;
+
+let cachedSchema;
+function schema() {
+  if (!cachedSchema) {
+    cachedSchema = createZeyosClient({ auth: { mode: 'none' } }).schema;
+  }
+  return cachedSchema;
+}
+
+/**
+ * Resolve a user-supplied resource name to the canonical schema key, honoring the
+ * same singular/plural/alias rules the other commands use (`create`, `update`,
+ * `list` go through resolveResource). Without this, `describe` was the lone command
+ * that rejected singular/alias names — `describe ticket` failed while `create
+ * ticket` worked. Order: exact schema match → CLI registry → bridge an operationId
+ * back to its schema resource.
+ */
+function schemaKeyFor(s, input) {
+  if (s.describe(input)) return input;
+  const def = resolveResource(input);
+  if (def) {
+    const op = def.list || def.get || def.create || def.update || def.delete;
+    const key = op ? s.resourceForOperation(op) : null;
+    if (key && s.describe(key)) return key;
+  }
+  return null;
+}
+
+export function run(values, positional = []) {
+  const resource = positional[0];
+  const s = schema();
+
+  if (!resource) {
+    error('A resource is required. Example: zeyos describe tickets  (run "zeyos resources" to list common ones)');
+    process.exit(1);
+  }
+
+  const key = schemaKeyFor(s, resource);
+  if (!key) {
+    error(`Unknown resource "${resource}". Run "zeyos resources" for common resources.`);
+    process.exit(1);
+  }
+  const def = s.describe(key);
+
+  const mode = outputMode(values);
+  if (mode === 'json') {
+    printJson(def);
+    return;
+  }
+  if (mode === 'yaml') {
+    printYaml(def);
+    return;
+  }
+
+  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(' '));
+    }
+    return { field: name, type: field.type, notes: notes.join('  ') };
+  });
+
+  const operations = s.operations(key);
+
+  process.stdout.write(`\n  ${c.bold(def.name)} ${c.dim(`(${def.type}, ${rows.length} fields)`)}\n`);
+  printTable(rows, ['field', 'type', 'notes']);
+  if (operations.length > 0) {
+    process.stdout.write(`  ${c.bold('operations')}  ${c.dim(operations.join(', '))}\n\n`);
+  }
+}