Allow the format option to appear anywhere in the command hierarchy

Signed-off-by: Kevin Stanley <stanleyk@objectcomputing.com>

Author: stanleykc

unityauth-cli/src/unityauth_cli/cli.py

@@ -116,6 +116,48 @@ def wrapper(ctx: CLIContext, *args, **kwargs):
     return wrapper  # type: ignore[return-value]
 
 
+def format_option(f: F) -> F:
+    """Decorator that adds -o/--format option to a command.
+
+    Allows format to be specified after the command (more intuitive):
+        unityauth tenant list -o json
+
+    If provided, overrides the global format from the parent context.
+    Must be used before @pass_context decorator.
+
+    Example:
+        @click.command()
+        @format_option
+        @pass_context
+        @require_auth
+        def list_tenants(ctx: CLIContext, client: UnityAuthAPIClient) -> None:
+            # ctx.output_format is set (from local -o or global -o or config)
+            ...
+    """
+    @functools.wraps(f)
+    def wrapper(*args, output_format: Optional[str] = None, **kwargs):
+        # Override context format if local option provided
+        if output_format:
+            # Get CLIContext from Click's current context
+            click_ctx = click.get_current_context(silent=True)
+            if click_ctx:
+                cli_ctx = click_ctx.find_object(CLIContext)
+                if cli_ctx:
+                    cli_ctx.output_format = output_format.lower()
+
+        return f(*args, **kwargs)
+
+    # Apply the click option decorator
+    decorated = click.option(
+        '-o', '--format',
+        'output_format',
+        type=click.Choice(['table', 'json', 'csv'], case_sensitive=False),
+        help='Output format (default: table)',
+    )(wrapper)
+
+    return decorated  # type: ignore[return-value]
+
+
 @click.group()
 @click.option(
     '--api-url',
@@ -146,7 +188,7 @@ def cli(ctx: click.Context, api_url: Optional[str], output_format: Optional[str]
       unityauth user create ...          # Create a new user
       unityauth user list --tenant-id 1  # List users in tenant
       unityauth tenant list              # List accessible tenants
-      unityauth batch create-users FILE  # Batch create from CSV
+      unityauth role list                # List available roles
 
     For command-specific help:
       unityauth COMMAND --help

unityauth-cli/src/unityauth_cli/commands/config.py

@@ -9,7 +9,7 @@
 
 import click
 
-from unityauth_cli.cli import CLIContext, console, error, info, pass_context, success
+from unityauth_cli.cli import CLIContext, console, error, format_option, info, pass_context, success
 from unityauth_cli.formatters.table import format_key_value_table
 from unityauth_cli.formatters.json_fmt import format_json
 
@@ -31,6 +31,7 @@ def config() -> None:
 
 
 @config.command()
+@format_option
 @pass_context
 def show(ctx: CLIContext) -> None:
     """Display current configuration settings.
@@ -40,7 +41,7 @@ def show(ctx: CLIContext) -> None:
     \b
     Examples:
       unityauth config show
-      unityauth config show --format json
+      unityauth config show -o json
     """
     try:
         if not ctx.config:

unityauth-cli/src/unityauth_cli/commands/login.py

@@ -13,6 +13,7 @@
     CLIContext,
     console,
     error,
+    format_option,
     handle_error,
     info,
     pass_context,
@@ -141,6 +142,7 @@ def logout(ctx: CLIContext) -> None:
 
 
 @click.command(name='token-info')
+@format_option
 @pass_context
 @require_auth
 def token_info(ctx: CLIContext, client: UnityAuthAPIClient) -> None:
@@ -152,7 +154,7 @@ def token_info(ctx: CLIContext, client: UnityAuthAPIClient) -> None:
     \b
     Examples:
       unityauth token-info
-      unityauth token-info --format json
+      unityauth token-info -o json
     """
     try:
         # Make token_info request

unityauth-cli/src/unityauth_cli/commands/permissions.py

@@ -11,6 +11,7 @@
     CLIContext,
     console,
     error,
+    format_option,
     handle_error,
     info,
     pass_context,
@@ -28,6 +29,7 @@
 @click.command('list')
 @click.option('-t', '--tenant-id', required=True, type=int, help='Tenant ID to check permissions for')
 @click.option('-s', '--service-id', required=True, type=int, help='Service ID to check permissions for')
+@format_option
 @pass_context
 @require_auth
 def list_permissions(
@@ -41,10 +43,15 @@ def list_permissions(
     Returns all permissions the authenticated user has for the specified
     tenant and service combination.
 
+    \b
+    Finding IDs:
+      - Tenant IDs: Run 'unityauth tenant list' to see available tenants
+      - Service IDs: Assigned by system administrator (common: 1=Libre311)
+
     \b
     Examples:
       unityauth permissions list --tenant-id 1 --service-id 1
-      unityauth permissions list --tenant-id 1 --service-id 1 --format json
+      unityauth permissions list --tenant-id 1 --service-id 1 -o json
     """
     try:
         # Validate IDs

unityauth-cli/src/unityauth_cli/commands/roles.py

@@ -11,6 +11,7 @@
     CLIContext,
     console,
     error,
+    format_option,
     handle_error,
     info,
     pass_context,
@@ -25,6 +26,7 @@
 
 
 @click.command('list')
+@format_option
 @pass_context
 @require_auth
 def list_roles(ctx: CLIContext, client: UnityAuthAPIClient) -> None:
@@ -33,11 +35,16 @@ def list_roles(ctx: CLIContext, client: UnityAuthAPIClient) -> None:
     Lists all roles defined in the system with their descriptions.
     Requires Unity Administrator or Tenant Administrator permissions.
 
+    \b
+    Role IDs are used in:
+      - 'unityauth user create --role-ids "1,2"'
+      - 'unityauth user update <ID> --role-ids "1,2"'
+
     \b
     Examples:
       unityauth role list
-      unityauth role list --format json
-      unityauth role list --format csv
+      unityauth role list -o json
+      unityauth role list -o csv
     """
     try:
         if ctx.verbose:

unityauth-cli/src/unityauth_cli/commands/tenants.py

@@ -11,6 +11,7 @@
     CLIContext,
     console,
     error,
+    format_option,
     handle_error,
     info,
     pass_context,
@@ -25,6 +26,7 @@
 
 
 @click.command('list')
+@format_option
 @pass_context
 @require_auth
 def list_tenants(ctx: CLIContext, client: UnityAuthAPIClient) -> None:
@@ -34,11 +36,17 @@ def list_tenants(ctx: CLIContext, client: UnityAuthAPIClient) -> None:
     Unity Administrators see all tenants.
     Tenant Administrators see only their assigned tenants.
 
+    \b
+    Tenant IDs are used in:
+      - 'unityauth user list --tenant-id <ID>'
+      - 'unityauth user create --tenant-id <ID>'
+      - 'unityauth permissions list --tenant-id <ID>'
+
     \b
     Examples:
       unityauth tenant list
-      unityauth tenant list --format json
-      unityauth tenant list --format csv
+      unityauth tenant list -o json
+      unityauth tenant list -o csv
     """
     try:
         if ctx.verbose:
@@ -89,6 +97,7 @@ def list_tenants(ctx: CLIContext, client: UnityAuthAPIClient) -> None:
 
 @click.command('users')
 @click.argument('tenant_id', type=int)
+@format_option
 @pass_context
 @require_auth
 def tenant_users(ctx: CLIContext, tenant_id: int, client: UnityAuthAPIClient) -> None:
@@ -100,8 +109,8 @@ def tenant_users(ctx: CLIContext, tenant_id: int, client: UnityAuthAPIClient) ->
     \b
     Examples:
       unityauth tenant users 1
-      unityauth tenant users 1 --format json
-      unityauth tenant users 2 --format csv
+      unityauth tenant users 1 -o json
+      unityauth tenant users 2 -o csv
     """
     try:
         # Validate tenant ID

unityauth-cli/src/unityauth_cli/commands/users.py

@@ -11,6 +11,7 @@
     CLIContext,
     console,
     error,
+    format_option,
     handle_error,
     info,
     pass_context,
@@ -52,6 +53,11 @@ def create(
     Creates a new user with the specified details and assigns roles.
     Requires Unity Administrator or Tenant Administrator permissions.
 
+    \b
+    Finding IDs:
+      - Tenant IDs: Run 'unityauth tenant list'
+      - Role IDs: Run 'unityauth role list'
+
     \b
     Examples:
       unityauth user create --email user@example.com --first-name John --last-name Doe --password MyP@ss123 --tenant-id 1 --role-ids "2"
@@ -171,6 +177,12 @@ def update(
     Updates the role assignments for an existing user in a specific tenant.
     This replaces all current roles with the specified roles for that tenant.
 
+    \b
+    Finding IDs:
+      - User IDs: Run 'unityauth user list --tenant-id <ID>'
+      - Tenant IDs: Run 'unityauth tenant list'
+      - Role IDs: Run 'unityauth role list'
+
     \b
     Examples:
       unityauth user update 5 --tenant-id 1 --role-ids "1,2"
@@ -256,6 +268,10 @@ def update_profile(
 
     At least one field must be provided.
 
+    \b
+    Finding your user ID:
+      Run 'unityauth token-info' to see your user ID.
+
     \b
     Examples:
       unityauth user update-profile 5 --first-name John
@@ -332,6 +348,7 @@ def update_profile(
 
 @click.command()
 @click.option('-t', '--tenant-id', type=int, required=True, help='Tenant ID to list users from')
+@format_option
 @pass_context
 @require_auth
 def list_users(ctx: CLIContext, tenant_id: int, client: UnityAuthAPIClient) -> None:
@@ -340,11 +357,15 @@ def list_users(ctx: CLIContext, tenant_id: int, client: UnityAuthAPIClient) -> N
     Lists all users in the specified tenant. Requires Unity Administrator
     or Tenant Administrator permissions for the target tenant.
 
+    \b
+    Finding IDs:
+      - Tenant IDs: Run 'unityauth tenant list'
+
     \b
     Examples:
       unityauth user list --tenant-id 1
-      unityauth user list --tenant-id 1 --format json
-      unityauth user list --tenant-id 1 --format csv
+      unityauth user list --tenant-id 1 -o json
+      unityauth user list --tenant-id 1 -o csv
     """
     try:
         # Validate tenant ID