From eeaff6e3e2279692aace91490ab3fb2915eabf8f Mon Sep 17 00:00:00 2001 From: Johnny Sequeira Date: Thu, 24 Oct 2024 15:08:20 -0600 Subject: [PATCH] Improving the documentation and adding advance commands examples --- docs/docs/examples.md | 336 ++++++++++++++++++++++++++++++++---------- 1 file changed, 259 insertions(+), 77 deletions(-) diff --git a/docs/docs/examples.md b/docs/docs/examples.md index 2561990..21eae89 100644 --- a/docs/docs/examples.md +++ b/docs/docs/examples.md @@ -19,13 +19,13 @@ Once installed, you're ready to manage your projects directly from the command l First, log in to your QFieldCloud account. -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli login 'ninjamaster' 'secret_password123' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli login "ninjamaster" "secret_password123" @@ -37,29 +37,59 @@ You can explicitly pass the authentication token via passing `--token` CLI argum The easier approach is to set an environment variable with your token: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash export QFIELDCLOUD_TOKEN='123abcXYZ987exampleToken' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell $env:QFIELDCLOUD_TOKEN = "123abcXYZ987exampleToken" ``` -#### Create a project +You may want to extract the session token directly from the JSON output of the `qfieldcloud-cli` login command. This is especially useful if you're automating tasks or chaining multiple commands. + +In this example, we'll use the `jq` tool to parse the JSON response and retrieve the session token. + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli --json login 'ninjamaster' 'secret_password123' | jq .session_token + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli --json login "ninjamaster" "secret_password123" | jq ".session_token" + ``` + +This command will output only the session token, which can be stored in an environment variable for future use: + +=== ":material-bash: Bash" + + ```bash + export QFIELDCLOUD_TOKEN=$(qfieldcloud-cli --json login 'ninjamaster' 'secret_password123' | jq -r .session_token) + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + $env:QFIELDCLOUD_TOKEN = (qfieldcloud-cli --json login "ninjamaster" "secret_password123" | jq ".session_token") + ``` + +### **Create a project** Create a project called `Tree_Survey` within your organization: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli create-project --owner 'My_Organization_Clan' --description 'Daily work project' --is-private 'Tree_Survey' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli create-project --owner "My_Organization_Clan" --description "Daily work project" --is-private "Tree_Survey" @@ -68,17 +98,49 @@ Create a project called `Tree_Survey` within your organization: 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. +If you forgot to copy your project ID, you can always check the list of all the projects on QFieldCloud. + +#### **List Your Projects** + +To list all projects associated with your account: + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli list-projects + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli list-projects + ``` + +To include public projects in the list: + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli list-projects --include-public + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli list-projects --include-public + ``` + ### **Upload Local Files to QFieldCloud** Prepare your local project files and upload them to QFieldCloud: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli upload-files '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/QField/cloud/Tree_survey' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\QField\cloud\Tree_survey" @@ -86,47 +148,157 @@ Prepare your local project files and upload them to QFieldCloud: You can also upload specific files by using the `--filter` option. For instance, to upload only `.gpkg` files: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli upload-files '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/QField/cloud/Tree_survey' --filter '*.gpkg' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli upload-files "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\QField\cloud\Tree_survey" --filter "*.gpkg" ``` +Now you can see your files on QFieldCloud... + +#### **List Files in a Project** + +To view all files in a specific project: + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli list-files '123e4567-e89b-12d3-a456-426614174000' + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli list-files "123e4567-e89b-12d3-a456-426614174000" + ``` + +### **Manage Members and Collaborators** + +QFieldCloud is a collaborative platform, so you can manage your fieldworks.... + +You can add, remove, or change the roles of members on your Organization. + +- **Add a Member to an Organization:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli members-add 'My_Organization_Clan' 'ninja007' admin + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli members-add "My_Organization_Clan" "ninja007" admin + ``` + +- **Change a Member's Role:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli members-patch 'My_Organization_Clan' 'ninja007' member + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli members-patch "My_Organization_Clan" "ninja007" member + ``` + +- **Remove a Member in an Organization:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli members-remove 'My_Organization_Clan' 'ninja007' + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli members-remove "My_Organization_Clan" "ninja007" + ``` + +You can add, remove, or change the roles of collaborators on your project. + +- **Add a Collaborator in a project:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli collaborators-add '123e4567-e89b-12d3-a456-426614174000' 'ninja007' admin + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli collaborators-add "123e4567-e89b-12d3-a456-426614174000" "ninja007" admin + ``` + +- **Change a Collaborator’s Role in a project:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli collaborators-patch '123e4567-e89b-12d3-a456-426614174000' 'ninja001' editor + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli collaborators-patch "123e4567-e89b-12d3-a456-426614174000" "ninja001" editor + ``` + +- **Remove a Collaboratorin a project:** + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli collaborators-remove '123e4567-e89b-12d3-a456-426614174000' 'ninja007' + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli collaborators-remove "123e4567-e89b-12d3-a456-426614174000" "ninja007" + ``` + ### **Schedule and Trigger a Package Job** Suppose your company packages the project every morning at 8:47 AM.: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash 47 8 * * * qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package ``` - This triggers the package job daily at the specified time. For more information about [cronjob](https://crontab.guru/) + This triggers the package job daily at the specified time. For more information about [cronjob](https://crontab.guru/). -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```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) + 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: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli job-trigger '123e4567-e89b-12d3-a456-426614174000' package --force ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli job-trigger "123e4567-e89b-12d3-a456-426614174000" package --force @@ -136,31 +308,77 @@ To manually trigger a package job at any time and force if require: After triggering a job, monitor its status to ensure successful completion: -=== ":material-linux: Linux" +- **List all jobs for a specific project**: + +Before checking the status of a job, you can list all jobs associated with a project by using the `list-jobs` command. + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli list-jobs '123e4567-e89b-12d3-a456-426614174000' --type package + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli list-jobs "123e4567-e89b-12d3-a456-426614174000" --type package + ``` + +- **Check the status of a specific job**: + +Once you have the job ID, you can check its status using the `job-status` command: + +=== ":material-bash: Bash" + + ```bash + qfieldcloud-cli job-status '321e4567-e89b-12d3-a456-426614174987' + ``` + +=== ":material-powershell: PowerShell" + + ```powershell + qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987" + ``` + +- **Continuously check job status until completion**: + +To automate the process of checking a job's status until it is finished, you can use a loop that will keep checking the status until the job either succeeds or fails. + +=== ":material-bash: Bash" ```bash - qfieldcloud-cli list-jobs '123e4567-e89b-12d3-a456-426614174000' --type package - qfieldcloud-cli job-status '321e4567-e89b-12d3-a456-426614174987' + JOB_STATUS=$(qfieldcloud-cli --json job-status '321e4567-e89b-12d3-a456-426614174987' | jq '.output' -r) + while [[ "$JOB_STATUS" != "success" && "$JOB_STATUS" != "failed" ]]; do + echo "Job is still running... Status: $JOB_STATUS" + sleep 10 # Wait for 10 seconds before checking again + JOB_STATUS=$(qfieldcloud-cli --json job-status '321e4567-e89b-12d3-a456-426614174987' | jq '.output' -r) + done + echo "Job finished with status: $JOB_STATUS" ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell - qfieldcloud-cli list-jobs "123e4567-e89b-12d3-a456-426614174000" --type package - qfieldcloud-cli job-status "321e4567-e89b-12d3-a456-426614174987" + $JOB_STATUS = (qfieldcloud-cli --json job-status "321e4567-e89b-12d3-a456-426614174987" | jq ".output" -r) + while ($JOB_STATUS -ne "success" -and $JOB_STATUS -ne "failed") { + Write-Host "Job is still running... Status: $JOB_STATUS" + Start-Sleep -Seconds 10 # Wait for 10 seconds before checking again + $JOB_STATUS = (qfieldcloud-cli --json job-status "321e4567-e89b-12d3-a456-426614174987" | jq ".output" -r) + } + Write-Host "Job finished with status: $JOB_STATUS" ``` ### **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): -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli package-download '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/backup_folder/DCIM/2024-11-10/' --filter '*.jpg' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\backup_folder\DCIM\2024-11-10\" --filter "*.jpg" @@ -168,13 +386,13 @@ Once the package job is complete, download the project files for backup. To down If files already exist locally and you want to overwrite them, use the `--force-download` option: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli package-download '123e4567-e89b-12d3-a456-426614174000' '/home/ninjamaster/backup_folder/DCIM/2024-11-10/' --force-download ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli package-download "123e4567-e89b-12d3-a456-426614174000" "C:\Users\ninjamaster\backup_folder\DCIM\2024-11-10\" --force-download @@ -184,13 +402,13 @@ If files already exist locally and you want to overwrite them, use the `--force- To free up storage on QFieldCloud, you can delete unnecessary files, such as `.jpg` files: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli delete-files '123e4567-e89b-12d3-a456-426614174000' --filter '*.jpg' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" --filter "*.jpg" @@ -198,68 +416,32 @@ To free up storage on QFieldCloud, you can delete unnecessary files, such as `.j You can also delete specific files by specifying their exact path: -=== ":material-linux: Linux" +=== ":material-bash: Bash" ```bash qfieldcloud-cli delete-files '123e4567-e89b-12d3-a456-426614174000' 'DCIM/tree-202411202334943.jpg' ``` -=== ":material-microsoft-windows: Windows" +=== ":material-powershell: PowerShell" ```powershell qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" "DCIM\tree-202411202334943.jpg" ``` -### **Other Useful QFieldCloud CLI Commands** +### **Delete a Project** -#### **List Your Projects** - -To list all projects associated with your account: - -```shell -qfieldcloud-cli list-projects -``` - -To include public projects in the list: - -```shell -qfieldcloud-cli list-projects --include-public -``` - -#### **List Files in a Project** - -To view all files in a specific project: - -```shell -qfieldcloud-cli list-files "123e4567-e89b-12d3-a456-426614174000" -``` - -#### **Delete a Project** +Once you are done with a project, you can delete it... To permanently delete a project (be cautious—this action cannot be undone): -```shell -qfieldcloud-cli delete-project "123e4567-e89b-12d3-a456-426614174000" -``` - -#### **Manage Collaborators** - -You can add, remove, or change the roles of collaborators on your project. - -- **Add a Collaborator:** - -```shell -qfieldcloud-cli collaborators-add "123e4567-e89b-12d3-a456-426614174000" "ninja007" admin -``` - -- **Remove a Collaborator:** +=== ":material-bash: Bash" -```shell -qfieldcloud-cli collaborators-remove "123e4567-e89b-12d3-a456-426614174000" "ninja007" -``` + ```bash + qfieldcloud-cli delete-project '123e4567-e89b-12d3-a456-426614174000' + ``` -- **Change a Collaborator’s Role:** +=== ":material-powershell: PowerShell" -```shell -qfieldcloud-cli collaborators-patch "123e4567-e89b-12d3-a456-426614174000" "ninja001" editor -``` + ```powershell + qfieldcloud-cli delete-project "123e4567-e89b-12d3-a456-426614174000" + ```