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.

Update notesCopy anchor link

Opens the 更新笔记 dialog, the recommended place to start an update. 更新当前笔记 updates the active literature note and appears only when one is active. 更新全部笔记 updates all existing literature notes in your library scope. The checkbox 更新全部笔记时，也为没有笔记的条目创建笔记 is off by default; turn it on to also create notes for items that have none.

The commands below stay available for keyboard shortcuts. ZotLit: 更新文献笔记 and ZotLit: 更新文献笔记元数据 run with no dialog. ZotLit: 覆盖文献笔记 and ZotLit: 创建或更新所有文献笔记 still ask for confirmation. A run that creates nothing reads 更新 … 篇文献笔记？ and lists items without a note under 没有笔记 (…). The Zotero metadata batch works the same way.

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 文库 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.

Reveals the active literature note's item in the Library View. Opens the Library View if closed, clears any active search text and filters so the paper is not hidden, and flashes the paper's row to highlight it.

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 打开 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 引用, Wiki 链接引用, 显示格式化引用, and 将引用作为链接打开.

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 参考文献 Sidebar for the active note.

Opens the 被引用 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 引擎 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 在关系图谱中显示引用 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 raises the same zotlit section in its pane menu. While its Preview panel is shown, the pane menu adds the choices that shape the preview, such as 自动刷新预览 and 显示 Markdown.

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.

To edit the profile that a literature note uses, run ZotLit: 打开模板工作台 from the note. See Templates and profiles.

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 移动到 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 选择要打开的 PDF.

Only PDF attachments are offered. An item with none shows 此条目没有 PDF 附件。 A PDF whose file is no longer on disk shows PDF 文件缺失。 Neither case falls back to Zotero's own reader. See Open an item's PDF in Obsidian.

Imported note actionsCopy anchor link

Overwrites an imported note with its latest content from Zotero. The file is replaced, so local edits are lost. A confirmation modal appears first, and its button reads 覆盖.

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 活动标签页.

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.

另存为查询文件… 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. The explorer is a view of its own, with its own item choice, and it changes no Template Workbench View.

Templates and profilesCopy anchor link

These commands open template documents in the Template Workbench and import a profile that someone shared with you.

Opens the Template Workbench View for the active document, in the Workbench's own window, with the Preview panel shown. A profile document, a partial, or the citation text opens directly. A literature note opens the profile document it resolves against, with the note's item selected, and the Workbench can then update that note. 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.

When a Workbench window already shows the document, the command brings that window to the front. From inside the view, it brings the view's own window to the front. To move a view to another window, use Obsidian's Move to new window.

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:

显示字段 opens or closes the view's Fields panel: the Fields popover, or the pinned panel beside the editor. 显示预览 shows or hides the Preview panel. Each has a check mark while it is on. Both are also view actions in the view header, where the Fields panel's action is named 字段. While the Fields panel is pinned beside the editor, the menu also holds 调整字段宽度. Beside them in the view header, 帮助 opens a menu of the template guide, the syntax and data references, and the community.

is also the button in the row above the panels, which names the chosen item. While the Preview panel is shown, the menu also holds the preview choices.

Four entries join the pane menu outside the zotlit section. 更改语言 switches the document between Liquid and Eta (JavaScript), and is not offered for a profile document. 将模板数据保存为 JSON saves the current template data as a JSON file, for the root the Fields panel shows while it is open, and for the editor's root otherwise; with the annotation root selected, the same entry reads 导出所选论文数据 when it can export the whole paper instead. 以 Markdown 打开 opens the document as Markdown. 恢复内置 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

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