@zeyos/cli 0.2.0 → 0.3.0

package/README.md

@@ -72,6 +72,20 @@ For larger or reusable filters, put the JSON in a file:
 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
@@ -91,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

@@ -51,11 +51,13 @@ ${_c.bold('Commands:')}
   ${_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
@@ -82,6 +84,7 @@ const OPTIONS = {
   'yaml':       { type: 'boolean' },
   'no-color':   { type: 'boolean' },
   'query':      { type: 'boolean' },
+  'profile':    { type: 'string' },
   // login
   'base-url':   { type: 'string' },
   'client-id':  { type: 'string' },
@@ -117,6 +120,8 @@ const OPTIONS = {
   'target':     { type: 'string' },
   'dir':        { type: 'string' },
   'no-logo':    { type: 'boolean' },
+  // profile
+  'from-current': { type: 'boolean' },
 };
 
 // ── Command registry ──────────────────────────────────────────────────────────
@@ -142,6 +147,8 @@ const COMMANDS = {
   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 ────────────────────────────────────────────────
@@ -149,8 +156,9 @@ const COMMANDS = {
 // 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 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'];
 
@@ -174,6 +182,8 @@ const COMMAND_FLAGS = {
   doctor:    [],
   skills:    SKILLS_FLAGS,
   skill:     SKILLS_FLAGS,
+  profile:   PROFILE_FLAGS,
+  profiles:  PROFILE_FLAGS,
 };
 
 // ── Main ──────────────────────────────────────────────────────────────────────

package/commands/count.mjs

@@ -51,7 +51,7 @@ export async function run(values, positional) {
   }
 
   // ── Call API ───────────────────────────────────────────────────────────────
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
   if (await maybeDryRun(clientState, res.list, body, values)) return;
 
   const result = await callApi(clientState, res.list, body);

package/commands/create.mjs

@@ -48,7 +48,7 @@ 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;

package/commands/delete.mjs

@@ -37,7 +37,7 @@ 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();
+  const clientState = buildCliClient(values);
 
   // ── Dry run ────────────────────────────────────────────────────────────────
   // Show the request without prompting or deleting anything.

package/commands/get.mjs

@@ -68,7 +68,7 @@ export async function run(values, positional) {
   requireRecordId(id, 'zeyos get <resource> <id>');
 
   const resName = canonicalName(resourceName);
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
 
   // ── Build params ───────────────────────────────────────────────────────────
   // GET endpoints use query parameters like ?extdata=1&tags=1 to include

package/commands/list.mjs

@@ -116,7 +116,7 @@ export async function run(values, positional) {
   }
 
   // ── Call API ───────────────────────────────────────────────────────────────
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
   if (await maybeDryRun(clientState, res.list, body, values)) return;
 
   const fn = requireApiMethod(clientState, res.list);

package/commands/login.mjs

@@ -20,7 +20,7 @@
 
 import { createInterface }                from 'node:readline';
 import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
-import { saveConfig, loadConfig }         from '../lib/config.mjs';
+import { saveConfig, loadConfig, getProfile, upsertProfile, setActiveProfile } from '../lib/config.mjs';
 import { waitForCallback, callbackUri, BrowserUnavailableError } from '../lib/login-server.mjs';
 import { success, error, info, warn }     from '../lib/output.mjs';
 
@@ -35,6 +35,7 @@ Options:
   --base-url <url>    ZeyOS platform URL  (prompted if missing)
   --client-id <id>    OAuth client ID     (prompted if missing)
   --secret <secret>   OAuth client secret (prompted if missing)
+  --profile <name>    Store credentials/tokens in a named profile and activate it
   --scope <scope>     OAuth scope  (default: all)
   --port <port>       Local callback server port  (default: 9005)
   --global            Store credentials globally (~/.config/zeyos/credentials.json)
@@ -45,12 +46,21 @@ Options:
 `;
 
 export async function run(values) {
+  const profileName = values.profile || null;
   const scope = values.global ? 'global' : 'local';
   const port  = values.port ? Number(values.port) : DEFAULT_CALLBACK_PORT;
   const redirectUri = callbackUri(port);
 
+  // Persist either into a named profile or the legacy local/global credential file.
+  const persist = (updates) => {
+    if (profileName) upsertProfile(profileName, updates);
+    else saveConfig(updates, scope);
+  };
+
   // ── Resolve connection params ──────────────────────────────────────────────
-  const existing = values.clean ? {} : loadConfig();
+  const existing = values.clean
+    ? {}
+    : (profileName ? (getProfile(profileName) || {}) : loadConfig());
   if (values.clean) values.force = true;
 
   let baseUrl      = values['base-url']    ?? existing.baseUrl;
@@ -79,12 +89,17 @@ export async function run(values) {
   }
 
   // Save connection params immediately so they are available on retries
-  saveConfig({ baseUrl, clientId, clientSecret }, scope);
+  persist({ baseUrl, clientId, clientSecret });
 
   // ── Check if already authenticated ────────────────────────────────────────
   if (existing.accessToken && !values.force) {
-    warn('Already logged in.  Use --force to re-authenticate.');
-    return;
+    if (_tokenExpired(existing)) {
+      info('Stored access token has expired — re-authenticating…');
+    } else {
+      const where = profileName ? `profile "${profileName}"` : 'this scope';
+      warn(`Already logged in (${where}).  Use --force to re-authenticate.`);
+      return;
+    }
   }
 
   // ── Build a temporary client (no token yet) ────────────────────────────────
@@ -138,7 +153,7 @@ export async function run(values) {
     info('Exchanging authorization code for tokens…');
     const tokenSet = await client.oauth2.exchangeAuthorizationCode({ code, redirectUri });
 
-    saveConfig({
+    persist({
       baseUrl,
       clientId,
       clientSecret,
@@ -146,9 +161,12 @@ export async function run(values) {
       refreshToken:          tokenSet.refreshToken          ?? undefined,
       expiresAt:             tokenSet.expiresAt             ?? undefined,
       refreshTokenExpiresAt: tokenSet.refreshTokenExpiresAt ?? undefined,
-    }, scope);
+    });
 
-    success('Logged in successfully.');
+    if (profileName) setActiveProfile(profileName);
+    success(profileName
+      ? `Logged in — profile "${profileName}" is now active.`
+      : 'Logged in successfully.');
   } catch (err) {
     error(`Token exchange failed: ${err.message}`);
     process.exit(1);
@@ -157,6 +175,13 @@ export async function run(values) {
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
+/** True when stored creds carry an access token whose expiry is in the past. */
+function _tokenExpired(creds) {
+  if (!creds?.accessToken || creds.expiresAt == null) return false;
+  const exp = Number(creds.expiresAt) > 2e10 ? Number(creds.expiresAt) / 1000 : Number(creds.expiresAt);
+  return Number.isFinite(exp) && exp < Math.floor(Date.now() / 1000);
+}
+
 /**
  * Try the browser + callback server flow.
  * On any failure, fall back to prompting the user for the code.

package/commands/logout.mjs

@@ -10,7 +10,7 @@
  */
 
 import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
-import { loadConfig, clearTokens }             from '../lib/config.mjs';
+import { loadConfigWithSource, clearTokens, clearTokensForSource } from '../lib/config.mjs';
 import { success, warn, info }                 from '../lib/output.mjs';
 
 export const USAGE = `\
@@ -19,13 +19,13 @@ Usage: zeyos logout [options]
 Revoke the current session and clear stored tokens.
 
 Options:
-  --global    Target the global credentials file
-  -h, --help  Show this help
+  --profile <name>  Log out of a specific profile
+  --global          Target the legacy global credentials file
+  -h, --help        Show this help
 `;
 
 export async function run(values) {
-  const scope  = values.global ? 'global' : 'local';
-  const config = loadConfig();
+  const { config, source } = loadConfigWithSource({ profile: values.profile });
 
   if (!config.accessToken) {
     warn('Not currently logged in.');
@@ -58,6 +58,11 @@ export async function run(values) {
     }
   }
 
-  clearTokens(scope);
-  success('Logged out.');
+  if (values.global) {
+    clearTokens('global');
+  } else {
+    clearTokensForSource(source);
+  }
+  const where = source?.kind === 'profile' ? `profile "${source.name}"` : (values.global ? 'global credentials' : 'local credentials');
+  success(`Logged out (${where}).`);
 }

package/commands/profile.mjs

@@ -0,0 +1,211 @@
+/**
+ * zeyos profile <list|current|use|add|remove>
+ *
+ * Manage named credential profiles (e.g. dev, prod, client-x) and switch between
+ * ZeyOS instances without re-running login each time.
+ *
+ *   list                     Show all profiles (active marked with *)
+ *   current                  Show the profile that resolves right now, and why
+ *   use <name> [--local]     Make <name> active globally, or pin it to this project
+ *   add <name> [opts]        Create/update a profile's connection params
+ *   remove <name>            Delete a profile
+ *
+ * `add` options: --base-url, --client-id, --secret, or --from-current to snapshot
+ * the credentials currently in effect (including tokens) into the new profile.
+ */
+
+import {
+  listProfiles, getProfile, upsertProfile, removeProfile,
+  setActiveProfile, writeLocalPin, readLocalPin,
+  resolveProfileSelection, loadConfigWithSource, profilesConfigPath
+} from '../lib/config.mjs';
+import { outputMode, printJson, printYaml, printTable, success, error, info, warn } from '../lib/output.mjs';
+
+export const USAGE = `\
+Usage: zeyos profile <command> [options]
+
+Manage named credential profiles and switch between ZeyOS instances.
+
+Commands:
+  list                       List all profiles (active marked with *)
+  current                    Show which profile is in effect, and why
+  use <name>                 Make <name> the active profile (global)
+  use <name> --local         Pin <name> to the current project (.zeyos/profile)
+  add <name> [options]       Create or update a profile
+  remove <name>              Delete a profile
+
+Add options:
+  --base-url <url>           ZeyOS platform URL for the profile
+  --client-id <id>           OAuth client ID
+  --secret <secret>          OAuth client secret
+  --from-current             Snapshot the credentials currently in effect (incl. tokens)
+
+Global options:
+  --json | --yaml            Machine-readable output (list / current)
+  -h, --help                 Show this help
+
+Examples:
+  zeyos profile add dev  --base-url https://zeyos.cms-it.de/dev
+  zeyos profile add prod --from-current
+  zeyos profile use prod
+  zeyos profile use dev --local        # only inside this project
+  zeyos whoami --profile dev           # one-off override on any command
+`;
+
+export async function run(values, positional) {
+  const sub = positional[0] || 'list';
+  switch (sub) {
+    case 'list':    return cmdList(values);
+    case 'current': return cmdCurrent(values);
+    case 'use':     return cmdUse(values, positional[1]);
+    case 'add':     return cmdAdd(values, positional[1]);
+    case 'remove':
+    case 'rm':
+    case 'delete':  return cmdRemove(values, positional[1]);
+    default:
+      error(`Unknown profile command: "${sub}".`);
+      process.stderr.write(`\n${USAGE}`);
+      process.exit(1);
+  }
+}
+
+// ── list ───────────────────────────────────────────────────────────────────────
+
+function cmdList(values) {
+  const { active, profiles } = listProfiles();
+  const names = Object.keys(profiles);
+  const mode = outputMode(values);
+
+  if (mode === 'json') return printJson({ active, profiles });
+  if (mode === 'yaml') return printYaml({ active, profiles });
+
+  if (names.length === 0) {
+    info('No profiles defined yet.');
+    console.error(`Create one with:  zeyos profile add <name> --base-url <url>`);
+    console.error(`              or:  zeyos login --profile <name>`);
+    return;
+  }
+
+  const rows = names.map((name) => ({
+    name: `${name === active ? '*' : ' '} ${name}`,
+    baseUrl: profiles[name].baseUrl || '(no URL)',
+    token: tokenStatus(profiles[name])
+  }));
+  printTable(rows, ['name', 'baseUrl', 'token'], { name: 'PROFILE', baseUrl: 'BASE URL', token: 'TOKEN' });
+  console.error(`\nProfiles file: ${profilesConfigPath()}`);
+}
+
+// ── current ────────────────────────────────────────────────────────────────────
+
+function cmdCurrent(values) {
+  const selection = resolveProfileSelection({ profileFlag: values.profile });
+  const loaded = loadConfigWithSource({ profile: values.profile });
+  const mode = outputMode(values);
+
+  const out = {
+    profile: selection.name || null,
+    origin: selection.origin || null,
+    source: loaded.source,
+    baseUrl: loaded.config.baseUrl || null,
+    token: tokenStatus(loaded.config)
+  };
+
+  if (mode === 'json') return printJson(out);
+  if (mode === 'yaml') return printYaml(out);
+
+  if (selection.name) {
+    if (selection.missing) {
+      warn(`Selected profile "${selection.name}" (via ${selection.origin}) does not exist.`);
+      return;
+    }
+    success(`Active profile: ${selection.name}  (selected via ${selection.origin})`);
+  } else if (loaded.source) {
+    info(`No named profile in effect — using legacy ${loaded.source.kind} credentials.`);
+  } else {
+    warn('No credentials configured. Run `zeyos login` or `zeyos profile add`.');
+    return;
+  }
+  console.error(`  base URL: ${out.baseUrl || '(none)'}`);
+  console.error(`  token:    ${out.token}`);
+}
+
+// ── use ────────────────────────────────────────────────────────────────────────
+
+function cmdUse(values, name) {
+  if (!name) fail('Usage: zeyos profile use <name> [--local]');
+  if (!getProfile(name)) failUnknown(name);
+
+  if (values.local) {
+    const path = writeLocalPin(name);
+    success(`Pinned profile "${name}" to this project.`);
+    console.error(`  ${path}`);
+    return;
+  }
+  setActiveProfile(name);
+  success(`Active profile: ${name}`);
+}
+
+// ── add ────────────────────────────────────────────────────────────────────────
+
+function cmdAdd(values, name) {
+  if (!name) fail('Usage: zeyos profile add <name> [--base-url <url>] [--client-id <id>] [--secret <secret>] | --from-current');
+
+  let updates = {};
+  if (values['from-current']) {
+    const cfg = loadConfigWithSource().config; // whatever is in effect right now
+    for (const k of ['baseUrl', 'instance', 'clientId', 'clientSecret', 'accessToken', 'refreshToken', 'expiresAt', 'refreshTokenExpiresAt']) {
+      if (cfg[k] != null) updates[k] = cfg[k];
+    }
+    if (!updates.baseUrl) fail('Nothing to snapshot: no credentials are currently in effect.');
+  } else {
+    if (values['base-url'])  updates.baseUrl      = values['base-url'];
+    if (values['client-id']) updates.clientId     = values['client-id'];
+    if (values.secret)       updates.clientSecret = values.secret;
+    if (Object.keys(updates).length === 0) {
+      fail('Provide at least --base-url (and ideally --client-id/--secret), or use --from-current.');
+    }
+  }
+
+  const existed = Boolean(getProfile(name));
+  upsertProfile(name, updates);
+  success(`${existed ? 'Updated' : 'Created'} profile "${name}".`);
+  if (!updates.accessToken) {
+    info(`Finish authenticating with:  zeyos login --profile ${name}`);
+  }
+}
+
+// ── remove ─────────────────────────────────────────────────────────────────────
+
+function cmdRemove(values, name) {
+  if (!name) fail('Usage: zeyos profile remove <name>');
+  const removed = removeProfile(name);
+  if (!removed) failUnknown(name);
+  success(`Removed profile "${name}".`);
+  const pin = readLocalPin();
+  if (pin && pin.name === name) {
+    warn(`This project still pins "${name}" (${pin.path}); that pin will no longer resolve.`);
+  }
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────────
+
+/** Human-readable token status from stored creds. Handles seconds or ms expiry. */
+function tokenStatus(creds = {}) {
+  if (!creds.accessToken) return 'none';
+  const exp = creds.expiresAt;
+  if (exp == null) return 'present';
+  const expSec = Number(exp) > 2e10 ? Number(exp) / 1000 : Number(exp);
+  const now = Math.floor(Date.now() / 1000);
+  return expSec < now ? 'expired' : 'ok';
+}
+
+function failUnknown(name) {
+  const names = Object.keys(listProfiles().profiles);
+  const known = names.length ? `Known profiles: ${names.join(', ')}.` : 'No profiles defined yet.';
+  fail(`No such profile: "${name}". ${known}`);
+}
+
+function fail(message) {
+  error(message);
+  process.exit(1);
+}

package/commands/update.mjs

@@ -56,7 +56,7 @@ export async function run(values, positional) {
   // (optional) JSON body some callers pass positionally instead of via --data.
   const data = buildRecordPayload(values, positional[2]);
 
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
 
   // ── Call API ───────────────────────────────────────────────────────────────
   if (await maybeDryRun(clientState, res.update, { ID: id, body: data }, values)) return;

package/commands/whoami.mjs

@@ -27,7 +27,7 @@ Options:
 export async function run(values) {
   let client, config, tokenStore, configSource;
   try {
-    ({ client, config, tokenStore, configSource } = buildClient());
+    ({ client, config, tokenStore, configSource } = buildClient({}, { profile: values.profile }));
   } catch (err) {
     error(err.message);
     process.exit(1);
@@ -38,7 +38,14 @@ export async function run(values) {
     userInfo = await client.oauth2.getUserInfo();
     await syncTokens(tokenStore, configSource);
   } catch (err) {
-    error(`Failed to fetch user info: ${err.message}`);
+    const status = err?.status;
+    if (status === 502 || status === 503 || status === 504) {
+      error(`ZeyOS instance is temporarily unavailable (HTTP ${status}). The server at ${config.baseUrl} may be down or restarting — this is server-side, not your credentials.`);
+    } else if (status === 401) {
+      error('Your session has expired or is invalid. Re-authenticate with: zeyos login --force');
+    } else {
+      error(`Failed to fetch user info: ${err.message}`);
+    }
     process.exit(1);
   }
 

package/config/actionstep.json

@@ -0,0 +1,21 @@
+{
+  "list": {
+    "fields": {
+      "ID": "ID",
+      "Num": "actionnum",
+      "Name": "name",
+      "Status": "status",
+      "Date": "date",
+      "Due": "duedate",
+      "Effort": "effort",
+      "Ticket": "ticket",
+      "Task": "task",
+      "Account": "account",
+      "Transaction": "transaction"
+    }
+  },
+  "get": {
+    "fields": ["ID", "actionnum", "name", "description", "status", "date", "duedate", "effort", "ticket", "task", "account", "transaction", "assigneduser", "creator", "creationdate", "lastmodified"],
+    "params": { "extdata": 1 }
+  }
+}

package/config/customfield.json

@@ -0,0 +1,17 @@
+{
+  "list": {
+    "fields": {
+      "ID": "ID",
+      "Name": "name",
+      "Identifier": "identifier",
+      "Context": "context",
+      "Reference": "reference",
+      "Type": "type",
+      "Entity": "entity",
+      "Activity": "activity"
+    }
+  },
+  "get": {
+    "fields": ["ID", "name", "identifier", "context", "source", "reference", "indexed", "type", "pattern", "entity", "options", "langaliases", "activity"]
+  }
+}

package/config/message.json

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

package/config/task.json

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

package/config/ticket.json

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

package/lib/client.mjs

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

package/lib/command.mjs

@@ -33,9 +33,9 @@ export function requireRecordId(id, usage) {
   }
 }
 
-export function buildCliClient() {
+export function buildCliClient(values = {}) {
   try {
-    return buildClient();
+    return buildClient({}, { profile: values.profile });
   } catch (err) {
     fail(err.message);
   }

package/lib/config.mjs

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

package/lib/flags.mjs

@@ -10,7 +10,7 @@ const RESERVED_FLAGS = new Set([
   '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', 'query',
+  'extdata', 'tags', 'all', 'clean', 'query', 'profile',
 ]);
 
 /**

package/lib/resources.mjs

@@ -14,13 +14,21 @@
 
 /** @type {Record<string, ResourceDef>} */
 const REGISTRY = {
+  actionstep: {
+    list:   'listActionSteps',
+    get:    'getActionStep',
+    create: 'createActionStep',
+    update: 'updateActionStep',
+    delete: 'deleteActionStep',
+    fields: ['ID', 'actionnum', 'name', 'status', 'date', 'duedate', 'effort', 'ticket', 'task', 'account'],
+  },
   ticket: {
     list:   'listTickets',
     get:    'getTicket',
     create: 'createTicket',
     update: 'updateTicket',
     delete: 'deleteTicket',
-    fields: ['ID', 'ticketnum', 'name', 'status', 'priority', 'duedate', 'lastmodified'],
+    fields: ['ID', 'ticketnum', 'name', 'status', 'priority', 'duedate', 'account', 'project', 'lastmodified'],
   },
   task: {
     list:   'listTasks',
@@ -28,7 +36,7 @@ const REGISTRY = {
     create: 'createTask',
     update: 'updateTask',
     delete: 'deleteTask',
-    fields: ['ID', 'tasknum', 'name', 'status', 'priority', 'duedate', 'ticket'],
+    fields: ['ID', 'tasknum', 'name', 'status', 'priority', 'duedate', 'ticket', 'project', 'projectedeffort'],
   },
   account: {
     list:   'listAccounts',
@@ -84,7 +92,7 @@ const REGISTRY = {
     create: 'createMessage',
     update: 'updateMessage',
     delete: 'deleteMessage',
-    fields: ['ID', 'subject', 'sender', 'created', 'read'],
+    fields: ['ID', 'date', 'mailbox', 'subject', 'sender_email', 'to_email', 'ticket', 'reference', 'messageid'],
   },
   item: {
     list:   'listItems',
@@ -144,6 +152,11 @@ const REGISTRY = {
     delete: 'deleteCampaign',
     fields: ['ID', 'name', 'status', 'startdate', 'enddate'],
   },
+  customfield: {
+    list:   'listCustomFields',
+    get:    'getCustomField',
+    fields: ['ID', 'name', 'identifier', 'context', 'reference', 'type', 'entity', 'activity'],
+  },
   file: {
     list:   'listFiles',
     get:    'getFile',
@@ -174,6 +187,13 @@ const REGISTRY = {
 
 const ALIASES = {
   // Plurals
+  actionsteps:  'actionstep',
+  'action-steps': 'actionstep',
+  action_steps: 'actionstep',
+  timeentry:    'actionstep',
+  timeentries:  'actionstep',
+  'time-entry': 'actionstep',
+  'time-entries': 'actionstep',
   tickets:      'ticket',
   tasks:        'task',
   accounts:     'account',
@@ -193,6 +213,9 @@ const ALIASES = {
   payments:     'payment',
   opportunities:'opportunity',
   campaigns:    'campaign',
+  customfields:  'customfield',
+  custom_fields: 'customfield',
+  'custom-fields': 'customfield',
   files:        'file',
   invitations:  'invitation',
   storages:     'storage',

package/package.json

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