feat: add slack docs search subcommand by lukegalbraithrussell · Pull Request #433 · slackapi/slack-cli

lukegalbraithrussell · 2026-03-24T01:43:39Z

Changelog

Adds slack docs search subcommand. It can output search results as JSON

Summary

slack docs search

Option	Type	Default	Description	Required
`<query>`	string		Search terms	Required
`--output`	string	`text`	Output format: `text' , 'browser` or `json`	Optional
`--limit`	int	`20`	Max number of results to return (JSON and text output only)	Optional

Examples

# Search and return JSON results
$ slack-cli docs search "Block Kit"

# Search and return JSON results with custom result limit
$ slack-cli docs search "api" --limit=5

# Search and open results in browser
$ slack-cli docs search "webhooks" --output=browser

Code coverage notes

The following lines in search.go have incomplete test coverage. They seemed cumbersome to cover.
(Summarized by Claude)

Lines 88-89 (if cfg.output == "json" branch): Conditional routing logic that's difficult to test through the command framework. The actual JSON output logic is thoroughly tested via direct function calls.
Lines 129-130 (JSON encoding error handling): Defensive error handling for an unrealistic scenario (broken pipe when piping output). Most CLI tools don't explicitly handle this edge case.

Requirements

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

codecov · 2026-03-24T01:47:06Z

Codecov Report

❌ Patch coverage is 89.47368% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.11%. Comparing base (15e0c40) to head (d815e69).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/docs/search.go	92.00%	3 Missing and 3 partials ⚠️
internal/api/docs.go	75.00%	3 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #433      +/-   ##
==========================================
+ Coverage   70.42%   71.11%   +0.68%     
==========================================
  Files         221      222       +1     
  Lines       18539    18569      +30     
==========================================
+ Hits        13057    13205     +148     
+ Misses       4307     4183     -124     
- Partials     1175     1181       +6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

lukegalbraithrussell · 2026-03-24T17:18:17Z

cmd/docs/search.go

+	"github.com/spf13/cobra"
+)
+
+const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/api/search"


This will be updated to docs.slack.dev once api endpoint PR is merged in private docs repo

Suggested change

const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/api/search"

const docsURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/"

🪬 suggestion: We might want to abstract this to the docs/docs.go file since we target it in multiple places? It might be useful for testing changes too?

🔬 note: Thanks for also including these as now separate variables:

slack-cli/cmd/docs/docs.go

Line 29 in 671b4c8

const docsURL = "https://docs.slack.dev"

slack-cli/internal/api/docs.go

Line 27 in 671b4c8

const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com"

srtaalej

left some comments about terminal ouput and tests but these changes are looking really good ⭐ ! lets get those addressed so we can merge 😝

srtaalej · 2026-03-25T02:55:47Z

cmd/docs/search.go

+	return nil
+}
+
+func fetchAndOutputSearchResults(ctx context.Context, clients *shared.ClientFactory, query string, limit int, httpClient *http.Client) error {


it'd be nice if URLs were full https://docs.slack.dev URLs so they're cmd+clickable in the terminal

{ "url": "https://docs.slack.dev/block-kit/", "title": "Block Kit" },

right now the json outputs as

{ "url": "/block-kit/", "title": "Block Kit" },

📚 thought: I agree listing entire links is ideal and might suggest we add a text format with this?

$ slack docs search "Block Kit" --output=text

👾 ramble: If this format is supported it seems awkward to write that flag instead of defaulting to it but this is personal preference I think!

cmd/docs/search_test.go

zimeg

@lukegalbraithrussell This is an awesome feature to be bringing 📚 ✨

I'm leaving a handful of comments that do request changes, but I'm hoping we can work through these:

The API method logic is included with command: I understand we reach a different host but we might still find api package useful.
Defaulting outputs for the person reading: I'm a fan of JSON but find this jarring when hoping for a quick search in terminal. I instead suggest a default text output to use section formatting:

$ slack docs search "Block Kit"

Deprecating the "--search" flag: Can we make this a separate PR? Adding JSON outputs might be blocking this PR from merging now, but I think those changes have a faster review 🏁
Standardizing the docs.slack.dev API client: We're starting to find the same URL in multiple places and I'm hoping changes toward a standard place for this has good pattern?
Erroring for unexpected inputs: One comment also notes that we should error instead of opening browsers for unexpected output types 👻

Please do let me know if I can share more toward these changes. I'd love to see this land 💌

zimeg · 2026-03-25T22:11:54Z

cmd/docs/docs.go

 	}

