From 85cdb8f525bb93c4cc3caad440b319a3b467480a Mon Sep 17 00:00:00 2001
From: mdatelle <mike@datelle.net>
Date: Thu, 16 Jan 2025 10:07:10 -0500
Subject: [PATCH] feat: add description flag, remove console log, and update
 readme

---
 api/README.md               | 46 +++++++++++++++++++++++++++++++------
 api/src/cli/commands/key.ts | 18 ++++++++-------
 2 files changed, 49 insertions(+), 15 deletions(-)

diff --git a/api/README.md b/api/README.md
index 7e3a6b274..2f67cd71d 100644
--- a/api/README.md
+++ b/api/README.md
@@ -17,11 +17,11 @@ root@Devon:~# unraid-api
 
 Unraid API
 
-  Thanks for using the official Unraid API 
+  Thanks for using the official Unraid API
 
 Usage:
 
-  $ unraid-api command <options> 
+  $ unraid-api command <options>
 
 Commands:
 
@@ -29,34 +29,66 @@ Commands:
 
 Options:
 
-  -h, --help                                                   Prints this usage guide.     
-  -d, --debug                                                  Enabled debug mode.          
-  -p, --port string                                            Set the graphql port.        
-  --environment production/staging/development                 Set the working environment. 
-  --log-level ALL/TRACE/DEBUG/INFO/WARN/ERROR/FATAL/MARK/OFF   Set the log level.           
+  -h, --help                                                   Prints this usage guide.
+  -d, --debug                                                  Enabled debug mode.
+  -p, --port string                                            Set the graphql port.
+  --environment production/staging/development                 Set the working environment.
+  --log-level ALL/TRACE/DEBUG/INFO/WARN/ERROR/FATAL/MARK/OFF   Set the log level.
 
   Copyright © 2024 Lime Technology, Inc.
 
 ```
 
+## Key
+
+To get an existing API key, run:
+
+```
+unraid-api key get --name "my-app-key"
+```
+
+To get an API key, and create if it doesn't exist, run:
+
+```
+unraid-api key get --name "my-app-key" --create
+```
+
+To create a new API key with specific roles, run:
+
+```
+unraid-api key create --name "backup-app" --roles "admin,guest"
+```
+
+To create a new API key with roles and permissions, run:
+
+```
+unraid-api key create --name "backup-app" --roles "admin,guest" --permissions "read:any"
+```
+
 ## Report
+
 To view the current status of the unraid-api and its connection to mothership, run:
+
 ```
 unraid-api report
 ```
 
 To view verbose data (anonymized), run:
+
 ```
 unraid-api report -v
 ```
 
 To view non-anonymized verbose data, run:
+
 ```
 unraid-api report -vv
 ```
 
 ## Secrets
+
 If you found this file you're likely a developer. If you'd like to know more about the API and when it's available please join [our discord](https://discord.unraid.net/).
 
 ## License
+
 Copyright Lime Technology Inc. All rights reserved.
diff --git a/api/src/cli/commands/key.ts b/api/src/cli/commands/key.ts
index 69e8610e1..5af096de9 100644
--- a/api/src/cli/commands/key.ts
+++ b/api/src/cli/commands/key.ts
@@ -10,11 +10,12 @@ enum Command {
 }
 
 type KeyFlags = {
-    command: string;
-    name: string;
     create?: boolean;
-    roles?: string;
+    command: string;
+    description?: string;
+    name: string;
     permissions?: string;
+    roles?: string;
 };
 
 const validRoles: Set<Role> = new Set(Object.values(Role));
@@ -42,6 +43,7 @@ const keyOptions: ArgumentConfig<KeyFlags> = {
     command: { type: String, description: 'get or create' },
     name: { type: String, description: 'Name of the API key', typeLabel: '{underline name}' },
     create: { type: Boolean, optional: true, description: "Create the key if it doesn't exist" },
+    description: { type: String, optional: true, description: 'Description of the API key' },
     roles: {
         type: String,
         optional: true,
@@ -70,12 +72,12 @@ export const key = async (...argv: string[]) => {
                 const roles = validateRoles(options.roles);
                 const key = await apiKeyService.create(
                     options.name,
-                    `CLI generated key: ${options.name}`,
+                    options.description || `CLI generated key: ${options.name}`,
                     roles,
                     true
                 );
 
-                console.log('API Key: ', key);
+                cliLogger.info('API Key: ', key);
                 cliLogger.info('API key created successfully');
 
                 break;
@@ -88,15 +90,15 @@ export const key = async (...argv: string[]) => {
                     const roles = validateRoles(options.roles);
                     const newKey = await apiKeyService.create(
                         options.name,
-                        `CLI generated key: ${options.name}`,
+                        options.description || `CLI generated key: ${options.name}`,
                         roles,
                         true
                     );
 
-                    console.log('New API Key: ', newKey);
+                    cliLogger.info('New API Key: ', newKey);
                     cliLogger.info('API key created successfully');
                 } else if (key) {
-                    console.log('API Key: ', key);
+                    cliLogger.info('API Key: ', key);
                 } else {
                     throw new Error(`No API key found with name: ${options.name}`);
                 }