The official QFieldCloud SDK and CLI

qfieldcloud-sdk is the official client to connect to QFieldCloud API either as a python module, or directly from the command line.

Note

qfieldcloud-sdk requires Python >=3.6

Install¶

pip install qfieldcloud-sdk

Module usage¶

import requests
from qfieldcloud_sdk import sdk

client = sdk.Client(
    url="https://app.qfield.cloud/api/v1/"
)
client.login(username='me', password='mysecret')

try:
    projects = client.list_projects()
    print(projects)
except requests.exceptions.RequestException:
    print("Oops!")

CLI usage¶

The official QFieldCloud CLI tool.

Usage¶

qfieldcloud-cli [OPTIONS] COMMAND [ARGS]...

Examples¶

# logs in user "user" with password "pass"
qfieldcloud-cli login user pass

# gets the projects of user "user" with password "pass" at "https://localhost/api/v1/"
qfieldcloud-cli -u user -p pass -U https://localhost/api/v1/ list-projects

# gets the projects of user authenticated with token `QFIELDCLOUD_TOKEN` at "https://localhost/api/v1/" as JSON
export QFIELDCLOUD_URL=https://localhost/api/v1/
export QFIELDCLOUD_TOKEN=017478ee2464440cb8d3e98080df5e5a
qfieldcloud-cli --json list-projects

Filters¶

Some commands allow you to define a filter on the results based on the filename with the --filter option (e.g. the download-files command).

The filters support Unix shell-style wildcards. The special characters used in shell-style wildcards are:

Pattern	Meaning
*	matches everything
?	matches any single character
[seq]	matches any character in seq
[!seq]	matches any character not in seq

For a literal match, wrap the meta-characters in brackets. For example, '[?]' matches the character '?'.

Examples¶

qfieldcloud-cli --filter 'DCIM/*.jpg'
qfieldcloud-cli --filter 'attachments/documentation-??.pdf'

Global options overview¶

-U, --url TEXT                  URL to the QFieldCloud API endpoint. If not
                                passed, gets the value from QFIELDCLOUD_URL
                                environment variable. Default:
                                https://app.qfield.cloud/api/v1/
-u, --username TEXT             Username or email.
-p, --password TEXT
-t, --token TEXT                Session token.
--json / --human                Output the result as newline formatted json. Default: False
--verify-ssl / --no-verify-ssl  Verify SSL. Default: True
--help                          Show this message and exit.

Environment variables can be used instead of passing some common global options.

QFIELDCLOUD_API - QFieldCloud API endpoint URL
QFIELDCLOUD_USERNAME - QFieldCloud username or email. Requires QFIELDCLOUD_PASSWORD to be set.
QFIELDCLOUD_PASSWORD - Password. Requires QFIELDCLOUD_USERNAME to be set.
QFIELDCLOUD_TOKEN - Token that can be used instead of passing username and password. It can be obtained by running qfieldcloud-cli login.
QFIELDCLOUD_VERIFY_SSL - When set to 0 has the same effect as passing --no-verify-ssl.

Commands overview¶

  login             Login to QFieldCloud.
  logout            Logout and expire the token.
  list-projects     List QFieldCloud projects.
  list-files        List QFieldCloud project files.
  create-project    Creates a new empty QFieldCloud project.
  delete-project    Deletes a QFieldCloud project.
  upload-files      Upload files to a QFieldCloud project.
  download-files    Download QFieldCloud project files.
  delete-files      Delete QFieldCloud project files.
  list-jobs         List project jobs.
  job-trigger       Triggers a new job.
  job-status        Get job status.
  package-latest    Check project packaging status.
  package-download  Download packaged QFieldCloud project files.
  collaborators-get     Get a list of project collaborators.
  collaborators-add     Add a project collaborator.
  collaborators-remove  Remove a project collaborator.
  collaborators-patch   Change project collaborator role.
  members-get           Get a list organization members.
  members-add           Add an organization member.
  members-remove        Remove an organization member.
  members-patch         Change organization member role.

Login to QFieldCloud.

qfieldcloud-cli login [OPTIONS] USERNAME PASSWORD

logout¶

Logout from QFieldCloud.

qfieldcloud-cli logout

list-projects¶

List QFieldCloud projects.

qfieldcloud-cli list-projects [OPTIONS]

Options:
  --include-public / --no-public  Includes the public project in the list. Default: False

list-files¶

List QFieldCloud project files.

qfieldcloud-cli list-files [OPTIONS] PROJECT_ID

create-project¶

Creates a new empty QFieldCloud project.

qfieldcloud-cli create-project [OPTIONS] NAME

Options:
  --owner TEXT                Owner of the project. If omitted, the current
                              user is the owner.
  --description TEXT          Description of the project.
  --is-public / --is-private  Mark the project as public.

delete-project¶

Deletes a QFieldCloud project.

qfieldcloud-cli delete-project [OPTIONS] PROJECT_ID

upload-files¶

Upload files to a QFieldCloud project.

qfieldcloud-cli upload-files [OPTIONS] PROJECT_ID PROJECT_PATH

Options:
  --filter TEXT                   Do not upload the whole project, but only
                                  the files which match the glob.
  --throw-on-error / --no-throw-on-error
                                  If any project file upload fails stop
                                  uploading the rest. Default: False

download-files¶

Download QFieldCloud project files.

qfieldcloud-cli download-files [OPTIONS] PROJECT_ID LOCAL_DIR

