CLI Reference

Overview

QuoxCLI is a standalone ESM package inside the QuoxCORE repository. It uses Node.js 20+ native fetch, Commander.js for command parsing, and supports JWT authentication with automatic token refresh.

Every command follows the pattern: quox <resource> <action> [options]

Installation

# From the QuoxCORE repository
cd cli
npm install
npm link        # makes 'quox' and 'quoxcli' available globally

# Verify
quox --version  # 0.1.0
quox --help     # shows all commands

Requirements: Node.js 20+ (uses native fetch). No additional HTTP client dependency needed.

Authentication

QuoxCLI supports two authentication methods: interactive JWT login and API key auth for CI/CD pipelines.

# Interactive login with MFA
$ quox login
? Email: [email protected]
? Password: ********
MFA required. Check your authenticator app.
? TOTP code: 482916
Logged in as [email protected] | Org: Quox (quox-ai)

# Check session
$ quox whoami
Email: [email protected]
Org:   Quox (quox-ai)
Role:  owner

# Logout
$ quox logout
Logged out.

Tokens are stored in ~/.config/quox/config.json with 0600 file permissions (owner read/write only). The CLI automatically refreshes expired tokens on 401 responses.

Profiles

Profiles let you manage multiple QuoxCORE environments. Switch between local development, staging, and production with a single command.

# Add a profile
$ quox config profile add staging --url https://staging.quox.ai

# Switch profiles
$ quox config profile use staging

# List all profiles
$ quox config profile list
NAME      URL                         ACTIVE   LOGGED IN
local     http://localhost:3000        no       yes
staging   https://staging.quox.ai     yes      no

# Override per-command
$ quox fleet status --profile production

Environment variables

Global flags

These flags work on every command:

Commands

Auth

quox login [--email --password --mfa-code]   # Authenticate with QuoxCORE
quox logout                                   # End current session
quox whoami                                   # Show current user info
quox signup --email --password --name         # Create new account
quox mfa setup|verify|disable|backup-codes    # Multi-factor authentication

Organizations

quox org list|create|get|update|delete         # Organization CRUD
quox org switch <slug>                         # Switch active organization
quox org members list|add|update|remove        # Member management
quox org divisions list|create|update|delete   # Division management
quox org audit [--action --limit]              # Audit trail

Agents & tools

quox agent list|get|create|update|delete       # Agent CRUD
quox agent activate|deactivate <agentId>       # Toggle agent status
quox agent tool list|assign|revoke             # Tool assignment
quox tool list|get|create|update|delete        # Tool CRUD
quox tool catalog [--search]                   # Browse tool catalog
quox tool install|publish                      # Tool distribution
quox workflow list|get|create|update|delete    # Workflow CRUD
quox workflow run|publish                      # Execute/publish workflows
quox workflow steps list|set                   # Manage workflow steps
quox assistant list|get|create|update|delete   # Assistant CRUD
quox assistant deploy|fork                     # Deploy/fork assistants

Fleet

quox fleet status                # Fleet agent status with CPU/memory
quox fleet summary               # Aggregate fleet counts
quox fleet agents                # Detailed agent listing
quox fleet tools                 # Available fleet tools
quox fleet exec --tool <name>    # Execute a fleet tool
quox watch fleet [--interval]    # Live fleet dashboard
quox watch services              # Live service health dashboard

Memory & entities

quox memory list [--type --limit]              # List memories
quox memory get <id>                           # Get memory detail
quox memory create --type --content [--tags]   # Create memory
quox memory update <id> --content              # Update memory
quox memory delete <id>                        # Delete memory
quox memory search --query <q>                 # Semantic search
quox memory stats                              # Memory statistics
quox memory export                             # Export all memories
quox entity list|get|create|search|relate      # Entity management
quox conversation list|get|search|stats        # Conversation history

Chat

quox chat "message"              # Send a message to CommanderQ
quox chat                        # Interactive chat mode
quox chat-status                 # Check chat service status

Admin & backups

quox admin config get|set                      # Platform configuration
quox admin key list|create|delete|test         # API key management
quox admin service list                        # Service status
quox admin logs|stats                          # Logs and statistics
quox admin retention config|cleanup|stats      # Data retention
quox backup list|create|get|delete             # Backup CRUD
quox backup verify|restore [--dry-run]         # Verify and restore
quox backup schedule list|create|update|delete # Scheduled backups

More commands

quox team list|get|create|update|delete        # Team CRUD
quox team members add|update|remove            # Team members
quox department list|get|create|update|delete  # Department CRUD
quox inbox list|get|respond [--action]         # HITL inbox
quox run list|get|create|cancel|resume         # Workflow runs
quox file upload|download|list|delete|stats    # File management
quox integration list|create|update|delete|test  # Integrations
quox consent list|grant|history                # Data consent
quox aee store|get|query|conversations|stats   # AEE protocol
quox tag list|create|update|delete             # Tags
quox scope list|create|update|delete           # Scopes
quox notification channels list|set            # Notifications
quox service health [service]                  # Health checks
quox setup status|admin|config                 # First-run setup
quox config profile list|add|use|set|get       # Profile management
quox completion bash|zsh|fish                  # Shell completions

Output modes

# Table (default) - colour-coded with status indicators
$ quox agent list
NAME        LEVEL         STATUS   TOOLS
QuoxCORE    orchestrator  active   12
WARDEN      manager       active    8

# JSON - pipe to jq
$ quox agent list --json | jq '.[].name'
"QuoxCORE"
"WARDEN"

# CSV - for spreadsheets
$ quox fleet status --output csv > fleet.csv

# Quiet - IDs only for scripting
$ quox backup list -q | xargs -I{} quox backup verify {}

Service routing

QuoxCORE runs 5 microservices. The CLI automatically routes each command to the correct service port:

Shell completions

# Bash
quox completion bash >> ~/.bashrc

# Zsh
quox completion zsh > ~/.zsh/completions/_quox

# Fish
quox completion fish > ~/.config/fish/completions/quox.fish

Plugins

QuoxCLI loads plugins from ~/.quox/plugins/ or the path set in QUOX_PLUGIN_DIR. Each plugin is a directory with an index.js that exports a register(program, context) function.

// ~/.quox/plugins/my-plugin/index.js
export const name = 'my-plugin'
export const version = '1.0.0'

export function register(program, context) {
  program
    .command('my-command')
    .description('Custom command from plugin')
    .action(async () => {
      const data = await context.client.get('/api/custom')
      console.log(data)
    })
}

Exit codes

Examples

Daily operations

# Morning fleet check
$ quox fleet status
$ quox service health
$ quox inbox list

# Deploy workflow
$ quox backup create --label "pre-deploy"
$ quox workflow run --id wf_deploy --input '{"target":"production"}'

# Investigate an agent
$ quox agent get sentinel --json | jq '.tools'
$ quox memory search --query "sentinel security audit"

CI/CD pipeline

# In your pipeline script
export QUOX_TOKEN="$YOUR_API_KEY"
export QUOX_URL=https://quox.example.com

# Pre-deploy checks
quox service health --json || exit 1
quox backup create --label "ci-$(date +%Y%m%d)" -y

# Post-deploy verification
quox fleet status --json | jq '.agents[] | select(.status != "healthy")'

Shell scripting

# Delete old backups
quox backup list --json \
  | jq -r '.[] | select(.created_at < "2026-01-01") | .id' \
  | xargs -I{} quox backup delete {} -y

# Export all memories to a file
quox memory export --json > memories-backup.json

# Watch fleet health every 30 seconds
quox watch fleet --interval 30