add with_about for CLI commands (#2741)

* add with_about for echo, server, and auth

* update for feedback

* finish (most) remaining command documentation

* update comments after additional clarification

* add expanded_api descriptions

* add comments for action_api

* add comments for remaining apis

* add comment for package-rebuild

* fix build errors

* missed one with_about

* add context to git-info subcommands

* remove context from git-info subcommands

* Make git-info from_fns generic over context

* make version::git_info generic over the context

* try removing generics from subcommand and version::git_info

* try adding a closure with context

* Updates for reviewer feedback

core/startos/src/action.rs

@@ -22,7 +22,8 @@ pub fn action_api<C: Context>() -> ParentHandler<C> {
             "get-input",
             from_fn_async(get_action_input)
                 .with_display_serializable()
-                .with_call_remote::<CliContext>(),
+                .with_about("Get action input spec")
+                .with_call_remote::<CliContext>()
         )
         .subcommand(
             "run",
@@ -34,7 +35,8 @@ pub fn action_api<C: Context>() -> ParentHandler<C> {
                     }
                     Ok(())
                 })
-                .with_call_remote::<CliContext>(),
+                .with_about("Run service action")
+                .with_call_remote::<CliContext>()
         )
 }
 

core/startos/src/auth.rs

@@ -91,28 +91,40 @@ pub fn auth<C: Context>() -> ParentHandler<C> {
                 .with_metadata("login", Value::Bool(true))
                 .no_cli(),
         )
-        .subcommand("login", from_fn_async(cli_login).no_display())
+        .subcommand(
+            "login",
+            from_fn_async(cli_login)
+                .no_display()
+                .with_about("Log in to StartOS server"),
+        )
         .subcommand(
             "logout",
             from_fn_async(logout)
                 .with_metadata("get_session", Value::Bool(true))
                 .no_display()
+                .with_about("Log out of StartOS server")
                 .with_call_remote::<CliContext>(),
         )
-        .subcommand("session", session::<C>())
+        .subcommand(
+            "session",
+            session::<C>().with_about("List or kill StartOS sessions"),
+        )
         .subcommand(
             "reset-password",
             from_fn_async(reset_password_impl).no_cli(),
         )
         .subcommand(
             "reset-password",
-            from_fn_async(cli_reset_password).no_display(),
+            from_fn_async(cli_reset_password)
+                .no_display()
+                .with_about("Reset StartOS password"),
         )
         .subcommand(
             "get-pubkey",
             from_fn_async(get_pubkey)
                 .with_metadata("authenticated", Value::Bool(false))
                 .no_display()
+                .with_about("Get public key derived from server private key")
                 .with_call_remote::<CliContext>(),
         )
 }
@@ -290,12 +302,14 @@ pub fn session<C: Context>() -> ParentHandler<C> {
                 .with_custom_display_fn(|handle, result| {
                     Ok(display_sessions(handle.params, result))
                 })
+                .with_about("Display all server sessions")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
             "kill",
             from_fn_async(kill)
                 .no_display()
+                .with_about("Terminate existing server session(s)")
                 .with_call_remote::<CliContext>(),
         )
 }

core/startos/src/backup/mod.rs

@@ -40,16 +40,21 @@ pub fn backup<C: Context>() -> ParentHandler<C> {
             "create",
             from_fn_async(backup_bulk::backup_all)
                 .no_display()
+                .with_about("Create backup for all packages")
                 .with_call_remote::<CliContext>(),
         )
-        .subcommand("target", target::target::<C>())
+        .subcommand(
+            "target",
+            target::target::<C>().with_about("Commands related to a backup target"),
+        )
 }
 
 pub fn package_backup<C: Context>() -> ParentHandler<C> {
     ParentHandler::new().subcommand(
         "restore",
         from_fn_async(restore::restore_packages_rpc)
             .no_display()
+            .with_about("Restore package(s) from backup")
             .with_call_remote::<CliContext>(),
     )
 }

core/startos/src/backup/target/cifs.rs

