CLI & live status

Since v0.3.9, OxiPulse exposes a small set of local commands to inspect a running agent without touching your OTLP backend or dashboard. These read from a local status socket that the agent keeps open while it runs — a Unix socket on Linux/macOS, a named pipe on Windows.

`--version`

Prints the installed version and exits.

bash

oxipulse --version

Output

oxipulse 0.3.10

`status`

Prints a single JSON snapshot of the running agent's state — useful for scripting, health checks, or piping into jq.

bash

oxipulse status

Output

{
  "agent": "oxipulse",
  "version": "0.3.10",
  "state": "running",
  "since_unix": 1755970483,
  "details": {
    "cpu_percent": 32.6,
    "ram_used_mb": 17780,
    "buffered": 0,
    "offline": false
  }
}

If the agent isn't running, the command fails with a connection error instead of printing a payload — safe to use as a liveness check in scripts.

`top`

Opens a live, auto-refreshing terminal view of the agent's status — state, version, uptime, and the same details object shown as pretty-printed JSON. Refreshes roughly once per second. Press q or Esc to quit.

bash

oxipulse top

status and top only work while the agent service is actually running on that machine — they talk to the local socket/pipe directly, not to SecuryBlack's backend. They're a local debugging tool, not a replacement for the dashboard.

Under the hood

These commands are provided by sb-agent-core, the runtime OxiPulse shares with SecuryBlack's other Rust agents (FerroSentry, Nexus Agent, CupraFlow). All four expose the same status/top interface, so the same muscle memory works across agents.