feat: add slack docs search subcommand

cmd/docs/docs.go

@@ -32,27 +32,33 @@ func NewCommand(clients *shared.ClientFactory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "docs",
 		Short: "Open Slack developer docs",
-		Long:  "Open the Slack developer docs in your browser, with optional search functionality",
+		Long:  "Open the Slack developer docs in your browser or search them using the search subcommand",
 		Example: style.ExampleCommandsf([]style.ExampleCommand{
 			{
 				Meaning: "Open Slack developer docs homepage",
 				Command: "docs",
 			},
 			{
 				Meaning: "Search Slack developer docs for Block Kit",
-				Command: "docs --search \"Block Kit\"",
+				Command: "docs search \"Block Kit\"",
 			},
 			{
-				Meaning: "Open Slack docs search page",
-				Command: "docs --search",
+				Meaning: "Search docs and open results in browser",
+				Command: "docs search \"Block Kit\" --output=browser",
 			},
 		}),
+		Args: cobra.ArbitraryArgs, // Allow any arguments
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runDocsCommand(clients, cmd, args)
 		},
+		// Disable automatic suggestions for unknown commands
+		DisableSuggestions: true,
 	}
 
-	cmd.Flags().BoolVar(&searchMode, "search", false, "open Slack docs search page or search with query")
+	cmd.Flags().BoolVar(&searchMode, "search", false, "[DEPRECATED] open Slack docs search page or search with query (use 'docs search' subcommand instead)")
+
+	// Add the search subcommand
+	cmd.AddCommand(NewSearchCommand(clients))
 
 	return cmd
 }
@@ -74,6 +80,7 @@ func runDocsCommand(clients *shared.ClientFactory, cmd *cobra.Command, args []st
 	}
 
 	if cmd.Flags().Changed("search") {
+		clients.IO.PrintWarning(ctx, "The `--search` flag is deprecated. Use 'docs search' subcommand instead.")
 		if len(args) > 0 {
 			// --search "query" (space-separated) - join all args as the query
 			query := strings.Join(args, " ")

cmd/docs/search.go

@@ -0,0 +1,136 @@
+// Copyright 2022-2026 Salesforce, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package docs
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+
+	"github.com/slackapi/slack-cli/internal/shared"
+	"github.com/slackapi/slack-cli/internal/slacktrace"
+	"github.com/slackapi/slack-cli/internal/style"
+	"github.com/spf13/cobra"
+)
+
+const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/api/search"
+
+type searchConfig struct {
+	output string
+	limit  int
+}
+
+type DocsSearchResponse struct {
+	TotalResults int                `json:"total_results"`
+	Results      []DocsSearchResult `json:"results"`
+	Limit        int                `json:"limit"`
+}
+
+type DocsSearchResult struct {
+	URL   string `json:"url"`
+	Title string `json:"title"`
+}
+
+func NewSearchCommand(clients *shared.ClientFactory) *cobra.Command {
+	cfg := &searchConfig{}
+
+	cmd := &cobra.Command{
+		Use:   "search <query>",
+		Short: "Search Slack developer docs",
+		Long:  "Search the Slack developer docs and return results in browser or JSON format",
+		Example: style.ExampleCommandsf([]style.ExampleCommand{
+			{
+				Meaning: "Search docs and return JSON results",
+				Command: "docs search \"Block Kit\"",
+			},
+			{
+				Meaning: "Search docs and open results in browser",
+				Command: "docs search \"webhooks\" --output=browser",
+			},
+			{
+				Meaning: "Search docs with limited JSON results",
+				Command: "docs search \"api\" --output=json --limit=5",
+			},
+		}),
+		Args: cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runDocsSearchCommand(clients, cmd, args, cfg, http.DefaultClient)
+		},
+	}
+
+	cmd.Flags().StringVar(&cfg.output, "output", "json", "output format: browser, json")
+	cmd.Flags().IntVar(&cfg.limit, "limit", 20, "maximum number of search results to return (only applies with --output=json)")
+
+	return cmd
+}
+
+func runDocsSearchCommand(clients *shared.ClientFactory, cmd *cobra.Command, args []string, cfg *searchConfig, httpClient *http.Client) error {
+	ctx := cmd.Context()
+
+	query := strings.Join(args, " ")
+
+	if cfg.output == "json" {
+		return fetchAndOutputSearchResults(ctx, clients, query, cfg.limit, httpClient)
+	}
+
+	encodedQuery := url.QueryEscape(query)
+	docsURL := fmt.Sprintf("https://docs.slack.dev/search/?q=%s", encodedQuery)
+
+	clients.IO.PrintInfo(ctx, false, "\n%s", style.Sectionf(style.TextSection{
+		Emoji: "books",
+		Text:  "Docs Search",
+		Secondary: []string{
+			docsURL,
+		},
+	}))
+
+	clients.Browser().OpenURL(docsURL)
+	clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, query)
+
+	return nil
+}
+
+func fetchAndOutputSearchResults(ctx context.Context, clients *shared.ClientFactory, query string, limit int, httpClient *http.Client) error {
+	apiURL := fmt.Sprintf("%s?q=%s&limit=%d", docsSearchAPIURL, url.QueryEscape(query), limit)
+
+	resp, err := httpClient.Get(apiURL)
+	if err != nil {
+		return fmt.Errorf("failed to fetch search results: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("API returned status %d", resp.StatusCode)
+	}
+
+	var searchResponse DocsSearchResponse
+	if err := json.NewDecoder(resp.Body).Decode(&searchResponse); err != nil {
+		return fmt.Errorf("failed to parse search results: %w", err)
+	}
+
+	encoder := json.NewEncoder(os.Stdout)
+	encoder.SetIndent("", "  ")
+	if err := encoder.Encode(searchResponse); err != nil {
+		return fmt.Errorf("failed to output search results: %w", err)
+	}
+
+	clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, query)
+
+	return nil
+}