refactor(cli): migrate to Cobra-based command structure

Refactor CLI to use Cobra instead of manual os.Args parsing.

- Introduce root command and structured subcommands under cmd/picoclaw/internal
- Convert agent, auth, cron, gateway, migrate, onboard, skills, status and version to Cobra commands
- Replace manual flag parsing with Cobra flags
- Remove direct os.Args usage from command handlers
- Keep existing command behavior and output semantics

This change focuses on CLI structure and maintainability.
No business logic changes intended.

.gitignore

@@ -10,7 +10,7 @@ build/
 *.out
 /picoclaw
 /picoclaw-test
-cmd/picoclaw/workspace
+cmd/**/workspace
 
 # Picoclaw specific
 

Makefile

@@ -11,7 +11,7 @@ VERSION?=$(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 GIT_COMMIT=$(shell git rev-parse --short=8 HEAD 2>/dev/null || echo "dev")
 BUILD_TIME=$(shell date +%FT%T%z)
 GO_VERSION=$(shell $(GO) version | awk '{print $$3}')
-LDFLAGS=-ldflags "-X main.version=$(VERSION) -X main.gitCommit=$(GIT_COMMIT) -X main.buildTime=$(BUILD_TIME) -X main.goVersion=$(GO_VERSION) -s -w"
+LDFLAGS=-ldflags "-X github.com/sipeed/picoclaw/cmd/picoclaw/internal.version=$(VERSION) -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.gitCommit=$(GIT_COMMIT) -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.buildTime=$(BUILD_TIME) -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.goVersion=$(GO_VERSION) -s -w"
 
 # Go variables
 GO?=go

cmd/picoclaw/internal/agent/command.go

@@ -0,0 +1,32 @@
+package agent
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewAgentCommand() *cobra.Command {
+	var (
+		message    string
+		sessionKey string
+		debug      bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "agent",
+		Short: "Interact with the agent directly",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			debug, _ = cmd.Flags().GetBool("debug")
+			message, _ = cmd.Flags().GetString("message")
+			sessionKey, _ = cmd.Flags().GetString("session")
+
+			return agentCmd(message, sessionKey, debug)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&debug, "debug", "d", false, "Enable debug logging")
+	cmd.Flags().StringVarP(&message, "message", "m", "", "Send a single message (non-interactive mode)")
+	cmd.Flags().StringVarP(&sessionKey, "session", "s", "cli:default", "Session key")
+
+	return cmd
+}

cmd/picoclaw/internal/agent/helpers.go

@@ -0,0 +1,152 @@
+package agent
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/chzyer/readline"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/agent"
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func agentCmd(message, sessionKey string, debug bool) error {
+	if sessionKey == "" {
+		sessionKey = "cli:default"
+	}
+
+	if debug {
+		logger.SetLevel(logger.DEBUG)
+		fmt.Println("🔍 Debug mode enabled")
+	}
+
+	cfg, err := internal.LoadConfig()
+	if err != nil {
+		return fmt.Errorf("error loading config: %w", err)
+	}
+
+	provider, err := providers.CreateProvider(cfg)
+	if err != nil {
+		return fmt.Errorf("error creating provider: %w", err)
+	}
+
+	msgBus := bus.NewMessageBus()
+	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
+
+	// Print agent startup info (only for interactive mode)
+	startupInfo := agentLoop.GetStartupInfo()
+	logger.InfoCF("agent", "Agent initialized",
+		map[string]interface{}{
+			"tools_count":      startupInfo["tools"].(map[string]interface{})["count"],
+			"skills_total":     startupInfo["skills"].(map[string]interface{})["total"],
+			"skills_available": startupInfo["skills"].(map[string]interface{})["available"],
+		})
+
+	if message != "" {
+		ctx := context.Background()
+		response, err := agentLoop.ProcessDirect(ctx, message, sessionKey)
+		if err != nil {
+			return fmt.Errorf("error processing message: %w", err)
+		}
+		fmt.Printf("\n%s %s\n", internal.Logo, response)
+		return nil
+	}
+
+	fmt.Printf("%s Interactive mode (Ctrl+C to exit)\n\n", internal.Logo)
+	interactiveMode(agentLoop, sessionKey)
+
+	return nil
+}
+
+func interactiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
+	prompt := fmt.Sprintf("%s You: ", internal.Logo)
+
+	rl, err := readline.NewEx(&readline.Config{
+		Prompt:          prompt,
+		HistoryFile:     filepath.Join(os.TempDir(), ".picoclaw_history"),
+		HistoryLimit:    100,
+		InterruptPrompt: "^C",
+		EOFPrompt:       "exit",
+	})
+
+	if err != nil {
+		fmt.Printf("Error initializing readline: %v\n", err)
+		fmt.Println("Falling back to simple input mode...")
+		simpleInteractiveMode(agentLoop, sessionKey)
+		return
+	}
+	defer rl.Close()
+
+	for {
+		line, err := rl.Readline()
+		if err != nil {
+			if err == readline.ErrInterrupt || err == io.EOF {
+				fmt.Println("\nGoodbye!")
+				return
+			}
+			fmt.Printf("Error reading input: %v\n", err)
+			continue
+		}
+
+		input := strings.TrimSpace(line)
+		if input == "" {
+			continue
+		}
+
+		if input == "exit" || input == "quit" {
+			fmt.Println("Goodbye!")
+			return
+		}
+
+		ctx := context.Background()
+		response, err := agentLoop.ProcessDirect(ctx, input, sessionKey)
+		if err != nil {
+			fmt.Printf("Error: %v\n", err)
+			continue
+		}
+
+		fmt.Printf("\n%s %s\n\n", internal.Logo, response)
+	}
+}
+
+func simpleInteractiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
+	reader := bufio.NewReader(os.Stdin)
+	for {
+		fmt.Print(fmt.Sprintf("%s You: ", internal.Logo))
+		line, err := reader.ReadString('\n')
+		if err != nil {
+			if err == io.EOF {
+				fmt.Println("\nGoodbye!")
+				return
+			}
+			fmt.Printf("Error reading input: %v\n", err)
+			continue
+		}
+
+		input := strings.TrimSpace(line)
+		if input == "" {
+			continue
+		}
+
+		if input == "exit" || input == "quit" {
+			fmt.Println("Goodbye!")
+			return
+		}
+
+		ctx := context.Background()
+		response, err := agentLoop.ProcessDirect(ctx, input, sessionKey)
+		if err != nil {
+			fmt.Printf("Error: %v\n", err)
+			continue
+		}
+
+		fmt.Printf("\n%s %s\n\n", internal.Logo, response)
+	}
+}

