From bfa709dd8d7030aa7688438e8348d54dc3885623 Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Fri, 20 Nov 2026 10:47:21 +0100 Subject: [PATCH 1/4] fix(root): use the right shorthand in the rules import example The file flag's shorthand is -F. The -f example fails with an unknown shorthand flag error and is copied into the generated docs. --- pkg/cmd/root/root.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/cmd/root/root.go b/pkg/cmd/root/root.go index 8aac09a7..8e7b7cb2 100644 --- a/pkg/cmd/root/root.go +++ b/pkg/cmd/root/root.go @@ -70,7 +70,7 @@ func NewRootCmd(f *cmdutil.Factory) *cobra.Command { $ algolia search MOVIES --query "toy story" $ algolia objects browse MOVIES $ algolia apikeys create --acl search - $ algolia rules import MOVIES -f rules.json + $ algolia rules import MOVIES -F rules.json `), } From 6fa1d8baac14d27c690ec5d6dd38afc4fecff8ae Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Fri, 20 Nov 2026 10:47:21 +0100 Subject: [PATCH 2/4] fix(docs): skip hidden flags and label deprecated ones The generator listed every flag, including hidden ones such as the deprecated --admin-api-key, and showed --profile without its deprecation notice. Skip hidden flags so the docs and describe match --help, and render the deprecation message for visible deprecated flags. The describe output gains a deprecated field. --- internal/docs/docs.go | 10 ++++++++++ internal/docs/mdx.tpl | 4 +++- internal/docs/mdx_test.go | 28 ++++++++++++++++++++++++++++ 3 files changed, 41 insertions(+), 1 deletion(-) diff --git a/internal/docs/docs.go b/internal/docs/docs.go index a743533c..024cfdfa 100644 --- a/internal/docs/docs.go +++ b/internal/docs/docs.go @@ -30,6 +30,9 @@ type Flag struct { Shorthand string `json:"shorthand,omitempty"` Description string `json:"description"` Default string `json:"default"` + // Deprecated holds the deprecation message when the flag is deprecated + // but still visible, such as --profile. + Deprecated string `json:"deprecated,omitempty"` } func newFlag(flag *pflag.Flag) Flag { @@ -38,12 +41,19 @@ func newFlag(flag *pflag.Flag) Flag { Shorthand: flag.Shorthand, Description: strings.TrimSpace(flag.Usage), Default: flag.DefValue, + Deprecated: strings.TrimSpace(flag.Deprecated), } } +// newFlags lists the flags of a flag set, skipping hidden ones so the docs and +// `describe` match what --help shows. MarkDeprecated hides a flag, so a flag +// deprecated that way is skipped too. func newFlags(flagSet *pflag.FlagSet) []Flag { flags := make([]Flag, 0) flagSet.VisitAll(func(flag *pflag.Flag) { + if flag.Hidden { + return + } flags = append(flags, newFlag(flag)) }) return flags diff --git a/internal/docs/mdx.tpl b/internal/docs/mdx.tpl index 9225e49d..28358506 100644 --- a/internal/docs/mdx.tpl +++ b/internal/docs/mdx.tpl @@ -37,7 +37,9 @@ public: true {{ formatAlgoliaDocLinks (trimTrailingNewlines $flag.Description) }} - +{{ if $flag.Deprecated }} +**Deprecated:** {{ $flag.Deprecated }}. +{{ end }} {{ end -}} diff --git a/internal/docs/mdx_test.go b/internal/docs/mdx_test.go index 592c6240..c30a9ed3 100644 --- a/internal/docs/mdx_test.go +++ b/internal/docs/mdx_test.go @@ -73,6 +73,34 @@ func TestGenMdxTreeWritesNestedCommandPages(t *testing.T) { require.Contains(t, listContent, ``) } +func TestGenMdxTreeSkipsHiddenFlagsAndLabelsDeprecatedOnes(t *testing.T) { + root := &cobra.Command{Use: "algolia", Short: "Algolia CLI"} + list := &cobra.Command{ + Use: "list", + Short: "List things", + RunE: func(*cobra.Command, []string) error { + return nil + }, + } + list.Flags().StringP("profile", "p", "", "The profile to use") + list.Flags().Lookup("profile").Deprecated = "use --application-id instead" + list.Flags().String("admin-api-key", "", "The admin API key") + require.NoError(t, list.Flags().MarkDeprecated("admin-api-key", "use --api-key instead")) + list.Flags().String("secret", "", "Internal flag") + require.NoError(t, list.Flags().MarkHidden("secret")) + + root.AddCommand(list) + + dir := t.TempDir() + require.NoError(t, GenMdxTree(root, dir)) + + listContent := readTestFile(t, filepath.Join(dir, "list.mdx")) + require.Contains(t, listContent, ``) + require.Contains(t, listContent, "**Deprecated:** use --application-id instead.") + require.NotContains(t, listContent, "--admin-api-key") + require.NotContains(t, listContent, "--secret") +} + func TestGenMdxTreeSupportsCodeOnlyExamples(t *testing.T) { root := &cobra.Command{ Use: "algolia", From 161955ea8ac7206d13720ea46eb4a9fa0edfcc0f Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Fri, 20 Nov 2026 10:47:21 +0100 Subject: [PATCH 3/4] fix(auth): clarify when to use --no-browser in the login help The help text named SSH sessions and containers as the use case, but the callback server listens on localhost, so the URL must be opened on the same machine. Say that, and point browserless machines to environment variables. --- pkg/cmd/auth/login/login.go | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/pkg/cmd/auth/login/login.go b/pkg/cmd/auth/login/login.go index 6f296616..b3bf2be9 100644 --- a/pkg/cmd/auth/login/login.go +++ b/pkg/cmd/auth/login/login.go @@ -77,9 +77,11 @@ func NewLoginCmd(f *cmdutil.Factory) *cobra.Command { A local HTTP server is started to receive the OAuth redirect automatically - no code copy-paste required. - Use --no-browser if the browser cannot be opened automatically - (e.g. SSH sessions, containers). The URL will be printed for you - to open manually; the CLI still waits for the redirect. + Use --no-browser to print the authorize URL instead of opening the + browser, for example when an agent runs the CLI. Open the URL on + the same machine: the CLI waits for a redirect to localhost. On a + machine without a browser, such as a CI server, set + ALGOLIA_APPLICATION_ID and ALGOLIA_API_KEY instead. Use --non-interactive to sign in without any prompt and print the result as JSON. It signs in only: no application is configured unless From 67951b4fdb6dd794d4186b82cfc224684412b245 Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Fri, 20 Nov 2026 10:47:21 +0100 Subject: [PATCH 4/4] docs(readme): use the Homebrew core formula The algolia formula lives in homebrew/core, so the tap path is no longer needed. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5ecdc733..e262489f 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ npm install -g @algolia/cli The Algolia CLI is available on [Homebrew](https://brew.sh/) and as a downloadable binary from the [releases page](https://github.com/algolia/cli/releases). ```sh -brew install algolia/algolia-cli/algolia +brew install algolia ``` ### Linux