Labels management for Projects

README.md

@@ -10,7 +10,8 @@ The TestRail CLI currently supports:
 - **Uploading automated test results from JUnit reports**
 - **Uploading automated test results from Robot Framework reports**
 - **Auto-generating test cases from OpenAPI specifications**
-- **Creating new test runs for results to be uploaded to.**
+- **Creating new test runs for results to be uploaded to**
+- **Managing project labels for better organization and categorization**
 
 To see further documentation about the TestRail CLI, please refer to the 
 [TestRail CLI documentation pages](https://support.gurock.com/hc/en-us/articles/7146548750868-TestRail-CLI)
@@ -39,6 +40,7 @@ Supported and loaded modules:
     - parse_robot: Robot Framework XML Files
     - parse_openapi: OpenAPI YML Files
     - add_run: Create a new empty test run
+    - labels: Manage labels (add, update, delete, list)
 ```
 
 CLI general reference
@@ -81,7 +83,7 @@ Options:
 
 Commands:
   add_run        Add a new test run in TestRail
-  labels         Label management facility for Projects, Test Run and Test cases
+  labels         Manage labels in TestRail
   parse_junit    Parse JUnit report and upload results to TestRail
   parse_openapi  Parse OpenAPI spec and create cases in TestRail
   parse_robot    Parse Robot Framework report and upload results to TestRail
@@ -287,7 +289,265 @@ will be used to upload all results into the same test run.
 
 #### Labels Management
 
-Manage labels for **Projects**, **Test Cases**, and **Test Runs** using the `labels` command. Labels help categorize and organize your test management assets efficiently.
+The TestRail CLI provides comprehensive label management capabilities for **Projects** using the `labels` command. Labels help categorize and organize your test management assets efficiently, making it easier to filter and manage test cases, runs, and projects.
+
+The `labels` command supports full CRUD (Create, Read, Update, Delete) operations:
+- **Add** new labels to projects
+- **List** existing labels with pagination support
+- **Get** detailed information about specific labels
+- **Update** existing label titles
+- **Delete** single or multiple labels in batch
+
+##### Reference
+```shell
+$ trcli labels --help
+Usage: trcli labels [OPTIONS] COMMAND [ARGS]...
+
+  Manage labels in TestRail
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  add     Add a new label in TestRail
+  delete  Delete labels from TestRail
+  get     Get a specific label by ID
+  list    List all labels in the project
+  update  Update an existing label in TestRail
+```
+
+##### Adding Labels
+Create new labels for your project with a descriptive title (maximum 20 characters).
+
+```shell
+# Add a single label
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels add --title "Critical"
+
+# Add a label for release management
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels add --title "Release-2.0"
+
+# Add a label for test categorization
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels add --title "Regression"
+```
+
+##### Listing Labels
+View all labels in your project with optional pagination support.
+
+```shell
+# List all labels (default: up to 250 labels)
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels list
+
+# List labels with pagination
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels list --limit 10 --offset 0
+
+# List next page of labels
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels list --limit 10 --offset 10
+```
+
+**Output example:**
+```
+Retrieving labels...
+Found 5 labels:
+  ID: 123, Title: 'Critical'
+  ID: 124, Title: 'Release-2.0'
+  ID: 125, Title: 'Regression'
+  ID: 126, Title: 'Bug-Fix'
+  ID: 127, Title: 'Performance'
+```
+
+##### Getting Label Details
+Retrieve detailed information about a specific label by its ID.
+
+```shell
+# Get details for a specific label
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels get --id 123
+```
+
+**Output example:**
+```
+Retrieving label with ID 123...
+Label details:
+  ID: 123
+  Title: 'Critical'
+  Created by: 2
+  Created on: 1234567890
+```
+
+##### Updating Labels
+Modify the title of existing labels (maximum 20 characters).
+
+```shell
+# Update a label's title
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels update --id 123 --title "High-Priority"
+```
+
+**Output example:**
+```
+Updating label with ID 123...
+Successfully updated label: ID=123, Title='High-Priority'
+```
+
+##### Deleting Labels
+Remove single or multiple labels from your project.
+
+```shell
+# Delete a single label
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels delete --ids 123
+
+# Delete multiple labels (batch operation)
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Your Project" \
+  labels delete --ids "123,124,125"
+
+```
+
+**Output example:**
+```
+Are you sure you want to delete these labels? [y/N]: y
+Deleting labels with IDs: 123,124...
+Successfully deleted 2 label(s)
+```
+
+##### Common Use Cases
+
+**1. Release Management**
+```shell
+# Create release-specific labels
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Mobile App" \
+  labels add --title "Sprint-42"
+
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Mobile App" \
+  labels add --title "Hotfix-2.1.3"
+```
+
+**2. Test Categorization**
+```shell
+# Create test type labels
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "API Tests" \
+  labels add --title "Smoke"
+
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "API Tests" \
+  labels add --title "Integration"
+
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "API Tests" \
+  labels add --title "E2E"
+```
+
+**3. Priority and Severity**
+```shell
+# Create priority labels
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Bug Tracking" \
+  labels add --title "P0-Critical"
+
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Bug Tracking" \
+  labels add --title "P1-High"
+```
+
+**4. Cleanup Operations**
+```shell
+# List all labels to identify unused ones
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Old Project" \
+  labels list
+
+# Bulk delete obsolete labels
+$ trcli -h https://yourinstance.testrail.io --username <your_username> --password <your_password> \
+  --project "Old Project" \
+  labels delete --ids "100,101,102,103,104"
+```
+
+##### Command Options Reference
+
+**Add Command:**
+```shell
+$ trcli labels add --help
+Options:
+  --title  Title of the label to add (max 20 characters) [required]
+  --help    Show this message and exit.
+```
+
+**List Command:**
+```shell
+$ trcli labels list --help
+Options:
+  --offset   Offset for pagination (default: 0)
+  --limit    Limit for pagination (default: 250, max: 250)
+  --help     Show this message and exit.
+```
+
+**Get Command:**
+```shell
+$ trcli labels get --help
+Options:
+  --id     ID of the label to retrieve [required]
+  --help   Show this message and exit.
+```
+
+**Update Command:**
+```shell
+$ trcli labels update --help
+Options:
+  --id     ID of the label to update [required]
+  --title  New title for the label (max 20 characters) [required]
+  --help   Show this message and exit.
+```
+
+**Delete Command:**
+```shell
+$ trcli labels delete --help
+Options:
+  --ids  Comma-separated list of label IDs to delete [required]
+  --help Show this message and exit.
+```
+
+##### Error Handling and Validation
+
+The labels command includes comprehensive validation:
+
+- **Title Length**: Label titles are limited to 20 characters maximum
+- **ID Validation**: Label IDs must be valid integers
+- **Batch Operations**: Multiple label IDs must be comma-separated
+- **Confirmation Prompts**: Delete operations require user confirmation (can be bypassed with `-y`)
+
+**Example error scenarios:**
+```shell
+# Title too long (>20 characters)
+$ trcli <host,credentials> labels add --title "This title is way too long for validation"
+Error: Label title must be 20 characters or less.
+
+# Invalid label ID
+$ trcli <host,credentials> labels get --id 999999
+Failed to retrieve label: Label not found
+
+# Invalid ID format in batch delete
+$ trcli <host,credentials> labels delete --ids "abc,def"
+Error: Invalid label IDs format
+```
 
 ### Reference
 ```shell