cmd/picoclaw/internal/auth/command.go

@@ -0,0 +1,21 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func NewAuthCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "auth",
+		Short: "Manage authentication (login, logout, status)",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+	}
+
+	cmd.AddCommand(
+		newLoginCommand(),
+		newLogoutCommand(),
+		newStatusCommand(),
+	)
+
+	return cmd
+}

cmd/picoclaw/internal/auth/helpers.go

@@ -0,0 +1,172 @@
+package auth
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func authHelp() {
+	fmt.Println("\nAuth commands:")
+	fmt.Println("  login       Login via OAuth or paste token")
+	fmt.Println("  logout      Remove stored credentials")
+	fmt.Println("  status      Show current auth status")
+	fmt.Println()
+	fmt.Println("Login options:")
+	fmt.Println("  --provider <name>    Provider to login with (openai, anthropic)")
+	fmt.Println("  --device-code        Use device code flow (for headless environments)")
+	fmt.Println()
+	fmt.Println("Examples:")
+	fmt.Println("  picoclaw auth login --provider openai")
+	fmt.Println("  picoclaw auth login --provider openai --device-code")
+	fmt.Println("  picoclaw auth login --provider anthropic")
+	fmt.Println("  picoclaw auth logout --provider openai")
+	fmt.Println("  picoclaw auth status")
+}
+
+func authLoginCmd(provider string, useDeviceCode bool) error {
+	switch provider {
+	case "openai":
+		return authLoginOpenAI(useDeviceCode)
+	case "anthropic":
+		return authLoginPasteToken(provider)
+	default:
+		return fmt.Errorf("unsupported provider: %s (supported: openai, anthropic)", provider)
+	}
+}
+
+func authLoginOpenAI(useDeviceCode bool) error {
+	cfg := auth.OpenAIOAuthConfig()
+
+	var cred *auth.AuthCredential
+	var err error
+
+	if useDeviceCode {
+		cred, err = auth.LoginDeviceCode(cfg)
+	} else {
+		cred, err = auth.LoginBrowser(cfg)
+	}
+
+	if err != nil {
+		return fmt.Errorf("login failed: %w", err)
+	}
+
+	if err := auth.SetCredential("openai", cred); err != nil {
+		return fmt.Errorf("failed to save credentials: %w", err)
+	}
+
+	appCfg, err := internal.LoadConfig()
+	if err == nil {
+		appCfg.Providers.OpenAI.AuthMethod = "oauth"
+		if err := config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
+			fmt.Printf("Warning: could not update config: %v\n", err)
+		}
+	}
+
+	fmt.Println("Login successful!")
+	if cred.AccountID != "" {
+		fmt.Printf("Account: %s\n", cred.AccountID)
+	}
+
+	return nil
+}
+
+func authLoginPasteToken(provider string) error {
+	cred, err := auth.LoginPasteToken(provider, os.Stdin)
+	if err != nil {
+		return fmt.Errorf("login failed: %w", err)
+	}
+
+	if err := auth.SetCredential(provider, cred); err != nil {
+		return fmt.Errorf("failed to save credentials: %w", err)
+	}
+
+	appCfg, err := internal.LoadConfig()
+	if err == nil {
+		switch provider {
+		case "anthropic":
+			appCfg.Providers.Anthropic.AuthMethod = "token"
+		case "openai":
+			appCfg.Providers.OpenAI.AuthMethod = "token"
+		}
+		if err = config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
+			fmt.Printf("Warning: could not update config: %v\n", err)
+		}
+	}
+
+	fmt.Printf("Token saved for %s!\n", provider)
+	return nil
+}
+
+func authLogoutCmd(provider string) error {
+	if provider != "" {
+		if err := auth.DeleteCredential(provider); err != nil {
+			return fmt.Errorf("failed to remove credentials: %w", err)
+		}
+
+		appCfg, err := internal.LoadConfig()
+		if err == nil {
+			switch provider {
+			case "openai":
+				appCfg.Providers.OpenAI.AuthMethod = ""
+			case "anthropic":
+				appCfg.Providers.Anthropic.AuthMethod = ""
+			}
+			_ = config.SaveConfig(internal.GetConfigPath(), appCfg)
+		}
+
+		fmt.Printf("Logged out from %s\n", provider)
+		return nil
+	}
+
+	if err := auth.DeleteAllCredentials(); err != nil {
+		return fmt.Errorf("failed to remove credentials: %w", err)
+	}
+
+	appCfg, err := internal.LoadConfig()
+	if err == nil {
+		appCfg.Providers.OpenAI.AuthMethod = ""
+		appCfg.Providers.Anthropic.AuthMethod = ""
+		_ = config.SaveConfig(internal.GetConfigPath(), appCfg)
+	}
+
+	fmt.Println("Logged out from all providers")
+	return nil
+}
+
+func authStatusCmd() error {
+	store, err := auth.LoadStore()
+	if err != nil {
+		return fmt.Errorf("failed to load auth store: %w", err)
+	}
+
+	if len(store.Credentials) == 0 {
+		return fmt.Errorf("no authenticated providers. run: picoclaw auth login --provider <name>")
+	}
+
+	fmt.Println("\nAuthenticated Providers:")
+	fmt.Println("------------------------")
+	for provider, cred := range store.Credentials {
+		status := "active"
+		if cred.IsExpired() {
+			status = "expired"
+		} else if cred.NeedsRefresh() {
+			status = "needs refresh"
+		}
+
+		fmt.Printf("  %s:\n", provider)
+		fmt.Printf("    Method: %s\n", cred.AuthMethod)
+		fmt.Printf("    Status: %s\n", status)
+		if cred.AccountID != "" {
+			fmt.Printf("    Account: %s\n", cred.AccountID)
+		}
+		if !cred.ExpiresAt.IsZero() {
+			fmt.Printf("    Expires: %s\n", cred.ExpiresAt.Format("2006-01-02 15:04"))
+		}
+	}
+
+	return nil
+}

cmd/picoclaw/internal/auth/login.go

@@ -0,0 +1,25 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newLoginCommand() *cobra.Command {
+	var (
+		provider      string
+		useDeviceCode bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "login",
+		Short: "Login via OAuth or paste token",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return authLoginCmd(provider, useDeviceCode)
+		},
+	}
+
+	cmd.Flags().StringVarP(&provider, "provider", "p", "", "Provider to login with (openai, anthropic)")
+	cmd.Flags().BoolVar(&useDeviceCode, "device-code", false, "Use device code flow (for headless environments)")
+	_ = cmd.MarkFlagRequired("provider")
+
+	return cmd
+}

cmd/picoclaw/internal/auth/logout.go

@@ -0,0 +1,20 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newLogoutCommand() *cobra.Command {
+	var provider string
+
+	cmd := &cobra.Command{
+		Use:   "logout",
+		Short: "Remove stored credentials",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return authLogoutCmd(provider)
+		},
+	}
+
+	cmd.Flags().StringVarP(&provider, "provider", "p", "", "Provider to logout from (openai, anthropic); empty = all")
+
+	return cmd
+}

cmd/picoclaw/internal/auth/status.go

@@ -0,0 +1,16 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newStatusCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "status",
+		Short: "Show current auth status",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return authStatusCmd()
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/cron/add.go

@@ -0,0 +1,74 @@
+package cron
+
+import (
+	"fmt"
+
+	"github.com/sipeed/picoclaw/pkg/cron"
+	"github.com/spf13/cobra"
+)
+
+func newAddCommand(storePath func() string) *cobra.Command {
+	var (
+		name    string
+		message string
+		every   int64
+		cronExp string
+		deliver bool
+		channel string
+		to      string
+	)
+
+	cmd := &cobra.Command{
+		Use:   "add",
+		Short: "Add a new scheduled job",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if name == "" {
+				return fmt.Errorf("--name is required")
+			}
+
+			if message == "" {
+				return fmt.Errorf("--message is required")
+			}
+
+			if every <= 0 && cronExp == "" {
+				return fmt.Errorf("either --every or --cron must be specified")
+			}
+
+			if every > 0 && cronExp != "" {
+				return fmt.Errorf("--every and --cron are mutually exclusive")
+			}
+
+			var schedule cron.CronSchedule
+			if every > 0 {
+				everyMS := every * 1000
+				schedule = cron.CronSchedule{Kind: "every", EveryMS: &everyMS}
+			} else {
+				schedule = cron.CronSchedule{Kind: "cron", Expr: cronExp}
+			}
+
+			cs := cron.NewCronService(storePath(), nil)
+			job, err := cs.AddJob(name, schedule, message, deliver, channel, to)
+			if err != nil {
+				return fmt.Errorf("error adding job: %w", err)
+			}
+
+			fmt.Printf("✓ Added job '%s' (%s)\n", job.Name, job.ID)
+
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVarP(&name, "name", "n", "", "Job name")
+	cmd.Flags().StringVarP(&message, "message", "m", "", "Message for agent")
+	cmd.Flags().Int64VarP(&every, "every", "e", 0, "Run every N seconds")
+	cmd.Flags().StringVarP(&cronExp, "cron", "c", "", "Cron expression (e.g. '0 9 * * *')")
+	cmd.Flags().BoolVarP(&deliver, "deliver", "d", false, "Deliver response to channel")
+	cmd.Flags().StringVar(&to, "to", "", "Recipient for delivery")
+	cmd.Flags().StringVar(&channel, "channel", "", "Channel for delivery")
+
+	_ = cmd.MarkFlagRequired("name")
+	_ = cmd.MarkFlagRequired("message")
+
+	return cmd
+}

cmd/picoclaw/internal/cron/command.go

@@ -0,0 +1,41 @@
+package cron
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/spf13/cobra"
+)
+
+func NewCronCommand() *cobra.Command {
+	var storePath string
+
+	cmd := &cobra.Command{
+		Use:     "cron",
+		Aliases: []string{"c"},
+		Short:   "Manage scheduled tasks",
+		Args:    cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+		PersistentPreRunE: func(_ *cobra.Command, _ []string) error {
+			cfg, err := internal.LoadConfig()
+			if err != nil {
+				return fmt.Errorf("error loading config: %w", err)
+			}
+			storePath = filepath.Join(cfg.WorkspacePath(), "cron", "jobs.json")
+			return nil
+		},
+	}
+
+	cmd.AddCommand(
+		newListCommand(func() string { return storePath }),
+		newAddCommand(func() string { return storePath }),
+		newRemoveCommand(func() string { return storePath }),
+		newEnableCommand(func() string { return storePath }, false),
+		newEnableCommand(func() string { return storePath }, true),
+	)
+
+	return cmd
+}

cmd/picoclaw/internal/cron/enable.go

@@ -0,0 +1,22 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newEnableCommand(storePath func() string, disable bool) *cobra.Command {
+	name := "enable"
+	short := "Enable a job"
+	if disable {
+		name = "disable"
+		short = "Disable a job"
+	}
+
+	return &cobra.Command{
+		Use:   name + " <id>",
+		Short: short,
+		Args:  cobra.ExactArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			cronEnableCmd(storePath(), disable, args[0])
+			return nil
+		},
+	}
+}

cmd/picoclaw/internal/cron/helpers.go

@@ -0,0 +1,72 @@
+package cron
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/cron"
+)
+
+func cronListCmd(storePath string) {
+	cs := cron.NewCronService(storePath, nil)
+	jobs := cs.ListJobs(true) // Show all jobs, including disabled
+
+	if len(jobs) == 0 {
+		fmt.Println("No scheduled jobs.")
+		return
+	}
+
+	fmt.Println("\nScheduled Jobs:")
+	fmt.Println("----------------")
+	for _, job := range jobs {
+		var schedule string
+		if job.Schedule.Kind == "every" && job.Schedule.EveryMS != nil {
+			schedule = fmt.Sprintf("every %ds", *job.Schedule.EveryMS/1000)
+		} else if job.Schedule.Kind == "cron" {
+			schedule = job.Schedule.Expr
+		} else {
+			schedule = "one-time"
+		}
+
+		nextRun := "scheduled"
+		if job.State.NextRunAtMS != nil {
+			nextTime := time.UnixMilli(*job.State.NextRunAtMS)
+			nextRun = nextTime.Format("2006-01-02 15:04")
+		}
+
+		status := "enabled"
+		if !job.Enabled {
+			status = "disabled"
+		}
+
+		fmt.Printf("  %s (%s)\n", job.Name, job.ID)
+		fmt.Printf("    Schedule: %s\n", schedule)
+		fmt.Printf("    Status: %s\n", status)
+		fmt.Printf("    Next run: %s\n", nextRun)
+	}
+}
+
+func cronRemoveCmd(storePath, jobID string) {
+	cs := cron.NewCronService(storePath, nil)
+	if cs.RemoveJob(jobID) {
+		fmt.Printf("✓ Removed job %s\n", jobID)
+	} else {
+		fmt.Printf("✗ Job %s not found\n", jobID)
+	}
+}
+
+func cronEnableCmd(storePath string, disable bool, jobID string) {
+	cs := cron.NewCronService(storePath, nil)
+	enabled := !disable
+
+	job := cs.EnableJob(jobID, enabled)
+	if job != nil {
+		status := "enabled"
+		if disable {
+			status = "disabled"
+		}
+		fmt.Printf("✓ Job '%s' %s\n", job.Name, status)
+	} else {
+		fmt.Printf("✗ Job %s not found\n", jobID)
+	}
+}

