home / ben / skills / org-ql.md

Org-QL

Query Org files with Emacs in batch mode using org-ql. Use when you need a structured view of projects, tasks, or org metadata.

Setup

Use the agent batch init so org-ql and your org config load correctly:

Process

  1. Run emacs --batch with the agent init file.
  2. Use org-ql-select with an org-ql query.
  3. Print results with princ (plain text) or JSON for easy parsing.

Examples

List all projects (TODO=PROJ)

emacs --batch -l /home/ben/.emacs.d/org-agent-init.el --eval "(progn
  (dolist (entry
           (org-ql-select (org-agenda-files)
             '(todo \"PROJ\")
             :action (lambda () (list (buffer-file-name)
                                      (org-get-heading t t t t)))))
    (princ (format \"%s\t%s\\n\" (car entry) (cadr entry)))))"

List TODOs tagged @work (JSON)

emacs --batch -l /home/ben/.emacs.d/org-agent-init.el --eval "(progn
  (require 'json)
  (let ((items
         (org-ql-select (org-agenda-files)
           '(and (todo \"TODO\") (tags \"@work\"))
           :action (lambda ()
                     (list (buffer-file-name)
                           (org-get-heading t t t t)
                           (org-get-category)
                           (org-entry-get (point) \"PRIORITY\"))))))
    (princ (json-encode items))))"

Find overdue tasks (deadline before today)

emacs --batch -l /home/ben/.emacs.d/org-agent-init.el --eval "(progn
  (dolist (entry
           (org-ql-select (org-agenda-files)
             '(deadline :to -1)
             :action (lambda () (list (buffer-file-name)
                                      (org-get-heading t t t t)
                                      (org-entry-get (point) \"DEADLINE\")))))
    (princ (format \"%s\t%s\t%s\\n\" (nth 0 entry) (nth 1 entry) (nth 2 entry)))))"

Notes