add-wshcmd

Adding a New wsh Command to Wave Terminal

This guide explains how to add a new command to the wsh CLI tool.

wsh Command System Overview

Wave Terminal's wsh command provides CLI access to Wave Terminal features. The system uses:

1. Cobra Framework - CLI command structure and parsing
2. Command Files - Individual command implementations in cmd/wsh/cmd/wshcmd-*.go
3. RPC Client - Communication with Wave Terminal backend via RpcClient
4. Activity Tracking - Telemetry for command usage analytics
5. Documentation - User-facing docs in docs/docs/wsh-reference.mdx

Commands are registered in their init() functions and execute through the Cobra framework.

Step-by-Step Guide

Step 1: Create Command File

Create a new file in cmd/wsh/cmd/ named wshcmd-[commandname].go:

// Copyright 2025, Command Line Inc.
// SPDX-License-Identifier: Apache-2.0

package cmd

import (
    "fmt"

    "github.com/spf13/cobra"
    "github.com/wavetermdev/waveterm/pkg/wshrpc"
    "github.com/wavetermdev/waveterm/pkg/wshrpc/wshclient"
)

var myCommandCmd = &cobra.Command{
    Use:   "mycommand [args]",
    Short: "Brief description of what this command does",
    Long: `Detailed description of the command.
Can include multiple lines and examples of usage.`,
    RunE:                  myCommandRun,
    PreRunE:               preRunSetupRpcClient,  // Include if command needs RPC
    DisableFlagsInUseLine: true,
}

// Flag variables
var (
    myCommandFlagExample string
    myCommandFlagVerbose bool
)

func init() {
    // Add command to root
    rootCmd.AddCommand(myCommandCmd)
    
    // Define flags
    myCommandCmd.Flags().StringVarP(&myCommandFlagExample, "example", "e", "", "example flag description")
    myCommandCmd.Flags().BoolVarP(&myCommandFlagVerbose, "verbose", "v", false, "enable verbose output")
}

func myCommandRun(cmd *cobra.Command, args []string) (rtnErr error) {
    // Always track activity for telemetry
    defer func() {
        sendActivity("mycommand", rtnErr == nil)
    }()
    
    // Validate arguments
    if len(args) == 0 {
        OutputHelpMessage(cmd)
        return fmt.Errorf("requires at least one argument")
    }
    
    // Command implementation
    fmt.Printf("Command executed successfully\n")
    return nil
}