Improving documentation and adding differentiation for unix and Windows users

Author: SeqLaz

docs/docs/examples.md

@@ -2,153 +2,243 @@
 
 ## CLI Example Usage
 
-### **1. Install QFieldCloud SDK**
+Here it is typical user story, for **Bash** (Linux/macOS) and **PowerShell** (Windows):
 
-To interact with the QFieldCloud API, start by installing the official QFieldCloud SDK:
+### **Install QFieldCloud SDK**
 
-```bash
+To interact with the QFieldCloud API, start by installing the official QFieldCloud SDK. The installation command is the same for both Bash and PowerShell:
+
+```shell
 pip install qfieldcloud-sdk
 ```
 
 Once installed, you're ready to manage your projects directly from the command line.
+> Note: All values are enclosed in quotes, with single quotes (`'`) recommended for Bash (_but not mandatory_) and double quotes (`"`) for PowerShell.
 
-### **2. Log in to QFieldCloud and Create a New Project**
+### **Log in to QFieldCloud and Create a New Project**
 
 First, log in to your QFieldCloud account.
-Note that all values are enclosed in single or double quote characters, depending on your operating system's shell.
 
-```bash
-qfieldcloud-cli login "ninjamaster" "secret_password123"
-```
+=== ":material-linux: Linux"
+
+    ```bash
+    qfieldcloud-cli login 'ninjamaster' 'secret_password123'
+    ```
+
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    qfieldcloud-cli login "ninjamaster" "secret_password123"
+    ```
 
 After signing in, the QFieldCloud CLI will output the value of the authentication token.
 The authentication token will be sent to QFieldCloud API to authorize you instead of sending the username and password.
 You can explicitly pass the authentication token via passing `--token` CLI argument for every command.
+
 The easier approach is to set an environment variable with your token:
 
-```bash
-export QFIELDCLOUD_TOKEN="123abcXYZ987exampleToken"
-```
+=== ":material-linux: Linux"
+
+    ```bash
+    export QFIELDCLOUD_TOKEN='123abcXYZ987exampleToken'
+    ```
+
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    $env:QFIELDCLOUD_TOKEN = "123abcXYZ987exampleToken"
+    ```
 
 #### Create a project
 
-Create a project called "Tree_Survey" within your organization:
+Create a project called `Tree_Survey` within your organization:
 
-```bash
-qfieldcloud-cli create-project --owner "My_Organization_Clan" --description "Daily work project" --is-private "Tree_Survey"
-```
+=== ":material-linux: Linux"
+
+    ```bash
+    qfieldcloud-cli create-project --owner 'My_Organization_Clan' --description 'Daily work project' --is-private 'Tree_Survey'
+    ```
+
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    qfieldcloud-cli create-project --owner "My_Organization_Clan" --description "Daily work project" --is-private "Tree_Survey"
+    ```
 
 The project is now created in your QFieldCloud organization, and its project ID (e.g., `123e4567-e89b-12d3-a456-426614174000`) is returned.
 You’re now ready for file uploads.
 
-### **3. Upload Local Files to QFieldCloud**
+### **Upload Local Files to QFieldCloud**
 
-Prepare your local project files and upload them to QFieldCloud. For example, if your files are located in `/home/ninjamaster/QField/cloud/Tree_survey`:
+Prepare your local project files and upload them to QFieldCloud:
 
-```bash
-qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/QField/cloud/Tree_survey"
-```
+=== ":material-linux: Linux"
+
+    ```bash
+    qfieldcloud-cli upload-files '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/QField/cloud/Tree_survey'
+    ```
+
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\QField\cloud\Tree_survey"
+    ```
 
 You can also upload specific files by using the `--filter` option. For instance, to upload only `.gpkg` files:
 
-```bash
-qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/QField/cloud/Tree_survey" --filter "*.gpkg"
-```
+=== ":material-linux: Linux"
 
-### **4. Schedule and Trigger a Package Job**
+    ```bash
+    qfieldcloud-cli upload-files '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/QField/cloud/Tree_survey' --filter '*.gpkg'
+    ```
 
-Suppose your company packages the project every morning at 8:47 AM. You can automate this process using a cron job:
+=== ":material-microsoft-windows: Windows"
 
-```bash
-47 8 * * * qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package
-```
+    ```powershell
+    qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\QField\cloud\Tree_survey" --filter "*.gpkg"
+    ```
 
-This command triggers the package job daily at the specified time. Here's what the cron job format means:
+### **Schedule and Trigger a Package Job**
 
-- `47`: Minute (47th minute).
-- `8`: Hour (8 AM).
-- `*`: Every day of the month.
-- `*`: Every month.
-- `*`: Every day of the week.
+Suppose your company packages the project every morning at 8:47 AM.:
 
-To manually trigger a package job at any time:
+=== ":material-linux: Linux"
 
-```bash
-qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package
-```
+    ```bash
+    47 8 * * * qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package
+    ```
 
