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