[CLI Commands Reference]

The @hoox-sh/hoox-cli tool (0.13.x) manages the entire monorepo development, provisioning, deployment, monitoring, and self-healing pipelines. This reference provides the complete command tree, positional arguments, optional flags, and concrete examples for all command groups. The binary is also available as hx.

Per-group stills: Interface gallery.

Install: bun add -g @hoox-sh/hoox-cli. Recommended bootstrap: hoox onboard. Prefer CLI commands over raw Wrangler for day-to-day ops.

Current defaults (0.13.x): ships with mesh security hardening (@hoox-sh/[email protected] + worker submodules) — two-phase gateway idempotency, RateLimiterStore, chatId allowlists, named D1 list RPCs, mesh-wide safeWaitUntil. CLI surface still includes monorepo auto-detect + remember (run hx from any cwd), Linear Rail banner (◆ H · O · O · X), quieter check setup secrets UX, setup gates, secret sync modes (--system / --required), hoox pyne for pyne-worker, operator security plane (doctor --security, tunnel check). Global UX: --no-color / NO_COLOR / TERM=dumb, completion footers, “did you mean …”, sectioned help. Historical release notes: v0.9.0 · v0.8.0.

---

📍 Workspace resolution (any cwd)

On every invocation the CLI resolves a monorepo root, remembers it, and chdirs into it so relative paths (wrangler.jsonc, workers/, …) work even when you launch hx from ~/Videos or another project.

Order:

1. HOOX_REPO — explicit absolute path
2. Walk up from cwd — local checkout markers
3. Remembered path — ~/.hoox/config/monorepo.json
4. Global clone — ~/.hoox/repo (hoox doctor --fix-runtime)

Monorepo markers: packages/cli/package.json plus one of wrangler.jsonc, wrangler.jsonc.example, workers/, or .gitmodules.

# Discover once from the monorepo
cd ~/Git/hoox && hoox doctor

# Use from anywhere
cd ~/Videos && hx check health

hoox doctor prints Remembered, Runtime root, and Source (env | cwd | remembered | global | none).

---

🗺️ Global Flags

These options are registered globally and can be appended to any command:

---

🗂️ Command Groups Directory

~30 top-level command groups (including doctor, tunnel, pyne, and the rest below).

