Merge pull request #610 from rgoldberg/543-help

Improve help output.
mas-cli · Oct 27, 2024 · b819488 · b819488
2 parents a256832 + 52a0638
commit b819488
Show file tree

Hide file tree

Showing 18 changed files with 63 additions and 54 deletions.
diff --git a/Sources/mas/Commands/Account.swift b/Sources/mas/Commands/Account.swift
@@ -12,7 +12,7 @@ import StoreFoundation
 extension MAS {
     struct Account: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Prints the primary account Apple ID"
+            abstract: "Display the Apple ID signed in in the Mac App Store"
         )
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Home.swift b/Sources/mas/Commands/Home.swift
@@ -13,10 +13,10 @@ extension MAS {
     /// https://performance-partners.apple.com/search-api
     struct Home: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Opens MAS Preview app page in a browser"
+            abstract: "Open app's Mac App Store web page in the default web browser"
         )
 
-        @Argument(help: "ID of app to show on MAS Preview")
+        @Argument(help: "App ID")
         var appID: AppID
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Info.swift b/Sources/mas/Commands/Info.swift
@@ -17,7 +17,7 @@ extension MAS {
             abstract: "Display app information from the Mac App Store"
         )
 
-        @Argument(help: "ID of app to show info")
+        @Argument(help: "App ID")
         var appID: AppID
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Install.swift b/Sources/mas/Commands/Install.swift
@@ -13,12 +13,12 @@ extension MAS {
     /// Installs previously purchased apps from the Mac App Store.
     struct Install: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Install from the Mac App Store"
+            abstract: "Install previously purchased app(s) from the Mac App Store"
         )
 
-        @Flag(help: "force reinstall")
+        @Flag(help: "Force reinstall")
         var force = false
-        @Argument(help: "app ID(s) to install")
+        @Argument(help: "App ID(s)")
         var appIDs: [AppID]
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/List.swift b/Sources/mas/Commands/List.swift
@@ -12,7 +12,7 @@ extension MAS {
     /// Command which lists all installed apps.
     struct List: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Lists apps from the Mac App Store which are currently installed"
+            abstract: "List apps installed from the Mac App Store for the Apple ID of the current macOS user"
         )
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Lucky.swift b/Sources/mas/Commands/Lucky.swift
@@ -15,12 +15,16 @@ extension MAS {
     /// This is handy as many MAS titles can be long with embedded keywords.
     struct Lucky: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Install the first result from the Mac App Store"
+            abstract:
+                """
+                Install the first app returned from searching the Mac App Store
+                (app must have been previously purchased)
+                """
         )
 
-        @Flag(help: "force reinstall")
+        @Flag(help: "Force reinstall")
         var force = false
-        @Argument(help: "the app name to install")
+        @Argument(help: "Search term")
         var searchTerm: String
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Open.swift b/Sources/mas/Commands/Open.swift
@@ -16,10 +16,10 @@ extension MAS {
     /// https://performance-partners.apple.com/search-api
     struct Open: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Opens app page in 'App Store.app'"
+            abstract: "Open app page in 'App Store.app'"
         )
 
-        @Argument(help: "the app ID")
+        @Argument(help: "App ID")
         var appID: AppID?
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Outdated.swift b/Sources/mas/Commands/Outdated.swift
@@ -15,10 +15,10 @@ extension MAS {
     /// ready to be installed from the Mac App Store.
     struct Outdated: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Lists pending updates from the Mac App Store"
+            abstract: "List pending app updates from the Mac App Store for the Apple ID of the current macOS user"
         )
 
-        @Flag(help: "Show warnings about apps")
+        @Flag(help: "Display warnings about apps unknown to the Mac App Store")
         var verbose = false
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Purchase.swift b/Sources/mas/Commands/Purchase.swift
@@ -12,10 +12,10 @@ import CommerceKit
 extension MAS {
     struct Purchase: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Purchase and download free apps from the Mac App Store"
+            abstract: "\"Purchase\" and install free apps from the Mac App Store"
         )
 
-        @Argument(help: "app ID(s) to install")
+        @Argument(help: "App ID(s)")
         var appIDs: [AppID]
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Reset.swift b/Sources/mas/Commands/Reset.swift
@@ -13,10 +13,10 @@ extension MAS {
     /// Kills several macOS processes as a means to reset the app store.
     struct Reset: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Resets the Mac App Store"
+            abstract: "Reset Mac App Store running processes"
         )
 
-        @Flag(help: "Enable debug mode")
+        @Flag(help: "Output debug information")
         var debug = false
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Search.swift b/Sources/mas/Commands/Search.swift
@@ -17,9 +17,9 @@ extension MAS {
             abstract: "Search for apps from the Mac App Store"
         )
 
-        @Flag(help: "Show price of found apps")
+        @Flag(help: "Display the price of each app")
         var price = false
