From e43029bca019e86d25b1c451ae0f0bad515447df Mon Sep 17 00:00:00 2001
From: Sylvia Crowe <software@oneirocosm.com>
Date: Mon, 10 Feb 2025 15:54:09 -0800
Subject: [PATCH] feat: add a wsh launch command

This creates a new command `wsh launch` that will launch a widget that
has been defined in the widgets.json file.
---
 cmd/wsh/cmd/wshcmd-launch.go | 65 ++++++++++++++++++++++++++++++++++++
 docs/docs/wsh-reference.mdx  | 32 ++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 cmd/wsh/cmd/wshcmd-launch.go

diff --git a/cmd/wsh/cmd/wshcmd-launch.go b/cmd/wsh/cmd/wshcmd-launch.go
new file mode 100644
index 000000000..6da60417e
--- /dev/null
+++ b/cmd/wsh/cmd/wshcmd-launch.go
@@ -0,0 +1,65 @@
+// 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 magnifyBlock bool
+
+var launchCmd = &cobra.Command{
+	Use:     "launch",
+	Short:   "launch a widget by its ID",
+	Args:    cobra.ExactArgs(1),
+	RunE:    launchRun,
+	PreRunE: preRunSetupRpcClient,
+}
+
+func init() {
+	launchCmd.Flags().BoolVarP(&magnifyBlock, "magnify", "m", false, "start the widget in magnified mode")
+	rootCmd.AddCommand(launchCmd)
+}
+
+func launchRun(cmd *cobra.Command, args []string) (rtnErr error) {
+	defer func() {
+		sendActivity("launch", rtnErr == nil)
+	}()
+
+	widgetId := args[0]
+
+	// Get the full configuration
+	config, err := wshclient.GetFullConfigCommand(RpcClient, &wshrpc.RpcOpts{Timeout: 2000})
+	if err != nil {
+		return fmt.Errorf("getting configuration: %w", err)
+	}
+
+	// Look for widget in both widgets and defaultwidgets
+	widget, ok := config.Widgets[widgetId]
+	if !ok {
+		widget, ok = config.DefaultWidgets[widgetId]
+		if !ok {
+			return fmt.Errorf("widget %q not found in configuration", widgetId)
+		}
+	}
+
+	// Create block data from widget config
+	createBlockData := wshrpc.CommandCreateBlockData{
+		BlockDef:  &widget.BlockDef,
+		Magnified: magnifyBlock || widget.Magnified,
+	}
+
+	// Create the block
+	oref, err := wshclient.CreateBlockCommand(RpcClient, createBlockData, nil)
+	if err != nil {
+		return fmt.Errorf("creating widget block: %w", err)
+	}
+
+	WriteStdout("launched widget %q: %s\n", widgetId, oref)
+	return nil
+}
diff --git a/docs/docs/wsh-reference.mdx b/docs/docs/wsh-reference.mdx
index 65fd02fb1..49dbd2fa5 100644
--- a/docs/docs/wsh-reference.mdx
+++ b/docs/docs/wsh-reference.mdx
@@ -668,6 +668,38 @@ wsh file ls wavefile://client/ | grep ".json$"
 
 ---
 
+## launch
+
+The `wsh launch` command allows you to open pre-configured widgets directly from your terminal.
+
+```sh
+wsh launch [flags] widget-id
+```
+
+The command will search for the specified widget ID in both user-defined widgets and default widgets, then create a new block using the widget's configuration.
+
+Flags:
+
+- `-m, --magnify` - open the widget in magnified mode, overriding the widget's default magnification setting
+
+Examples:
+
+```sh
+# Launch a widget with its default settings
+wsh launch my-custom-widget
+
+# Launch a widget in magnified mode
+wsh launch -m system-monitor
+```
+
+The widget's configuration determines the initial block settings, including the view type, metadata, and default magnification state. The `-m` flag can be used to override the widget's default magnification setting.
+
+:::tip
+Widget configurations can be customized in your `widgets.json` configuration file, which you can edit using `wsh editconfig widgets.json`
+:::
+
+---
+
 ## getvar/setvar
 
 Wave Terminal provides commands for managing persistent variables at different scopes (block, tab, workspace, or client-wide).