From 51b591edda3407739468d58d4fe01e07f90f38a7 Mon Sep 17 00:00:00 2001
From: Rahul Bansal <rahul@hudle.in>
Date: Sat, 21 Feb 2026 10:23:44 +0530
Subject: [PATCH] fix: add --help/-h flag support to CLI and all subcommands

Fixes #562: picoclaw --help and -h now print help and exit 0 instead of
showing 'Unknown command'. No-args also exits 0.

Fixes #574: every subcommand (agent, auth, cron, gateway, onboard, status,
skills) now responds to --help/-h with usage info.
---
 cmd/picoclaw/cmd_agent.go   | 12 ++++++++++++
 cmd/picoclaw/cmd_auth.go    |  2 ++
 cmd/picoclaw/cmd_cron.go    |  5 +++++
 cmd/picoclaw/cmd_gateway.go | 15 ++++++++++++---
 cmd/picoclaw/cmd_onboard.go | 13 +++++++++++++
 cmd/picoclaw/cmd_status.go  | 13 +++++++++++++
 cmd/picoclaw/main.go        |  9 ++++++++-
 7 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/cmd/picoclaw/cmd_agent.go b/cmd/picoclaw/cmd_agent.go
index 6151a158b..b705ff8c5 100644
--- a/cmd/picoclaw/cmd_agent.go
+++ b/cmd/picoclaw/cmd_agent.go
@@ -29,6 +29,18 @@ func agentCmd() {
 	args := os.Args[2:]
 	for i := 0; i < len(args); i++ {
 		switch args[i] {
+		case "--help", "-h":
+			fmt.Println("Interact with the agent directly")
+			fmt.Println()
+			fmt.Println("Usage: picoclaw agent [options]")
+			fmt.Println()
+			fmt.Println("Options:")
+			fmt.Println("  -m, --message <text>   Send a single message (non-interactive)")
+			fmt.Println("  -s, --session <key>    Session key (default: cli:default)")
+			fmt.Println("  --model <model>        Override the default model")
+			fmt.Println("  -d, --debug            Enable debug logging")
+			fmt.Println("  -h, --help             Show this help message")
+			return
 		case "--debug", "-d":
 			logger.SetLevel(logger.DEBUG)
 			fmt.Println("🔍 Debug mode enabled")
diff --git a/cmd/picoclaw/cmd_auth.go b/cmd/picoclaw/cmd_auth.go
index 26f64e627..79b352609 100644
--- a/cmd/picoclaw/cmd_auth.go
+++ b/cmd/picoclaw/cmd_auth.go
@@ -26,6 +26,8 @@ func authCmd() {
 	}
 
 	switch os.Args[2] {
+	case "--help", "-h":
+		authHelp()
 	case "login":
 		authLoginCmd()
 	case "logout":
diff --git a/cmd/picoclaw/cmd_cron.go b/cmd/picoclaw/cmd_cron.go
index 8c42bde06..db3c4bd90 100644
--- a/cmd/picoclaw/cmd_cron.go
+++ b/cmd/picoclaw/cmd_cron.go
@@ -18,6 +18,11 @@ func cronCmd() {
 		return
 	}
 
+	if os.Args[2] == "--help" || os.Args[2] == "-h" {
+		cronHelp()
+		return
+	}
+
 	subcommand := os.Args[2]
 
 	// Load config to get workspace path
diff --git a/cmd/picoclaw/cmd_gateway.go b/cmd/picoclaw/cmd_gateway.go
index 58b11f0fb..f42ec2b0b 100644
--- a/cmd/picoclaw/cmd_gateway.go
+++ b/cmd/picoclaw/cmd_gateway.go
@@ -28,13 +28,22 @@ import (
 )
 
 func gatewayCmd() {
-	// Check for --debug flag
+	// Check for flags
 	args := os.Args[2:]
 	for _, arg := range args {
-		if arg == "--debug" || arg == "-d" {
+		switch arg {
+		case "--help", "-h":
+			fmt.Println("Start the picoclaw gateway server")
+			fmt.Println()
+			fmt.Println("Usage: picoclaw gateway [options]")
+			fmt.Println()
+			fmt.Println("Options:")
+			fmt.Println("  -d, --debug   Enable debug logging")
+			fmt.Println("  -h, --help    Show this help message")
+			return
+		case "--debug", "-d":
 			logger.SetLevel(logger.DEBUG)
 			fmt.Println("🔍 Debug mode enabled")
-			break
 		}
 	}
 
diff --git a/cmd/picoclaw/cmd_onboard.go b/cmd/picoclaw/cmd_onboard.go
index 1a9ebad61..92112ab48 100644
--- a/cmd/picoclaw/cmd_onboard.go
+++ b/cmd/picoclaw/cmd_onboard.go
@@ -18,6 +18,19 @@ import (
 var embeddedFiles embed.FS
 
 func onboard() {
+	for _, arg := range os.Args[2:] {
+		switch arg {
+		case "--help", "-h":
+			fmt.Println("Initialize picoclaw configuration and workspace")
+			fmt.Println()
+			fmt.Println("Usage: picoclaw onboard")
+			fmt.Println()
+			fmt.Println("Creates the default config file and workspace directory.")
+			fmt.Println("If a config already exists, prompts before overwriting.")
+			return
+		}
+	}
+
 	configPath := getConfigPath()
 
 	if _, err := os.Stat(configPath); err == nil {
diff --git a/cmd/picoclaw/cmd_status.go b/cmd/picoclaw/cmd_status.go
index 07296784e..b4d36181a 100644
--- a/cmd/picoclaw/cmd_status.go
+++ b/cmd/picoclaw/cmd_status.go
@@ -11,6 +11,19 @@ import (
 )
 
 func statusCmd() {
+	for _, arg := range os.Args[2:] {
+		switch arg {
+		case "--help", "-h":
+			fmt.Println("Show picoclaw status and configuration")
+			fmt.Println()
+			fmt.Println("Usage: picoclaw status")
+			fmt.Println()
+			fmt.Println("Displays version, config path, workspace path, configured")
+			fmt.Println("providers, and authentication status.")
+			return
+		}
+	}
+
 	cfg, err := loadConfig()
 	if err != nil {
 		fmt.Printf("Error loading config: %v\n", err)
diff --git a/cmd/picoclaw/main.go b/cmd/picoclaw/main.go
index 0dd2e04f7..a05834dd1 100644
--- a/cmd/picoclaw/main.go
+++ b/cmd/picoclaw/main.go
@@ -95,7 +95,7 @@ func copyDirectory(src, dst string) error {
 func main() {
 	if len(os.Args) < 2 {
 		printHelp()
-		os.Exit(1)
+		os.Exit(0)
 	}
 
 	command := os.Args[1]
@@ -125,6 +125,11 @@ func main() {
 
 		subcommand := os.Args[2]
 
+		if subcommand == "--help" || subcommand == "-h" {
+			skillsHelp()
+			return
+		}
+
 		cfg, err := loadConfig()
 		if err != nil {
 			fmt.Printf("Error loading config: %v\n", err)
@@ -168,6 +173,8 @@ func main() {
 		}
 	case "version", "--version", "-v":
 		printVersion()
+	case "--help", "-h":
+		printHelp()
 	default:
 		fmt.Printf("Unknown command: %s\n", command)
 		printHelp()