feat: add slack docs search subcommand (#433)

* go

* refactoring

* go

* more test coverage

* refactor

* remove deprecation warning

* go

* test

* resty api

* test: replace docs base url for fake client runner

* feat: output request and response details in verbose

* test: confirm query string keeps capitals

* test: command test cases in a single table

* Apply suggestions from code review

Co-authored-by: Eden Zimbelman <zim@o526.net>

* feedback

* go

* go

* tests

* real docs URL nowgit add .

* moves search stuff into search per request

* error

* wrong docgen

* refactor for test

* coverage

* chore!: remove search flag from docs command (#470)

* woo

* code coverage

* removes custom error

---------

Co-authored-by: Eden Zimbelman <eden.zimbelman@salesforce.com>
Co-authored-by: Eden Zimbelman <zim@o526.net>

Author: lukegalbraithrussell

cmd/docs/docs.go

@@ -15,101 +15,64 @@
 package docs
 
 import (
-	"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"
 )
 
-var searchMode bool
+const docsURL = "https://docs.slack.dev"
 
 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.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runDocsCommand(clients, cmd, args)
+			return runDocsCommand(clients, cmd)
 		},
+		// 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))
+
+	// Catch removed --search flag
+	cmd.Flags().BoolP("search", "", false, "DEPRECATED: use 'docs search' subcommand instead")
 
 	return cmd
 }
 
 // runDocsCommand opens Slack developer docs in the browser
-func runDocsCommand(clients *shared.ClientFactory, cmd *cobra.Command, args []string) error {
+func runDocsCommand(clients *shared.ClientFactory, cmd *cobra.Command) error {
 	ctx := cmd.Context()
 
-	var docsURL string
-	var sectionText string
-
-	// Validate: if there are arguments, --search flag 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),
-		)
-	}
-
-	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)
-			sectionText = "Docs Search"
-		} else {
-			// --search (no argument) - open search page
-			docsURL = "https://docs.slack.dev/search/"
-			sectionText = "Docs Search"
-		}
-	} else {
-		// No search flag: default homepage
-		docsURL = "https://docs.slack.dev"
-		sectionText = "Docs Open"
-	}
-
 	clients.IO.PrintInfo(ctx, false, "\n%s", style.Sectionf(style.TextSection{
 		Emoji: "books",
-		Text:  sectionText,
+		Text:  "Docs Open",
 		Secondary: []string{
 			docsURL,
 		},
 	}))
 
 	clients.Browser().OpenURL(docsURL)
-
-	if cmd.Flags().Changed("search") {
-		traceValue := ""
-		if len(args) > 0 {
-			traceValue = strings.Join(args, " ")
-		}
-		clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, traceValue)
-	} else {
-		clients.IO.PrintTrace(ctx, slacktrace.DocsSuccess)
-	}
+	clients.IO.PrintTrace(ctx, slacktrace.DocsSuccess)
 
 	return nil
 }

cmd/docs/docs_test.go

@@ -27,7 +27,7 @@ import (
 
 func Test_Docs_DocsCommand(t *testing.T) {
 	testutil.TableTestCommand(t, testutil.CommandTests{
-		"opens docs homepage without search": {
+		"opens docs homepage": {
 			Setup: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock, cf *shared.ClientFactory) {
 			},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
@@ -40,93 +40,9 @@ func Test_Docs_DocsCommand(t *testing.T) {
 				"https://docs.slack.dev",
 			},
 		},
-		"fails when positional argument provided without search flag": {
+		"rejects positional arguments": {
 			CmdArgs:              []string{"Block Kit"},
-			ExpectedErrorStrings: []string{"Invalid docs command. Did you mean to search?"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				// No browser calls should be made when command fails
-				cm.Browser.AssertNotCalled(t, "OpenURL")
-			},
-		},
-		"fails when multiple positional arguments provided without search flag": {
-			CmdArgs:              []string{"webhook", "send", "message"},
-			ExpectedErrorStrings: []string{"Invalid docs command. Did you mean to search?"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				// No browser calls should be made when command fails
-				cm.Browser.AssertNotCalled(t, "OpenURL")
-			},
-		},
-		"opens docs with search query using space syntax": {
-			CmdArgs: []string{"--search", "messaging"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/?q=messaging"
-				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
-				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
-			},
-			ExpectedOutputs: []string{
-				"Docs Search",
-				"https://docs.slack.dev/search/?q=messaging",
-			},
-		},
-		"handles search with multiple arguments": {
-			CmdArgs: []string{"--search", "Block", "Kit", "Element"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/?q=Block+Kit+Element"
-				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
-				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
-			},
-			ExpectedOutputs: []string{
-				"Docs Search",
-				"https://docs.slack.dev/search/?q=Block+Kit+Element",
-			},
-		},
-		"handles search query with multiple words": {
-			CmdArgs: []string{"--search", "socket mode"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/?q=socket+mode"
-				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
-				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
-			},
-			ExpectedOutputs: []string{
-				"Docs Search",
-				"https://docs.slack.dev/search/?q=socket+mode",
-			},
-		},
-		"handles special characters in search query": {
-			CmdArgs: []string{"--search", "messages & webhooks"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/?q=messages+%26+webhooks"
-				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
-				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
-			},
-			ExpectedOutputs: []string{
-				"Docs Search",
-				"https://docs.slack.dev/search/?q=messages+%26+webhooks",
-			},
-		},
-		"handles search query with quotes": {
-			CmdArgs: []string{"--search", "webhook \"send message\""},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/?q=webhook+%22send+message%22"
-				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
-				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
-			},
-			ExpectedOutputs: []string{
-				"Docs Search",
-				"https://docs.slack.dev/search/?q=webhook+%22send+message%22",
-			},
-		},
-		"handles search flag without argument": {
-			CmdArgs: []string{"--search"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/"
-				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
-				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
-			},
-			ExpectedOutputs: []string{
-				"Docs Search",
-				"https://docs.slack.dev/search/",
-			},
+			ExpectedErrorStrings: []string{"unknown command"},
 		},
 	}, func(cf *shared.ClientFactory) *cobra.Command {
 		return NewCommand(cf)

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",
+		)
+	}
+}