Template Workbench CLI

How an agent inspects, tests, and checks template documents through the Obsidian CLI, and what the commands never write.

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 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 ZotLit skill sends the agent to this guide for current instructions.

For current command help, use:

obsidian help zotlit
obsidian zotlit:template-guide

What 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 Template Workbench CLI reference 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=frontmatter