-	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)")


Suggested change

cmd.Flags().BoolVar(&searchMode, "search", false, "[DEPRECATED] open Slack docs search page or search with query (use 'docs search' subcommand instead)")

// DEPRECATED(semver:major): Remove in favor of "search" command

cmd.Flags().BoolVar(&searchMode, "search", false, "open Slack docs search page or search with query")

cmd.Flag("search").Hidden = true

🔭 suggestion: Let's prefer to hide deprecated features!

🪓 note: We might now consider breaking this for the next update. I'm starting to think removing these fallbacks can be alright in this PR? @lukegalbraithrussell

zimeg · 2026-03-25T22:21:56Z

cmd/docs/search.go

+	return nil
+}
+
+func fetchAndOutputSearchResults(ctx context.Context, clients *shared.ClientFactory, query string, limit int, httpClient *http.Client) error {


📚 thought: I agree listing entire links is ideal and might suggest we add a text format with this?

$ slack docs search "Block Kit" --output=text

👾 ramble: If this format is supported it seems awkward to write that flag instead of defaulting to it but this is personal preference I think!

cmd/docs/search.go

zimeg · 2026-03-25T22:34:28Z

cmd/docs/search.go

+	"github.com/spf13/cobra"
+)
+
+const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/api/search"


Suggested change

const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/api/search"

const docsURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/"

🪬 suggestion: We might want to abstract this to the docs/docs.go file since we target it in multiple places? It might be useful for testing changes too?

cmd/docs/search.go

zimeg

@lukegalbraithrussell I'm fascinated with the first test I ran... Amazing! 📚 ✨

$ slack docs search chat.postmessage
chat.postMessage method
https://docs.slack.dev/reference/methods/chat.postMessage/

Here are some new thoughts I have since review:

Breaking search: We might be alright to avoid fallbacks for the "--search" flag with upcoming releases happening soon? I understand our releases are not too predictable at this time and I apologize for the thrash on this.
No results found: When I search for more obtuse terms I find no output appears! This is confusing to me when I'd at least like to know nothing was found but perhaps personal preference 📚
Section formats: The text format is amazing to read. An example similar of the samples command shows how we might want these outputs to appear more perhaps before landing this?

I also made a handful of changes during review to find patterns we're moving toward in the api package and tests. I hope pushing these direct was alright since I found words were failing me...

All testing is working superb for me too so I'm marking this as approved with confidence 🤓 The comments remaining are suggestions toward polished experience and maintenance ongoing.

Super nice work on bringing this to life! 🏆

zimeg · 2026-04-02T00:09:56Z

cmd/docs/docs.go

+func buildDocsSearchURL(query string) string {
+	encodedQuery := url.QueryEscape(query)
+	return fmt.Sprintf("%s/search/?q=%s", docsURL, encodedQuery)
+}


🎁 suggestion(non-blocking): I understand this is shared between this file and search.go but perhaps it'd be alright to move to the search file?

👾 ramble: If we do decide to remove the "--search" flag let's also perhaps inline this!

🔬 note: With these changes let's update remediation for an invalid docs command to suggest the "search" command also:

$ slack docs apps 🚫 Invalid docs command. Did you mean to search? (docs_search_flag_required) 💡 Suggestion Use --search flag: slack docs --search "apps"

zimeg · 2026-04-02T00:11:15Z

cmd/docs/docs.go

 	"github.com/spf13/cobra"
 )

+const docsURL = "https://docs.slack.dev"


🔗 praise: This is a nice constant to share I'll claim! Global variables sometimes can give me stress...

cmd/docs/search.go

zimeg · 2026-04-02T00:18:59Z

cmd/docs/search.go

+	"github.com/spf13/cobra"
+)
+
+const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/api/search"