cmd/picoclaw/internal/cron/list.go

@@ -0,0 +1,17 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newListCommand(storePath func() string) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List all scheduled jobs",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			cronListCmd(storePath())
+			return nil
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/cron/remove.go

@@ -0,0 +1,17 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newRemoveCommand(storePath func() string) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "remove <id>",
+		Short: "Remove a job by ID",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			cronRemoveCmd(storePath(), args[0])
+			return nil
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/gateway/command.go

@@ -0,0 +1,23 @@
+package gateway
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewGatewayCommand() *cobra.Command {
+	var debug bool
+
+	cmd := &cobra.Command{
+		Use:     "gateway",
+		Aliases: []string{"g"},
+		Short:   "Start picoclaw gateway",
+		Args:    cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return gatewayCmd(debug)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&debug, "debug", "d", false, "Enable debug logging")
+
+	return cmd
+}

cmd/picoclaw/internal/gateway/helpers.go

@@ -0,0 +1,212 @@
+package gateway
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"time"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/agent"
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/cron"
+	"github.com/sipeed/picoclaw/pkg/devices"
+	"github.com/sipeed/picoclaw/pkg/health"
+	"github.com/sipeed/picoclaw/pkg/heartbeat"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/state"
+	"github.com/sipeed/picoclaw/pkg/tools"
+	"github.com/sipeed/picoclaw/pkg/voice"
+)
+
+func gatewayCmd(debug bool) error {
+	if debug {
+		logger.SetLevel(logger.DEBUG)
+		fmt.Println("🔍 Debug mode enabled")
+	}
+
+	cfg, err := internal.LoadConfig()
+	if err != nil {
+		return fmt.Errorf("error loading config: %w", err)
+	}
+
+	provider, err := providers.CreateProvider(cfg)
+	if err != nil {
+		return fmt.Errorf("error creating provider: %w", err)
+	}
+
+	msgBus := bus.NewMessageBus()
+	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
+
+	// Print agent startup info
+	fmt.Println("\n📦 Agent Status:")
+	startupInfo := agentLoop.GetStartupInfo()
+	toolsInfo := startupInfo["tools"].(map[string]interface{})
+	skillsInfo := startupInfo["skills"].(map[string]interface{})
+	fmt.Printf("  • Tools: %d loaded\n", toolsInfo["count"])
+	fmt.Printf("  • Skills: %d/%d available\n",
+		skillsInfo["available"],
+		skillsInfo["total"])
+
+	// Log to file as well
+	logger.InfoCF("agent", "Agent initialized",
+		map[string]interface{}{
+			"tools_count":      toolsInfo["count"],
+			"skills_total":     skillsInfo["total"],
+			"skills_available": skillsInfo["available"],
+		})
+
+	// Setup cron tool and service
+	execTimeout := time.Duration(cfg.Tools.Cron.ExecTimeoutMinutes) * time.Minute
+	cronService := setupCronTool(agentLoop, msgBus, cfg.WorkspacePath(), cfg.Agents.Defaults.RestrictToWorkspace, execTimeout, cfg)
+
+	heartbeatService := heartbeat.NewHeartbeatService(
+		cfg.WorkspacePath(),
+		cfg.Heartbeat.Interval,
+		cfg.Heartbeat.Enabled,
+	)
+	heartbeatService.SetBus(msgBus)
+	heartbeatService.SetHandler(func(prompt, channel, chatID string) *tools.ToolResult {
+		// Use cli:direct as fallback if no valid channel
+		if channel == "" || chatID == "" {
+			channel, chatID = "cli", "direct"
+		}
+		// Use ProcessHeartbeat - no session history, each heartbeat is independent
+		response, err := agentLoop.ProcessHeartbeat(context.Background(), prompt, channel, chatID)
+		if err != nil {
+			return tools.ErrorResult(fmt.Sprintf("Heartbeat error: %v", err))
+		}
+		if response == "HEARTBEAT_OK" {
+			return tools.SilentResult("Heartbeat OK")
+		}
+		// For heartbeat, always return silent - the subagent result will be
+		// sent to user via processSystemMessage when the async task completes
+		return tools.SilentResult(response)
+	})
+
+	channelManager, err := channels.NewManager(cfg, msgBus)
+	if err != nil {
+		return fmt.Errorf("error creating channel manager: %w", err)
+	}
+
+	// Inject channel manager into agent loop for command handling
+	agentLoop.SetChannelManager(channelManager)
+
+	var transcriber *voice.GroqTranscriber
+	if cfg.Providers.Groq.APIKey != "" {
+		transcriber = voice.NewGroqTranscriber(cfg.Providers.Groq.APIKey)
+		logger.InfoC("voice", "Groq voice transcription enabled")
+	}
+
+	if transcriber != nil {
+		if telegramChannel, ok := channelManager.GetChannel("telegram"); ok {
+			if tc, ok := telegramChannel.(*channels.TelegramChannel); ok {
+				tc.SetTranscriber(transcriber)
+				logger.InfoC("voice", "Groq transcription attached to Telegram channel")
+			}
+		}
+		if discordChannel, ok := channelManager.GetChannel("discord"); ok {
+			if dc, ok := discordChannel.(*channels.DiscordChannel); ok {
+				dc.SetTranscriber(transcriber)
+				logger.InfoC("voice", "Groq transcription attached to Discord channel")
+			}
+		}
+		if slackChannel, ok := channelManager.GetChannel("slack"); ok {
+			if sc, ok := slackChannel.(*channels.SlackChannel); ok {
+				sc.SetTranscriber(transcriber)
+				logger.InfoC("voice", "Groq transcription attached to Slack channel")
+			}
+		}
+	}
+
+	enabledChannels := channelManager.GetEnabledChannels()
+	if len(enabledChannels) > 0 {
+		fmt.Printf("✓ Channels enabled: %s\n", enabledChannels)
+	} else {
+		fmt.Println("⚠ Warning: No channels enabled")
+	}
+
+	fmt.Printf("✓ Gateway started on %s:%d\n", cfg.Gateway.Host, cfg.Gateway.Port)
+	fmt.Println("Press Ctrl+C to stop")
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	if err := cronService.Start(); err != nil {
+		fmt.Printf("Error starting cron service: %v\n", err)
+	}
+	fmt.Println("✓ Cron service started")
+
+	if err := heartbeatService.Start(); err != nil {
+		fmt.Printf("Error starting heartbeat service: %v\n", err)
+	}
+	fmt.Println("✓ Heartbeat service started")
+
+	stateManager := state.NewManager(cfg.WorkspacePath())
+	deviceService := devices.NewService(devices.Config{
+		Enabled:    cfg.Devices.Enabled,
+		MonitorUSB: cfg.Devices.MonitorUSB,
+	}, stateManager)
+	deviceService.SetBus(msgBus)
+	if err := deviceService.Start(ctx); err != nil {
+		fmt.Printf("Error starting device service: %v\n", err)
+	} else if cfg.Devices.Enabled {
+		fmt.Println("✓ Device event service started")
+	}
+
+	if err := channelManager.StartAll(ctx); err != nil {
+		fmt.Printf("Error starting channels: %v\n", err)
+	}
+
+	healthServer := health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
+	go func() {
+		if err := healthServer.Start(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			logger.ErrorCF("health", "Health server error", map[string]interface{}{"error": err.Error()})
+		}
+	}()
+	fmt.Printf("✓ Health endpoints available at http://%s:%d/health and /ready\n", cfg.Gateway.Host, cfg.Gateway.Port)
+
+	go agentLoop.Run(ctx)
+
+	sigChan := make(chan os.Signal, 1)
+	signal.Notify(sigChan, os.Interrupt)
+	<-sigChan
+
+	fmt.Println("\nShutting down...")
+	cancel()
+	healthServer.Stop(context.Background())
+	deviceService.Stop()
+	heartbeatService.Stop()
+	cronService.Stop()
+	agentLoop.Stop()
+	channelManager.StopAll(ctx)
+	fmt.Println("✓ Gateway stopped")
+
+	return nil
+}
+
+func setupCronTool(agentLoop *agent.AgentLoop, msgBus *bus.MessageBus, workspace string, restrict bool, execTimeout time.Duration, config *config.Config) *cron.CronService {
+	cronStorePath := filepath.Join(workspace, "cron", "jobs.json")
+
+	// Create cron service
+	cronService := cron.NewCronService(cronStorePath, nil)
+
+	// Create and register CronTool
+	cronTool := tools.NewCronTool(cronService, agentLoop, msgBus, workspace, restrict, execTimeout, config)
+	agentLoop.RegisterTool(cronTool)
+
+	// Set the onJob handler
+	cronService.SetOnJob(func(job *cron.CronJob) (string, error) {
+		result := cronTool.ExecuteJob(context.Background(), job)
+		return result, nil
+	})
+
+	return cronService
+}