hoox                                 Startup: resolve monorepo + chdir. No args: auto-onboard if no wrangler.jsonc; else menu/TUI
├── onboard                          One-shot full bootstrap (init + setup) [recommended]
├── init                             Interactive setup wizard (config only)
├── setup                            Auto-bootstrap infrastructure (keys, D1, secrets, dashboard)
├── clone [name]                     Clone worker repositories as submodules
├── dev                              Local development execution engine
│   ├── start                        Start all workers (native or Docker)
│   ├── worker <name>                Start a single worker
│   └── dashboard                    Start Next.js dashboard dev server
├── deploy                           Edge deployment pipelines
│   ├── all                          Roll out all workers + dashboard in sequence
│   ├── workers                      Deploy all workers only (skip dashboard)
│   ├── worker <name>                Deploy a single edge worker
│   ├── dashboard                    Deploy Next.js dashboard via OpenNext
│   ├── telegram-webhook             Register Telegram bot webhook API
│   ├── update-internal-urls         Bind inter-worker Service Binding URLs
│   ├── kv-config                    Synchronize KV manifest variables
│   ├── history <worker>             Show deployment history
│   └── rollback <worker>            Rollback to a previous version
├── infra                            Cloudflare resource provisioning IaC
│   ├── provision                    Auto-provision all required services
│   ├── d1 [list/create/delete]      Manage D1 databases
│   ├── kv [list/create/delete]      Manage KV namespaces
│   ├── r2 [list/create/delete]      Manage R2 object storage buckets
│   ├── queues [list/create/delete]  Manage Cloudflare Queues
│   ├── vectorize [create/delete]    Manage vector search indexes
│   └── analytics [list]             Manage Analytics Engine datasets
├── config                           Manage wrangler.jsonc configuration
│   ├── show                         View current configuration
│   ├── set <key> <value>            Update a config value
│   ├── env [init/show/validate/generate-dev-vars]  Manage .env.local build variables
│   ├── kv [set/get/list/delete/apply-manifest/manifest]  CONFIG_KV runtime keys
│   ├── transport [show|set]         Operator transport (public|access|mtls|tunnel)
│   ├── secrets [list/set/delete/sync]  Cloudflare Worker secrets (legacy location)
│   └── keys [generate/list]         Internal auth keys (legacy location)
├── secrets                          Manage Cloudflare Worker secrets [top-level]
│   ├── list [worker]                List secrets for a worker
│   ├── set <worker> <name>          Set a secret
│   ├── delete <worker> <name>       Delete a secret
│   └── sync [worker] [--system|--required]  Sync .dev.vars → CF (mesh-only with --system)
├── keys                             Manage internal auth keys [top-level]
│   ├── generate                     Generate new keys
│   └── list                         List existing keys
├── check                            Toolchain and route diagnostic suite
│   ├── prerequisites                Validate local machine tool installs
│   ├── setup                        Full system validation (config, infra, secrets, db)
│   ├── health [--fix]               Probe worker /health endpoints
│   ├── fix [--dry-run]              Auto-repair common issues
│   └── submodule-gitignore (sg)     Validate/fix worker submodule .gitignore
├── doctor                           Runtime paths, remembered monorepo, TUI entry, security hygiene
├── tunnel                           Private ingress helpers (cloudflared / Access)
│   └── check                        Detect cloudflared; optional /v1/health probe
├── db                               SQLite D1 Database administration
│   ├── apply                        Apply DDL schemas to D1
│   ├── migrate                      Run schema migrations
│   ├── list                         Display active SQLite tables
│   ├── query <sql>                  Execute custom SQL reads
│   ├── export                       Dump database as a secure SQL file
│   └── reset                        Destructive truncate of all tables
├── monitor                          Observability and emergency controls
│   ├── trades [N]                   Aggregate recent filled transactions
│   ├── logs [worker]                Tail and inspect time-series logs
│   ├── queue-depth                  Audit message counts in queues
│   ├── backup                       Backup SQL ledger to backups/
│   ├── kill-switch [show/on/off]    Emergency global trading halt
│   └── analytics                    Query analytics data from D1
├── workers                          Per-worker operations
│   ├── list                         List all workers with status/path/secrets count
│   ├── dev <name>                   Start a worker for local development
│   └── logs <name>                  Tail logs for a specific worker
├── repair                           System diagnostics & self-healing
│   ├── check                        Run 5-step checklist
│   ├── worker <name>                Rebuild a degraded worker
│   ├── infra                        Verify and repair missing edge bindings
│   ├── secrets                      Re-sync hardware secrets
│   ├── kv                           Restore KV manifest defaults
│   ├── db                           Re-apply Drizzle migrations
│   └── rebuild                      Full destructive interactive rebuild
├── logs                             Real-time Cloudflare Worker log tailing
│   ├── worker <name>                Tail logs for a specific worker
│   └── all                          Tail logs from all enabled workers
├── schema                           Validate/generate worker manifests
│   ├── validate [worker]            Validate worker(s) against canonical manifest
│   ├── list                         List workers with binding counts
│   └── generate <worker>            Generate wrangler.jsonc + .dev.vars from manifest
├── update                           Self-update the CLI or wrangler
├── test                             Run verification pipeline (CI)
├── waf                              Auto-configure Cloudflare WAF firewall rules
├── dashboard                        Unified dashboard operations
│   ├── dev                          Start the dashboard dev server
│   └── deploy [--rebuild]           Build and deploy the dashboard
├── tui                              Launch the OpenTUI terminal dashboard
├── agent                            AI agent operations and health checks
│   └── health [--probe]             Provider config check; optional live probes
├── pyne                             PYNE edge evaluate (pyne-worker / Pine Script™)
│   ├── health                       Probe pyne-worker GET /health
│   ├── run <script>                 POST /run with a .pine file
│   ├── scripts [list|get|deploy|delete]  Managed scripts
│   ├── cron [jobs|run]              Bar-close jobs list / manual trigger
│   ├── feed refresh                 Pull latest klines into R2
│   ├── ingest                       Fetch OHLCV into storage
│   ├── sync-vendor                  Sync pynescript vendor modules
│   └── deploy                       sync-vendor + wrangler deploy
├── trace                            Cloudflare Workers Observability (beta)
│   ├── events                       Query trace events (spans) with filters
│   ├── metrics                      Aggregate metrics (count, p99, …)
│   ├── live                         Live tail traces
│   ├── keys / values <key>          Filter key discovery
│   ├── destinations [add|remove]    OTLP export destinations
│   └── usage                        Trace event counts
├── perf                             Performance measurement tools
│   └── fastpath                     Probe-based latency measurement
│       ├── run [options]            Send N probes, report p50/p95/p99
│       ├── tail [options]           Continuous probing for a duration
│       └── report [options]         Query past probe events
├── disclaimer                       Display legal disclaimer
└── completion [shell]               Generate shell completion script (bash, zsh, fish)

