Pearl Edits and Reflects Linear

Features | Installation | Quick Start | Commands | Configuration | Development & Testing | FAQ | History | License

" 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

• 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
• Well-tested with isolated ERT files, request fixtures, and coverage support

Installation

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+)

(unless (package-installed-p 'pearl)
  (package-vc-install "https://git.cjennings.net/pearl.git"))

use-package with :vc (Emacs 29+)

(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))

Straight

(straight-use-package
 '(pearl :type git :repo "https://git.cjennings.net/pearl.git"))

Doom Emacs

In packages.el:

(package! pearl
  :recipe (:type git :repo "https://git.cjennings.net/pearl.git" :files ("*.el")))

In config.el:

(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))

Manual

git clone https://git.cjennings.net/pearl.git

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

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

Quick Start

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:

   export LINEAR_API_KEY=lin_api_...

   Then load it from Emacs:

   (pearl-load-api-key-from-env)

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

   machine api.linear.app login apikey password YOUR_API_KEY
   

   (setq pearl-api-key
         (auth-source-pick-first-password :host "api.linear.app"))

3. Choose the Org file Pearl owns:

   (setq pearl-org-file-path (expand-file-name "gtd/linear.org" org-directory))

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

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:

(global-set-key (kbd "C-c L") #'pearl-menu)

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

Fetching and refreshing

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:

(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)))

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.

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:

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

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

(pearl-enable-org-sync)
(pearl-disable-org-sync)

The Org File

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:

#+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.

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

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.

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

Clone the repo and install the Eask-managed dependencies:

git clone https://git.cjennings.net/pearl.git
cd pearl
make setup

Useful development targets:

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

FAQ

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

• 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

Pearl is based on and inspired by Gael Blanchemain's 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

GPL-3.0-or-later. See LICENSE.