cmd/picoclaw/internal/helpers.go

@@ -0,0 +1,49 @@
+package internal
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+const Logo = "🦞"
+
+var (
+	version   = "dev"
+	gitCommit string
+	buildTime string
+	goVersion string
+)
+
+func GetConfigPath() string {
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, ".picoclaw", "config.json")
+}
+
+func LoadConfig() (*config.Config, error) {
+	return config.LoadConfig(GetConfigPath())
+}
+
+// FormatVersion returns the version string with optional git commit
+func FormatVersion() string {
+	v := version
+	if gitCommit != "" {
+		v += fmt.Sprintf(" (git: %s)", gitCommit)
+	}
+	return v
+}
+
+// FormatBuildInfo returns build time and go version info
+func FormatBuildInfo() (build string, goVer string) {
+	if buildTime != "" {
+		build = buildTime
+	}
+	goVer = goVersion
+	if goVer == "" {
+		goVer = runtime.Version()
+	}
+	return
+}

cmd/picoclaw/internal/migrate/command.go

@@ -0,0 +1,47 @@
+package migrate
+
+import (
+	"github.com/sipeed/picoclaw/pkg/migrate"
+	"github.com/spf13/cobra"
+)
+
+func NewMigrateCommand() *cobra.Command {
+	var opts migrate.Options
+
+	cmd := &cobra.Command{
+		Use:   "migrate",
+		Short: "Migrate from OpenClaw to PicoClaw",
+		Args:  cobra.NoArgs,
+		Example: `  picoclaw migrate
+  picoclaw migrate --dry-run
+  picoclaw migrate --refresh
+  picoclaw migrate --force`,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			result, err := migrate.Run(opts)
+			if err != nil {
+				return err
+			}
+			if !opts.DryRun {
+				migrate.PrintSummary(result)
+			}
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false,
+		"Show what would be migrated without making changes")
+	cmd.Flags().BoolVar(&opts.Refresh, "refresh", false,
+		"Re-sync workspace files from OpenClaw (repeatable)")
+	cmd.Flags().BoolVar(&opts.ConfigOnly, "config-only", false,
+		"Only migrate config, skip workspace files")
+	cmd.Flags().BoolVar(&opts.WorkspaceOnly, "workspace-only", false,
+		"Only migrate workspace files, skip config")
+	cmd.Flags().BoolVar(&opts.Force, "force", false,
+		"Skip confirmation prompts")
+	cmd.Flags().StringVar(&opts.OpenClawHome, "openclaw-home", "",
+		"Override OpenClaw home directory (default: ~/.openclaw)")
+	cmd.Flags().StringVar(&opts.PicoClawHome, "picoclaw-home", "",
+		"Override PicoClaw home directory (default: ~/.picoclaw)")
+
+	return cmd
+}

cmd/picoclaw/internal/onboard/command.go

