How to Develop Obsidian Plugins and Themes Using the CLI Skill

The obsidian-cli skill streamlines Obsidian plugin and theme development by providing command-line tools to reload components, capture screenshots, inspect the DOM, and evaluate JavaScript directly within a running Obsidian instance.

The kepano/obsidian-skills repository offers a developer-focused automation layer that connects your terminal to the Obsidian desktop app via WebSocket. By leveraging the commands defined in skills/obsidian-cli/SKILL.md, you can script the entire edit-reload-verify workflow, turning tedious manual testing into a repeatable, terminal-driven process.

Core Architecture

The obsidian-cli skill acts as a bridge between your shell and the running Obsidian application. It communicates through a local WebSocket server managed by the official Obsidian CLI, translating your terminal commands into app actions.

According to the skill definition in skills/obsidian-cli/SKILL.md, the system uses key=value parameter syntax for all commands. You can target specific vaults using vault= parameters and reference files using either file= (wikilink style) or path= (absolute vault-relative) resolution methods.

Essential Development Commands

Reload Plugins After Code Changes

Use the plugin:reload command to hot-swap your plugin code immediately after saving changes in your external editor. This eliminates the need to manually disable and re-enable plugins through the Obsidian settings interface, significantly accelerating your development feedback loop.

obsidian plugin:reload id=my-plugin

As documented in skills/obsidian-cli/SKILL.md, this command instructs the Obsidian instance to unload and reload the specified plugin by its ID, applying your source code changes immediately without requiring an app restart. The command specifically targets the plugin by its unique identifier as defined in your manifest.json file, matching the reference implementation in the skill documentation.

Inspect Runtime Errors

After reloading your plugin, immediately check for runtime exceptions using the dev:errors command. This captures JavaScript stack traces and initialization failures that occurred during the reload process, presenting them in your terminal without opening Obsidian's developer tools.

obsidian dev:errors

This command queries the Obsidian console for any errors produced during the most recent reload operation, returning structured error data to your terminal. You can use this output to identify syntax mistakes, missing module dependencies, or API conflicts that prevent your plugin from initializing correctly.

Capture Visual Verification Screenshots

Validate UI changes programmatically with the dev:screenshot command, which renders the current Obsidian window to a PNG file. This enables automated visual regression testing and documentation generation without manual screen capture.

obsidian dev:screenshot path=./screenshots/after-reload.png

This is particularly valuable for regression testing themes or verifying plugin UI components across different workspace states. By specifying the output path parameter, you can systematically save interface states before and after modifications, creating a visual history of your development progress or evidence of bug fixes.

Query the DOM Programmatically

The dev:dom command lets you inspect specific HTML elements without opening the developer tools. Pass a CSS selector to retrieve text content, HTML markup, or element attributes directly to your terminal output.

obsidian dev:dom selector=".workspace-leaf" text

This capability enables automated assertions that your plugin correctly rendered its interface components. You can validate that expected DOM structures exist after reloading your code, ensuring your theme or plugin modifications produced the intended visual effects.

Execute JavaScript in App Context

Use the eval command to run arbitrary code within Obsidian's JavaScript environment and inspect runtime state. This provides deep visibility into plugin internals, settings objects, and application state without modifying source code to add temporary logging statements.

obsidian eval code="app.plugins.plugins['my-plugin'].settings.enableFeature"

The example above accesses the plugin instance directly through app.plugins.plugins. This demonstrates how you can verify configuration values or internal data structures during automated testing procedures without interrupting your development workflow.

Filter Console Output

For targeted debugging, the dev:console command filters log output by severity level. This surfaces only error-level messages from the Obsidian console, helping you distinguish critical failures from routine informational logs.

obsidian dev:console level=error

Automating the Development Workflow

Combine these commands into shell scripts to create automated verification pipelines. The following example demonstrates a complete edit-test cycle that validates plugin reloads, checks for errors, captures screenshots, and verifies DOM elements.

#!/usr/bin/env bash
set -e

# Reload the plugin after external editor changes

obsidian plugin:reload id=my-plugin

# Verify no errors occurred during reload

if ! obsidian dev:errors | grep -q "No errors"; then
  echo "Reload failed – fix errors and retry"
  exit 1
fi

# Capture visual verification

obsidian dev:screenshot path=./screenshots/after.png

# Verify specific UI component rendered

obsidian dev:dom selector=".my-widget" text

echo "✅ Plugin reloaded and verified successfully"

This workflow is documented in the skill definition under the plugin development workflow section of skills/obsidian-cli/SKILL.md, which outlines the standard edit-reload-verify loop used by Obsidian developers.

Summary

• The obsidian-cli skill in skills/obsidian-cli/SKILL.md provides terminal access to Obsidian's internal operations via WebSocket communication.
• plugin:reload hot-swaps plugin code without restarting the application.
• dev:errors and dev:console provide immediate feedback on runtime failures.
• dev:screenshot and dev:dom enable automated visual and structural verification.
• eval executes JavaScript within the Obsidian context for deep state inspection.
• All commands support vault= targeting and can be chained in shell scripts for CI/CD integration.

Frequently Asked Questions

What is the obsidian-cli skill?

The obsidian-cli skill is a markdown-based automation definition located in the kepano/obsidian-skills repository that wraps the official Obsidian CLI. It exposes developer commands for reloading plugins, inspecting errors, and querying the DOM from your terminal. By leveraging this skill, you can script the entire Obsidian development workflow without manual GUI interaction.

How do I target a specific vault when reloading plugins?

By default, commands affect the most recently focused vault in your Obsidian instance. To specify a different vault, append vault= to any command as defined in the vault targeting documentation within skills/obsidian-cli/SKILL.md. This parameter overrides the default selection, ensuring your development scripts target the correct environment when multiple vaults are open.

Can I use these commands in continuous integration pipelines?

Yes, because all obsidian-cli skill commands return standard exit codes and text output, you can integrate them into npm scripts, Makefiles, or CI pipelines. These automated workflows can execute screenshot comparisons, verify DOM selectors, and validate that plugins load without errors before deployment. The skill's support for path= and file= parameters also enables testing against specific vault configurations in isolated test environments.

Where are the command parameters documented?

The authoritative reference for all commands, parameter syntax using key=value pairs, and file resolution rules is skills/obsidian-cli/SKILL.md in the kepano/obsidian-skills repository. Lines 12 through 30 detail the parameter handling syntax, while lines 62 through 92 document the specific development commands including reload, error inspection, and screenshot capture. This file serves as the complete specification for the WebSocket communication protocol between your terminal and the Obsidian application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}