Pattern for exposing Obsidian plugin features via the Obsidian CLI

Canonical version: Pattern for exposing Obsidian plugin features via the Obsidian CLI.

Chris Gurney's Note Toolbar plugin for Obsidian has a clean answer to a question I care about for my own plugins: how do you expose plugin features through the Obsidian CLI ?

The pattern is a command handler registry. A single CliHandlers class owns a record mapping namespaced command names (note-toolbar:add-command, note-toolbar:add-break, ...) to bound async handler methods. The plugin prefix namespaces every command, so multiple plugins can coexist on the CLI without collisions.

The interesting points:

• One dispatcher, one handler per command. Each handler receives a parsed CliData object with the arguments, validates them, does the work, and returns a string.
• Strings in, strings out. Handlers never throw at the CLI boundary. Errors come back as localized message keys (via t()), so the CLI prints readable messages instead of stack traces, in the user's language.
• Shared argument helpers. resolveFileArgs() accepts both file and path arguments; addItemHelper() centralizes the common add-item flow and takes a type-specific callback for the differences. No copy-pasted validation across handlers.
• Machine-friendly output. List and status commands can emit TSV or CSV, which makes the output pipeable into other tools (and into AI agents).

What I like about this is that plugins that exposes their features through the CLI becomes scriptable AND agent-friendly.

References

• CliHandlers.ts (Note Toolbar plugin): https://github.com/chrisgurney/obsidian-note-toolbar/blob/master/src/Cli/CliHandlers.ts

Related

• Obsidian CLI
• Obsidian Starter Kit

About Sébastien

Ready to get to the next level?