path: root/README.org

* Pearl Edits and Reflects Linear

[[#features][Features]] | [[#installation][Installation]] | [[#quick-start][Quick Start]] | [[#commands][Commands]] | [[#configuration][Configuration]] | [[#development--testing][Development & Testing]] | [[#faq][FAQ]] | [[#history][History]] | [[#license][License]]

[[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPLv3-blue.svg]]

" /We like lists because we don't want to die./ "
— /Umberto Eco/

Pearl (backronym: *Pearl Edits and Reflects Linear*) brings Linear issues into Emacs as a working Org file. Fetch your open issues, a project, a Linear Custom View, an ad-hoc filter, or a saved local query; Pearl renders each issue as an Org heading with the description and comments in the body and Linear metadata in a namespaced property drawer. Edit what you need, then push it back explicitly with conflict-aware commands.

** Features
:PROPERTIES:
:CUSTOM_ID: features
:END:

- Fetch open issues, project issues, server-side Linear Custom Views, ad-hoc filters, or named local saved queries
- Read issues as an Org outline: title as heading, description in the body, comments as a chronological subtree
- Keep structured fields in =LINEAR-*= properties: id, URL, team, state, priority, assignee, labels, timestamps, and sync hashes
- Edit descriptions, titles, and your own comments in place, then push them with a three-way conflict check
- Set priority, state, assignee, and labels by command, using Linear ids behind display-name completion
- Add comments, create issues, delete issues, and open the current issue or view in Linear
- Refresh the active view from the source recorded in the file, or refresh one issue at point
- Optionally sync Org TODO keyword changes back to Linear workflow states
- Use one transient dispatcher, =M-x pearl-menu=, for the whole command surface
- [[file:TESTING.org][Well-tested]] with isolated ERT files, request fixtures, and coverage support

** Installation
:PROPERTIES:
:CUSTOM_ID: installation
:END:

Pearl requires Emacs 27.1+, Org, a Linear API key, and the =request=, =dash=, =s=, and =transient= packages. =transient= ships with Emacs 28+, and package managers handle the rest.

*** MELPA

Pearl is not on MELPA yet.

*** package-vc-install (Emacs 29+)

#+begin_src emacs-lisp
  (unless (package-installed-p 'pearl)
    (package-vc-install "https://git.cjennings.net/pearl.git"))
#+end_src

*** use-package with =:vc= (Emacs 29+)

#+begin_src emacs-lisp
  (use-package pearl
    :vc (:url "https://git.cjennings.net/pearl.git" :rev :newest)
    :commands (pearl-menu pearl-list-issues pearl-run-view pearl-new-issue)
    :bind ("C-c L" . pearl-menu)
    :custom
    (pearl-org-file-path (expand-file-name "gtd/linear.org" org-directory))
    :config
    (pearl-load-api-key-from-env))
#+end_src

*** Straight

#+begin_src emacs-lisp
  (straight-use-package
   '(pearl :type git :repo "https://git.cjennings.net/pearl.git"))
#+end_src

*** Doom Emacs

In =packages.el=:

#+begin_src emacs-lisp
  (package! pearl
    :recipe (:type git :repo "https://git.cjennings.net/pearl.git" :files ("*.el")))
#+end_src

In =config.el=:

#+begin_src emacs-lisp
  (use-package! pearl
    :commands (pearl-menu pearl-list-issues pearl-new-issue
               pearl-run-view pearl-enable-org-sync)
    :init
    (setq pearl-org-file-path (expand-file-name "gtd/linear.org" org-directory))
    :config
    (pearl-load-api-key-from-env))
#+end_src

*** Manual

#+begin_src bash
  git clone https://git.cjennings.net/pearl.git
#+end_src

#+begin_src emacs-lisp
  (add-to-list 'load-path "/path/to/pearl")
  (require 'pearl)
#+end_src

Install =request=, =dash=, and =s= first if your package manager did not already pull them in.

** Quick Start
:PROPERTIES:
:CUSTOM_ID: quick-start
:END:

1. Create a Linear API key from Linear's Settings -> Account -> API -> Personal API Keys.

2. Put it somewhere Pearl can read it. The simplest development setup is:

   #+begin_src sh
     export LINEAR_API_KEY=lin_api_...
   #+end_src

   Then load it from Emacs:

   #+begin_src emacs-lisp
     (pearl-load-api-key-from-env)
   #+end_src

   For normal use, keep the key in =auth-source= instead:

   #+begin_example
   machine api.linear.app login apikey password YOUR_API_KEY
   #+end_example

   #+begin_src emacs-lisp
     (setq pearl-api-key
           (auth-source-pick-first-password :host "api.linear.app"))
   #+end_src

3. Choose the Org file Pearl owns:

   #+begin_src emacs-lisp
     (setq pearl-org-file-path (expand-file-name "gtd/linear.org" org-directory))
   #+end_src

4. Run =M-x pearl-menu=, or start with =M-x pearl-list-issues=.

Pearl writes one active Org file. Running a different query or view replaces that file's contents after checking for dirty buffers. Refresh commands reuse the source stored in the file header.

** Commands
:PROPERTIES:
:CUSTOM_ID: commands
:END:

*** Command menu

=M-x pearl-menu= opens a transient dispatcher with commands grouped by fetch, view, issue-at-point, creation, Org sync, and setup. Bind that command if you use Pearl regularly:

#+begin_src emacs-lisp
  (global-set-key (kbd "C-c L") #'pearl-menu)
#+end_src

Every command below is also available directly through =M-x=.

*** Fetching and refreshing

| Command                      | What it does                                     |
|------------------------------+--------------------------------------------------|
| =pearl-list-issues=            | Fetch your open issues                           |
| =pearl-list-issues-by-project= | Fetch open issues in a chosen project            |
| =pearl-list-issues-filtered=   | Build an ad-hoc issue filter interactively       |
| =pearl-run-view=               | Run a Linear Custom View server-side             |
| =pearl-run-saved-query=        | Run a named local query from =pearl-saved-queries= |
| =pearl-refresh-current-view=   | Re-run the source recorded in the active file    |
| =pearl-refresh-current-issue=  | Re-fetch the issue at point                      |

Ad-hoc filtering starts with a team, then completes states, projects, and labels from that team's actual Linear values. Saved queries are local Lisp data:

#+begin_src emacs-lisp
  (setq pearl-saved-queries
        '(("My open work" :filter (:assignee :me :open t) :sort updated :order desc)
          ("Open bugs"    :filter (:labels ("bug") :open t) :sort priority :order asc)))
#+end_src

Sorting is local and deterministic. Query filters are AND-only; use a Linear Custom View for OR-heavy logic.

*** Editing issues

All issue commands work from anywhere inside an issue subtree.

| Command                           | What it changes                                  |
|-----------------------------------+--------------------------------------------------|
| =pearl-sync-current-issue=          | Push the edited description body                 |
| =pearl-sync-current-issue-title=    | Push the edited heading title                    |
| =pearl-set-priority=                | Set None, Urgent, High, Medium, or Low           |
| =pearl-set-state=                   | Set a workflow state from the issue's team       |
| =pearl-set-assignee=                | Set a team member as assignee                    |
| =pearl-set-labels=                  | Replace labels; empty selection clears them      |
| =pearl-add-comment=                 | Add a new Linear comment                         |
| =pearl-edit-current-comment=        | Push edits to one of your own comments           |
| =pearl-delete-current-issue=        | Soft-delete the current issue after confirmation |
| =pearl-open-current-issue=          | Open the issue URL in a browser                  |
| =pearl-open-current-view-in-linear= | Open the active view in Linear                   |

Description, title, and comment pushes use the same conflict gate: unchanged local text sends nothing; a local edit against an unchanged remote pushes; if both local and remote changed since fetch, Pearl refuses to clobber either side and reports the conflict. Destructive conflict choices stash local text in =*pearl-conflict-backup*= first.

Only comments you authored are editable. Pearl refuses edits to comments from another person, a bot, or an integration before making an API call.

*** Org TODO sync

=pearl-state-to-todo-mapping= maps Linear state names to Org TODO keywords for rendering and optional state sync:

#+begin_src emacs-lisp
  (setq pearl-state-to-todo-mapping
        '(("Todo" . "TODO")
          ("In Progress" . "IN-PROGRESS")
          ("In Review" . "IN-REVIEW")
          ("Backlog" . "BACKLOG")
          ("Blocked" . "BLOCKED")
          ("Done" . "DONE")))
#+end_src

Make sure your =org-todo-keywords= include every keyword you map to. Enable and disable the save/TODO-change hooks with:

#+begin_src emacs-lisp
  (pearl-enable-org-sync)
  (pearl-disable-org-sync)
#+end_src

** The Org File
:PROPERTIES:
:CUSTOM_ID: the-org-file
:END:

A fetched Pearl file is intentionally readable. The header records the source, run time, filter summary, count, and whether pagination truncated the result. Issues sit under one top-level view heading:

#+begin_src org
  #+title: Linear - My open issues
  #+STARTUP: show3levels
  #+TODO: TODO IN-PROGRESS IN-REVIEW BACKLOG BLOCKED | DONE
  #+LINEAR-SOURCE: (:type filter :name "My open issues" :filter (:assignee :me :open t))
  #+LINEAR-RUN-AT: 2026-05-23 19:30
  #+LINEAR-COUNT: 12
  #+LINEAR-TRUNCATED: no

  * My open issues
  ** TODO [#B] ENG-123 Issue title
  :PROPERTIES:
  :LINEAR-ID:               <uuid>
  :LINEAR-IDENTIFIER:       ENG-123
  :LINEAR-URL:              https://linear.app/.../ENG-123
  :LINEAR-STATE-NAME:       In Progress
  :LINEAR-ASSIGNEE-NAME:    Craig
  :LINEAR-LABELS:           [bug, p1]
  :LINEAR-DESC-SHA256:      <last-fetched markdown hash>
  :LINEAR-DESC-ORG-SHA256:  <rendered Org body hash>
  :END:

  The issue description renders here as Org and can be edited in place.

  *** Comments
  **** Author Name - 2026-05-23T10:00:00.000Z
  A comment, oldest first.
#+end_src

The =LINEAR-*= properties store both ids and display names so common commands do not need a network lookup just to render. The hash properties are provenance for conflict-aware sync.

** Configuration
:PROPERTIES:
:CUSTOM_ID: configuration
:END:

Most users only need an API key and an output path. The rest are knobs for teams with large issue sets or stronger preferences about window behavior.

| Variable                    | Purpose                                           |
|-----------------------------+---------------------------------------------------|
| =pearl-api-key=               | Linear API key                                    |
| =pearl-org-file-path=         | Active Org output file                            |
| =pearl-default-team-id=       | Default team for issue creation                   |
| =pearl-saved-queries=         | Named local issue queries                         |
| =pearl-state-to-todo-mapping= | Linear state to Org keyword mapping               |
| =pearl-max-issue-pages=       | Pagination cap, 100 issues per page               |
| =pearl-request-timeout=       | Synchronous request timeout in seconds            |
| =pearl-fold-after-update=     | Re-fold the active page after fetch/refresh       |
| =pearl-surface-buffer=        | Show the active buffer after a command updates it |
| =pearl-surface-select-window= | Move focus to the surfaced buffer                 |
| =pearl-debug=                 | Log request/response details to =*Messages*=        |

If a fetch stops at the pagination cap, Pearl writes =#+LINEAR-TRUNCATED: yes= in the file header. Raise =pearl-max-issue-pages= if your result set is larger than the default 1000 issues.

** Development & Testing
:PROPERTIES:
:CUSTOM_ID: development--testing
:END:

Clone the repo and install the Eask-managed dependencies:

#+begin_src bash
  git clone https://git.cjennings.net/pearl.git
  cd pearl
  make setup
#+end_src

Useful development targets:

| Target                                 | What it does                                          |
|----------------------------------------+-------------------------------------------------------|
| =make test=                              | Run unit and integration tests, excluding =:slow= tests |
| =make test-all=                          | Run every test, including =:slow= tests                 |
| =make test-unit=                         | Run unit tests only                                   |
| =make test-integration=                  | Run integration tests only                            |
| =make test-file FILE=mapping=            | Run one test file by fuzzy match                      |
| =make test-one TEST=priority=            | Run one test by fuzzy match                           |
| =make test-name TEST='test-pearl-map-*'= | Run tests matching an ERT selector                    |
| =make coverage=                          | Generate undercover/simplecov coverage data           |
| =make compile=                           | Byte-compile =pearl.el=                                 |
| =make lint=                              | Run the lint/checkdoc path from the test harness      |
| =make validate=                          | Check parentheses across source and tests             |
| =make clean=                             | Remove test artifacts and coverage output             |

Each test file runs in its own Emacs batch process for isolation. See [[file:TESTING.org][TESTING.org]] for the full test guide, naming conventions, fixture helpers, and coverage notes.

** FAQ
:PROPERTIES:
:CUSTOM_ID: faq
:END:

*** I edited the heading title and synced the description. Why did the title stay the same?

Titles and descriptions push through separate commands. Use =pearl-sync-current-issue= for the body and =pearl-sync-current-issue-title= for the heading title.

*** Why did square brackets disappear from a synced title?

Pearl strips =[= and =]= from titles before rendering so Org does not misparse them. A title like =Fix [URGENT] bug= round-trips as =Fix URGENT bug=.

*** Why did a Markdown heading or single-asterisk italic change after syncing?

The Markdown-to-Org round trip is intentionally lossy for a few constructs. Markdown =# heading= renders as a bold line, and single-asterisk =*italic*= is read as bold. Use these constructs carefully in descriptions you plan to edit from Org.

*** Why did Pearl refuse my comment edit?

Linear only lets you edit comments you authored. Pearl checks that before pushing and refuses edits to other people's comments, bot comments, and integration comments.

*** Why did Pearl refuse a description, title, or comment sync as a conflict?

The local text and remote text both changed since the last fetch. Refresh to reconcile, or use the conflict prompt. Pearl stashes local text before any destructive resolution.

*** Why did a hand-edited drawer field get overwritten?

Drawer fields are generated metadata. Change priority, state, assignee, and labels through Pearl commands so display names can resolve to Linear ids correctly.

*** Why are renamed teams, states, labels, or assignees stale?

Pearl caches Linear lookup tables. Run =M-x pearl-clear-cache=.

*** Can I keep the file expanded after refresh?

Yes. Set =pearl-fold-after-update= to nil.

** Troubleshooting
:PROPERTIES:
:CUSTOM_ID: troubleshooting
:END:

- =M-x pearl-check-setup= checks whether the API key is loaded.
- =M-x pearl-test-connection= checks API connectivity.
- =M-x pearl-toggle-debug= enables request/response logging in =*Messages*=.
- =M-x pearl-clear-cache= refreshes cached names after Linear-side changes.

** History
:PROPERTIES:
:CUSTOM_ID: history
:END:

Pearl is based on and inspired by Gael Blanchemain's [[https://github.com/gael/linear-emacs][linear-emacs]]. The package has since grown into a separately maintained Linear workflow for Org, including broader fetch modes, editable descriptions and comments, conflict-aware sync, view refresh, command menus, and a dedicated test suite.

Bug reports, feature requests, and pull requests are welcome.

** License
:PROPERTIES:
:CUSTOM_ID: license
:END:

GPL-3.0-or-later. See [[file:LICENSE][LICENSE]].