echoctl

A Scala 3 CLI client for echo, the LED matrix HTTP proxy. It intentionally talks only to the HTTP API (/api/v1/...) and never uses the raw TCP firmware protocol.

# Basic health checks
echoctl health
echoctl ready
echoctl devices

# Play animations
echoctl animations list
echoctl animations catalog
echoctl play alert --priority 80
echoctl preset matrix_rain_background
echoctl effect chase --interval 80ms --color '#00FF55'
echoctl stop

# Direct matrix controls
echoctl matrix fill '#00FF55'
echoctl matrix clear
echoctl matrix brightness 20

# Discovery
echoctl openapi
echoctl metrics

# Notify and generic event
 echoctl notify "deploy done" --duration 3s
echoctl event --source cli --type deploy --attr animation=notify --attr duration=2s

# Background and queue
echoctl background get
echoctl background set matrix_rain_background
echoctl queue
echoctl queue --clear

Features implemented

• Endpoints for health, ready, devices, animations, play, preset, effect, stop, notify, event, matrix, background, and queue.
• Additional helper endpoints: /openapi.json and /metrics.
• Config resolution precedence: flags > env > config file > defaults.
• Built-in firmware effect id/name table for effect.
• Duration/interval and color input validation.
• --json and --verbose output modes.
• com.lihaoyi-backed CLI ergonomics (picocli, fansi, pprint, os-lib, requests, upickle).
• Mill build with NativeImageModule support.
• Unit tests cover color/duration parsing, preset resolution, and config precedence.

Configuration

Config path: ~/.config/echoctl/config.json.

{
  "default_profile": "home",
  "profiles": {
    "home": {
      "server": "http://pi4.lan:8080",
      "device": "living-room",
      "token": ""
    }
  }
}

Environment variables:

• ECHOCTL_SERVER
• ECHOCTL_TOKEN
• ECHOCTL_DEVICE
• MATRIX_PROXY_ADMIN_TOKEN (token fallback)

Global flags:

• --server
• --token
• --device
• --profile
• --config
• --json
• --verbose
• --help