---

🚀 Key Commands Detail & Examples

A. Onboarding (Start Here)

# Recommended: one-shot full bootstrap (collects credentials, provisions, deploys)
hoox onboard

# Non-interactive one-shot
hoox onboard --token cfut_xxx --account xxx --preset full

# Step-by-step (more control)
hoox init        # Write wrangler.jsonc, collect integration secrets
hoox setup       # Generate keys, apply D1 schema, push secrets, deploy dashboard

# Verify the system
hoox check setup
hoox check prerequisites

B. Local Development

# Start all workers in a Docker container stack
hoox dev start --runtime docker

# Start all workers natively via wrangler dev
hoox dev start --runtime native

# Start a single worker
hoox dev worker trade-worker

# Start the Next.js dashboard dev server
hoox dev dashboard
# OR (equivalent):
hoox dashboard dev

C. Edge Provisioning & Deployment

# Provision all databases, buckets, and queues on your Cloudflare® account
hoox infra provision

# Deploy the entire microservices stack in sequence, automatically updating URLs
hoox deploy all --auto

# Deploy a single worker
hoox deploy worker trade-worker

# Build and deploy the Next.js dashboard
hoox dashboard deploy --rebuild
# OR (equivalent):
hoox deploy dashboard --rebuild

D. Health Checks & Monitoring

# Check all worker health endpoints (the single source of truth)
hoox check health

# Try to auto-fix any issues found
hoox check health --fix

# Audit active trade history table
hoox monitor trades 25

# Emergency Halt: halt all trade signals globally in under 10 seconds
hoox monitor kill-switch on

E. Secrets & Keys Management

# Set a Cloudflare® Worker secret (live exchange keys)
hoox secrets set trade-worker BINANCE_KEY_BINDING "your_key_here"
hoox secrets set trade-worker BINANCE_SECRET_BINDING "your_secret_here"

# Optional: dedicated testnet keys for "test": true webhooks
hoox secrets set trade-worker BINANCE_TESTNET_KEY_BINDING "your_testnet_key"
hoox secrets set trade-worker BINANCE_TESTNET_SECRET_BINDING "your_testnet_secret"
hoox secrets set trade-worker BYBIT_TESTNET_KEY_BINDING "your_testnet_key"
hoox secrets set trade-worker BYBIT_TESTNET_SECRET_BINDING "your_testnet_secret"

# List secrets for a worker
hoox secrets list trade-worker

# Sync mesh/system secrets only (INTERNAL_KEY_BINDING, WEBHOOK_*, …)
hoox secrets sync --system
# Alias: hoox secrets sync --required

# Sync all declared secrets from .dev.vars
# Reports partial results: synced / skipped (placeholders) / failed
hoox secrets sync

# Generate internal auth keys
hoox keys generate

# List existing keys
hoox keys list

F. Database Administration

# Query the total sum of fees paid today across Bybit
hoox db query "SELECT SUM(fee) FROM trades WHERE created_at >= date('now')" --remote

G. Performance Measurement

# Send 50 synthetic probes and report p50/p95/p99 per-hop latency
hoox perf fastpath run --n 50

