Zum Hauptinhalt springen

CLI Getting Started

The ZeyOS CLI gives you fast, scriptable access to the ZeyOS REST API from your terminal. It is the default entry point for coding agents and shell automation against the CLI's curated resource registry.

Installation​

Requirements

Node.js 18.3+ is required. The CLI has zero external dependencies beyond the bundled @zeyos/client package.

Install the CLI globally from npm:

Bash
npm install -g @zeyos/cli
zeyos --help

Running from source​

If you are contributing to the CLI or need to run an unreleased version, clone the repository and run directly from the source tree:

Bash
# Clone the repository
git clone <repo-url>
cd client

# Run directly
./cli/bin/zeyos.mjs --help

For convenience, create a symlink so you can run zeyos from anywhere:

Bash
ln -s $(pwd)/cli/bin/zeyos.mjs /usr/local/bin/zeyos

First Login​

Authenticate with your ZeyOS instance using the login command:

Bash
# Interactive — prompts for URL, app ID, and secret
zeyos login

# Or provide all values upfront
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. Passing secrets as command-line arguments is best reserved for controlled automation.

What happens:

  1. The CLI opens your browser to the ZeyOS authorization page
  2. You log in and authorize the application
  3. The CLI exchanges the authorization code for access + refresh tokens
  4. Credentials are saved to .zeyos/auth.json in your project
Switching Instances

Use --clean to discard all saved credentials and start fresh:

Bash
zeyos login --clean

This is useful when switching between ZeyOS instances.

Your First Commands​

Once logged in, you can start working with your data:

Bash
# Check who you're logged in as
zeyos whoami

# List tickets (table output by default)
zeyos list tickets

# Get a specific ticket with all details
zeyos get ticket 42 --all

# Count records
zeyos count accounts

# Create a new ticket
zeyos create ticket --name "Fix login bug" --status 0 --priority 3

# Update a ticket's status
zeyos update ticket 42 --status 4

# Delete a ticket
zeyos delete ticket 42

Inspect the curated CLI-supported resource set at any time:

Bash
zeyos resources

If the resource you need does not appear there, switch to @zeyos/client.

Discover the Schema​

Inspect a resource's fields, types, foreign keys, and enum values before querying. This works offline -- no login required -- so it is a fast way to learn the data model:

Bash
zeyos describe tickets
zeyos describe accounts --json

Install Agent Skills​

If you are driving the CLI from a coding agent (Claude Code, Codex, opencode, Factory Droid, pi, …), install the bundled ZeyOS skill packs so the agent picks up the right query conventions:

Bash
zeyos skills list                 # see the available skills
zeyos skills install              # interactive: pick an agent, then local vs. global
zeyos skills install --target claude --global   # or skip the prompts with flags

See the Commands Reference for details.

Working with Filters​

Query specific records using JSON filter expressions:

Bash
# Tickets with status = 1 (In Progress)
zeyos list tickets --filter '{"status":1}'

# Combine multiple criteria (AND logic)
zeyos list tickets --filter '{"status":1,"priority":3}'

# Count matching records
zeyos count tickets --filter '{"status":1}'

For larger filters, store the JSON in a file and use --filter-file:

Bash
zeyos list tickets --filter-file ./filters/open-tickets.json --json
zeyos count tickets --filter-file ./filters/open-tickets.json --json

For normal operational views, include visibility: 0:

Bash
zeyos list tickets --filter '{"visibility":0,"status":1}'

Sorting and Pagination​

Bash
# Sort by name ascending, then by last modified descending
zeyos list tickets --sort "+name,-lastmodified"

# Limit results and paginate
zeyos list tickets --limit 10
zeyos list tickets --limit 10 --offset 10   # page 2

When results fill the page limit, the CLI automatically shows pagination info:

Text
Showing 1–10 of 47  (--offset 10 for next page)

Output Formats​

Choose the format that fits your workflow:

Bash
# Default: formatted table (human-readable)
zeyos list tickets

# JSON: for scripting and piping
zeyos list tickets --json

# YAML: for config-friendly output
zeyos list tickets --yaml
Piping

JSON output works great with tools like jq:

Bash
zeyos list tickets --json | jq '.[].name'

JSON-First Automation​

For coding agents and non-interactive scripts, prefer --json output and JSON-first writes:

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 whoami --json does not print access tokens. If a local tool explicitly needs the current token, use zeyos whoami --show-token --json and treat the output as a secret.

Credential Storage​

Tokens are saved to .zeyos/auth.json in your project directory (or the nearest parent that has one). For global credentials shared across projects:

Bash
zeyos login --global

This saves to ~/.config/zeyos/credentials.json instead.

warning

Add .zeyos/auth.json to your .gitignore — it contains access tokens.

Next Steps​