-You can force the job to re-run even if one is already queued:
+    This triggers the package job daily at the specified time. For more information about [cronjob](https://crontab.guru/)
 
-```bash
-qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package --force
-```
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    schtasks /create /tn "QFieldCloud Job Trigger" /tr "qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package" /sc daily /st 08:47
+    ```
+
+    This triggers the package job daily at the specified time. For more information about [schtasks](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/schtasks)
+
+To manually trigger a package job at any time and force if require:
 
-### **5. Monitor Job Status**
+=== ":material-linux: Linux"
+
+    ```bash
+    qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package --force
+    ```
+
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package --force
+    ```
+
+### **Monitor Job Status**
 
 After triggering a job, monitor its status to ensure successful completion:
 
-```bash
-qfieldcloud-cli list-jobs "123e4567-e89b-12d3-a456-426614174000" --type package
-qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987"
-```
+=== ":material-linux: Linux"
+
+    ```bash
+    qfieldcloud-cli list-jobs '123e4567-e89b-12d3-a456-426614174000' --type package
+    qfieldcloud-cli job-status '321e4567-e89b-12d3-a456-426614174987'
+    ```
 
-### **6. Download Files for Backup**
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    qfieldcloud-cli list-jobs "123e4567-e89b-12d3-a456-426614174000" --type package
+    qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987"
+    ```
+
+### **Download Files for Backup**
 
 Once the package job is complete, download the project files for backup. To download all files or filter specific ones (e.g., `.jpg` files):
 
-```bash
-qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/backup_folder/DCIM/2024-11-10/" --filter "*.jpg"
-```
+=== ":material-linux: Linux"
+
+    ```bash
+    qfieldcloud-cli package-download '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/backup_folder/DCIM/2024-11-10/' --filter '*.jpg'
+    ```
+
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\backup_folder\DCIM\2024-11-10\" --filter "*.jpg"
+    ```
 
 If files already exist locally and you want to overwrite them, use the `--force-download` option:
 
-```bash
-qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "/home/ninjamaster/backup_folder/DCIM/2024-11-10/" --force-download
-```
+=== ":material-linux: Linux"
+
+    ```bash
+    qfieldcloud-cli package-download '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/backup_folder/DCIM/2024-11-10/' --force-download
+    ```
+
+=== ":material-microsoft-windows: Windows"
 
-### **7. Delete Files to Save Space**
+    ```powershell
+    qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\backup_folder\DCIM\2024-11-10\" --force-download
+    ```
+
+### **Delete Files to Save Space**
 
 To free up storage on QFieldCloud, you can delete unnecessary files, such as `.jpg` files:
 
-```bash
-qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" --filter "*.jpg"
-```
+=== ":material-linux: Linux"
+
+    ```bash
+    qfieldcloud-cli delete-files '123e4567-e89b-12d3-a456-426614174000' --filter '*.jpg'
+    ```
+
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" --filter "*.jpg"
+    ```
 
 You can also delete specific files by specifying their exact path:
 
-```bash
-qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" DCIM/tree-202411202334943.jpg
-```
+=== ":material-linux: Linux"
+
+    ```bash
+    qfieldcloud-cli delete-files '123e4567-e89b-12d3-a456-426614174000' 'DCIM/tree-202411202334943.jpg'
+    ```
+
+=== ":material-microsoft-windows: Windows"
+
+    ```powershell
+    qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" "DCIM\tree-202411202334943.jpg"
+    ```
 
 ### **Other Useful QFieldCloud CLI Commands**
 
 #### **List Your Projects**
 
 To list all projects associated with your account:
 
-```bash
+```shell
 qfieldcloud-cli list-projects
 ```
 
 To include public projects in the list:
 
-```bash
+```shell
 qfieldcloud-cli list-projects --include-public
 ```
 
 #### **List Files in a Project**
 
 To view all files in a specific project:
 
-```bash
+```shell
 qfieldcloud-cli list-files "123e4567-e89b-12d3-a456-426614174000"
 ```
 
 #### **Delete a Project**
 
 To permanently delete a project (be cautious—this action cannot be undone):
 
-```bash
+```shell
 qfieldcloud-cli delete-project "123e4567-e89b-12d3-a456-426614174000"
 ```
 
@@ -158,18 +248,18 @@ You can add, remove, or change the roles of collaborators on your project.
 
 - **Add a Collaborator:**
 
-```bash
+```shell
 qfieldcloud-cli collaborators-add "123e4567-e89b-12d3-a456-426614174000" "ninja007" admin
 ```
 
 - **Remove a Collaborator:**
 
-```bash
+```shell
 qfieldcloud-cli collaborators-remove "123e4567-e89b-12d3-a456-426614174000" "ninja007"
 ```
 
 - **Change a Collaborator’s Role:**
 
-```bash
+```shell
 qfieldcloud-cli collaborators-patch "123e4567-e89b-12d3-a456-426614174000" "ninja001" editor
 ```