Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pixlcore/xyops/llms.txt

Use this file to discover all available pages before exploring further.

xyOps provides a comprehensive set of command-line tools for service management, database operations, and administrative tasks.

​
Control Script

The main control script manages the xyOps service lifecycle: 
/opt/xyops/bin/control.sh [COMMAND]

​
Available Commands

Starts xyOps in daemon mode.
/opt/xyops/bin/control.sh start
The process runs in the background with output logged to logs/xyops.pid.
Stops the xyOps daemon and waits for graceful exit.
/opt/xyops/bin/control.sh stop
Sends SIGTERM and waits for the process to exit cleanly.
Performs a full restart (stop + start).
/opt/xyops/bin/control.sh restart
Equivalent to calling stop then start in sequence.
Checks whether xyOps is currently running.
/opt/xyops/bin/control.sh status
Example output:
status: xyOps Server running (pid 12345)
Starts xyOps in debug mode (foreground with verbose logging).
/opt/xyops/bin/control.sh debug
Runs with:
  • --debug flag
  • --debug_level 9 (maximum verbosity)
  • --trace-warnings
  • Interactive REPL
  • Colored console output
Creates an emergency admin account.
/opt/xyops/bin/control.sh admin USERNAME PASSWORD
See Recover Admin Access below.
Manually grants a privilege to a user.
/opt/xyops/bin/control.sh grant USERNAME PRIVILEGE_ID
Example:
/opt/xyops/bin/control.sh grant johndoe admin
Manually revokes a privilege from a user.
/opt/xyops/bin/control.sh revoke USERNAME PRIVILEGE_ID
Example:
/opt/xyops/bin/control.sh revoke johndoe create_events
Upgrades xyOps to the latest stable release or specified version.
# Upgrade to latest stable
/opt/xyops/bin/control.sh upgrade

# Upgrade to specific version
/opt/xyops/bin/control.sh upgrade 1.0.4

# Upgrade to HEAD (bleeding edge - use with caution)
/opt/xyops/bin/control.sh upgrade HEAD
See Upgrading xyOps below.
Outputs the current xyOps package version.
/opt/xyops/bin/control.sh version
Example output:
1.0.3

​
Service Management

​
Starting and Stopping

1

Start the service

/opt/xyops/bin/control.sh start
2

Verify it's running

/opt/xyops/bin/control.sh status
3

Stop when needed

/opt/xyops/bin/control.sh stop

​
Systemd Integration

Register xyOps as a system service for automatic startup on reboot: 
cd /opt/xyops
npm run boot
This uses pixl-boot to configure:
  • Systemd (if available)
  • SysV Init (fallback)
  • launchd (macOS)
Once registered with Systemd, use systemctl commands:
sudo systemctl start xyops.service
sudo systemctl stop xyops.service
sudo systemctl status xyops.service
To unregister the startup service: 
cd /opt/xyops
npm run unboot
When xyOps starts on server boot, it typically lacks a proper PATH environment. Scripts relying on binaries in non-standard locations must redeclare PATH internally.

​
Admin Operations

​
Recover Admin Access

Lost access to your admin account? Create a temporary emergency admin: 
/opt/xyops/bin/control.sh admin USERNAME PASSWORD
1

Create emergency admin

/opt/xyops/bin/control.sh admin emergency MySecurePass123
2

Login with new credentials

Use the username and password to access the UI.
3

Create permanent admin account

Create a proper admin account through the UI.
4

Delete emergency account

Remove the emergency admin for security.
  • Emergency accounts don’t appear in the main user list
  • This is an emergency operation only - not for permanent users
  • Does not work with SSO-enabled deployments

​
Manage User Privileges

Grant or revoke privileges via command line: 
# Grant admin privilege
/opt/xyops/bin/control.sh grant alice admin

# Grant event creation
/opt/xyops/bin/control.sh grant bob create_events

# Revoke privilege
/opt/xyops/bin/control.sh revoke bob create_events
Common privilege IDs:
  • admin - Full administrative access
  • create_events - Create new events
  • edit_events - Edit existing events
  • run_jobs - Run jobs manually
  • create_tickets - Create tickets
  • edit_tickets - Edit tickets

​
Upgrading xyOps

The built-in upgrade command handles version updates: 
/opt/xyops/bin/control.sh upgrade
  • Downloads latest stable release from GitHub
  • Preserves all data, users, and configuration
  • Automatically restarts the service
/opt/xyops/bin/control.sh upgrade 1.0.4
Can be used to upgrade or downgrade to any released version.
/opt/xyops/bin/control.sh upgrade HEAD
The HEAD version is for developers and beta-testers. It may contain bugs. Use at your own risk.
Multi-Server Clusters: Repeat the upgrade command on each server in your cluster.

​
Database CLI

Direct database access for debugging and troubleshooting: 
/opt/xyops/bin/db-cli.js COMMAND INDEX ARG1 ARG2 ...

​
Search Database Records

Query any database index using Unbase query syntax: 
# Search for open tickets
/opt/xyops/bin/db-cli.js search tickets "status:open"

# Search jobs with specific tags
/opt/xyops/bin/db-cli.js search jobs "tags:production" --limit 50

# Search with field selection
/opt/xyops/bin/db-cli.js search jobs "result:error" \
  --select id,event,result,code \
  --limit 100

# Status match
status:open

# Date range
created:>2024-01-01

# Multiple conditions
status:open assignee:alice

# Tag search
tags:production tags:critical

# Negative match
status:!closed

# Date comparison
due:<today
See Indexer Query Documentation.

​
Get Single Record

Fetch a specific record by ID: 
# Get alert definition
/opt/xyops/bin/db-cli.js get alerts "amg6sl6z0cc"

# Get job record
/opt/xyops/bin/db-cli.js get jobs "jmhzaot10tm"

# Get ticket
/opt/xyops/bin/db-cli.js get tickets "tmhzbmbagig"
Output is always in JSON format.

​
Common Database Indexes

/opt/xyops/bin/db-cli.js search tickets "status:open"

​
Database Indexes Reference

Available indexes defined in /opt/xyops/internal/unbase.json:
IndexDescription
alertsAlert history records
jobsJob execution records
ticketsTicket system records
serversServer registration and state
snapshotsSystem snapshot records
activityActivity log entries

​
Storage CLI

Low-level storage operations (advanced use): 
/opt/xyops/bin/storage-cli.js [COMMAND] [ARGS]
This tool provides direct access to the pixl-server-storage layer.
The storage CLI is a low-level developer tool. Incorrect usage can corrupt your database. Use the database CLI for normal operations.

​
Environment Variables

Control script behavior via environment variables:
​
NODE_MAX_MEMORY
number
default:"4096"
Maximum Node.js heap size in MB.
export NODE_MAX_MEMORY=8192
/opt/xyops/bin/control.sh start
​
HOSTNAME
string
Override system hostname detection.
​
PATH
string
The control script augments PATH with common binary locations:
/usr/bin:/bin:/usr/local/bin:/usr/sbin:/sbin:/usr/local/sbin

​
Exit Codes

The control script returns standard exit codes:
CodeMeaning
0Operation completed successfully
2Usage error (invalid command)
3Binary could not be started
4Binary could not be stopped
8Configuration syntax error
Use in scripts: 
if /opt/xyops/bin/control.sh start; then
  echo "Started successfully"
else
  echo "Failed to start (exit code: $?)"
fi

​
References

Build docs developers (and LLMs) love

Get started for freeTalk to us