@@ -0,0 +1,24 @@
+package onboard
+
+import (
+	"embed"
+
+	"github.com/spf13/cobra"
+)
+
+//go:generate cp -r ../../../../workspace .
+//go:embed workspace
+var embeddedFiles embed.FS
+
+func NewOnboardCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "onboard",
+		Aliases: []string{"o"},
+		Short:   "Initialize picoclaw configuration and workspace",
+		Run: func(cmd *cobra.Command, args []string) {
+			onboard()
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/onboard/helpers.go

@@ -0,0 +1,95 @@
+package onboard
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func onboard() {
+	configPath := internal.GetConfigPath()
+
+	if _, err := os.Stat(configPath); err == nil {
+		fmt.Printf("Config already exists at %s\n", configPath)
+		fmt.Print("Overwrite? (y/n): ")
+		var response string
+		fmt.Scanln(&response)
+		if response != "y" {
+			fmt.Println("Aborted.")
+			return
+		}
+	}
+
+	cfg := config.DefaultConfig()
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		fmt.Printf("Error saving config: %v\n", err)
+		os.Exit(1)
+	}
+
+	workspace := cfg.WorkspacePath()
+	createWorkspaceTemplates(workspace)
+
+	fmt.Printf("%s picoclaw is ready!\n", internal.Logo)
+	fmt.Println("\nNext steps:")
+	fmt.Println("  1. Add your API key to", configPath)
+	fmt.Println("     Get one at: https://openrouter.ai/keys")
+	fmt.Println("  2. Chat: picoclaw agent -m \"Hello!\"")
+}
+
+func createWorkspaceTemplates(workspace string) {
+	err := copyEmbeddedToTarget(workspace)
+	if err != nil {
+		fmt.Printf("Error copying workspace templates: %v\n", err)
+	}
+}
+
+func copyEmbeddedToTarget(targetDir string) error {
+	// Ensure target directory exists
+	if err := os.MkdirAll(targetDir, 0755); err != nil {
+		return fmt.Errorf("Failed to create target directory: %w", err)
+	}
+
+	// Walk through all files in embed.FS
+	err := fs.WalkDir(embeddedFiles, "workspace", func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+
+		// Skip directories
+		if d.IsDir() {
+			return nil
+		}
+
+		// Read embedded file
+		data, err := embeddedFiles.ReadFile(path)
+		if err != nil {
+			return fmt.Errorf("Failed to read embedded file %s: %w", path, err)
+		}
+
+		new_path, err := filepath.Rel("workspace", path)
+		if err != nil {
+			return fmt.Errorf("Failed to get relative path for %s: %v\n", path, err)
+		}
+
+		// Build target file path
+		targetPath := filepath.Join(targetDir, new_path)
+
+		// Ensure target file's directory exists
+		if err := os.MkdirAll(filepath.Dir(targetPath), 0755); err != nil {
+			return fmt.Errorf("Failed to create directory %s: %w", filepath.Dir(targetPath), err)
+		}
+
+		// Write file
+		if err := os.WriteFile(targetPath, data, 0644); err != nil {
+			return fmt.Errorf("Failed to write file %s: %w", targetPath, err)
+		}
+
+		return nil
+	})
+
+	return err
+}

cmd/picoclaw/internal/skills/command.go

@@ -0,0 +1,53 @@
+package skills
+
+import (
+	"fmt"
+	"path/filepath"
+
+	internal2 "github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/spf13/cobra"
+)
+
+func NewSkillsCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "skills",
+		Short: "Manage skills (install, list, remove)",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+	}
+
+	var loaded bool
+
+	cmd.PersistentPreRunE = func(cmd *cobra.Command, _ []string) error {
+		cfg, err := internal2.LoadConfig()
+		if err != nil {
+			return fmt.Errorf("error loading config: %w", err)
+		}
+
+		workspace := cfg.WorkspacePath()
+		installer := skills.NewSkillInstaller(workspace)
+
+		globalDir := filepath.Dir(internal2.GetConfigPath())
+		globalSkillsDir := filepath.Join(globalDir, "skills")
+		builtinSkillsDir := filepath.Join(globalDir, "picoclaw", "skills")
+		skillsLoader := skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir)
+
+		if !loaded {
+			cmd.AddCommand(
+				newListCommand(skillsLoader),
+				newInstallCommand(installer),
+				newInstallBuiltinCommand(workspace),
+				newListBuiltinCommand(),
+				newRemoveCommand(installer),
+				newSearchCommand(installer),
+				newShowCommand(skillsLoader),
+			)
+			loaded = true
+		}
+		return nil
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/helpers.go

