QuoxCLI
Talk to Quox from your terminal, or script it.
Maturity: Beta. The commands below were read from the CLI's own command definitions (QuoxCLI 0.3.1, shipped with QuoxCORE 1b8bf54d). The interactive screens are Beta. The full, generated command reference is at quox.ai/cli.
| At a glance | |
|---|---|
| What it is | quox, the command line for Quox. Run it with no arguments to talk to Quox; add a command to script it. |
| Where it runs | On your QuoxCORE server, or on any machine with Node.js 20 or newer that can reach it. |
| When to reach for it | Day-to-day operation, scripts and CI, or anything faster typed than clicked. |
| How to start | On a QuoxCORE server it is already installed: quox -p local status. Elsewhere: npm install -g quoxcli. |
Install
On your QuoxCORE server, the installer already put quox at /usr/local/bin/quox, with a profile called local that points at the install. Nothing else to do:
quox -p local status
On any other machine (Node.js 20 or newer):
npm install -g quoxcli
quox --version
The package installs two commands: quox and quoxon.
Sign in
quox login # asks for email, password and MFA code
quox whoami
quox logout
For scripts, pass the password on standard input so it never appears in your shell history or process list:
quox login --email [email protected] --password-stdin < password-file
For CI, set a token instead of signing in: QUOX_TOKEN. Your session is stored in ~/.config/quox/config.json (readable only by you) and refreshes itself when it expires.
Profiles
A profile is a named Quox instance. Use one per server.
quox config profile add work --url https://quox.example.com
quox config profile use work
quox config profile list
quox config profile remove work
Pick a profile for one command with -p work, or for a shell with QUOX_PROFILE=work. QUOX_URL points a command at an instance directly.
Global flags
| Flag | Does |
|---|---|
-o, --output <format> | table (default), json, csv or quiet |
--json | Short for --output json |
-q, --quiet | Print IDs only |
-p, --profile <name> | Use this profile |
--org <slug or id> | Act in this organisation (must match your session) |
-y, --yes | Skip confirmation prompts |
-v, --verbose, --debug | More detail |
--no-color | Plain output |
--insecure | Accept a self-signed certificate |
A tour of the commands
| Job | Command |
|---|---|
| Is everything healthy? | quox status, quox doctor, quox service health |
| Talk to Quox | quox (interactive), or quox chat "what is running on web-01?" |
| See what waits for your approval | quox approvals list, quox inbox list |
| Answer an approval | quox inbox respond <itemId> --action approve |
| Agents | quox agent list, quox agent get <id> |
| Run a workflow | quox workflow run <workflowId> |
| Memory | quox memory search --query "backup window" |
| Backups | quox backup create --label before-upgrade, quox backup list |
| AI providers | quox provider connect anthropic --key-from-stdin, quox provider list |
| Safety | quox safety status |
| Evidence | quox volt fetch <runId>, then quox volt verify <file> |
Every command has --help. The full list, generated from the CLI itself, is at quox.ai/cli.
Scripting
Use --json and a JSON tool such as jq:
quox agent list --json
quox backup create --label nightly -y
Exit codes tell a script what went wrong:
| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Invalid input |
| 3 | Not signed in, or the session expired |
| 4 | Not allowed |
| 5 | Not found |
| 6 | Conflict |
| 7 | Could not reach the server |
| 8 | The server reported an error |
Shell completion and plugins
quox completion bash # or zsh, fish
The CLI loads plugins from ~/.quox/plugins/, or from the folder in QUOX_PLUGIN_DIR.
Limits
- The interactive screens are Beta.
- The version on npm can be newer than the one inside your server.
quox --versiontells you which you are running. - This page shows a tour, not every command. Use
quox --helpor quox.ai/cli for the full list.
Related
- quox.ai/cli: the full CLI documentation and guides.
- Install and deploy: the server the CLI talks to.
- Safety: what the approval commands are approving.
Last verified 2026-10-29 against QuoxCLI 0.3.1 (QuoxCORE 1b8bf54d) and quoxcli 0.4.0 on npm.