Skip to main content

Agent Quickstart

This guide gets a coding agent from zero to authenticated CRUD access with the ZeyOS CLI.

Install or Run the CLI​

From this repository:

Bash
npm install
node cli/bin/zeyos.mjs --help

For a global zeyos command during development:

Bash
npm link cli/
zeyos --help

Load the ZeyOS Skills​

Before doing real work, install the bundled skill packs so the agent picks up ZeyOS's query conventions (entity model, filters usage, safe writes):

Bash
zeyos skills list                 # see what's available
zeyos skills install              # interactive: pick an agent (claude, codex, opencode, droid, pi…), then local/global
zeyos skills install --target claude --global -y   # or non-interactively with flags

This is the recommended entry point for an agent: the skills encode how to resolve names to IDs, which resource to query first, and how to escalate from the CLI to @zeyos/client.

Authenticate​

Interactive login:

Bash
zeyos login

Pre-fill login parameters:

Bash
zeyos login \
  --base-url https://cloud.zeyos.com/demo \
  --client-id myapp \
  --secret "$ZEYOS_CLIENT_SECRET"

This still starts the OAuth authorization-code flow and requires a browser redirect or pasted code. For fully unattended agents, inject ZEYOS_BASE_URL, ZEYOS_TOKEN, and optionally ZEYOS_REFRESH_TOKEN, ZEYOS_CLIENT_ID, and ZEYOS_CLIENT_SECRET through the environment.

The CLI stores credentials in .zeyos/auth.json in the current project tree, or in ~/.config/zeyos/credentials.json when --global is used.

Verify the Session​

Check the current user:

Bash
zeyos whoami --json

whoami hides access tokens by default. Use zeyos whoami --show-token --json only when the token must be handed to another local tool.

Discover which curated resources the CLI can operate on directly:

Bash
zeyos resources

Inspect a resource's fields, types and enum values before querying (works offline, no login needed):

Bash
zeyos describe tickets

Read Data​

List tickets in machine-readable form:

Bash
zeyos list tickets --json

List only the fields an agent needs:

Bash
zeyos list tickets \
  --fields ID,ticketnum,name,status,priority,lastmodified \
  --filter '{"visibility":0}' \
  --sort -lastmodified \
  --limit 20 \
  --json

Fetch one record:

Bash
zeyos get ticket 42 --all --json

Count matching records:

Bash
zeyos count tickets --filter '{"visibility":0,"status":4}' --json
zeyos count customfields --json
zeyos count actionsteps --filter '{"status":0}' --json

Summarize actionstep effort/time-entry evidence:

Bash
zeyos list actionsteps \
  --fields ID,name,status,date,duedate,effort,ticket,task,account \
  --filter '{"status":3}' \
  --limit 100 \
  --json

Inspect ticket-linked mail without sending anything:

Bash
zeyos list messages \
  --fields ID,date,mailbox,subject,sender_email,to_email,ticket,reference,messageid \
  --filter '{"ticket":42}' \
  --sort +date \
  --json

Write Data​

Create with JSON-first input:

Bash
zeyos create ticket \
  --data '{"name":"Follow up with customer","status":0,"priority":2,"visibility":0}' \
  --json

Update with JSON-first input:

Bash
zeyos update ticket 42 \
  --data '{"status":4,"priority":3}' \
  --json

Delete interactively:

Bash
zeyos delete ticket 42

Delete non-interactively only when the automation has already decided the record must be removed:

Bash
zeyos delete ticket 42 --force

Safe Defaults for Agents​

  • Use --json unless a human is actively reading the output.
  • Include visibility: 0 in filters for normal business views.
  • Prefer --data '<json>' over many separate flags in automation.
  • Run zeyos resources before assuming a resource is CLI-supported.
  • Use actionsteps.effort for time-entry totals; do not infer booked time from task assignment.
  • Draft e-mail text in the response unless the user explicitly asks for a real ZeyOS draft record; never send mail from an agent workflow.
  • Escalate to @zeyos/client when the CLI resource registry is not enough.