gtasks.el

gtasks.el is a synchronous Emacs Lisp client for the Google Tasks REST API. It provides functions for listing, creating, and modifying tasklists and tasks.

Installation

gtasks.el is available on MELPA and can be installed by adding the following to your Emacs init file:

(use-package gtasks
  :ensure t)

Alternatively, you can clone this repository, add the directory to your load-path, and require the library:

(add-to-list 'load-path "/path/to/gtasks")
(require 'gtasks)

Authorization

1. Visit the Google Cloud Console and under APIs & Services > Credentials create OAuth client credentials of type Desktop.
2. Copy the generated Client ID and Client Secret into the relevant customization options (see below).
3. Go to APIs & Services > Library, search for Google Tasks API, click on the result, and click Enable.
4. Setup credentials in Emacs (see Securely providing credentials below).
5. Run (gtasks-authorize) once, authorize your app in the browser, and paste the authorization code back into Emacs when prompted.
6. Tokens are cached in ~/.emacs.d/.gtasks/token.json by default and refreshed automatically when they expire.

Tip: Ensure the token directory is only readable by you. gtasks.el creates it with 0700 permissions.

Securely providing credentials

You can configure gtasks.el using either a plain client secret (which is not recommended) or, preferably, by defining a function that returns the client secret. Below is an example of how to use authinfo to securely retrieve the client secret:

(setq gtasks-client-id
      "some-client-id.apps.googleusercontent.com")

(setq gtasks-client-secret
	(lambda ()
		(auth-source-pick-first-password :host "google-api-creds")))

Usage

The library exposes synchronous helpers that return plists matching the Google Tasks API responses.

List titles of tasklists:

(mapcar (lambda (list) (plist-get list :title))
        (plist-get (gtasks-list-list) :items))

Create a tasklist and add two tasks:

(let* ((birthday-list (gtasks-list-insert '(:title "Birthday")))
       (birthday-list-id (plist-get birthday-list :id))
       (task-1 (gtasks-task-insert birthday-list-id
				   (list :title "Get birthday card"
					     :notes "Something funny"
					     :due "2025-11-05T00:00:00.000Z")))
       (task-2 (gtasks-task-insert birthday-list-id
				   (list :title "Bake cake"))))
  (message "Task 1 ID: %s" (plist-get task-1 :id)))

Find a tasklist's ID by its title:

(let ((birthday-list-id (gtasks-list-id-by-title "Birthday")))
  ;; Do something with the list ...
  )

Retrieve all tasks from a tasklist:

(gtasks-task-list list-id)

Mark a task as complete:

(gtasks-task-complete list-id task-id)

Move a task to another tasklist:

(gtasks-task-move list-id task-id dest-list-id)

Delete a tasklist:

(gtasks-list-delete (gtasks-list-id-by-title "Birthday"))

For more entry points and detailed documentation, inspect the functions starting with gtasks-list- and gtasks-task-.

Customization

All package options live under M-x customize-group RET gtasks RET.

• gtasks-client-id – OAuth2 client ID (string).
• gtasks-client-secret – Client secret, either a string or a zero-argument function returning the secret.
• gtasks-token-directory – Directory where tokens are cached (~/.emacs.d/.gtasks/ by default).
• gtasks-token-file – File inside the token directory storing the refresh token (token.json by default).
• gtasks-user-agent – HTTP User-Agent header value sent with API requests.
• gtasks-timeout – Timeout in seconds for HTTP calls.
• gtasks-api-root – Base URL for the Tasks API (override for testing or proxies).

Adjust these variables either through Customize or by setting them in your init file prior to requiring gtasks.el.

License

Distributed under the terms of the GNU General Public License Version 3. See LICENSE for details.