Template Workbench CLI

This reference lists the commands the Template Workbench registers in the Obsidian CLI, the answers they return, and the diagnostic codes they answer with.

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.14.2 or later.

Place the vault selector before the command name:

obsidian vault=MyVault zotlit:template-inspect

vault= 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.

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.

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.

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 7, 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": 7,
  "command": "zotlit:template-check",
  "ok": true
}

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

Every code in the registry is declared together with its recovery action, and every diagnostic carries that action as hint. A hint is therefore always present on a registry code, and the caller follows it.

Diagnostic codes

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.

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 Template Workbench for the workflow, and Install the ZotLit skill for the skill that drives this CLI.