feat: add slack docs search subcommand

cmd/docs/docs.go

@@ -16,7 +16,6 @@ package docs
 
 import (
 	"fmt"
-	"net/url"
 	"strings"
 
 	"github.com/slackapi/slack-cli/internal/shared"
@@ -26,80 +25,89 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const docsURL = "https://docs.slack.dev"
+
 var searchMode bool
 
 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")
 
+	// Add the search subcommand
+	cmd.AddCommand(NewSearchCommand(clients))
+
 	return cmd
 }
 
 // runDocsCommand opens Slack developer docs in the browser
 func runDocsCommand(clients *shared.ClientFactory, cmd *cobra.Command, args []string) error {
 	ctx := cmd.Context()
 
-	var docsURL string
+	var finalURL string
 	var sectionText string
 
-	// Validate: if there are arguments, --search flag must be used
+	// Validate: if there are arguments, search subcommand must be used
 	if len(args) > 0 && !cmd.Flags().Changed("search") {
 		query := strings.Join(args, " ")
-		return slackerror.New(slackerror.ErrDocsSearchFlagRequired).WithRemediation(
-			"Use --search flag: %s",
-			style.Commandf(fmt.Sprintf("docs --search \"%s\"", query), false),
+		return slackerror.New(slackerror.ErrDocsSearchFlagRequired).WithMessage(
+			"Invalid docs command. Did you mean to search?",
+		).WithRemediation(
+			"Use search subcommand: %s",
+			style.Commandf(fmt.Sprintf("docs search \"%s\"", query), false),
 		)
 	}
 
 	if cmd.Flags().Changed("search") {
 		if len(args) > 0 {
 			// --search "query" (space-separated) - join all args as the query
 			query := strings.Join(args, " ")
-			encodedQuery := url.QueryEscape(query)
-			docsURL = fmt.Sprintf("https://docs.slack.dev/search/?q=%s", encodedQuery)
+			finalURL = buildDocsSearchURL(query)
 			sectionText = "Docs Search"
 		} else {
 			// --search (no argument) - open search page
-			docsURL = "https://docs.slack.dev/search/"
+			finalURL = fmt.Sprintf("%s/search/", docsURL)
 			sectionText = "Docs Search"
 		}
 	} else {
 		// No search flag: default homepage
-		docsURL = "https://docs.slack.dev"
+		finalURL = docsURL
 		sectionText = "Docs Open"
 	}
 
 	clients.IO.PrintInfo(ctx, false, "\n%s", style.Sectionf(style.TextSection{
 		Emoji: "books",
 		Text:  sectionText,
 		Secondary: []string{
-			docsURL,
+			finalURL,
 		},
 	}))
 
-	clients.Browser().OpenURL(docsURL)
+	clients.Browser().OpenURL(finalURL)
 
 	if cmd.Flags().Changed("search") {
 		traceValue := ""

cmd/docs/search.go

@@ -0,0 +1,168 @@
+// 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 (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"strings"
+
+	"github.com/slackapi/slack-cli/internal/shared"
+	"github.com/slackapi/slack-cli/internal/slackerror"
+	"github.com/slackapi/slack-cli/internal/slacktrace"
+	"github.com/slackapi/slack-cli/internal/style"
+	"github.com/spf13/cobra"
+)
+
+func buildDocsSearchURL(query string) string {
+	encodedQuery := url.QueryEscape(query)
+	return fmt.Sprintf("%s/search/?q=%s", docsURL, encodedQuery)
+}
+
+type searchConfig struct {
+	output string
+	limit  int
+}
+
+func makeAbsoluteURL(relativeURL string) string {
+	if strings.HasPrefix(relativeURL, "http") {
+		return relativeURL
+	}
+	return docsURL + relativeURL
+}
+
+func NewSearchCommand(clients *shared.ClientFactory) *cobra.Command {
+	cfg := &searchConfig{}
+
+	cmd := &cobra.Command{
+		Use:   "search [query]",
+		Short: "Search Slack developer docs",
+		Long: strings.Join([]string{
+			"Search the Slack developer docs and return results in text, JSON, or browser",
+			"format.",
+		}, "\n"),
+		Example: style.ExampleCommandsf([]style.ExampleCommand{
+			{
+				Meaning: "Search docs and return text 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)
+		},
+	}
+
+	cmd.Flags().StringVar(&cfg.output, "output", "text", "output format: text, json, browser")
+	cmd.Flags().IntVar(&cfg.limit, "limit", 20, "maximum number of text or json search results to return")
+
+	return cmd
+}
+
+func runDocsSearchCommand(clients *shared.ClientFactory, cmd *cobra.Command, args []string, cfg *searchConfig) error {
+	ctx := cmd.Context()
+
+	query := strings.Join(args, " ")
+
+	switch cfg.output {
+	case "json":
+		searchResponse, err := clients.API().DocsSearch(ctx, query, cfg.limit)
+		if err != nil {
+			return err
+		}
+
+		for i := range searchResponse.Results {
+			searchResponse.Results[i].URL = makeAbsoluteURL(searchResponse.Results[i].URL)
+		}
+
+		encoder := json.NewEncoder(clients.IO.WriteOut())
+		encoder.SetIndent("", "  ")
+		if err := encoder.Encode(searchResponse); err != nil {
+			return slackerror.New(slackerror.ErrUnableToParseJSON).WithRootCause(err)
+		}
+
+		clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, query)
+
+		return nil
+	case "text":
+		searchResponse, err := clients.API().DocsSearch(ctx, query, cfg.limit)
+		if err != nil {
+			return err
+		}
+
+		if len(searchResponse.Results) == 0 {
+			clients.IO.PrintInfo(ctx, false, "\n%s", style.Sectionf(style.TextSection{
+				Emoji: "books",
+				Text:  "Docs Search",
+				Secondary: []string{
+					fmt.Sprintf("Found zero results for \"%s\"", query),
+				},
+			}))
+			clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, query)
+			return nil
+		}
+
+		clients.IO.PrintInfo(ctx, false, "\n%s", style.Sectionf(style.TextSection{
+			Emoji: "books",
+			Text:  "Docs Search",
+			Secondary: []string{
+				fmt.Sprintf("Displaying first %d of %d results for \"%s\"", len(searchResponse.Results), searchResponse.TotalResults, query),
+			},
+		}))
+
+		for _, result := range searchResponse.Results {
+			absoluteURL := makeAbsoluteURL(result.URL)
+			clients.IO.PrintInfo(ctx, false, "%s", style.Sectionf(style.TextSection{
+				Emoji:     "book",
+				Text:      result.Title,
+				Secondary: []string{absoluteURL},
+			}))
+		}
+
+		clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, query)
+
+		return nil
+	case "browser":
+		docsSearchURL := buildDocsSearchURL(query)
+
+		clients.IO.PrintInfo(ctx, false, "\n%s", style.Sectionf(style.TextSection{
+			Emoji: "books",
+			Text:  "Docs Search",
+			Secondary: []string{
+				docsSearchURL,
+			},
+		}))
+
+		clients.Browser().OpenURL(docsSearchURL)
+		clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, query)
+
+		return nil
+	default:
+		return slackerror.New(slackerror.ErrInvalidFlag).WithMessage(
+			"Invalid output format: %s", cfg.output,
+		).WithRemediation(
+			"Use one of: text, json, browser",
+		)
+	}
+}