@@ -0,0 +1,224 @@
+package skills
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func skillsListCmd(loader *skills.SkillsLoader) {
+	allSkills := loader.ListSkills()
+
+	if len(allSkills) == 0 {
+		fmt.Println("No skills installed.")
+		return
+	}
+
+	fmt.Println("\nInstalled Skills:")
+	fmt.Println("------------------")
+	for _, skill := range allSkills {
+		fmt.Printf("  ✓ %s (%s)\n", skill.Name, skill.Source)
+		if skill.Description != "" {
+			fmt.Printf("    %s\n", skill.Description)
+		}
+	}
+}
+
+func skillsInstallCmd(installer *skills.SkillInstaller, repo string) {
+	fmt.Printf("Installing skill from %s...\n", repo)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	if err := installer.InstallFromGitHub(ctx, repo); err != nil {
+		fmt.Printf("✗ Failed to install skill: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("✓ Skill '%s' installed successfully!\n", filepath.Base(repo))
+}
+
+func skillsRemoveCmd(installer *skills.SkillInstaller, skillName string) {
+	fmt.Printf("Removing skill '%s'...\n", skillName)
+
+	if err := installer.Uninstall(skillName); err != nil {
+		fmt.Printf("✗ Failed to remove skill: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("✓ Skill '%s' removed successfully!\n", skillName)
+}
+
+func skillsInstallBuiltinCmd(workspace string) {
+	builtinSkillsDir := "./picoclaw/skills"
+	workspaceSkillsDir := filepath.Join(workspace, "skills")
+
+	fmt.Printf("Copying builtin skills to workspace...\n")
+
+	skillsToInstall := []string{
+		"weather",
+		"news",
+		"stock",
+		"calculator",
+	}
+
+	for _, skillName := range skillsToInstall {
+		builtinPath := filepath.Join(builtinSkillsDir, skillName)
+		workspacePath := filepath.Join(workspaceSkillsDir, skillName)
+
+		if _, err := os.Stat(builtinPath); err != nil {
+			fmt.Printf("⊘ Builtin skill '%s' not found: %v\n", skillName, err)
+			continue
+		}
+
+		if err := os.MkdirAll(workspacePath, 0755); err != nil {
+			fmt.Printf("✗ Failed to create directory for %s: %v\n", skillName, err)
+			continue
+		}
+
+		if err := copyDirectory(builtinPath, workspacePath); err != nil {
+			fmt.Printf("✗ Failed to copy %s: %v\n", skillName, err)
+		}
+	}
+
+	fmt.Println("\n✓ All builtin skills installed!")
+	fmt.Println("Now you can use them in your workspace.")
+}
+
+func skillsListBuiltinCmd() {
+	cfg, err := internal.LoadConfig()
+	if err != nil {
+		fmt.Printf("Error loading config: %v\n", err)
+		return
+	}
+	builtinSkillsDir := filepath.Join(filepath.Dir(cfg.WorkspacePath()), "picoclaw", "skills")
+
+	fmt.Println("\nAvailable Builtin Skills:")
+	fmt.Println("-----------------------")
+
+	entries, err := os.ReadDir(builtinSkillsDir)
+	if err != nil {
+		fmt.Printf("Error reading builtin skills: %v\n", err)
+		return
+	}
+
+	if len(entries) == 0 {
+		fmt.Println("No builtin skills available.")
+		return
+	}
+
+	for _, entry := range entries {
+		if entry.IsDir() {
+			skillName := entry.Name()
+			skillFile := filepath.Join(builtinSkillsDir, skillName, "SKILL.md")
+
+			description := "No description"
+			if _, err := os.Stat(skillFile); err == nil {
+				data, err := os.ReadFile(skillFile)
+				if err == nil {
+					content := string(data)
+					if idx := strings.Index(content, "\n"); idx > 0 {
+						firstLine := content[:idx]
+						if strings.Contains(firstLine, "description:") {
+							descLine := strings.Index(content[idx:], "\n")
+							if descLine > 0 {
+								description = strings.TrimSpace(content[idx+descLine : idx+descLine])
+							}
+						}
+					}
+				}
+			}
+			status := "✓"
+			fmt.Printf("  %s  %s\n", status, entry.Name())
+			if description != "" {
+				fmt.Printf("     %s\n", description)
+			}
+		}
+	}
+}
+
+func skillsSearchCmd(installer *skills.SkillInstaller) {
+	fmt.Println("Searching for available skills...")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	availableSkills, err := installer.ListAvailableSkills(ctx)
+	if err != nil {
+		fmt.Printf("✗ Failed to fetch skills list: %v\n", err)
+		return
+	}
+
+	if len(availableSkills) == 0 {
+		fmt.Println("No skills available.")
+		return
+	}
+
+	fmt.Printf("\nAvailable Skills (%d):\n", len(availableSkills))
+	fmt.Println("--------------------")
+	for _, skill := range availableSkills {
+		fmt.Printf("  📦 %s\n", skill.Name)
+		fmt.Printf("     %s\n", skill.Description)
+		fmt.Printf("     Repo: %s\n", skill.Repository)
+		if skill.Author != "" {
+			fmt.Printf("     Author: %s\n", skill.Author)
+		}
+		if len(skill.Tags) > 0 {
+			fmt.Printf("     Tags: %v\n", skill.Tags)
+		}
+		fmt.Println()
+	}
+}
+
+func skillsShowCmd(loader *skills.SkillsLoader, skillName string) {
+	content, ok := loader.LoadSkill(skillName)
+	if !ok {
+		fmt.Printf("✗ Skill '%s' not found\n", skillName)
+		return
+	}
+
+	fmt.Printf("\n📦 Skill: %s\n", skillName)
+	fmt.Println("----------------------")
+	fmt.Println(content)
+}
+
+func copyDirectory(src, dst string) error {
+	return filepath.Walk(src, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		relPath, err := filepath.Rel(src, path)
+		if err != nil {
+			return err
+		}
+
+		dstPath := filepath.Join(dst, relPath)
+
+		if info.IsDir() {
+			return os.MkdirAll(dstPath, info.Mode())
+		}
+
+		srcFile, err := os.Open(path)
+		if err != nil {
+			return err
+		}
+		defer srcFile.Close()
+
+		dstFile, err := os.OpenFile(dstPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
+		if err != nil {
+			return err
+		}
+		defer dstFile.Close()
+
+		_, err = io.Copy(dstFile, srcFile)
+		return err
+	})
+}

cmd/picoclaw/internal/skills/install.go

@@ -0,0 +1,20 @@
+package skills
+
+import (
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/spf13/cobra"
+)
+
+func newInstallCommand(installer *skills.SkillInstaller) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "install",
+		Short:   "Install skill from GitHub",
+		Example: `picoclaw skills install sipeed/picoclaw-skills/weather`,
+		Args:    cobra.ExactArgs(1),
+		Run: func(_ *cobra.Command, args []string) {
+			skillsInstallCmd(installer, args[0])
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/installbuiltin.go

@@ -0,0 +1,16 @@
+package skills
+
+import "github.com/spf13/cobra"
+
+func newInstallBuiltinCommand(workspace string) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "install-builtin",
+		Short:   "Install all builtin skills to workspace",
+		Example: `picoclaw skills install-builtin`,
+		Run: func(_ *cobra.Command, _ []string) {
+			skillsInstallBuiltinCmd(workspace)
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/list.go

@@ -0,0 +1,19 @@
+package skills
+
+import (
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/spf13/cobra"
+)
+
+func newListCommand(skillsLoader *skills.SkillsLoader) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "list",
+		Short:   "List installed skills",
+		Example: `picoclaw skills list`,
+		Run: func(_ *cobra.Command, _ []string) {
+			skillsListCmd(skillsLoader)
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/listbuiltin.go

@@ -0,0 +1,16 @@
+package skills
+
+import "github.com/spf13/cobra"
+
+func newListBuiltinCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "list-builtin",
+		Short:   "List available builtin skills",
+		Example: `picoclaw skills list-builtin`,
+		Run: func(_ *cobra.Command, _ []string) {
+			skillsListBuiltinCmd()
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/remove.go

@@ -0,0 +1,21 @@
+package skills
+
+import (
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/spf13/cobra"
+)
+
+func newRemoveCommand(installer *skills.SkillInstaller) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "remove",
+		Aliases: []string{"rm", "uninstall"},
+		Short:   "Remove installed skill",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw skills remove weather`,
+		Run: func(_ *cobra.Command, args []string) {
+			skillsRemoveCmd(installer, args[0])
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/search.go

@@ -0,0 +1,18 @@
+package skills
+
+import (
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/spf13/cobra"
+)
+
+func newSearchCommand(installer *skills.SkillInstaller) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "search",
+		Short: "Search available skills",
+		Run: func(_ *cobra.Command, _ []string) {
+			skillsSearchCmd(installer)
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/show.go

@@ -0,0 +1,20 @@
+package skills
+
+import (
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/spf13/cobra"
+)
+
+func newShowCommand(skillsLoader *skills.SkillsLoader) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "show",
+		Short:   "Show skill details",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw skills show weather`,
+		Run: func(_ *cobra.Command, args []string) {
+			skillsShowCmd(skillsLoader, args[0])
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/status/command.go

@@ -0,0 +1,18 @@
+package status
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewStatusCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "status",
+		Aliases: []string{"s"},
+		Short:   "Show picoclaw status",
+		Run: func(cmd *cobra.Command, args []string) {
+			statusCmd()
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/status/helpers.go

@@ -0,0 +1,84 @@
+package status
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/auth"
+)
+
+func statusCmd() {
+	cfg, err := internal.LoadConfig()
+	if err != nil {
+		fmt.Printf("Error loading config: %v\n", err)
+		return
+	}
+
+	configPath := internal.GetConfigPath()
+
+	fmt.Printf("%s picoclaw Status\n", internal.Logo)
+	fmt.Printf("Version: %s\n", internal.FormatVersion())
+	build, _ := internal.FormatBuildInfo()
+	if build != "" {
+		fmt.Printf("Build: %s\n", build)
+	}
+	fmt.Println()
+
+	if _, err := os.Stat(configPath); err == nil {
+		fmt.Println("Config:", configPath, "✓")
+	} else {
+		fmt.Println("Config:", configPath, "✗")
+	}
+
+	workspace := cfg.WorkspacePath()
+	if _, err := os.Stat(workspace); err == nil {
+		fmt.Println("Workspace:", workspace, "✓")
+	} else {
+		fmt.Println("Workspace:", workspace, "✗")
+	}
+
+	if _, err := os.Stat(configPath); err == nil {
+		fmt.Printf("Model: %s\n", cfg.Agents.Defaults.Model)
+
+		hasOpenRouter := cfg.Providers.OpenRouter.APIKey != ""
+		hasAnthropic := cfg.Providers.Anthropic.APIKey != ""
+		hasOpenAI := cfg.Providers.OpenAI.APIKey != ""
+		hasGemini := cfg.Providers.Gemini.APIKey != ""
+		hasZhipu := cfg.Providers.Zhipu.APIKey != ""
+		hasGroq := cfg.Providers.Groq.APIKey != ""
+		hasVLLM := cfg.Providers.VLLM.APIBase != ""
+
+		status := func(enabled bool) string {
+			if enabled {
+				return "✓"
+			}
+			return "not set"
+		}
+		fmt.Println("OpenRouter API:", status(hasOpenRouter))
+		fmt.Println("Anthropic API:", status(hasAnthropic))
+		fmt.Println("OpenAI API:", status(hasOpenAI))
+		fmt.Println("Gemini API:", status(hasGemini))
+		fmt.Println("Zhipu API:", status(hasZhipu))
+		fmt.Println("Groq API:", status(hasGroq))
+		if hasVLLM {
+			fmt.Printf("vLLM/Local: ✓ %s\n", cfg.Providers.VLLM.APIBase)
+		} else {
+			fmt.Println("vLLM/Local: not set")
+		}
+
+		store, _ := auth.LoadStore()
+		if store != nil && len(store.Credentials) > 0 {
+			fmt.Println("\nOAuth/Token Auth:")
+			for provider, cred := range store.Credentials {
+				status := "authenticated"
+				if cred.IsExpired() {
+					status = "expired"
+				} else if cred.NeedsRefresh() {
+					status = "needs refresh"
+				}
+				fmt.Printf("  %s (%s): %s\n", provider, cred.AuthMethod, status)
+			}
+		}
+	}
+}

cmd/picoclaw/internal/version/command.go

@@ -0,0 +1,32 @@
+package version
+
+import (
+	"fmt"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/spf13/cobra"
+)
+
+func NewVersionCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "version",
+		Aliases: []string{"v"},
+		Short:   "Show version information",
+		Run: func(_ *cobra.Command, _ []string) {
+			printVersion()
+		},
+	}
+
+	return cmd
+}
+
+func printVersion() {
+	fmt.Printf("%s picoclaw %s\n", internal.Logo, internal.FormatVersion())
+	build, goVer := internal.FormatBuildInfo()
+	if build != "" {
+		fmt.Printf("  Build: %s\n", build)
+	}
+	if goVer != "" {
+		fmt.Printf("  Go: %s\n", goVer)
+	}
+}

go.mod

@@ -22,7 +22,10 @@ require (
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/spf13/cobra v1.10.2 // indirect
+	github.com/spf13/pflag v1.0.10 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
 

go.sum

@@ -25,6 +25,7 @@ github.com/chzyer/test v1.0.0 h1:p3BQDXSxOhOG0P9z6/hGnII4LGiEPOYBhs8asl/fC04=
 github.com/chzyer/test v1.0.0/go.mod h1:2JlltgoNkt4TW/z9V/IzDdFaMTM2JPIi26O1pF38GC8=
 github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
 github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
@@ -72,6 +73,8 @@ github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/ad
 github.com/grbit/go-json v0.11.0 h1:bAbyMdYrYl/OjYsSqLH99N2DyQ291mHy726Mx+sYrnc=
 github.com/grbit/go-json v0.11.0/go.mod h1:IYpHsdybQ386+6g3VE6AXQ3uTGa5mquBme5/ZWmtzek=
 github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
 github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
 github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
@@ -108,8 +111,14 @@ github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZN
 github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/slack-go/slack v0.17.3 h1:zV5qO3Q+WJAQ/XwbGfNFrRMaJ5T/naqaonyPV/1TP4g=
 github.com/slack-go/slack v0.17.3/go.mod h1:X+UqOufi3LYQHDnMG1vxf0J8asC6+WllXrVrhl8/Prk=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
+github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
@@ -151,6 +160,7 @@ github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9dec
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
 go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/arch v0.24.0 h1:qlJ3M9upxvFfwRM51tTg3Yl+8CP9vCC1E7vlFpgv99Y=
 golang.org/x/arch v0.24.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=