[CLI Commands Reference]

The @jango-blockchained/hoox-cli tool 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.

Heads up (v0.9.0): The output framework was polished. New global flag --no-color (alongside NO_COLOR env var and TERM=dumb honored); every successful command prints a Done in 1.2s footer with an optional → next: hoox … suggestion; typos like hoox deplpy produce did you mean 'hoox deploy' ?; hoox --help uses a new sectioned layout (Usage / Options / Examples / See also). See the changelog below. Also see the v0.8.0 refactor notes further down for the command-tree changes.

---

Global Flags

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

---

Command Groups Directory

hoox                                 Launch TUI (when run with no args on an init'd workspace)
├── onboard                          One-shot full bootstrap (init + setup) [recommended]
├── init                             Interactive setup wizard (config only)
├── setup                            Auto-bootstrap infrastructure (keys, D1, secrets, dashboard)
├── clone [name]                     Bootstrap workspace from template
├── 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]     Get/Set dynamic KV runtime parameters
│   ├── 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]                Sync local .dev.vars to Cloudflare
├── 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
├── 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                             Time-series log extraction
│   ├── tail <worker>                Stream live edge logging console
│   └── download <worker>            Download logs to a local file
├── schema                           Validate wrangler.jsonc schemas and workers
├── update                           Self-update the CLI or wrangler
├── test                             Run verification pipeline (CI)
├── waf                              Auto-configure Cloudflare WAF firewall rules
├── clone [name]                     Clone worker repositories as submodules
├── 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
├── trace                            Query Cloudflare Workers Observability (events, metrics)
├── 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
hoox secrets set trade-worker BINANCE_KEY_BINDING "your_key_here"
hoox secrets set trade-worker BINANCE_SECRET_BINDING "your_secret_here"

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

# Sync local .dev.vars to Cloudflare
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

---

🆕 v0.9.0 Output Polish

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 status / 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 — minimal (was legacy). The banner's version is read dynamically from package.json (v0.9.0 also fixed a real version-drift bug where the banner was hardcoded to v0.3.0 while the package was at v0.8.0).

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

---

🆕 v0.8.0 Refactor

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 (added in v0.8.0)

• 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.