@@ -52,18 +52,21 @@ pub fn cifs<C: Context>() -> ParentHandler<C> {
             "add",
             from_fn_async(add)
                 .no_display()
+                .with_about("Add a new backup target")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
             "update",
             from_fn_async(update)
                 .no_display()
+                .with_about("Update an existing backup target")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
             "remove",
             from_fn_async(remove)
                 .no_display()
+                .with_about("Remove an existing backup target")
                 .with_call_remote::<CliContext>(),
         )
 }

core/startos/src/backup/target/mod.rs

@@ -141,11 +141,15 @@ impl FileSystem for BackupTargetFS {
 // #[command(subcommands(cifs::cifs, list, info, mount, umount))]
 pub fn target<C: Context>() -> ParentHandler<C> {
     ParentHandler::new()
-        .subcommand("cifs", cifs::cifs::<C>())
+        .subcommand(
+            "cifs",
+            cifs::cifs::<C>().with_about("Add, remove, or update a backup target"),
+        )
         .subcommand(
             "list",
             from_fn_async(list)
                 .with_display_serializable()
+                .with_about("List existing backup targets")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
@@ -155,16 +159,20 @@ pub fn target<C: Context>() -> ParentHandler<C> {
                 .with_custom_display_fn::<CliContext, _>(|params, info| {
                     Ok(display_backup_info(params.params, info))
                 })
+                .with_about("Display package backup information")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
             "mount",
-            from_fn_async(mount).with_call_remote::<CliContext>(),
+            from_fn_async(mount)
+                .with_about("Mount backup target")
+                .with_call_remote::<CliContext>(),
         )
         .subcommand(
             "umount",
             from_fn_async(umount)
                 .no_display()
+                .with_about("Unmount backup target")
                 .with_call_remote::<CliContext>(),
         )
 }

core/startos/src/db/mod.rs

@@ -31,16 +31,29 @@ lazy_static::lazy_static! {
 
 pub fn db<C: Context>() -> ParentHandler<C> {
     ParentHandler::new()
-        .subcommand("dump", from_fn_async(cli_dump).with_display_serializable())
+        .subcommand(
+            "dump",
+            from_fn_async(cli_dump)
+                .with_display_serializable()
+                .with_about("Filter/query db to display tables and records"),
+        )
         .subcommand("dump", from_fn_async(dump).no_cli())
         .subcommand(
             "subscribe",
             from_fn_async(subscribe)
                 .with_metadata("get_session", Value::Bool(true))
                 .no_cli(),
         )
-        .subcommand("put", put::<C>())
-        .subcommand("apply", from_fn_async(cli_apply).no_display())
+        .subcommand(
+            "put",
+            put::<C>().with_about("Command for adding UI record to db"),
+        )
+        .subcommand(
+            "apply",
+            from_fn_async(cli_apply)
+                .no_display()
+                .with_about("Update a db record"),
+        )
         .subcommand("apply", from_fn_async(apply).no_cli())
 }
 
@@ -299,6 +312,7 @@ pub fn put<C: Context>() -> ParentHandler<C> {
         "ui",
         from_fn_async(ui)
             .with_display_serializable()
+            .with_about("Add path and value to db")
             .with_call_remote::<CliContext>(),
     )
 }

core/startos/src/diagnostic.rs

@@ -13,31 +13,48 @@ use crate::Error;
 
 pub fn diagnostic<C: Context>() -> ParentHandler<C> {
     ParentHandler::new()
-        .subcommand("error", from_fn(error).with_call_remote::<CliContext>())
-        .subcommand("logs", crate::system::logs::<DiagnosticContext>())
+        .subcommand(
+            "error",
+            from_fn(error)
+                .with_about("Display diagnostic error")
+                .with_call_remote::<CliContext>(),
+        )
+        .subcommand(
+            "logs",
+            crate::system::logs::<DiagnosticContext>().with_about("Display OS logs"),
+        )
         .subcommand(
             "logs",
-            from_fn_async(crate::logs::cli_logs::<DiagnosticContext, Empty>).no_display(),
+            from_fn_async(crate::logs::cli_logs::<DiagnosticContext, Empty>)
+                .no_display()
+                .with_about("Display OS logs"),
         )
         .subcommand(
             "kernel-logs",
-            crate::system::kernel_logs::<DiagnosticContext>(),
+            crate::system::kernel_logs::<DiagnosticContext>().with_about("Display kernel logs"),
         )
         .subcommand(
             "kernel-logs",
-            from_fn_async(crate::logs::cli_logs::<DiagnosticContext, Empty>).no_display(),
+            from_fn_async(crate::logs::cli_logs::<DiagnosticContext, Empty>)
+                .no_display()
+                .with_about("Display kernal logs"),
         )
         .subcommand(
             "restart",
             from_fn(restart)
                 .no_display()
+                .with_about("Restart the server")
                 .with_call_remote::<CliContext>(),
         )
-        .subcommand("disk", disk::<C>())
+        .subcommand(
+            "disk",
+            disk::<C>().with_about("Command to remove disk from filesystem"),
+        )
         .subcommand(
             "rebuild",
             from_fn_async(rebuild)
                 .no_display()
+                .with_about("Teardown and rebuild service containers")
                 .with_call_remote::<CliContext>(),
         )
 }
@@ -72,7 +89,8 @@ pub fn disk<C: Context>() -> ParentHandler<C> {
             CallRemoteHandler::<CliContext, _, _>::new(
                 from_fn_async(forget_disk::<RpcContext>).no_display(),
             )
-            .no_display(),
+            .no_display()
+            .with_about("Remove disk from filesystem"),
         )
 }
 

core/startos/src/disk/mod.rs

@@ -51,13 +51,16 @@ pub fn disk<C: Context>() -> ParentHandler<C> {
                 .with_custom_display_fn(|handle, result| {
                     Ok(display_disk_info(handle.params, result))
                 })
+                .with_about("List disk info")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand("repair", from_fn_async(|_: C| repair()).no_cli())
         .subcommand(
             "repair",
             CallRemoteHandler::<CliContext, _, _>::new(
-                from_fn_async(|_: RpcContext| repair()).no_display(),
+                from_fn_async(|_: RpcContext| repair())
+                    .no_display()
+                    .with_about("Repair disk in the event of corruption"),
             ),
         )
 }

core/startos/src/init.rs

@@ -549,18 +549,33 @@ pub async fn init(
 
 pub fn init_api<C: Context>() -> ParentHandler<C> {
     ParentHandler::new()
-        .subcommand("logs", crate::system::logs::<InitContext>())
         .subcommand(
             "logs",
-            from_fn_async(crate::logs::cli_logs::<InitContext, Empty>).no_display(),
+            crate::system::logs::<InitContext>().with_about("Disply OS logs"),
+        )
+        .subcommand(
+            "logs",
+            from_fn_async(crate::logs::cli_logs::<InitContext, Empty>)
+                .no_display()
+                .with_about("Display OS logs"),
+        )
+        .subcommand(
+            "kernel-logs",
+            crate::system::kernel_logs::<InitContext>().with_about("Display kernel logs"),
         )
-        .subcommand("kernel-logs", crate::system::kernel_logs::<InitContext>())
         .subcommand(
             "kernel-logs",
-            from_fn_async(crate::logs::cli_logs::<InitContext, Empty>).no_display(),
+            from_fn_async(crate::logs::cli_logs::<InitContext, Empty>)
+                .no_display()
+                .with_about("Display kernel logs"),
         )
         .subcommand("subscribe", from_fn_async(init_progress).no_cli())
-        .subcommand("subscribe", from_fn_async(cli_init_progress).no_display())
+        .subcommand(
+            "subscribe",
+            from_fn_async(cli_init_progress)
+                .no_display()
+                .with_about("Get initialization progress"),
+        )
 }
 
 #[derive(Debug, Deserialize, Serialize, TS)]