cli

The CLI module provides real-time system observability for an eevee-bot deployment. It connects to the NATS messaging backbone, tracks module health and connector status, detects anomalies, and displays periodic summary tables — giving operators a live dashboard of the entire bot infrastructure.

A companion Docker image (the toolbox) packages the monitor into a lightweight Alpine container with the NATS CLI utility pre-installed, making it easy to run debugging sessions alongside your eevee workloads in Kubernetes.

Features link

• Real-time system observability — tracks module health, connector status, and registrations across the deployment
• Periodic summary tables — 9-column ASCII table with version, uptime, message/command counts, errors, memory, and p50/p95 latency percentiles
• Event detection — 12 event types covering module lifecycle, connector changes, registration activity, and anomalies
• Anomaly detection — automatic restart detection, error delta tracking, stale module detection, connector channel count changes
• Two renderers — follow mode (colored events + summary tables) and raw mode (unformatted NATS firehose)
• CRD-driven configuration — summaryInterval, maxModuleAge, displayEvents, and filters configurable via YAML
• Container-friendly — forces ANSI colors for kubectl logs / k9s
• Stats reporting — monitor reports its own module/connector counts and event throughput

Usage link

Follow Mode (default) link

Displays real-time events as timestamped lines, plus a periodic summary table:

  eevee monitor
  

Example output:

  04:12:03 ▸ module appeared: weather
04:12:03 ▸ module appeared: router
04:12:08 ▸ connector-irc:libera reconnected
04:13:03 ▸ admin errors increased by 2 (0 → 2)

──────────────────────────────────────────────────────────
  eevee monitor · 04:13 UTC · 12 modules · 1 connector
──────────────────────────────────────────────────────────
  Module          Ver      Uptime   Msgs    Cmds  Errs    Mem   MsgLat     CmdLat
  ● admin         2.7.3     2h15m   1.2k      43     2   58MB  3/12ms    15/89ms
  ● router        2.5.5     2h15m   4.1k     210     0   72MB  1/5ms     8/34ms
  ○ seen          1.5.5     2h15m     86       5     0   42MB  —         —
  ● connector-irc 1.6.6     2h15m   3.8k       0     0   65MB  2/8ms     —
  ...

  IRC: libera ● connected  #eevee,#testing
──────────────────────────────────────────────────────────
  

Summary Table Columns link

Status Dots link

Raw Mode link

Dumps every NATS message unformatted — useful for low-level debugging:

  eevee monitor --raw
  

Example output:

  [stats.emit.response.weather] {"module":"weather","stats":{"version":"1.4.5",...}}
[command.register] {"module":"admin","command":"health"}
[control.connectors.irc.libera] {"action":"connect","network":"libera"}
  

Options link

Events link

The monitor observes 12 event types across the NATS backbone:

Some events are suppressed from the stdout renderer (first-cycle discovery, passive anomaly detection, stale module detection) — they’re still processed for state tracking, but not printed as event lines. Raw mode (--raw) shows everything.

NATS Subjects link

Inbound (subscribed) link

Outbound (published) link

Configuration link

To deploy the CLI module, add it to your bot’s botModules configuration with moduleName: "cli":

  botModules:
- name: cli
  spec:
    size: 1
    image: ghcr.io/eeveebot/cli:latest
    pullPolicy: Always
    ipcConfig: my-eevee-bot
    moduleName: cli
    moduleConfig: |
      monitor:
        summaryInterval: 60000
        maxModuleAge: 300000
        displayEvents:
          - module_start
          - module_error
          - connector_disconnect
          - stats_anomaly
        filters:
          - chat.irc
  

Configuration Fields link

Environment Variables link

Toolbox Container link

The toolbox image bundles eevee monitor as its default entrypoint. On startup, it:

1. Runs init hooks from /eevee/hook.d/init/ (prints hostname and IP for debugging)
2. Launches eevee monitor in follow mode

  docker run --rm \
  -e NATS_HOST="nats://nats.example.com:4222" \
  -e NATS_TOKEN="my-secret-token" \
  ghcr.io/eeveebot/cli:latest
  

The image also includes the nats CLI for manual NATS inspection:

  docker exec -it <container> bash
nats sub ">"
  

Anomaly Detection link

The monitor detects anomalies by comparing current and previous module state:

• Uptime reset — module restarted (current uptime < previous uptime)
• Error count increase — any delta triggers a module_error event
• Stale module — no stats received within maxModuleAge → module marked down
• Status recovery — module transitioned from down/degraded to healthy
• Channel count change — connector gained or lost channels

Connector data is extracted from connector module stats responses (e.g. connector-irc includes a connector array in its stats payload).

Monitor Stats link

The monitor reports its own stats when queried via stats.emit.request: