argb-ai CLI

Part of the argb-ai ecosystem. Works alongside argb-core and mcp-server.

argb-ai/cli is the terminal entry point for the argb-ai ecosystem. It is designed for humans, scripts, CI jobs, and hardware debugging sessions that need clear commands and predictable output.

Responsibility Boundary

This repository owns:

• Command-line UX and subcommand structure.
• Argument parsing, validation, help text, and exit codes.
• Human-readable and script-friendly output formats.
• Debug workflows for discovering devices, testing effects, and inspecting runtime state.

This repository does not own:

• Low-level USB, serial, HID, or device protocol implementations.
• AI protocol semantics or MCP tool/resource definitions.
• Long-running orchestration logic that belongs in a server process.

Device I/O should flow through argb-core. AI-facing behavior should live in mcp-server.

Intended Commands

The command surface should stay small and composable:

argb scan
argb status
argb pulse --color "#FF0000"
argb set --color "#00AAFF" --brightness 0.7
argb stream --profile ./profiles/rainbow.toml
argb inspect --json

Planned command groups:

• scan: find supported ARGB controllers and ports.
• status: report controller health, channel count, LED count, and active mode.
• set: apply a static color or simple one-shot state.
• pulse: run a short diagnostic animation.
• stream: send a predefined or generated frame stream.
• inspect: print detailed diagnostics for automation and bug reports.

UX Principles

• Default output should be concise and useful in a terminal.
• --json should be available for commands used by scripts or CI.
• Error messages should explain what failed and what the user can try next.
• Commands that touch hardware should be explicit about the target device when more than one device is present.
• Dangerous or high-frequency operations should require clear flags rather than hidden defaults.

Automation Use Cases

The CLI should support:

• Local hardware bring-up and smoke testing.
• CI/CD checks that verify configuration files or profiles.
• Shell scripts that set status colors during builds, deployments, or demos.
• Reproducible bug reports with structured diagnostic output.

AI Collaboration Contract

When using Cursor, Claude, Gemini, or another AI coding assistant in this repository:

• Treat this as a terminal application.
• Focus on command parsing, output clarity, error handling, and user workflows.
• Do not implement MCP tools, resources, prompts, or AI orchestration here.
• Do not implement hardware protocols directly here; add reusable device behavior to argb-core.
• Prefer small commands with stable output over broad, implicit behavior.

Current Status

This repository is in early design. Public command names and flags may change until the first tagged release.