CLI Reference
This page provides documentation for our command line tools.
cli
The official QFieldCloud CLI tool. Allows interaction with the QFieldCloud server API.
Environment:
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`.
Examples:
qfieldcloud-cli login user pass
qfieldcloud-cli -u user -p pass -U https://localhost/api/v1/ list-projects
Usage:
cli [OPTIONS] COMMAND [ARGS]...
Options:
-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
--version Show the version and exit.
--help Show this message and exit.
collaborators-add
Add collaborator with USERNAME with specific ROLE to a project with PROJECT_ID. Possible ROLE values: admin, manager, editor, reporter, reader.
Usage:
cli collaborators-add [OPTIONS] PROJECT_ID USERNAME ROLE
Options:
--help Show this message and exit.
collaborators-get
Get a list of project collaborators for specific project with PROJECT_ID.
Usage:
cli collaborators-get [OPTIONS] PROJECT_ID
Options:
--help Show this message and exit.
collaborators-patch
Change collaborator with USERNAME to new ROLE in project with PROJECT_ID. Possible ROLE values: admin, manager, editor, reporter, reader.
Usage:
cli collaborators-patch [OPTIONS] PROJECT_ID USERNAME ROLE
Options:
--help Show this message and exit.
collaborators-remove
Remove collaborator with USERNAME from project with PROJECT_ID.
Usage:
cli collaborators-remove [OPTIONS] PROJECT_ID USERNAME
Options:
--help Show this message and exit.
create-project
Creates a new empty QFieldCloud project.
Usage:
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.
--help Show this message and exit.
delete-files
Delete QFieldCloud project files.
Usage:
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
--help Show this message and exit.
delete-project
Deletes a QFieldCloud project.
Usage:
cli delete-project [OPTIONS] PROJECT_ID
Options:
--help Show this message and exit.
delta-push
Push a delta file to a project with PROJECT_ID.
Usage:
cli delta-push [OPTIONS] PROJECT_ID DELTA_FILENAME
Options:
--help Show this message and exit.
download-files
Download QFieldCloud project files.
Usage:
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
--help Show this message and exit.
job-status
Get job status.
Usage:
cli job-status [OPTIONS] JOB_ID
Options:
--help Show this message and exit.
job-trigger
Triggers a new job.
Usage:
cli job-trigger [OPTIONS] PROJECT_ID JOB_TYPE
Options:
--force / --no-force Should force creating a new job. Default: False
--help Show this message and exit.
list-files
List QFieldCloud project files.
Usage:
cli list-files [OPTIONS] PROJECT_ID
Options:
--skip-metadata / --no-skip-metadata
Skip requesting for additional metadata
(currently the `sha256` checksum) for each
version. Default: --skip-metadata
--help Show this message and exit.
list-jobs
List project jobs.
Usage:
cli list-jobs [OPTIONS] PROJECT_ID
Options:
--type JOBTYPES Job type. One of package, delta_apply or
process_projectfile.
-l, --limit INTEGER Limits the number of records to return in the
paginated JSON response.
-o, --offset INTEGER Offsets the given number of records in the paginated
JSON response.
--help Show this message and exit.
list-projects
List QFieldCloud projects.
Usage:
cli list-projects [OPTIONS]
Options:
-l, --limit INTEGER Limits the number of records to return in
the paginated JSON response.
-o, --offset INTEGER Offsets the given number of records in the
paginated JSON response.
--include-public / --no-public Includes the public project in the list.
Default: False
--help Show this message and exit.
login
Login to QFieldCloud.
Usage:
cli login [OPTIONS] USERNAME PASSWORD
Options:
--help Show this message and exit.
logout
Logout and expire the token.
Usage:
cli logout [OPTIONS]
Options:
--help Show this message and exit.
members-add
Add member with USERNAME with ROLE to ORGANIZATION. Possible ROLE values: admin, member.
Usage:
cli members-add [OPTIONS] ORGANIZATION USERNAME ROLE
Options:
--public / --no-public
--help Show this message and exit.
members-get
Get a list of ORGANIZATION members.
Usage:
cli members-get [OPTIONS] ORGANIZATION
Options:
--help Show this message and exit.
members-patch
Change member with USERNAME to new ROLE in ORGANIZATION. Possible ROLE values: admin, member.
Usage:
cli members-patch [OPTIONS] ORGANIZATION USERNAME ROLE
Options:
--help Show this message and exit.
members-remove
Remove member with USERNAME from ORGANIZATION.
Usage:
cli members-remove [OPTIONS] ORGANIZATION USERNAME
Options:
--help Show this message and exit.
package-download
Download packaged QFieldCloud project files.
Usage:
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
--help Show this message and exit.
package-latest
Check project packaging status.
Usage:
cli package-latest [OPTIONS] PROJECT_ID
Options:
--help Show this message and exit.
patch-project
Patch the project with new data. Pass only the parameters that shall be changed.
Usage:
cli patch-project [OPTIONS] PROJECT_ID
Options:
--name TEXT New project name
--description TEXT New project description
--owner TEXT Transfer the project to a new owner
--is-public / --is-no-public Whether the project shall be public
--help Show this message and exit.
upload-files
Upload files to a QFieldCloud project.
Usage:
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
--help Show this message and exit.