🔬 note: Thanks for also including these as now separate variables:

slack-cli/cmd/docs/docs.go

Line 29 in 671b4c8

const docsURL = "https://docs.slack.dev"

slack-cli/internal/api/docs.go

Line 27 in 671b4c8

const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com"

zimeg · 2026-04-02T00:22:48Z

cmd/docs/docs.go

 	}

-	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)")


🪓 note: We might now consider breaking this for the next update. I'm starting to think removing these fallbacks can be alright in this PR? @lukegalbraithrussell

cmd/docs/search.go

zimeg · 2026-04-02T01:46:44Z

cmd/docs/search.go

+	case "json":
+		return fetchAndOutputSearchResults(ctx, clients, query, cfg.limit)
+	case "text":
+		return fetchAndOutputTextResults(ctx, clients, query, cfg.limit)


🪩 quibble: I'd support inlining these functions to avoid jumping around the page but not a blocker!

cmd/docs/search.go

zimeg

👾 One note more after continued testing. This is a nice development build to use!

zimeg · 2026-04-02T02:21:09Z

cmd/docs/search.go

+				Command: "docs search \"api\" --output=json --limit=5",
+			},
+		}),
+		Args: cobra.MinimumNArgs(1),


Suggested change

Args: cobra.MinimumNArgs(1),

Args: cobra.MinimumNArgs(0),

👾 issue: We might want to default to opening the browser if no arguments are provided?

zimeg

🙀 note: Another thought on dog food!

cmd/docs/search.go

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

go

f248043

lukegalbraithrussell changed the title go Feat: Adds slack docs search subcommand Mar 24, 2026

lukegalbraithrussell and others added 4 commits March 24, 2026 09:38

refactoring

94c8a90

go

d7bbb84

more test coverage

727d7ce

Merge branch 'main' into docs-search-subcommand

e1b0d80

lukegalbraithrussell commented Mar 24, 2026

View reviewed changes

lukegalbraithrussell marked this pull request as ready for review March 24, 2026 17:25

lukegalbraithrussell requested a review from a team as a code owner March 24, 2026 17:25

srtaalej reviewed Mar 25, 2026

View reviewed changes

srtaalej added docs M-T: Documentation work only enhancement M-T: A feature request for new functionality semver:minor Use on pull requests to describe the release version increment labels Mar 25, 2026

srtaalej assigned lukegalbraithrussell Mar 25, 2026

zimeg changed the title ~~Feat: Adds slack docs search subcommand~~ feat: add slack docs search subcommand Mar 25, 2026

zimeg requested changes Mar 25, 2026

View reviewed changes

lukegalbraithrussell and others added 7 commits March 26, 2026 14:37

refactor

4985713

remove deprecation warning

91b5ac5

go

086b9e5

Merge branch 'main' into docs-search-subcommand

2bf8133

test

47613d0

resty api

5650feb

Merge branch 'main' into docs-search-subcommand

671b4c8

zimeg self-requested a review April 2, 2026 00:17

zimeg added this to the Next Release milestone Apr 2, 2026

zimeg added 4 commits April 1, 2026 18:23

test: replace docs base url for fake client runner

0baf948

feat: output request and response details in verbose

6c6875e

test: confirm query string keeps capitals

3317e11

test: command test cases in a single table

d815e69

zimeg approved these changes Apr 2, 2026

View reviewed changes

zimeg reviewed Apr 2, 2026

View reviewed changes

cmd/docs/search.go Outdated Show resolved Hide resolved

lukegalbraithrussell and others added 4 commits April 2, 2026 08:56

Apply suggestions from code review

1bb0949

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

feedback

2fdee9b

go

8fd1999

go

962d75d

	const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/api/search"
	const docsURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/"

Conversation

lukegalbraithrussell commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

Summary

Examples

Code coverage notes

Requirements

Uh oh!

codecov bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

srtaalej left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zimeg left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

lukegalbraithrussell commented Mar 24, 2026 •

edited

Loading

codecov bot commented Mar 24, 2026 •

edited

Loading

zimeg left a comment •

edited

Loading