hyprbox CLI

Operator command-line, mirrors what the dashboard does. Built from cli/hyprbox.

cd cli/hyprbox
go build -o /usr/local/bin/hyprbox .
hyprbox --help

#Configuration

Both the API URL and the user JWT come from --flag > env > default:

Quick way to get a token:

export HYPRBOX_API_TOKEN=$(curl -s -X POST $HYPRBOX_API_URL/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@hyprbox.local","password":"hyprbox-admin"}' | jq -r .token)

#Commands

#hyprbox status

Fleet table — every registered node, status, last-seen, CPU/RAM/disk.

hyprbox status
hyprbox status --json   # raw JSON for piping into jq

Output:

HyprBox - Node Status  [http://localhost:4000]
----------------------------------------------------

[OK]  prod-eu-1
   Hostname : prod-eu-1
   OS       : Debian 12
   Status   : ONLINE
   Last seen: 4s ago
   CPU      : 14.6%
   RAM      : 46.0%
   Disk     : 41.0%

Status icons: [OK] ONLINE, [!!] WARNING, [XX] CRITICAL, [--] OFFLINE, [??] UNKNOWN.

#hyprbox preset list

Catalogue of presets shipped with the API.

hyprbox preset list

NAME               VERSION    STEPS    DESCRIPTION
--------------------------------------------------------------------------------
monitoring-only    0.1.0      2        Drop-in monitoring stack — Prometheus...
pme-web            0.1.0      2        Web app + Postgres + Caddy with automatic HTTPS
server-light       0.1.0      5        Minimal hardened Linux server baseline...

#hyprbox preset show <name>

Full preset JSON (validated schema). Useful for piping into jq.

hyprbox preset show server-light | jq '.steps[].type'

#hyprbox preset preview <name>

Render to bash without queuing or executing anything.

hyprbox preset preview server-light \
  -V hostname=prod-eu-1 \
  -V ssh_port=2222 \
  -o /tmp/server-light.sh

# stdout-default flavour, pipe-friendly:
hyprbox preset preview server-light | less
hyprbox preset preview server-light | ssh user@host bash

Flags:

• -V key=value — repeat for each variable. Values are passed as-is; the API normalises numeric-looking strings.
• -o file.sh — write to file (mode 0755) instead of stdout. Warnings go to stderr in both modes.

#hyprbox preset apply <name> [--target=local|<nodeId>]

Currently only --target=local is wired, and only on Linux hosts. Use the dashboard's Apply button (or POST /api/jobs directly) for remote nodes — that path goes through the job queue and the agent.

hyprbox preset apply server-light --target=local -V hostname=$(hostname) -y

-y skips the confirmation prompt.

#Other commands (stubs)

hyprbox install, hyprbox audit, hyprbox backup, hyprbox restore, hyprbox update — TODO placeholders. They'll land alongside the HyprVault/HyprGuard modules in Phase 4.

#Exit codes

• 0 — success.
• 1 — operational error (4xx/5xx from API, unreachable, validation). The CLI prints the API's message field on 4xx so you don't have to inspect curl output.