# Continuous probing for 60 seconds
hoox perf fastpath tail --duration 60

# Query past probe events
hoox perf fastpath report --from 1h

H. Self-Healing & Diagnostics

# Run a full workspace system audit
hoox repair check

# Verify worker health (the single source of truth)
hoox check health

---

Historical: v0.9.0 Output Polish

Historical notes from the v0.9.0 release (retained for upgrade context). Current CLI is 0.13.x — Linear Rail is the default banner style; monorepo remember and quieter secrets checks landed later; mesh security hardening ships with 0.13.

The v0.9.0 release polished the output framework. No new commands and no breaking changes — every command picks up the improvements automatically through the shared formatters. The new primitives are also available to plugin authors via the package's public exports.

New output primitives

• --no-color global flag — suppresses all ANSI color output. Also honored: NO_COLOR=1 env var (https://no-color.org standard) and TERM=dumb.
• formatCompletion(message, { durationMs, suggestion }) — prints a ✓ Done in 1.2s footer after every successful command, with an optional → next: hoox … suggestion. Wired into the global program.hook("postAction", ...).
• "Did you mean" suggestions — typos like hoox deplpy produce did you mean 'hoox deploy' ?. Levenshtein distance ≤ 2 against all registered command names.
• Custom help formatter — hoox --help and per-command --help use a sectioned layout (Usage / Options / Examples / See also) with refined colors.
• formatNumber(n) — compact notation (1.2K, 1.5M, 2.5B) used by formatTable number auto-alignment and by hoox perf fastpath / hoox monitor trades / hoox trace metrics.
• formatBytes(n, { binary? }) — SI (KB, MB) or binary (KiB, MiB) units.

Visual changes (visible in every command)

• Theme palette — refined to a modern-minimal aesthetic: zinc/slate text, single indigo-400 accent, de-saturated status colors (emerald/rose/amber/sky). The visual change ripples through every command; information content is unchanged.
• Badge style — formatBadge() no longer uses high-contrast background chips; it now renders colored glyph + colored text (Vercel / Linear style).
• Spinner — uses braille dots (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏) instead of plain ASCII (-\|/).
• formatTable options — supports zebra, alignNumbers, colorizeStatus, compact (all default to on, except compact which defaults to off). Backward compatible.
• formatError — card layout with [code] badge and suggestions support. JSON output now includes a new suggestions field.
• Banner default — later superseded by Linear Rail (◆ H · O · O · X) as the default compact banner in 0.11.x; version is read dynamically from package.json.

See packages/cli/CHANGELOG.md for the full release notes.

---

Historical: v0.8.0 Refactor

Historical notes from the v0.8.0 release. Commands listed here remain current; this section documents when they were introduced.

The v0.8.0 release consolidated and cleaned up the CLI surface. Pre-1.0 breaking changes were made without deprecation warnings since this is still active development.

New commands (introduced in v0.8.0; still current)

• hoox onboard (aliases: bootstrap, quickstart) — One-shot full bootstrap that chains init + setup. The recommended entry point for new users. When you run hoox with no arguments and no wrangler.jsonc exists, the CLI now auto-launches this.
• hoox secrets (top-level) — Promoted from hoox config secrets for discoverability.
• hoox keys (top-level) — Promoted from hoox config keys for discoverability.
• hoox perf fastpath — Probe-based latency measurement (active synthetic probes with p50/p95/p99 per-hop breakdown).
• hoox dashboard dev / hoox dashboard deploy — Unified dashboard operations that were previously split across hoox dev dashboard and hoox deploy dashboard.

Removed commands (use the replacement)

• hoox monitor status → use hoox check health (single source of truth for health checks)
• hoox workers status → use hoox check health
• hoox dashboard update-urls → use hoox deploy update-internal-urls
• hoox config secrets → use hoox secrets (top-level now)
• hoox config keys → use hoox keys (top-level now)

---

🔗 Next Steps

• Configuration Dictionary — Comprehensive dictionary of all 31 env keys and 16 KV key-value items.
• API Endpoint Reference — Analyze REST routes, schemas, and gateway error structures.