Template Workbench CLI
Every live command in the ZotLit CLI namespace, with its synopsis, the guide topics, the answer envelope, and the diagnostic codes.
This reference lists the commands the Template Workbench registers in the Obsidian CLI, the answers they return, and the diagnostic codes they answer with.
The Template Workbench CLI is a set of ZotLit commands in the Obsidian CLI that let an agent read your template documents, render them against your Zotero library, and report what each render produced. You describe the note you want; the agent writes the Liquid or Eta. The same answers show why a document renders wrong or fails to render.
How the parts fit together
The Template Workbench CLI is the command surface. It selects a template document, reads the Zotero data a template receives, and renders a document in memory to show what it would produce. It reads and renders; it never edits.
The ZotLit template skill is published with the identifier zotlit-template. Its template workflow uses the CLI to inspect, edit, and check templates. Claude Code, Codex, and pi can use it.
The Workbench Guide is the live usage guide built into ZotLit. It ships inside the plugin you have installed, so it always matches the commands in that version. The template skill sends the agent to this guide for current instructions.
For current command help, use:
obsidian help zotlit
obsidian zotlit:template-guideWhat the commands do
Five commands answer in the Obsidian CLI. They are CLI commands, not command palette entries.
Inspection selects one template document and verifies that the source ZotLit compiled is the source on disk, so the agent never edits a stale copy. The answer names the document, the Shared Partials and citation text it depends on, and any problems ZotLit found in it. With no target selected, the same command lists every template document in the template folder, including the built-in Default profile.
Data returns the data a template receives, under zt. The root selects its shape: Note, Annotation, Note name, or Citation. Optional discovery narrows the answer to the fields an edit needs, which keeps a large Zotero item out of the agent's context.
Checking renders a document, or a draft the agent keeps in a scratch file outside the template folder, against a real Zotero item or an existing literature note. It reports each part as passed, failed, or not checked: for a profile, the note name, properties, body, managed region, and annotations; for a citation text or a partial, the rendered text. For an update it reports the properties it would fold into the note and the note text that would result, so you can read the change before you commit to it.
State reports the Workbench at a glance: the plugin version, the vault and Zotero source the commands are talking to, whether JavaScript templates are enabled on this device, and the profiles and documents ZotLit found.
The guide prints the instructions shipped with your installed version, one topic per subject. The skill sends the agent here, so the agent follows the contract of the release you run.
Every answer is JSON and carries a contract version, the command name, and an ok flag. A failure carries a diagnostic with a code, a message, and a hint that names the recovery. See Live commands and Diagnostic codes for the flags and syntax of each command, and for the diagnostic codes.
Commands from earlier releases that rendered a template file directly, or that read and wrote managed frontmatter through the plugin settings, are retired. They still answer, with a retirement diagnostic that points at inspection, data, and check. Managed frontmatter is not edited through the CLI: it lives in the profile document.
Reading and editing boundaries
The CLI reads your template documents and your Zotero library, and renders documents in memory. A check writes nothing: no template document, no note, no setting, and no Zotero record. Checking a draft leaves the draft uninstalled.
Your agent edits template documents through its own vault-aware file tools. Those edits change files in the vault, exactly as your own edits do, so you can read the change before you rely on it and check it with the CLI afterwards. The checked output is the evidence, not the agent's summary of it.
Agent data access
The selected agent can receive Zotero metadata and annotation text returned by the CLI. The agent's own data-handling policies apply.
JavaScript templates
Liquid remains available without extra consent. Eta documents and managed frontmatter entries written with the js member require the JavaScript Templates gate.
You enable this gate yourself on each device at Settings > ZotLit > Advanced > Template engine. The CLI never changes it: a command that meets an Eta document while the gate is off fails with a diagnostic instead, and the agent must ask you to enable the setting.
Managed frontmatter
Managed frontmatter fields are YAML properties in literature note frontmatter whose values come from template expressions. ZotLit re-evaluates them on every note update.
The list of entries lives in the manifest of the profile document, in the order ZotLit writes them. Each entry names its language in the entry itself: expr for a Liquid expression, value for a JSON-e template, or js for a JavaScript expression behind the gate. The agent edits that list in the document with its file tools, and reads the result back through a check.
For manual configuration in the UI, see Configure frontmatter properties. For the entry members and the merge strategies, see the Profile document and the Frontmatter reference.
For the frontmatter rules as the shipped guide states them, use:
obsidian zotlit:template-guide topic=frontmatterTemplate Workbench CLI and Template Data Explorer
The Template Workbench CLI gives an agent data and in-memory rendering through the command line. The agent can then edit and check your template documents.
The Template Data Explorer is a visual sidebar for you. It lets you browse current template data and copy paths or snippets while editing templates yourself. See Explore template data for its panes and copy actions.
Both use the same data resolution and neither writes: browsing and rendering do not create notes, import attachments, or change settings.
Reaching the CLI
The Template Workbench registers its commands with Obsidian's own CLI. The namespace is zotlit, the plugin ID. These commands are desktop-only, like ZotLit itself, which requires Obsidian 1.15.1 or later.
Place the vault selector before the command name:
obsidian vault=MyVault zotlit:template-inspectvault= is accepted only in that position. A vault= after the command name is refused, because Obsidian ignores it there and routes the call by the working directory or the focused window instead.
These commands are not command-palette commands. Commands lists the commands that appear in the palette.
Use obsidian help zotlit for the namespace overview, and obsidian help zotlit:template-check for the flags of one command.
Live commands
Five commands answer. The Template Workbench registers nine further commands that are retired, and those answer only with a refusal.
| Command | Synopsis | Returns |
|---|---|---|
zotlit:template-inspect | obsidian zotlit:template-inspect [note=<vault-path>] [profile=<id-or-label>] [document=<path-or-reference>] [source=full] [editor] [expect-source=<source-id>] | Without a selector, the inventory of template documents by kind. With one selector, the document, its dependencies, source freshness, and problems, plus the complete source with source=full. Every answer also carries the vault and Zotero source identity and the profile diagnostics. |
zotlit:template-check | obsidian zotlit:template-check [profile=<id-or-label>] [key=<indexed-key>] [output=all]obsidian zotlit:template-check draft=/absolute/path/draft.md [profile=<id-or-label>] [key=<indexed-key>]obsidian zotlit:template-check attempt=<id> evidence=full [output=all] | The status of every checked component, the input revisions and source freshness, the attempt identity, and the outputs the call disclosed. It answers with a diagnostic when it refuses the document identity. |
zotlit:template-status | obsidian zotlit:template-status | The plugin version, the vault and Zotero source identity, the JavaScript Templates gate, the status of each template document, the legacy template slots while a conversion is pending, and every profile with its bindings. |
zotlit:template-data | obsidian zotlit:template-data root=<note|annotation|filename|citation> (key=<indexed-key> | note=<vault-path> | example=<example-id>) [query=<words> | path=<zt.path> | full] [format=json] [expect-source=<source-id>] | The template data of one root, under zt. query, path, and full widen the answer to focused discovery. |
zotlit:template-guide | obsidian zotlit:template-guide [topic=<name>] | The quickstart, or one guide topic, as plain text. |
A check runs every component regardless of output. output decides only which outputs the answer discloses, so a compact answer is not a check that stopped early.
An indexed key is a Zotero item key of eight characters, with an optional group suffix, as in ABCD1234g118. Copy a Zotero key describes the form.
Guide topics
obsidian zotlit:template-guide without a topic prints the quickstart. With topic=<name> it prints one reference section. A topic name outside this list is refused.
| Topic | Covers |
|---|---|
| No topic | The workflow, the synopsis, the identity and output rules, and the topic index. |
inspect | Target selection, source revisions and freshness, the inspect flags, and the inspect diagnostics. |
check | Create and update checks, baselines, drafts, output disclosure, and retained attempts. |
data | The template-data synopsis, each root, focused discovery, and the serialization markers. |
frontmatter | Managed frontmatter entries, JSON-e and spread entries, merge strategies, and reserved keys. |
profiles | The profile documents, their create and update semantics, and drafts. |
citations | Citation Variants and the built-in example sets. |
partials | Shared Partials, their caller roots, and their reserved names. |
troubleshooting | YAML repair, source freshness, reading a failed check, and legacy conversion. |
liquid | The supported Liquid tags and filters. |
eta | Eta templates and the JavaScript Templates gate. |
Retired commands
Nine commands remain registered so that a call to them answers usefully instead of failing as an unknown command. Each one answers ok: false with the COMMAND_RETIRED diagnostic, and carries the description "Retired: use template-inspect, template-data, and template-check". Every flag they once carried is now optional and described as a retired parameter.
| Retired command | Replaced by |
|---|---|
zotlit:template-schema | zotlit:template-inspect and zotlit:template-data |
zotlit:template-render | zotlit:template-check |
zotlit:template-document-render | zotlit:template-check |
zotlit:template-source | zotlit:template-inspect source=full |
zotlit:frontmatter-status | zotlit:template-check output=frontmatter |
zotlit:frontmatter-eval | zotlit:template-check output=frontmatter |
zotlit:frontmatter-set | Edit the profile document, then zotlit:template-check output=frontmatter |
zotlit:frontmatter-remove | Edit the profile document, then zotlit:template-check output=frontmatter |
zotlit:frontmatter-reorder | Edit the profile document, then zotlit:template-check output=frontmatter |
The replacement path is the same for all nine. Select the document with zotlit:template-inspect, edit the profile document with file tools, and verify the result with zotlit:template-check. Managed frontmatter is a list in the profile document manifest, not a setting.
Contract version
The namespace declares its own contract version, currently 8, once, with the answer envelope that every Template Workbench command answers through. Every answer carries it as contractVersion, the first field of the answer. Each ZotLit CLI namespace versions its contract on its own, so this number does not track any other namespace.
An installed skill states the version it was written against. Compare that pin with the contractVersion of the first answer. When the two differ, the skill is the stale one: read the live guide again, starting with obsidian zotlit:template-guide, and follow the live contract rather than the skill.
Answer envelope
Every answer except a successful zotlit:template-guide is a JSON string. The first three fields are always present:
{
"contractVersion": 8,
"command": "zotlit:template-check",
"ok": true
}| Field | Present | Meaning |
|---|---|---|
contractVersion | Every answer | The contract version of this namespace. |
command | Every answer | The command that answered. |
ok | Every answer | Whether the call succeeded. The rest of the answer is discriminated on this field. |
diagnostic | Failures | The fault, described below. A success never carries it. |
request | When a selector was resolved | The parsed request, echoed back. |
identity | When identity was resolved | vault.name, vault.path, source.id, and source.databasePath. |
template | When the command defines one | The template the answer concerns. |
warnings | When the command defines them | Non-fatal notes about the answer. |
The success and failure tails are separate shapes, so a failure cannot carry a result and a success cannot carry a diagnostic. When a call fails before the command resolves the vault and the Zotero source, the answer carries no identity.
Verify identity.vault and identity.source on every answer, and pass expect-source=<identity.source.id> when inspecting, discovering data, or running a new check. A supplied value that differs from the connected source answers TARGET_MISMATCH.
zotlit:template-guide prints plain text on success, not an envelope. Its failures are envelopes.
zotlit:template-inspect and zotlit:template-check build their own answers with the same three leading fields, and print a single line of JSON rather than the indented form the other commands use.
Diagnostic fields
| Field | Meaning |
|---|---|
code | The stable code, from the registry below. |
message | What went wrong, naming the offending parameter, path, key, or template. |
hint | The most specific recovery action to follow. |
severity | Always error. |
report | The diagnostic as an array of lines: the message, the place and the marked source line when the fault has one, and the recovery actions. Read it first. |
location | Optional place: span gives UTF-16 offsets from (inclusive) and to (exclusive) in the named source, path names a manifest field or parameter, argument a parameter. |
excerpt | Optional before, at, and after text on the source line; at is the marked text. |
found | The marked text or the received value, or an empty string. |
expected | The allowed values, or an empty array. |
suggestions | Candidate corrections, or an empty array. |
details | Optional context: parameter, a source expectation (target, expected, actual), key, or template with its 1-based line and column. |
These are the fields of a zotlit:query diagnostic too, so one reader serves both namespaces.
A report for a fault in a template, a document, or a frontmatter expression names the place and marks it:
undefined filter: bogus, line:2, col:1
--> note:2:1
{{ zt.creators | bogus: 1 }}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Correct "{{ zt.creators | bogus: 1 }}" at note:2:1, or the selected object, then run the command again.
Read the message to find the failed expression, correct the Template or the selected object, then run the command again.Every code in the registry is declared together with its default recovery action, and every diagnostic carries a hint. When the fault gives a more specific action, such as the place to correct, the file name of a missing partial, or the nearest configured frontmatter key, hint is that action and the default action is the last line of report. A rejected parameter can carry a recovery action of its own, such as the name=value form of a -- token. The caller follows the hint of the response.
Diagnostic codes
| Code | Meaning |
|---|---|
COMMAND_RETIRED | The command is retired from template document authoring. |
INVALID_SELECTOR | A parameter is missing, unknown, or holds a value the command does not accept. |
TARGET_MISMATCH | The connected Zotero source differs from expect-source. |
TEMPLATE_NOT_READY | Template compilation had not settled, or failed to start. |
KEY_NOT_FOUND | The indexed key is not in the connected Zotero source. |
NO_PARENT_ITEM | The selected object has no parent item. |
ANNOTATION_REQUIRED | The annotation root needs an Annotation key. |
ANNOTATION_ATTACHMENT_MISSING | The Annotation's parent Attachment is missing. |
ETA_OPT_IN_REQUIRED | The source needs JavaScript Templates, which is off on this device. |
TEMPLATE_COMPILE_ERROR | The template source does not compile. |
TEMPLATE_RENDER_ERROR | An expression failed while the template rendered. |
EXPRESSION_COMPILE_ERROR | A managed frontmatter expression does not compile. |
RESERVED_KEY | The key is managed by ZotLit. The retired frontmatter commands only. |
FIELD_NOT_FOUND | The key is not a configured managed frontmatter field. The retired frontmatter commands only. |
DOCUMENT_NOT_FOUND | A configured template document is missing. |
UNKNOWN_PROFILE_STAMP | The zotlit-profile stamp of a note does not resolve. |
DUPLICATE_MANAGED_BLOCK | The document carries more than one managed block. |
MISSING_ANNOTATION_SECTION | The document has no standalone --- zotlit:annotation --- header. |
DUPLICATE_ANNOTATION_SECTION | The document carries more than one --- zotlit:annotation --- header. |
UNKNOWN_SECTION_HEADER | A section header is not the exact standalone --- zotlit:annotation --- line. |
RESERVED_ANNOTATION_PARTIAL | The manifest declares a partial named annotation, which the Annotation Section reserves. |
DOCUMENT_INVALID | The document failed validation. |
RESERVED_PARTIAL_NAME | A Shared Partial file uses a reserved name. |
MISSING_PARTIAL | A called Shared Partial has no file. |
BUNDLED_PARTIAL | A partial is still carried in a profile document manifest. |
zotlit:template-inspect and zotlit:template-check declare further codes in their own guide topics, among them AMBIGUOUS_TARGET, TARGET_NOT_FOUND, NOT_LITERATURE_NOTE, SOURCE_NOT_LOADED, SOURCE_READ_FAILED, SOURCE_SUPERSEDED, EDITOR_TARGET_MISMATCH, INVALID_PROFILE_ID, PROFILE_ID_MISMATCH, ATTEMPT_NOT_FOUND, DRAFT_READ_FAILED, BASELINE_READ_FAILED, and BASELINE_SUPERSEDED. Read topic=inspect and topic=check for those. One code, duplicate-literature-notes, is lower case as it is raised.
Refusals
zotlit:template-check refuses a document whose identity your vault rejects, rather than reporting a check that passed. A refusal is not a failed check, and the answer says which one it is.
| Shape | Raised when | Carries |
|---|---|---|
| Refusal before parsing | The rule reads the filename, so no check runs. | No checks field. RESERVED_PARTIAL_NAME has this shape. |
| Refusal from parsing | The manifest ID fails the profile ID rule. | The checks map, with the failing check. INVALID_PROFILE_ID and PROFILE_ID_MISMATCH have this shape. |
Data access
The CLI reads Zotero metadata and annotation text, and renders templates in memory. No check writes a note, changes a profile, or imports an attachment, and the preview commands write no template document, note, or setting.
Your agent edits vault files through its own file tools, so those edits change the selected vault. See How the parts fit together for the workflow, and Install the ZotLit skills for the skill that drives this CLI.
Last updated on