Merge pull request #23 from kaincenteno/cli-annotated-help

docs(cli): improve cli documentation and add type hints

Author: kaincenteno

README.md

@@ -39,25 +39,9 @@ The token path is the location where the access token will be stored.
 `pip install pyaxm`
 
 ## CLI:
-Usage: pyaxm-cli COMMAND [ARGS]
+A command-line interface (CLI) tool called `pyaxm-cli` is included for easy access to the API.
 
-### Commands
-`devices` -> List all devices in the organization.
-
-`device` -> Get a device by ID.
-
-`mdm-servers` -> List all MDM servers.
-
-`mdm-server` -> List devices in a specific MDM server.
-
-`mdm-server-assigned` -> Get the server assignment for a device.
-
-`assign-device` -> Assign a device to an MDM server.
-
-`unassign-device` -> Unassign a device from an MDM server.
-
-`apple-care-coverage` -> Get AppleCare warranty coverage information for a device.
-The data returned is on CSV format so you can store it as a CSV if needed
+For detailed usage instructions, available commands, options, and examples, please refer to the [CLI documentation](docs/cli.md).
 
 # Client:
 Example usage:

docs/cli.md

@@ -0,0 +1,162 @@
+# `pyaxm-cli`
+
+**Usage**:
+
+```console
+$ pyaxm-cli [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `devices`: List all devices in the organization.
+* `device`: Get a device by ID.
+* `apple-care-coverage`: Get AppleCare coverage for a device.
+* `mdm-servers`: List all MDM servers.
+* `mdm-server`: List devices in a specific MDM server.
+* `mdm-server-assigned`: Get the server assignment for a device.
+* `assign-device`: Assign one or more devices to an MDM server.
+* `unassign-device`: Unassign one or more devices from an MDM...
+
+## `pyaxm-cli devices`
+
+List all devices in the organization.
+
+**Usage**:
+
+```console
+$ pyaxm-cli devices [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `pyaxm-cli device`
+
+Get a device by ID.
+
+**Usage**:
+
+```console
+$ pyaxm-cli device [OPTIONS] DEVICE_ID
+```
+
+**Arguments**:
+
+* `DEVICE_ID`: [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `pyaxm-cli apple-care-coverage`
+
+Get AppleCare coverage for a device.
+
+**Usage**:
+
+```console
+$ pyaxm-cli apple-care-coverage [OPTIONS] DEVICE_ID
+```
+
+**Arguments**:
+
+* `DEVICE_ID`: [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `pyaxm-cli mdm-servers`
+
+List all MDM servers.
+
+**Usage**:
+
+```console
+$ pyaxm-cli mdm-servers [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `pyaxm-cli mdm-server`
+
+List devices in a specific MDM server.
+
+**Usage**:
+
+```console
+$ pyaxm-cli mdm-server [OPTIONS] SERVER_ID
+```
+
+**Arguments**:
+
+* `SERVER_ID`: [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `pyaxm-cli mdm-server-assigned`
+
+Get the server assignment for a device.
+
+**Usage**:
+
+```console
+$ pyaxm-cli mdm-server-assigned [OPTIONS] DEVICE_ID
+```
+
+**Arguments**:
+
+* `DEVICE_ID`: [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `pyaxm-cli assign-device`
+
+Assign one or more devices to an MDM server.
+
+**Usage**:
+
+```console
+$ pyaxm-cli assign-device [OPTIONS] DEVICE_ID... SERVER_ID
+```
+
+**Arguments**:
+
+* `DEVICE_ID...`: [required]
+* `SERVER_ID`: [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `pyaxm-cli unassign-device`
+
+Unassign one or more devices from an MDM server.
+
+**Usage**:
+
+```console
+$ pyaxm-cli unassign-device [OPTIONS] DEVICE_ID... SERVER_ID
+```
+
+**Arguments**:
+
+* `DEVICE_ID...`: [required]
+* `SERVER_ID`: [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.

pyaxm/cli.py

@@ -1,6 +1,7 @@
 import sys
 import pandas as pd
 import typer
+from typing_extensions import Annotated
 from typing import List
 from pyaxm.client import Client
 
@@ -20,7 +21,7 @@ def devices():
     df.to_csv(sys.stdout, index=False)
 
 @app.command()
-def device(device_id: str):
+def device(device_id: Annotated[str, typer.Argument()]):
     """Get a device by ID."""
     device = client.get_device(device_id)
     device_info = {'id': device.id}
@@ -29,7 +30,7 @@ def device(device_id: str):
     df.to_csv(sys.stdout, index=False)
 
 @app.command()
-def apple_care_coverage(device_id: str):
+def apple_care_coverage(device_id: Annotated[str, typer.Argument()]):
     """Get AppleCare coverage for a device."""
     coverage = client.get_apple_care_coverage(device_id)
     coverage_data = [item.attributes.model_dump() for item in coverage]
@@ -49,23 +50,23 @@ def mdm_servers():
     df.to_csv(sys.stdout, index=False)
 
 @app.command()
-def mdm_server(server_id: str):
+def mdm_server(server_id: Annotated[str, typer.Argument()]):
     """List devices in a specific MDM server."""
     devices = client.list_devices_in_mdm_server(server_id)
     devices_data = [{'id': device.id} for device in devices]
     df = pd.DataFrame(devices_data)
     df.to_csv(sys.stdout, index=False)
 
 @app.command()
-def mdm_server_assigned(device_id: str):
+def mdm_server_assigned(device_id: Annotated[str, typer.Argument()]):
     """Get the server assignment for a device."""
     server_assignment = client.get_device_server_assignment(device_id)
     assignment_info = {'id': server_assignment.id}
     df = pd.DataFrame([assignment_info])
     df.to_csv(sys.stdout, index=False)
 
 @app.command()
-def assign_device(device_id: List[str], server_id: str):
+def assign_device(device_id: Annotated[List[str], typer.Argument()], server_id: Annotated[str, typer.Argument()]):
     """Assign one or more devices to an MDM server."""
     activity = client.assign_unassign_device_to_mdm_server(device_id, server_id, 'ASSIGN_DEVICES')
     activity_data = {'id': activity.id}
@@ -74,7 +75,7 @@ def assign_device(device_id: List[str], server_id: str):
     df.to_csv(sys.stdout, index=False)
 
 @app.command()
-def unassign_device(device_id: List[str], server_id: str):
+def unassign_device(device_id: Annotated[List[str], typer.Argument()], server_id: Annotated[str, typer.Argument()]):
     """Unassign one or more devices from an MDM server."""
     activity = client.assign_unassign_device_to_mdm_server(device_id, server_id, 'UNASSIGN_DEVICES')
     activity_data = {'id': activity.id}