-        @Argument(help: "the app name to search")
+        @Argument(help: "Search term")
         var searchTerm: String
 
         func run() throws {

diff --git a/Sources/mas/Commands/SignIn.swift b/Sources/mas/Commands/SignIn.swift
@@ -13,10 +13,10 @@ extension MAS {
     struct SignIn: ParsableCommand {
         static let configuration = CommandConfiguration(
             commandName: "signin",
-            abstract: "Sign in to the Mac App Store"
+            abstract: "Sign in to an Apple ID in the Mac App Store"
         )
 
-        @Flag(help: "Complete login with graphical dialog")
+        @Flag(help: "Provide password via graphical dialog")
         var dialog = false
         @Argument(help: "Apple ID")
         var appleID: String

diff --git a/Sources/mas/Commands/SignOut.swift b/Sources/mas/Commands/SignOut.swift
@@ -13,7 +13,7 @@ extension MAS {
     struct SignOut: ParsableCommand {
         static let configuration = CommandConfiguration(
             commandName: "signout",
-            abstract: "Sign out of the Mac App Store"
+            abstract: "Sign out of the Apple ID currently signed in in the Mac App Store"
         )
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Uninstall.swift b/Sources/mas/Commands/Uninstall.swift
@@ -13,13 +13,13 @@ extension MAS {
     /// Command which uninstalls apps managed by the Mac App Store.
     struct Uninstall: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Uninstall app installed from the Mac App Store"
+            abstract: "Uninstall app installed from the Mac App Store for the Apple ID of the current macOS user"
         )
 
         /// Flag indicating that removal shouldn't be performed.
-        @Flag(help: "dry run")
+        @Flag(help: "Perform dry run")
         var dryRun = false
-        @Argument(help: "ID of app to uninstall")
+        @Argument(help: "App ID")
         var appID: AppID
 
         /// Runs the uninstall command.

diff --git a/Sources/mas/Commands/Upgrade.swift b/Sources/mas/Commands/Upgrade.swift
@@ -14,11 +14,12 @@ extension MAS {
     /// Command which upgrades apps with new versions available in the Mac App Store.
     struct Upgrade: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Upgrade outdated apps from the Mac App Store"
+            abstract:
+                "Upgrade outdated app(s) installed from the Mac App Store for the Apple ID of the current macOS user"
         )
 
-        @Argument(help: "app(s) to upgrade")
-        var appIDs: [String] = []
+        @Argument(help: "App ID(s)/app name(s)")
+        var appIDOrNames: [String] = []
 
         /// Runs the command.
         func run() throws {
@@ -56,9 +57,9 @@ extension MAS {
             searcher: AppStoreSearcher
         ) throws -> [(SoftwareProduct, SearchResult)] {
             let apps =
-                appIDs.isEmpty
+                appIDOrNames.isEmpty
                 ? appLibrary.installedApps
-                : appIDs.flatMap { appID in
+                : appIDOrNames.flatMap { appID in
                     if let appID = AppID(appID) {
                         // argument is an AppID, lookup apps by id using argument
                         return appLibrary.installedApps(withAppID: appID)

diff --git a/Sources/mas/Commands/Vendor.swift b/Sources/mas/Commands/Vendor.swift
@@ -13,10 +13,10 @@ extension MAS {
     /// https://performance-partners.apple.com/search-api
     struct Vendor: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Opens vendor's app page in a browser"
+            abstract: "Open vendor's app web page in the default web browser"
         )
 
-        @Argument(help: "the app ID to show the vendor's website")
+        @Argument(help: "App ID")
         var appID: AppID
 
         /// Runs the command.

diff --git a/Sources/mas/Commands/Version.swift b/Sources/mas/Commands/Version.swift
@@ -12,7 +12,7 @@ extension MAS {
     /// Command which displays the version of the mas tool.
     struct Version: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Print version number"
+            abstract: "Display version number"
         )
 
         /// Runs the command.

diff --git a/contrib/completion/mas.fish b/contrib/completion/mas.fish
@@ -23,61 +23,65 @@ end
 complete -c mas -f
 
 ### account
-complete -c mas -n "__fish_use_subcommand" -f -a account -d "Prints the primary account Apple ID"
+complete -c mas -n "__fish_use_subcommand" -f -a account -d "Display the Apple ID signed in in the Mac App Store"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "account"
 ### help
 complete -c mas -n "__fish_use_subcommand" -f -a help -d "Display general or command-specific help"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "help"
 ### home
-complete -c mas -n "__fish_use_subcommand" -f -a home -d "Opens MAS Preview app page in a browser"
+complete -c mas -n "__fish_use_subcommand" -f -a home -d "Open app's Mac App Store web page in the default web browser"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "home"
-complete -c mas -n "__fish_seen_subcommand_from home info install open vendor" -xa "(__fish_mas_list_available)"
+complete -c mas -n "__fish_seen_subcommand_from home info install open purchase vendor" -xa "(__fish_mas_list_available)"
 ### info
 complete -c mas -n "__fish_use_subcommand" -f -a info -d "Display app information from the Mac App Store"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "info"
 ### install
-complete -c mas -n "__fish_use_subcommand" -f -a install -d "Install from the Mac App Store"
+complete -c mas -n "__fish_use_subcommand" -f -a install -d "Install previously purchased app(s) from the Mac App Store"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "install"
 complete -c mas -n "__fish_seen_subcommand_from install lucky" -l force -d "Force reinstall"
 ### list
-complete -c mas -n "__fish_use_subcommand" -f -a list -d "Lists apps from the Mac App Store which are currently installed"
+complete -c mas -n "__fish_use_subcommand" -f -a list -d "List apps installed from the Mac App Store for the Apple ID of the current macOS user"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "list"
 ### lucky
-complete -c mas -n "__fish_use_subcommand" -f -a lucky -d "Install the first result from the Mac App Store"
+complete -c mas -n "__fish_use_subcommand" -f -a lucky -d "Install the first app returned from searching the Mac App Store (app must have been previously purchased)"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "lucky"
 ### open
-complete -c mas -n "__fish_use_subcommand" -f -a open -d "Opens app page in 'App Store.app'"
+complete -c mas -n "__fish_use_subcommand" -f -a open -d "Open app page in 'App Store.app'"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "open"
 ### outdated
-complete -c mas -n "__fish_use_subcommand" -f -a outdated -d "Lists pending updates from the Mac App Store"
+complete -c mas -n "__fish_use_subcommand" -f -a outdated -d "List pending app updates from the Mac App Store for the Apple ID of the current macOS user"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "outdated"
+complete -c mas -n "__fish_seen_subcommand_from outdated" -l verbose -d "Display warnings about apps unknown to the Mac App Store"
+### purchase
+complete -c mas -n "__fish_use_subcommand" -f -a purchase -d "\"Purchase\" and install free apps from the Mac App Store"
+complete -c mas -n "__fish_seen_subcommand_from help" -xa "purchase"
 ### reset
-complete -c mas -n "__fish_use_subcommand" -f -a reset -d "Resets the Mac App Store"
+complete -c mas -n "__fish_use_subcommand" -f -a reset -d "Reset Mac App Store running processes"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "reset"
-complete -c mas -n "__fish_seen_subcommand_from reset" -l debug -d "Enable debug mode"
+complete -c mas -n "__fish_seen_subcommand_from reset" -l debug -d "Output debug information"
 ### search
 complete -c mas -n "__fish_use_subcommand" -f -a search -d "Search for apps from the Mac App Store"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "search"
-complete -c mas -n "__fish_seen_subcommand_from search" -l price -d "Show price of found apps"
+complete -c mas -n "__fish_seen_subcommand_from search" -l price -d "Display the price of each app"
 ### signin
-complete -c mas -n "__fish_use_subcommand" -f -a signin -d "Sign in to the Mac App Store"
+complete -c mas -n "__fish_use_subcommand" -f -a signin -d "Sign in to an Apple ID in the Mac App Store"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "signin"
-complete -c mas -n "__fish_seen_subcommand_from signin" -l dialog -d "Complete login with graphical dialog"
+complete -c mas -n "__fish_seen_subcommand_from signin" -l dialog -d "Provide password via graphical dialog"
 ### signout
-complete -c mas -n "__fish_use_subcommand" -f -a signout -d "Sign out of the Mac App Store"
+complete -c mas -n "__fish_use_subcommand" -f -a signout -d "Sign out of the Apple ID currently signed in in the Mac App Store"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "signout"
 ### uninstall
-complete -c mas -n "__fish_use_subcommand" -f -a uninstall -d "Uninstall app installed from the Mac App Store"
+complete -c mas -n "__fish_use_subcommand" -f -a uninstall -d "Uninstall app installed from the Mac App Store for the Apple ID of the current macOS user"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "uninstall"
-complete -c mas -n "__fish_seen_subcommand_from uninstall" -l dry-run -d "Dry run mode"
+complete -c mas -n "__fish_seen_subcommand_from uninstall" -l dry-run -d "Perform dry run"
 complete -c mas -n "__fish_seen_subcommand_from uninstall" -x -a "(__fish_mas_list_installed)"
 ### upgrade
-complete -c mas -n "__fish_use_subcommand" -f -a upgrade -d "Upgrade outdated apps from the Mac App Store"
+complete -c mas -n "__fish_use_subcommand" -f -a upgrade -d "Upgrade outdated app(s) from the Mac App Store for the Apple ID of the current macOS user"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "upgrade"
 complete -c mas -n "__fish_seen_subcommand_from upgrade" -x -a "(__fish_mas_outdated_installed)"
 ### vendor
-complete -c mas -n "__fish_use_subcommand" -f -a vendor -d "Opens vendor's app page in a browser"
+complete -c mas -n "__fish_use_subcommand" -f -a vendor -d "Open vendor's app web page in the default web browser"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "vendor"
 ### version
-complete -c mas -n "__fish_use_subcommand" -f -a version -d "Print version number"
+complete -c mas -n "__fish_use_subcommand" -f -a version -d "Display version number"
 complete -c mas -n "__fish_seen_subcommand_from help" -xa "version"