NextCloud tasks API and CLI

Python library for managing todo-lists on a Nextcloud instance with the default Tasks app. Also includes an interactive CLI client to browse and edit tasks.

The default NextCloud Tasks App allows to manage task lists in calendars, which can be synced across devices via iCal todos. The corresponding WebGUI can be inconvenient for some use-cases or might not be exposed/reachable, so a console client that can work with tunnels or in SSH sessions could come in handy. A library-like interface to the NextCloud Tasks WebDAV API allows to use the core functionality also in the context of other projects or for automation.

This is the archived and now legacy predecessor of the API-only async reimplementation and the fully interactive terminal client.

As there seems to be no library specialized on NextCloud tasks available yet, this project comes in three parts:

Python Tasks API Quickstart

An API instance can be obtained by the convenience wrapper get_nextcloud_tasks_api. The following example snippet creates a new task and prints all tasks for all task lists found:

api = get_nextcloud_tasks_api("https://my.nextcloud.com/", "username", "password")
for task_list in api.get_lists():  # all task lists belonging to the authenticated user
    print(task_list.name)

    new_task = Task()  # empty iCal VTODO stub
    new_task.summary = "Test"
    new_task.completed = int(time.time())
    api.create(task_list, new_task.to_string())  # add (as completed) to task list

    for task in api.get_list(task_list):  # get all tasks in the list
        print(Task(task.content).summary)

Endpoints

The following API operations are supported:

get_lists() -> Iterator[TaskList]
Find all available task lists.
get_list(task_list: TaskList, completed: Optional[bool]) -> Iterator[TaskFile]
Get all tasks of a task list, optionally filter remotely by completion state for performance reasons. Note that by default responses are streamed and parsed incrementally, so late exceptions can happen while iterating.
update_list(task_list: TaskList)
Update a list, i.e., with a new display name.
delete_list(task_list: TaskList)
Delete the given list.
create_list(filename: str, name: Optional[str]) -> TaskList
Create a new list with the given (unverified) filename and display name.
update(task: TaskFile) -> TaskFile
Update a task with its updated content.
delete(task: TaskFile)
Delete a task.
create(task_list: TaskList, task: str) -> TaskFile
Create a new task in the task list with the given iCal content.

iCal Task Parser

The API itself transparently operates on unparsed content – i.e., vCalendar/vEvent/iCal strings via XML/WebDAV – so any parsing approach can be used.

However, a simple iCal parser/factory as well as a Task class is included that can optionally be used for working with basic VTODO properties. More elaborate libraries with todo support already exist on PyPI, for example ical or iCal-library.

NextCloud Tasks Console Client

Based on the NextCloud tasks API, an interactive CLI client for browsing, managing, and editing tasks is also included. This command-line client is optional, as its additional dependency (questionary) is only included when the cli extra is specified at installation time.

Screenshot: Example task list view via CLI

On all found task lists, creating, (un-)completing, editing, and deleting tasks is supported, also for arbitrarily nested sub-tasks. In particular, guided by an interactive menu, you can:

Usage and Configuration

Simply run nextcloud-tasks-api with a configuration file:

usage: nextcloud-tasks-api [-h] [-c CONFIG]

Interactive CLI client for managing tasks on a NextCloud instance.

optional arguments:
  -h, --help  show this help message and exit
  -c CONFIG   configuration file, in .ini or .json format (default: ./tasks_config.ini)

The config file consists of simple key/value pairs and will be read from tasks_config.ini in the current directory if not specified otherwise. In INI format, it should contain a single (arbitrarily named) section with the following keys. Alternatively, a .json file with a corresponding dictionary can be given.

base_url
URL of the instance, appending remote.php to the given path for API calls, for example: https://my.nextcloud.com/ or https://example.org:443/nextcloud/
username
Username to login with.
password
Password to login with. Using an App Password instead of the main account password should be considered. Adding an App Password is also needed when the account has 2FA enabled.
password_type
Either plain (default) or openssl-aes, the latter for an encrypted password which requires the openssl binary. A compatible encryption step is for example:
echo -n "nextcloud-password" | openssl enc -e -aes-256-cbc -salt -pbkdf2 -base64
This will prompt for a password that then needs to be given to the CLI at startup.
verify_ssl
Verify the SSL certificate of an HTTPS API URL, enabled per default.

Installation

The most easy way to (un-)install the nextcloud-tasks-api package is via pip. If not already done so, you can get the package manager with something equivalent to sudo apt-get install python3-pip.

pip install .[cli]
pip uninstall nextcloud-tasks-api

This includes the optional cli as extra. Without root privileges, the installation is for the current user only – the resulting executable in ~/.local/ might then not be directly accessible via $PATH. The above pip commands are also the ones used by make install and make uninstall.

For trying out or local development, a virtual environment can be used. Wrapped by the Makefile, you can simply use make run. A make check will invoke type checker and linter.

Code & Download