Merge pull request #982 from zeroclaw-labs/fix/cli-help-text-improvements
docs(cli): add detailed help text and examples to complex subcommands
This commit is contained in:
Alex Gorevski
GitHub
commit
b6f99c31d1
2 changed files with 219 additions and 0 deletions
115
src/lib.rs
115
src/lib.rs
|
|
@ -96,6 +96,17 @@ pub enum ChannelCommands {
|
|||
/// Run health checks for configured channels (handled in main.rs for async)
|
||||
Doctor,
|
||||
/// Add a new channel configuration
|
||||
#[command(long_about = "\
|
||||
Add a new channel configuration.
|
||||
|
||||
Provide the channel type and a JSON object with the required \
|
||||
configuration keys for that channel type.
|
||||
|
||||
Supported types: telegram, discord, slack, whatsapp, matrix, imessage, email.
|
||||
|
||||
Examples:
|
||||
zeroclaw channel add telegram '{\"bot_token\":\"...\",\"name\":\"my-bot\"}'
|
||||
zeroclaw channel add discord '{\"bot_token\":\"...\",\"name\":\"my-discord\"}'")]
|
||||
Add {
|
||||
/// Channel type (telegram, discord, slack, whatsapp, matrix, imessage, email)
|
||||
channel_type: String,
|
||||
|
|
@ -108,6 +119,16 @@ pub enum ChannelCommands {
|
|||
name: String,
|
||||
},
|
||||
/// Bind a Telegram identity (username or numeric user ID) into allowlist
|
||||
#[command(long_about = "\
|
||||
Bind a Telegram identity into the allowlist.
|
||||
|
||||
Adds a Telegram username (without the '@' prefix) or numeric user \
|
||||
ID to the channel allowlist so the agent will respond to messages \
|
||||
from that identity.
|
||||
|
||||
Examples:
|
||||
zeroclaw channel bind-telegram zeroclaw_user
|
||||
zeroclaw channel bind-telegram 123456789")]
|
||||
BindTelegram {
|
||||
/// Telegram identity to allow (username without '@' or numeric user ID)
|
||||
identity: String,
|
||||
|
|
@ -152,6 +173,16 @@ pub enum CronCommands {
|
|||
/// List all scheduled tasks
|
||||
List,
|
||||
/// Add a new scheduled task
|
||||
#[command(long_about = "\
|
||||
Add a new recurring scheduled task.
|
||||
|
||||
Uses standard 5-field cron syntax: 'min hour day month weekday'. \
|
||||
Times are evaluated in UTC by default; use --tz with an IANA \
|
||||
timezone name to override.
|
||||
|
||||
Examples:
|
||||
zeroclaw cron add '0 9 * * 1-5' 'Good morning' --tz America/New_York
|
||||
zeroclaw cron add '*/30 * * * *' 'Check system health'")]
|
||||
Add {
|
||||
/// Cron expression
|
||||
expression: String,
|
||||
|
|
@ -162,6 +193,14 @@ pub enum CronCommands {
|
|||
command: String,
|
||||
},
|
||||
/// Add a one-shot scheduled task at an RFC3339 timestamp
|
||||
#[command(long_about = "\
|
||||
Add a one-shot task that fires at a specific UTC timestamp.
|
||||
|
||||
The timestamp must be in RFC 3339 format (e.g. 2025-01-15T14:00:00Z).
|
||||
|
||||
Examples:
|
||||
zeroclaw cron add-at 2025-01-15T14:00:00Z 'Send reminder'
|
||||
zeroclaw cron add-at 2025-12-31T23:59:00Z 'Happy New Year!'")]
|
||||
AddAt {
|
||||
/// One-shot timestamp in RFC3339 format
|
||||
at: String,
|
||||
|
|
@ -169,6 +208,14 @@ pub enum CronCommands {
|
|||
command: String,
|
||||
},
|
||||
/// Add a fixed-interval scheduled task
|
||||
#[command(long_about = "\
|
||||
Add a task that repeats at a fixed interval.
|
||||
|
||||
Interval is specified in milliseconds. For example, 60000 = 1 minute.
|
||||
|
||||
Examples:
|
||||
zeroclaw cron add-every 60000 'Ping heartbeat' # every minute
|
||||
zeroclaw cron add-every 3600000 'Hourly report' # every hour")]
|
||||
AddEvery {
|
||||
/// Interval in milliseconds
|
||||
every_ms: u64,
|
||||
|
|
@ -176,6 +223,16 @@ pub enum CronCommands {
|
|||
command: String,
|
||||
},
|
||||
/// Add a one-shot delayed task (e.g. "30m", "2h", "1d")
|
||||
#[command(long_about = "\
|
||||
Add a one-shot task that fires after a delay from now.
|
||||
|
||||
Accepts human-readable durations: s (seconds), m (minutes), \
|
||||
h (hours), d (days).
|
||||
|
||||
Examples:
|
||||
zeroclaw cron once 30m 'Run backup in 30 minutes'
|
||||
zeroclaw cron once 2h 'Follow up on deployment'
|
||||
zeroclaw cron once 1d 'Daily check'")]
|
||||
Once {
|
||||
/// Delay duration
|
||||
delay: String,
|
||||
|
|
@ -188,6 +245,15 @@ pub enum CronCommands {
|
|||
id: String,
|
||||
},
|
||||
/// Update a scheduled task
|
||||
#[command(long_about = "\
|
||||
Update one or more fields of an existing scheduled task.
|
||||
|
||||
Only the fields you specify are changed; others remain unchanged.
|
||||
|
||||
Examples:
|
||||
zeroclaw cron update <task-id> --expression '0 8 * * *'
|
||||
zeroclaw cron update <task-id> --tz Europe/London --name 'Morning check'
|
||||
zeroclaw cron update <task-id> --command 'Updated message'")]
|
||||
Update {
|
||||
/// Task ID
|
||||
id: String,
|
||||
|
|
@ -230,13 +296,39 @@ pub enum IntegrationCommands {
|
|||
#[derive(Subcommand, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
|
||||
pub enum HardwareCommands {
|
||||
/// Enumerate USB devices (VID/PID) and show known boards
|
||||
#[command(long_about = "\
|
||||
Enumerate USB devices and show known boards.
|
||||
|
||||
Scans connected USB devices by VID/PID and matches them against \
|
||||
known development boards (STM32 Nucleo, Arduino, ESP32).
|
||||
|
||||
Examples:
|
||||
zeroclaw hardware discover")]
|
||||
Discover,
|
||||
/// Introspect a device by path (e.g. /dev/ttyACM0)
|
||||
#[command(long_about = "\
|
||||
Introspect a device by its serial or device path.
|
||||
|
||||
Opens the specified device path and queries for board information, \
|
||||
firmware version, and supported capabilities.
|
||||
|
||||
Examples:
|
||||
zeroclaw hardware introspect /dev/ttyACM0
|
||||
zeroclaw hardware introspect COM3")]
|
||||
Introspect {
|
||||
/// Serial or device path
|
||||
path: String,
|
||||
},
|
||||
/// Get chip info via USB (probe-rs over ST-Link). No firmware needed on target.
|
||||
#[command(long_about = "\
|
||||
Get chip info via USB using probe-rs over ST-Link.
|
||||
|
||||
Queries the target MCU directly through the debug probe without \
|
||||
requiring any firmware on the target board.
|
||||
|
||||
Examples:
|
||||
zeroclaw hardware info
|
||||
zeroclaw hardware info --chip STM32F401RETx")]
|
||||
Info {
|
||||
/// Chip name (e.g. STM32F401RETx). Default: STM32F401RETx for Nucleo-F401RE
|
||||
#[arg(long, default_value = "STM32F401RETx")]
|
||||
|
|
@ -250,6 +342,19 @@ pub enum PeripheralCommands {
|
|||
/// List configured peripherals
|
||||
List,
|
||||
/// Add a peripheral (board path, e.g. nucleo-f401re /dev/ttyACM0)
|
||||
#[command(long_about = "\
|
||||
Add a peripheral by board type and transport path.
|
||||
|
||||
Registers a hardware board so the agent can use its tools (GPIO, \
|
||||
sensors, actuators). Use 'native' as path for local GPIO on \
|
||||
single-board computers like Raspberry Pi.
|
||||
|
||||
Supported boards: nucleo-f401re, rpi-gpio, esp32, arduino-uno.
|
||||
|
||||
Examples:
|
||||
zeroclaw peripheral add nucleo-f401re /dev/ttyACM0
|
||||
zeroclaw peripheral add rpi-gpio native
|
||||
zeroclaw peripheral add esp32 /dev/ttyUSB0")]
|
||||
Add {
|
||||
/// Board type (nucleo-f401re, rpi-gpio, esp32)
|
||||
board: String,
|
||||
|
|
@ -257,6 +362,16 @@ pub enum PeripheralCommands {
|
|||
path: String,
|
||||
},
|
||||
/// Flash ZeroClaw firmware to Arduino (creates .ino, installs arduino-cli if needed, uploads)
|
||||
#[command(long_about = "\
|
||||
Flash ZeroClaw firmware to an Arduino board.
|
||||
|
||||
Generates the .ino sketch, installs arduino-cli if it is not \
|
||||
already available, compiles, and uploads the firmware.
|
||||
|
||||
Examples:
|
||||
zeroclaw peripheral flash
|
||||
zeroclaw peripheral flash --port /dev/cu.usbmodem12345
|
||||
zeroclaw peripheral flash -p COM3")]
|
||||
Flash {
|
||||
/// Serial port (e.g. /dev/cu.usbmodem12345). If omitted, uses first arduino-uno from config.
|
||||
#[arg(short, long)]
|
||||
|
|
|
|||
104
src/main.rs
104
src/main.rs
|
|
@ -138,6 +138,17 @@ enum Commands {
|
|||
},
|
||||
|
||||
/// Start the AI agent loop
|
||||
#[command(long_about = "\
|
||||
Start the AI agent loop.
|
||||
|
||||
Launches an interactive chat session with the configured AI provider. \
|
||||
Use --message for single-shot queries without entering interactive mode.
|
||||
|
||||
Examples:
|
||||
zeroclaw agent # interactive session
|
||||
zeroclaw agent -m \"Summarize today's logs\" # single message
|
||||
zeroclaw agent -p anthropic --model claude-sonnet-4-20250514
|
||||
zeroclaw agent --peripheral nucleo-f401re:/dev/ttyACM0")]
|
||||
Agent {
|
||||
/// Single message mode (don't enter interactive mode)
|
||||
#[arg(short, long)]
|
||||
|
|
@ -161,6 +172,18 @@ enum Commands {
|
|||
},
|
||||
|
||||
/// Start the gateway server (webhooks, websockets)
|
||||
#[command(long_about = "\
|
||||
Start the gateway server (webhooks, websockets).
|
||||
|
||||
Runs the HTTP/WebSocket gateway that accepts incoming webhook events \
|
||||
and WebSocket connections. Bind address defaults to the values in \
|
||||
your config file (gateway.host / gateway.port).
|
||||
|
||||
Examples:
|
||||
zeroclaw gateway # use config defaults
|
||||
zeroclaw gateway -p 8080 # listen on port 8080
|
||||
zeroclaw gateway --host 0.0.0.0 # bind to all interfaces
|
||||
zeroclaw gateway -p 0 # random available port")]
|
||||
Gateway {
|
||||
/// Port to listen on (use 0 for random available port); defaults to config gateway.port
|
||||
#[arg(short, long)]
|
||||
|
|
@ -172,6 +195,21 @@ enum Commands {
|
|||
},
|
||||
|
||||
/// Start long-running autonomous runtime (gateway + channels + heartbeat + scheduler)
|
||||
#[command(long_about = "\
|
||||
Start the long-running autonomous daemon.
|
||||
|
||||
Launches the full ZeroClaw runtime: gateway server, all configured \
|
||||
channels (Telegram, Discord, Slack, etc.), heartbeat monitor, and \
|
||||
the cron scheduler. This is the recommended way to run ZeroClaw in \
|
||||
production or as an always-on assistant.
|
||||
|
||||
Use 'zeroclaw service install' to register the daemon as an OS \
|
||||
service (systemd/launchd) for auto-start on boot.
|
||||
|
||||
Examples:
|
||||
zeroclaw daemon # use config defaults
|
||||
zeroclaw daemon -p 9090 # gateway on port 9090
|
||||
zeroclaw daemon --host 127.0.0.1 # localhost only")]
|
||||
Daemon {
|
||||
/// Port to listen on (use 0 for random available port); defaults to config gateway.port
|
||||
#[arg(short, long)]
|
||||
|
|
@ -198,6 +236,25 @@ enum Commands {
|
|||
Status,
|
||||
|
||||
/// Configure and manage scheduled tasks
|
||||
#[command(long_about = "\
|
||||
Configure and manage scheduled tasks.
|
||||
|
||||
Schedule recurring, one-shot, or interval-based tasks using cron \
|
||||
expressions, RFC 3339 timestamps, durations, or fixed intervals.
|
||||
|
||||
Cron expressions use the standard 5-field format: \
|
||||
'min hour day month weekday'. Timezones default to UTC; \
|
||||
override with --tz and an IANA timezone name.
|
||||
|
||||
Examples:
|
||||
zeroclaw cron list
|
||||
zeroclaw cron add '0 9 * * 1-5' 'Good morning' --tz America/New_York
|
||||
zeroclaw cron add '*/30 * * * *' 'Check system health'
|
||||
zeroclaw cron add-at 2025-01-15T14:00:00Z 'Send reminder'
|
||||
zeroclaw cron add-every 60000 'Ping heartbeat'
|
||||
zeroclaw cron once 30m 'Run backup in 30 minutes'
|
||||
zeroclaw cron pause <task-id>
|
||||
zeroclaw cron update <task-id> --expression '0 8 * * *' --tz Europe/London")]
|
||||
Cron {
|
||||
#[command(subcommand)]
|
||||
cron_command: CronCommands,
|
||||
|
|
@ -213,6 +270,19 @@ enum Commands {
|
|||
Providers,
|
||||
|
||||
/// Manage channels (telegram, discord, slack)
|
||||
#[command(long_about = "\
|
||||
Manage communication channels.
|
||||
|
||||
Add, remove, list, and health-check channels that connect ZeroClaw \
|
||||
to messaging platforms. Supported channel types: telegram, discord, \
|
||||
slack, whatsapp, matrix, imessage, email.
|
||||
|
||||
Examples:
|
||||
zeroclaw channel list
|
||||
zeroclaw channel doctor
|
||||
zeroclaw channel add telegram '{\"bot_token\":\"...\",\"name\":\"my-bot\"}'
|
||||
zeroclaw channel remove my-bot
|
||||
zeroclaw channel bind-telegram zeroclaw_user")]
|
||||
Channel {
|
||||
#[command(subcommand)]
|
||||
channel_command: ChannelCommands,
|
||||
|
|
@ -243,18 +313,52 @@ enum Commands {
|
|||
},
|
||||
|
||||
/// Discover and introspect USB hardware
|
||||
#[command(long_about = "\
|
||||
Discover and introspect USB hardware.
|
||||
|
||||
Enumerate connected USB devices, identify known development boards \
|
||||
(STM32 Nucleo, Arduino, ESP32), and retrieve chip information via \
|
||||
probe-rs / ST-Link.
|
||||
|
||||
Examples:
|
||||
zeroclaw hardware discover
|
||||
zeroclaw hardware introspect /dev/ttyACM0
|
||||
zeroclaw hardware info --chip STM32F401RETx")]
|
||||
Hardware {
|
||||
#[command(subcommand)]
|
||||
hardware_command: zeroclaw::HardwareCommands,
|
||||
},
|
||||
|
||||
/// Manage hardware peripherals (STM32, RPi GPIO, etc.)
|
||||
#[command(long_about = "\
|
||||
Manage hardware peripherals.
|
||||
|
||||
Add, list, flash, and configure hardware boards that expose tools \
|
||||
to the agent (GPIO, sensors, actuators). Supported boards: \
|
||||
nucleo-f401re, rpi-gpio, esp32, arduino-uno.
|
||||
|
||||
Examples:
|
||||
zeroclaw peripheral list
|
||||
zeroclaw peripheral add nucleo-f401re /dev/ttyACM0
|
||||
zeroclaw peripheral add rpi-gpio native
|
||||
zeroclaw peripheral flash --port /dev/cu.usbmodem12345
|
||||
zeroclaw peripheral flash-nucleo")]
|
||||
Peripheral {
|
||||
#[command(subcommand)]
|
||||
peripheral_command: zeroclaw::PeripheralCommands,
|
||||
},
|
||||
|
||||
/// Manage configuration
|
||||
#[command(long_about = "\
|
||||
Manage ZeroClaw configuration.
|
||||
|
||||
Inspect and export configuration settings. Use 'schema' to dump \
|
||||
the full JSON Schema for the config file, which documents every \
|
||||
available key, type, and default value.
|
||||
|
||||
Examples:
|
||||
zeroclaw config schema # print JSON Schema to stdout
|
||||
zeroclaw config schema > schema.json")]
|
||||
Config {
|
||||
#[command(subcommand)]
|
||||
config_command: ConfigCommands,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue