Commands

This reference lists every ZotLit command, its entry points, availability, and Obsidian CLI parameters.

DatabaseCopy Anchor Link

Reloads the Zotero database from disk. Use this after making changes in Zotero when automatic watching is disabled.

Library-wide updateCopy Anchor Link

Creates or updates a literature note for every item in every library of your library scope. Opens the same batch confirmation modal as a multi-item update from Zotero.

The Zotero entry scopes the batch to the row you right-click: a library covers every item in it, a collection covers that collection and its subcollections. That target is exact, so it runs whether or not the row is in your library scope.

Library-wide note importCopy Anchor Link

Imports all child notes attached to regular items and all standalone notes in every library of your library scope. Opens the same batch confirmation modal as a multi-note import from Zotero.

The Zotero entry scopes the import to the row you right-click, subcollections included. That target is exact, so it runs whether or not the row is in your library scope.

Library ViewCopy Anchor Link

Opens the Library View, a tab titled Zotero library that lists your Zotero library, and puts the cursor in its search box. If the tab is already open, the command brings it forward. See Browse your library in the Library View.

A selected row in the view answers the quick switcher's chords below, and its right-click menu lists every action on the item. See Open, write, and cite from a row.

Literature note quick switcherCopy Anchor Link

Opens a modal to search every library in your library scope and jump to (or create) the corresponding literature note.

A result takes five chords, listed along the bottom of the modal:

Alt+Enter opens the Library View on the item's first collection, or on its library when the item is in no collection, and selects its row. It clears the view's search and turns off its reading-state filters, so nothing hides the row. When the item falls beyond the view's limit of 1,000 papers, nothing is selected and a notice says so.

The two PDF chords run Open PDF on the selected result, listed under Literature note actions.

CitationsCopy Anchor Link

Opens a modal to search every library in your library scope and insert a Markdown citation at the cursor.

Insertion remains available independently of Pandoc citations, Wikilink citations, Show formatted citations, and Open citations as links.

Citation navigationCopy Anchor Link

The following commands open the recognized Pandoc citation under the cursor. They have no default hotkeys.

Opens or creates the Literature Note in the current tab.

Opens or creates the Literature Note in a new tab.

Opens or creates the Literature Note in a split to the right.

Opens or creates the Literature Note in a new window.

References and exportCopy Anchor Link

Opens the References Sidebar for the active note.

Opens the Cited by Sidebar, which lists the notes in your vault that cite the active literature note. Each result is grouped by source file and links to the citation inside it. The sidebar follows the active note, so it asks for a literature note before it shows results.

Opens a modal that sets the citation and references style and the document language of the active Markdown note. Confirming writes the zotlit-csl and lang properties of that note together. Choosing the vault style or the language reset removes the matching property.

Opens the built-in export modal for the active Markdown note. The command requires the Pandoc engine when you run it.

The export uses its own citation membership. Citation source, presentation, and navigation settings do not change exported content.

Citation textCopy Anchor Link

Opens the citation text in the Template Workbench View. When the vault holds no citation document, the command creates zotlit-citation.md from the built-in citation text first.

Graph viewCopy Anchor Link

Opens Obsidian's graph view with the Citation Graph preset applied, where Obsidian's own Open graph view opens it: the tab you are in, or the new tab, split, or window a modifier-held invocation asks for. See Explore citations in the graph view for what the preset sets.

Opens a local Citation Graph for the active note in a vertical split, grouped to the pane it was opened from so the graph follows that pane's file.

Neither command has a default hotkey. Where a Citation Graph cannot be opened, the command shows a notice naming the one thing to put right: the Graph view core plugin, the Show citations in graph view setting, or Citation Graph availability.

Literature note actionsCopy Anchor Link

The following commands operate on a literature note: the file currently open in the editor must be a ZotLit literature note. They also appear in the file menu (right-click the tab or use the file menu icon) under the zotlit section. The Template Workbench view and the Note preview view raise the same zotlit section in their pane menus, and the Note preview view adds two more: zotlit-preview, for the choices that shape the preview, and zotlit-display, for the display toggles.

Re-renders the full literature note (frontmatter and managed body region) from the current Zotero data.

Re-renders only the frontmatter of the literature note from the current Zotero data. Body content is unchanged.

Destructively replaces the entire literature note with a fresh render. A confirmation modal appears before proceeding.

Imports the Zotero notes attached to the current item into the vault.

Copies the note's Zotero key to the clipboard.

Opens the profile document that the note resolves against in the Template Workbench View. A note with no profile stamp resolves against the Default profile. A profile the vault cannot resolve shows a notice instead. See Profiles for what a profile decides.

Opens the profile picker for the note, then asks for consent before writing anything. The switch re-renders the note with the chosen profile. The dialog also offers to move the note into that profile's folder. The checkbox names the folder the note moves into, for example Move to books/2024/. The move keeps the subfolders the note has under its current profile's folder: literatures/2024/Smith2020.md moves to books/2024/Smith2020.md. A note outside its profile's folder, or a note whose profile ZotLit does not recognize, moves by its file name alone.

Opens the item's PDF attachment in Obsidian's own PDF reader, whether the file sits inside your vault or in Zotero's storage folder. One PDF opens straight away; several open a picker whose search box reads Select a PDF to open.

Only PDF attachments are offered. An item with none shows This item has no PDF attachment. A PDF whose file is no longer on disk shows The PDF file is missing. Neither case falls back to Zotero's own reader. See Open an item's PDF in Obsidian.

Imported note actionsCopy Anchor Link

Re-imports a Zotero note that was previously imported. A confirmation modal appears before overwriting.

AnnotationsCopy Anchor Link

Opens the annotation view in the right sidebar, or brings it forward when it is already open. The view keeps the follow mode you last chose. A new view starts in Active tab.

These five change what the annotation view follows. Each acts on the open annotation view, and the command palette offers it only where it applies — so the mode the view already follows, and a pin with no item to take, are absent rather than inert. See Use the annotation view.

Undo takes back the last annotation change ZotLit saved to Zotero for the PDF you have open. Redo applies an undone change again. The command palette offers each one only where there is a step to take that way. See Undo and redo a change.

Query filesCopy Anchor Link

Creates a query file named Untitled.zotquery and opens it in a tab. The file has two views. The default view, Items, is a Table of the papers in your whole library, newest first by date modified, with a limit of 100 rows. The second view, Annotations, shows the annotations of your whole library, grouped by paper, with a limit of 100 rows. See Use query files and query blocks.

Save as query file… in the annotation view's More options menu also creates a query file. See Save the annotation sidebar as a query file. The Library View's view menu has the same entry. See Save the view as a query file.

Template data explorerCopy Anchor Link

Opens the template data explorer, showing the full data object available to templates for the current item.

Templates and profilesCopy Anchor Link

These commands open profile documents in the Template Workbench and import a profile that someone shared with you. Two of them are palette entries labelled Open template workbench. One opens the profile document you are editing; the other brings the Workbench forward from inside the view.

Opens the active profile document in the Template Workbench View.

Opens the Template Workbench View in the current leaf for the active document. A profile document, a partial, or the citation text opens directly. A literature note opens the profile document it resolves against.

Brings the Workbench forward for the document being edited. When its pane shares a container with unrelated panes, the editor moves into a window of its own instead.

Opens the Note preview pane beside the Workbench, which shows how the current data renders.

Imports a profile that someone shared with you, from the clipboard or from a file. The import sheet previews the partials, citation style, and Profile Match it carries before anything is written.

Template Workbench pane menuCopy Anchor Link

The Workbench view's pane menu is where most template work starts. These entries sit in the zotlit section:

Four entries join the pane menu outside the zotlit section. Change language switches the document between Liquid and Eta (JavaScript), and is not offered for a profile document. Save template data as JSON saves the current template data as a JSON file; with the annotation root selected, the same entry reads Export selected paper data when it can export the whole paper instead. Open as Markdown opens the document as Markdown. Restore built-in moves the Default profile's custom document to the trash, so the built-in profile applies again, and is offered on that document only.

Onboarding & releaseCopy Anchor Link

Opens the Library View and shows the setup banner above it, even after you dismissed it or setup is complete. The banner holds the setup steps, after a v1-to-v2 upgrade the link to the migration guide, and after ZotLit updates the link to the release notes.

Opens the release notes for the installed ZotLit version.

Entry-point summaryCopy Anchor Link

The two Open template workbench rows are separate commands. The first opens the profile document you are editing; the second brings the Workbench forward from inside the view.

Query CLICopy Anchor Link

The Query CLI reads works, files, and reading marks for agents and scripts. One zotlit:query command selects a Query Dataset with from. How ZotLit Query works explains the datasets, filters, and groups.

zotlit:query uses these parameters:

ZotLit splits fields and sort at commas outside quotes and brackets.

Query datasetsCopy Anchor Link

Choose the dataset that represents one result row:

Standalone Attachments are outside these datasets. Relation Lists contain records from the same dataset universes. Use list methods in filters and an explicit [] in Projection Paths.

notes lists the Child Notes of an Item that are outside the trash, in note key order. A note record has indexedKey, key, title, dateAdded, dateModified, library, and its parent item. No dataset reads notes as rows. This query finds papers with a Child Note and lists the note titles:

obsidian zotlit:query filter='!notes.isEmpty()' fields='title,notes[].title'

For example, this query finds papers with no PDF that ZotLit can open on this computer:

obsidian zotlit:query filter='attachments.filter(value.contentType == "application/pdf" && value.exists).isEmpty()' fields=title,citationKey

Start from Attachments when each file must be one row. This query finds missing linked files:

obsidian zotlit:query from=attachments filter='linkMode == "linked_file" && !exists' fields=item.title,path

Select a record by Indexed Key in the filter. Use indexedKey for a row, item.indexedKey for its parent Item, or attachment.indexedKey for an Annotation's parent Attachment. A key outside the Target Libraries gives a Query Warning. The Target Libraries stay unchanged.

Query ContextCopy Anchor Link

this-item and this-attachment set the Query Context of a query: the Item and the Attachment that a filter reads as this.item and this.attachment. Query files and query blocks set the same context from the note that shows them. See this: the paper of the note.

obsidian zotlit:query from=annotations filter='item == this.item' this-item=ABCD2345 limit=all

A filter that reads this.item or this.attachment without its parameter fails with the unbound-context diagnostic.

Projection and groupingCopy Anchor Link

A path such as attachments[].path returns one value for each Attachment. It keeps source order and keeps null in its original position. A complete related record has a fixed summary:

group accepts one scalar path. This command counts Attachments by fileType, which is pdf, epub, web, or other:

obsidian zotlit:query from=attachments group=fileType

Each group contains value, count, and rows. count is the number of matches before the per-group limit. totalCount counts all matched records, and returnedCount counts the row entries returned across all groups.

A path with one [] groups by each element of a list. This command counts papers per tag:

obsidian zotlit:query group='tags[].name' fields='[]' limit=1

A paper joins one group for each of its tags, and a paper without tags is in the null group. Groups can overlap, so their counts can add up to more than totalCount. Use collections[] for papers per Collection and attachments[].fileType for papers per file type.

This command returns the three most recent marks for each paper:

obsidian zotlit:query from=annotations group=item.indexedKey sort=-dateModified limit=3 fields=text,item.title

Collection and Tag valuesCopy Anchor Link

zotlit:query-values lists the names that a filter matches exactly. Run it before you filter by a Collection or Tag.

Collection values are full paths joined by /, including empty Collections. Tag values are { name, type }, where type is manual, auto, or unknown. Each Library reports its library selector, name, values, totalCount, returnedCount, and truncated.

obsidian zotlit:query-values kind=collections match=thesis

A Collection path in collections.contains or collections.within that no Target Library holds gives an unknown-collection Query Warning. Its suggestions lists the nearest paths, and a library value when another Library holds the path.

Schema, guide, and resultsCopy Anchor Link

The single query.schema.json catalog has datasets.items, datasets.attachments, and datasets.annotations. It also has the shared functions, methods, properties, and types. zotlit:query-schema returns the catalog URL, source custom fields, and defaults by dataset. Add from=items, from=attachments, or from=annotations to narrow the live response.

zotlit:query-guide accepts datasets, filter, fields, sort, group, results, schema, values, or cancel as its topic. Omit topic to print the full guide.

Query results use CLI Contract version 3. The JSON envelope has command: "zotlit:query"; request.from names the dataset, and request.library names its Libraries. The top-level libraries field describes the Libraries that ZotLit read.

Read warnings before you report an empty result. On failure, read diagnostic.report and follow its final recovery action.

Every Attachment Row contains the Attachment and parent Item Indexed Keys. Every Annotation Row also contains its parent Attachment Indexed Key. Annotation default values include pageLabel, pageIndex, hasExcerptImage, Attachment details, Item title, and Citation Key. Request position in fields when source geometry is required. Read attachment.path to open the source document when attachment.exists is true.

When hasExcerptImage is true, pass the Annotation Indexed Key as key to zotlit:annotation-image. The command returns a file path instead of image bytes.

The zotlit-query agent skill reads zotlit:query-guide and zotlit:query-schema before it composes a query. See Ask an AI agent.

Template Workbench CLICopy Anchor Link

The Template Workbench registers its own commands with the Obsidian CLI, for agents and scripts rather than for the command palette. Five answer live:

• zotlit:template-inspect inspects one template document and verifies that its saved source is current.
• zotlit:template-check checks every saved component of every profile.
• zotlit:template-status reports the state of the Workbench for the vault.
• zotlit:template-data returns the template data for one root.
• zotlit:template-guide prints the Workbench guide.

The earlier schema, rendering, source, and managed-frontmatter commands are retired. Each stays registered and answers a COMMAND_RETIRED diagnostic.

See Template Workbench CLI for every command, live and retired, with its flags and diagnostics, and Template Workbench for the concept.

See alsoCopy Anchor Link