fix: Editorial changes to the CLI docs

.gitignore

@@ -16,4 +16,7 @@
 vendor/
 
 # local build
-algolia
+algolia
+
+# Ignore docs directory
+docs/

Makefile

@@ -14,7 +14,7 @@ VARIATION ?= old
 ifeq ($(VARIATION),old)
 DOCS_FOLDER = docs
 DOCS_GENERATED_PATH = app_data/cli/commands
-DOCS_REPO_URL = https://github.com/algolia/doc.git
+DOCS_REPO_URL = git@github.com:algolia/doc.git
 DOCS_BRANCH = master
 DOCS_EXTENSION = yml
 else ifeq ($(VARIATION),new)

pkg/cmd/apikeys/create/create.go

@@ -61,42 +61,41 @@ func NewCreateCmd(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co
 	}
 
 	cmd.Flags().StringSliceVar(&opts.ACL, "acl", nil, heredoc.Docf(`
-		ACL of the API Key.
-
-			%[1]ssearch%[1]s: allowed to perform search operations.
-			%[1]sbrowse%[1]s: allowed to retrieve all index data with the browse endpoint.
-			%[1]saddObject%[1]s: allowed to add or update a records in the index.
-			%[1]sdeleteObject%[1]s: allowed to delete an existing record.
-			%[1]slistIndexes%[1]s: allowed to get a list of all existing indices.
-			%[1]sdeleteIndex%[1]s: allowed to delete an index.
-			%[1]ssettings%[1]s: allowed to read all index settings.
-			%[1]seditSettings%[1]s: allowed to update all index settings.
-			%[1]sanalytics%[1]s: allowed to retrieve data with the Analytics API.
-			%[1]srecommendation%[1]s: allowed to interact with the Recommendation API.
-			%[1]susage%[1]s: allowed to retrieve data with the Usage API.
-			%[1]slogs%[1]s: allowed to query the logs.
-			%[1]sseeUnretrievableAttributes%[1]s: allowed to retrieve unretrievableAttributes for all operations that return records.
+		API key's ACL.
+
+			%[1]ssearch%[1]s: can perform search operations.
+			%[1]sbrowse%[1]s: can retrieve all index data with the browse endpoint.
+			%[1]saddObject%[1]s: can add or update records in the index.
+			%[1]sdeleteObject%[1]s: can delete an existing record.
+			%[1]slistIndexes%[1]s: can get a list of all indices.
+			%[1]sdeleteIndex%[1]s: can delete an index.
+			%[1]ssettings%[1]s: can read all index settings.
+			%[1]seditSettings%[1]s: can update all index settings.
+			%[1]sanalytics%[1]s: can retrieve data with the Analytics API.
+			%[1]srecommendation%[1]s: can interact with the Recommendation API.
+			%[1]susage%[1]s: can retrieve data with the Usage API.
+			%[1]slogs%[1]s: can query the logs.
+			%[1]sseeUnretrievableAttributes%[1]s: can retrieve unretrievableAttributes for all operations that return records.
 	`, "`"))
 
 	cmd.Flags().StringSliceVarP(&opts.Indices, "indices", "i", nil, heredoc.Docf(`
-		Specify the list of targeted indices.
-		You can target all indices starting with a prefix or ending with a suffix using the %[1]s*%[1]s character.
-		For example, %[1]sdev_*%[1]s matches all indices starting with %[1]sdev_%[1]s and %[1]s*_dev%[1]s matches all indices ending with %[1]s_dev%[1]s.
+		Index names or patterns that this API key can access. By default, an API key can access all indices in the same application.
+
+		You can use leading and trailing wildcard characters (%[1]s*%[1]s).
+		For example, %[1]sdev_*%[1]s matches all indices starting with %[1]sdev_%[1]s. %[1]s*_dev%[1]s matches all indices ending with %[1]s_dev%[1]s. %[1]s*_products_*%[1]s matches all indices containing %[1]sproducts%[1]s.
 	`, "`"))
 
 	cmd.Flags().DurationVarP(&opts.Validity, "validity", "u", 0, heredoc.Doc(`
-		How long this API key is valid, in seconds.
-		A value of 0 means the API key doesn’t expire.`,
+		Duration (in seconds) after which the API key expires. By default (a value of 0), API keys don't expire.`,
 	))
 
 	cmd.Flags().StringSliceVarP(&opts.Referers, "referers", "r", nil, heredoc.Docf(`
 		Specify the list of referrers that can perform an operation.
-		You can use the %[1]s*%[1]s (asterisk) character as a wildcard to match subdomains, or all pages of a website.
+		You can use the wildcard character (%[1]s*%[1]s) to match subdomains or entire websites.
 	`, "`"))
 
 	cmd.Flags().StringVarP(&opts.Description, "description", "d", "", heredoc.Doc(`
-		Specify a description of the API key.
-		Used for informative purposes only. It has no impact on the functionality of the API key.`,
+		Describe an API key to help you identify its uses.`,
 	))
 
 	_ = cmd.RegisterFlagCompletionFunc("indices", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
@@ -130,7 +129,7 @@ func NewCreateCmd(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co
 			"usage":                      "retrieve data with the Usage API",
 			"logs":                       "query the logs",
 			"seeUnretrievableAttributes": "retrieve unretrievableAttributes for all operations that return records",
-		}, "allowed to"))
+		}, "can"))
 
 	return cmd
 }

pkg/cmd/apikeys/delete/delete.go

@@ -36,7 +36,7 @@ func NewDeleteCmd(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Co
 
 	cmd := &cobra.Command{
 		Use:   "delete <api-key>",
-		Short: "Delete API key",
+		Short: "Deletes the API key",
 		Args:  validators.ExactArgs(1),
 		Annotations: map[string]string{
 			"acls": "admin",
@@ -58,7 +58,7 @@ func NewDeleteCmd(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Co
 		},
 	}
 
-	cmd.Flags().BoolVarP(&confirm, "confirm", "y", false, "skip confirmation prompt")
+	cmd.Flags().BoolVarP(&confirm, "confirm", "y", false, "Skip the delete API key confirmation prompt")
 
 	return cmd
 }

pkg/cmd/apikeys/get/get.go

@@ -37,7 +37,7 @@ func NewGetCmd(f *cmdutil.Factory, runF func(*GetOptions) error) *cobra.Command
 
 	cmd := &cobra.Command{
 		Use:   "get <api-key>",
-		Short: "Get API key",
+		Short: "Get the API key",
 		Long: heredoc.Doc(`
 			Get the details of a given API Key (ACLs, description, indexes, and other attributes).
 		`),

pkg/cmd/apikeys/list/list.go

@@ -40,7 +40,7 @@ func NewListCmd(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
 		Annotations: map[string]string{
 			"acls": "admin",
 		},
-		Short: "List API keys",
+		Short: "Lists all API keys associated with your Algolia application, including their permissions and restrictions.",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if runF != nil {
 				return runF(opts)

pkg/cmd/crawler/crawl/crawl.go

@@ -39,7 +39,7 @@ func NewCrawlCmd(f *cmdutil.Factory, runF func(*CrawlOptions) error) *cobra.Comm
 		ValidArgsFunction: cmdutil.CrawlerIDs(opts.CrawlerClient),
 		Short:             "Crawl specific URLs",
 		Long: heredoc.Doc(`
-			Immediately crawl the given URLs.
+			Immediately crawl these URLs.
 			The generated records are pushed to the live index if there's no ongoing reindex, and to the temporary index otherwise.
 		`),
 		Example: heredoc.Doc(`
@@ -71,9 +71,9 @@ func NewCrawlCmd(f *cmdutil.Factory, runF func(*CrawlOptions) error) *cobra.Comm
 	_ = cmd.MarkFlagRequired("urls")
 
 	cmd.Flags().BoolVarP(&opts.Save, "save", "s", false, heredoc.Doc(`
-		When true, the given URLs are added to the extraUrls list of your configuration (unless already present in startUrls or sitemaps).
-		When false, the URLs aren't saved in the configuration.
-		When unspecified, the URLs are added to the extraUrls list of your configuration, but only if they haven't been indexed during the last reindex, and they aren't already present in startUrls or sitemaps.
+		When true, the URLs are added to your %[1]sextraUrls%[1]s (unless present in %[1]sstartUrls%[1]s or %[1]ssitemaps%[1]s).
+		When false, the URLs aren't added.
+		When unspecified, the URLs are added to your %[1]sextraUrls%[1]s (unless present in %[1]sstartUrls%[1]s or %[1]ssitemaps%[1]s or they weren't indexed during the preceding reindex).
 	`))
 
 	return cmd

pkg/cmd/crawler/pause/pause.go

@@ -35,7 +35,7 @@ func NewPauseCmd(f *cmdutil.Factory, runF func(*PauseOptions) error) *cobra.Comm
 		ValidArgsFunction: cmdutil.CrawlerIDs(opts.CrawlerClient),
 		Short:             "Pause one or multiple crawlers",
 		Long: heredoc.Doc(`
-			Request the specified crawler to pause its execution.
+			Pauses the specified crawler.
 		`),
 		Example: heredoc.Doc(`
 			# Pause the crawler with the ID "my-crawler"

pkg/cmd/crawler/reindex/reindex.go

@@ -33,7 +33,7 @@ func NewReindexCmd(f *cmdutil.Factory, runF func(*ReindexOptions) error) *cobra.
 		Use:               "reindex <crawler_id>...",
 		Args:              cobra.MinimumNArgs(1),
 		ValidArgsFunction: cmdutil.CrawlerIDs(opts.CrawlerClient),
-		Short:             "Reindex one or multiple crawlers",
+		Short:             "Reindexs the specified crawlers",
 		Long: heredoc.Doc(`
 			Request the specified crawler to start (or restart) crawling.
 		`),

pkg/cmd/crawler/run/run.go

@@ -33,10 +33,10 @@ func NewRunCmd(f *cmdutil.Factory, runF func(*RunOptions) error) *cobra.Command
 		Use:               "run <crawler_id>",
 		Args:              cobra.ExactArgs(1),
 		ValidArgsFunction: cmdutil.CrawlerIDs(opts.CrawlerClient),
-		Short:             "Run a crawler",
+		Short:             "Start or resume a crawler",
 		Long: heredoc.Doc(`
-			Unpause the specified crawler. If a crawl was previously ongoing, it will be resumed.
-			Otherwise, the crawler will go into the active state and wait for the next schedule.
+			Unpause the specified crawler.
+			Previously ongoing crawls will be resumed. Otherwise, the crawler waits for its next scheduled run.
 		`),
 		Example: heredoc.Doc(`
 			# Run the crawler with the ID "my-crawler"

pkg/cmd/crawler/test/test.go

@@ -42,10 +42,9 @@ func NewTestCmd(f *cmdutil.Factory, runF func(*TestOptions) error) *cobra.Comman
 		Use:               "test <crawler_id> --url <url> [-F <file>]",
 		Args:              cobra.ExactArgs(1),
 		ValidArgsFunction: cmdutil.CrawlerIDs(opts.CrawlerClient),
-		Short:             "Test a URL on a crawler",
+		Short:             "Tests a URL with the crawler's configuration and shows the extracted records.",
 		Long: heredoc.Doc(`
-			Test an URL against the given crawler's configuration and see what will be processed.
-			You can also override parts of the configuration to try your changes before updating the configuration.
+			You can override parts of the configuration to test your changes before updating the configuration.
 		`),
 		Example: heredoc.Doc(`
 			# Test the URL "https://www.example.com" against the crawler with the ID "my-crawler"

pkg/cmd/dictionary/entries/browse/browse.go

@@ -28,7 +28,7 @@ type BrowseOptions struct {
 	PrintFlags *cmdutil.PrintFlags
 }
 
-// DictionaryEntry can be plural, compound or stopword entry.
+// DictionaryEntry can be plural, compound, or stop word entry.
 type DictionaryEntry struct {
 	Type          shared.EntryType
 	Word          string   `json:"word,omitempty"`
@@ -63,7 +63,7 @@ func NewBrowseCmd(f *cmdutil.Factory, runF func(*BrowseOptions) error) *cobra.Co
 			This command retrieves all entries from the specified %s dictionaries.
 		`, cs.Bold("custom")),
 		Example: heredoc.Doc(`
-			# Retrieve all entries from the "stopwords" dictionary (doesn't include default stopwords)
+			# Retrieve all entries from the "stopwords" dictionary (not including the Algolia default stop words)
 			$ algolia dictionary entries browse stopwords
 
 			# Retrieve all entries from the "stopwords" and "plurals" dictionaries
@@ -72,7 +72,7 @@ func NewBrowseCmd(f *cmdutil.Factory, runF func(*BrowseOptions) error) *cobra.Co
 			# Retrieve all entries from all dictionaries
 			$ algolia dictionary entries browse --all
 
-			# Retrieve all entries from the "stopwords" dictionaries (including default stopwords)
+			# Retrieve all entries from the "stopwords" dictionaries (including the Algolia default stop words)
 			$ algolia dictionary entries browse stopwords --include-defaults
 		`),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -120,7 +120,7 @@ func runBrowseCmd(opts *BrowseOptions) error {
 		pageCount := 0
 		maxPages := 1
 
-		// implement infinite pagination
+		// Infinite pagination
 		for pageCount < maxPages {
 			res, err := client.SearchDictionaryEntries(dictionary, "", opt.HitsPerPage(1000), opt.Page(pageCount))
 			if err != nil {
@@ -131,13 +131,13 @@ func runBrowseCmd(opts *BrowseOptions) error {
 
 			data, err := json.Marshal(res.Hits)
 			if err != nil {
-				return fmt.Errorf("cannot unmarshal dictionary entries: error while marshalling original dictionary entries: %v", err)
+				return fmt.Errorf("can't unmarshal dictionary entries: error while marshalling original dictionary entries: %v", err)
 			}
 
 			var entries []DictionaryEntry
 			err = json.Unmarshal(data, &entries)
 			if err != nil {
-				return fmt.Errorf("cannot unmarshal dictionary entries: error while unmarshalling original dictionary entries: %v", err)
+				return fmt.Errorf("can't unmarshal dictionary entries: error while unmarshalling original dictionary entries: %v", err)
 			}
 
 			if len(entries) != 0 {
@@ -146,12 +146,12 @@ func runBrowseCmd(opts *BrowseOptions) error {
 
 			for _, entry := range entries {
 				if opts.IncludeDefaultStopwords {
-					// print all entries (default stopwords included)
+					// Print all entries (inlcuding the default Algolia stop words)
 					if err = p.Print(opts.IO, entry); err != nil {
 						return err
 					}
 				} else if entry.Type == shared.CustomEntryType {
-					// print only custom entries
+					// Print only custom entries
 					if err = p.Print(opts.IO, entry); err != nil {
 						return err
 					}
@@ -161,12 +161,12 @@ func runBrowseCmd(opts *BrowseOptions) error {
 			pageCount++
 		}
 
-		// in case no entry is found in all the dictionaries
+		// If no entry is found in all the dictionaries
 		if hasNoEntries {
 			if _, err = fmt.Fprintf(opts.IO.Out, "%s No entries found.\n\n", cs.WarningIcon()); err != nil {
 				return err
 			}
-			// go to the next dictionary
+			// Go to the next dictionary
 			break
 		}
 	}

pkg/cmd/dictionary/entries/clear/clear.go

@@ -97,8 +97,8 @@ func NewClearCmd(f *cmdutil.Factory, runF func(*ClearOptions) error) *cobra.Comm
 		},
 	}
 
-	cmd.Flags().BoolVarP(&confirm, "confirm", "y", false, "skip confirmation prompt")
-	cmd.Flags().BoolVarP(&opts.All, "all", "a", false, "clear all dictionaries")
+	cmd.Flags().BoolVarP(&confirm, "confirm", "y", false, "Skip the clear dictionary entry confirmation prompt")
+	cmd.Flags().BoolVarP(&opts.All, "all", "a", false, "Clear all dictionaries")
 
 	return cmd
 }

pkg/cmd/dictionary/entries/delete/delete.go

@@ -78,7 +78,7 @@ func NewDeleteCmd(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Co
 	cmd.Flags().StringSliceVarP(&opts.ObjectIDs, "object-ids", "", nil, "Object IDs to delete")
 	_ = cmd.MarkFlagRequired("object-ids")
 
-	cmd.Flags().BoolVarP(&confirm, "confirm", "y", false, "skip confirmation prompt")
+	cmd.Flags().BoolVarP(&confirm, "confirm", "y", false, "Skip the delete dictionary entry confirmation prompt")
 
 	return cmd
 }

pkg/cmd/dictionary/entries/entries.go

@@ -10,11 +10,11 @@ import (
 	"github.com/algolia/cli/pkg/cmdutil"
 )
 
-// NewEntriesCmd returns a new command for dictionaries' entries.
+// NewEntriesCmd returns a new command for dictionary entries.
 func NewEntriesCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "entries",
-		Short: "Manage your Algolia dictionaries entries",
+		Short: "Manage your Algolia dictionary entries",
 	}
 
 	cmd.AddCommand(clear.NewClearCmd(f, nil))

pkg/cmd/dictionary/entries/import/import.go

@@ -60,10 +60,10 @@ func NewImportCmd(f *cmdutil.Factory, runF func(*ImportOptions) error) *cobra.Co
 			The file must contains one single JSON object per line (newline delimited JSON objects - ndjson format: https://ndjson.org/).
 		`),
 		Example: heredoc.Doc(`
-			# Import entries from the "entries.ndjson" file to "stopwords" dictionary
+			# Import entries from the "entries.ndjson" file to the "stopwords" dictionary
 			$ algolia dictionary import stopwords -F entries.ndjson
 
-			# Import entries from the "entries.ndjson" file to "plurals" dictionary and continue importing entries even if some entries are invalid
+			# Import entries from the "entries.ndjson" file to the "plurals" dictionary and continue importing entries even if some entries are invalid
 			$ algolia dictionary import plurals -F entries.ndjson --continue-on-errors
 		`),
 		RunE: func(cmd *cobra.Command, args []string) error {

pkg/cmd/dictionary/settings/set/set.go

@@ -41,16 +41,16 @@ func NewSetCmd(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command
 		Long: heredoc.Doc(`
 			Set the dictionary settings.
 
-			For now, the only setting available is to enable/disable the standard entries for the stopwords dictionary.
+			You can turn the standard stop words dictionary on or off.
 		`),
 		Example: heredoc.Doc(`
-			# Disable standard entries for English and French
+			# Tuen off standard entries for English and French
 			$ algolia dictionary settings set --disable-standard-entries en,fr
 
-			# Enable standard entries for English and French languages
+			# Enable standard entries for English and French
 			$ algolia dictionary settings set --enable-standard-entries en,fr
 
-			# Disable standard entries for English and French languages and enable standard entries for Spanish language.
+			# Turn off standard entries for English and French and enable standard entries for Spanish.
 			$ algolia dictionary settings set --disable-standard-entries en,fr --enable-standard-entries es
 
 			# Reset standard entries to their default values
@@ -62,16 +62,16 @@ func NewSetCmd(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command
 				return cmdutil.FlagErrorf("Either --disable-standard-entries and/or --enable-standard-entries or --reset-standard-entries must be set")
 			}
 
-			// Check that the user is not resetting standard entries and trying to disable or enable standard entries at the same time
+			// Check that the user isn't resetting standard entries and trying to turn standard entries on or off at the same time
 			if opts.ResetStandardEntries && (len(opts.DisableStandardEntries) > 0 || len(opts.EnableStandardEntries) > 0) {
-				return cmdutil.FlagErrorf("You cannot reset standard entries and disable or enable standard entries at the same time")
+				return cmdutil.FlagErrorf("You can't reset standard entries and turn them on or off at the same time")
 			}
 
-			// Check if the user is trying to disable and enable standard entries for the same languages at the same time
+			// Check if the user is trying to turn standard entries on or off for the same languages at the same time
 			for _, disableLanguage := range opts.DisableStandardEntries {
 				for _, enableLanguage := range opts.EnableStandardEntries {
 					if disableLanguage == enableLanguage {
-						return cmdutil.FlagErrorf("You cannot disable and enable standard entries for the same language: %s", disableLanguage)
+						return cmdutil.FlagErrorf("You can't turn standard entries on or off for the same language: %s", disableLanguage)
 					}
 				}
 			}
@@ -84,8 +84,8 @@ func NewSetCmd(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command
 		},
 	}
 
-	cmd.Flags().StringSliceVarP(&opts.DisableStandardEntries, "disable-standard-entries", "d", []string{}, "Disable standard entries for the given languages")
-	cmd.Flags().StringSliceVarP(&opts.EnableStandardEntries, "enable-standard-entries", "e", []string{}, "Enable standard entries for the given languages")
+	cmd.Flags().StringSliceVarP(&opts.DisableStandardEntries, "disable-standard-entries", "d", []string{}, "Turn off standard entries for these languages")
+	cmd.Flags().StringSliceVarP(&opts.EnableStandardEntries, "enable-standard-entries", "e", []string{}, "Turn on standard entries for these languages")
 	cmd.Flags().BoolVarP(&opts.ResetStandardEntries, "reset-standard-entries", "r", false, "Reset standard entries to their default values")
 
 	SupportedLanguages := make(map[string]string, len(LanguagesWithStopwordsSupport))

pkg/cmd/dictionary/settings/settings.go

@@ -12,7 +12,7 @@ import (
 func NewSettingsCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "settings",
-		Short: "Manage your Algolia dictionaries settings",
+		Short: "Manage your Algolia dictionary settings",
 	}
 
 	cmd.AddCommand(set.NewSetCmd(f, nil))