Options:
  --filter TEXT                   Do not download the whole project, but only
                                  the files which match the glob.
  --throw-on-error / --no-throw-on-error
                                  If any project file downloads fails stop
                                  downloading the rest. Default: False
  --force-download/--no-force-download
                                 Download file even if it already exists locally.
                                  Default: False

delete-files¶

Delete QFieldCloud project files.

qfieldcloud-cli delete-files [OPTIONS] PROJECT_ID PATHS...

Options:
  --throw-on-error / --no-throw-on-error
                                  If any project file delete operations fails
                                  stop, stop deleting the rest. Default: False

job-list¶

List project jobs.

qfieldcloud-cli list-jobs [OPTIONS] PROJECT_ID

Options:
  --type JOBTYPES  Job type. One of package, delta_apply or
                   process_projectfile.

job-trigger¶

Triggers a new job.

qfieldcloud-cli job-trigger [OPTIONS] PROJECT_ID JOB_TYPE

Options:
  --force / --no-force  Should force creating a new job. Default: False

job-status¶

Get job status.

qfieldcloud-cli job-status [OPTIONS] JOB_ID

package-latest¶

Check project packaging status.

qfieldcloud-cli package-latest [OPTIONS] PROJECT_ID

package-download¶

Download packaged QFieldCloud project files.

qfieldcloud-cli package-download [OPTIONS] PROJECT_ID LOCAL_DIR

Options:
  --filter TEXT                   Do not download the whole packaged project,
                                  but only the files which match the glob.
  --throw-on-error / --no-throw-on-error
                                  If any packaged file downloads fails stop
                                  downloading the rest. Default: False
  --force-download/--no-force-download
                                 Download file even if it already exists locally.
                                  Default: False

collaborators-get¶¶

Get a list of project collaborators for a specific project with PROJECT_ID.

`qfieldcloud-cli collaborators-get [OPTIONS] PROJECT_ID`

Options:
- `PROJECT_ID`
  The ID of the project for which you want to list collaborators.

collaborators-add¶¶

Add a collaborator with USERNAME and a specific ROLE to a project with PROJECT_ID.

qfieldcloud-cli collaborators-add [OPTIONS] PROJECT_ID USERNAME ROLE

Options:
- `PROJECT_ID`
  The ID of the project to which the collaborator will be added.

- `USERNAME`
  The username of the collaborator to add.

- `ROLE`
  The role to assign to the collaborator. Possible values: `admin`, `manager`, `editor`, `reporter`, `reader`.

collaborators-remove¶¶

Remove a collaborator with USERNAME from a project with PROJECT_ID.

qfieldcloud-cli collaborators-remove [OPTIONS] PROJECT_ID USERNAME

Options:
- `PROJECT_ID`
  The ID of the project from which to remove the collaborator.

- `USERNAME`
  The username of the collaborator to remove.

collaborators-patch¶¶

Change the role of a collaborator with USERNAME to a new ROLE in a project with PROJECT_ID.

qfieldcloud-cli collaborators-patch [OPTIONS] PROJECT_ID USERNAME ROLE

Options:
- `PROJECT_ID`
  The ID of the project in which to change the collaborator’s role.

- `USERNAME`
  The username of the collaborator whose role is to be changed.

- `ROLE`
  The new role to assign to the collaborator. Possible values: `admin`, `manager`, `editor`, `reporter`, `reader`.

members-get¶¶

Get a list of members of an ORGANIZATION.

qfieldcloud-cli members-get [OPTIONS] ORGANIZATION

Options:
- `ORGANIZATION`
  The name of the organization for which to list members.

members-add¶¶

Add a member with USERNAME and ROLE to an ORGANIZATION.

qfieldcloud-cli members-add [OPTIONS] ORGANIZATION USERNAME ROLE

Options:
- `ORGANIZATION`
  The name of the organization to which the member will be added.

- `USERNAME`
  The username of the member to add.

- `ROLE`
  The role to assign to the member. Possible values: `admin`, `member`.

- `--public / --no-public`
  Specifies whether the membership should be public.

members-remove¶¶

Remove a member with USERNAME from an ORGANIZATION.

qfieldcloud-cli members-remove [OPTIONS] ORGANIZATION USERNAME

Options:
- `ORGANIZATION`
  The name of the organization from which to remove the member.

- `USERNAME`
  The username of the member to remove.

members-patch¶¶

Change the role of a member with USERNAME to a new ROLE in an ORGANIZATION.

qfieldcloud-cli members-patch [OPTIONS] ORGANIZATION USERNAME ROLE

Options:
- `ORGANIZATION`
  The name of the organization in which to change the member’s role.

- `USERNAME`
  The username of the member whose role is to be changed.

- `ROLE`
  The new role to assign to the member. Values: `admin`, `member`.

The official QFieldCloud SDK and CLI

Install¶

Module usage¶

CLI usage¶

Usage¶

Examples¶

Filters¶

Examples¶

Global options overview¶

Commands overview¶

login¶

logout¶

list-projects¶

list-files¶

create-project¶

delete-project¶

upload-files¶

download-files¶

delete-files¶

job-list¶

job-trigger¶

job-status¶

package-latest¶

package-download¶

collaborators-get¶¶

collaborators-add¶¶

collaborators-remove¶¶

collaborators-patch¶¶

members-get¶¶

members-add¶¶

members-remove¶¶

members-patch¶¶