playbooks

home / skills / nweii / agent-stuff / obsidian-cli

obsidian-cli skill

/skills/obsidian-cli

This skill enables terminal control of Obsidian via the obsidian CLI to automate vaults, create and open notes, search, and manage plugins.

npx playbooks add skill nweii/agent-stuff --skill obsidian-cli

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
5.2 KB
---
name: obsidian-cli
description: Control Obsidian from the terminal via the Obsidian CLI. Read, create, search, and manage notes, tasks, properties, and more. Includes vault structure commands (orphans, dead ends, backlinks, unresolved wikilinks), Bases, and plugin development.
compatibility: Requires the Obsidian desktop app
metadata:
  author: nweii
  version: "1.2.1"
---

# Obsidian CLI

Run `obsidian <command>` to control Obsidian from the terminal. The app must be running for most commands; the first command will launch Obsidian if not open.

Run `obsidian help` or `obsidian help <command>` for the canonical, always-up-to-date command reference. This skill documents common patterns and non-obvious behaviors.

## Targeting vaults and files

- **Vault**: `vault=<name>` as first parameter. Default: cwd if it's a vault folder, else the active vault.
- **File**: `file=<name>` resolves like a wikilink (name only, no path or extension needed). `path=<path>` for exact path from vault root.
- **TUI**: Run `obsidian` with no args for interactive mode; omit the `obsidian` prefix inside.

## Parameters and flags

- **Parameters**: `param=value`. Quote values with spaces: `content="Hello world"`.
- **Flags**: Boolean, no value: `silent`, `overwrite`, `newtab`.
- **Multiline content**: Use `\n` for newlines, `\t` for tabs in `content=`.

## Search, links, and structure

```bash
obsidian search query="text" [path=folder] [limit=n] [format=text|json] [total] [case]
obsidian search:context query="text" [path=folder] [limit=n]  # includes surrounding context
obsidian links [file=Note] [total]
obsidian backlinks [file=Note] [counts] [total]
obsidian outline [file=Note] [format=tree|md]
obsidian orphans [total] [active]       # notes with no links to or from them
obsidian deadends [total] [active]      # notes with no outgoing links
obsidian unresolved [total] [counts] [verbose]  # broken wikilinks
obsidian tags [active] [file=Note] [total] [counts] [sort=count]
obsidian tag name=project [total] [verbose]
```

## Common patterns

### Notes and content

To peek at a note without reading its full content, use `property:read` or `properties file=Note`.

```bash
obsidian read file="Note" # Use this to read the content of a wikilink
obsidian create name="Note" content="# Title\n\nBody" [template=Name] [overwrite] [silent]
obsidian append file="Note" content="- [ ] Task"
obsidian prepend file="Note" content="# Header\n"
obsidian move file="Note" to=folder/newpath.md
obsidian rename file="Note" name="New file name"
obsidian delete file="Note"
```

### Daily notes (Daily notes plugin)

```bash
obsidian daily:read
obsidian daily [paneType=tab|split|window] [open]
obsidian daily:append content="- [ ] Buy groceries" [inline] [open]
obsidian daily:prepend content="- [ ] Morning routine" [inline]  # goes after frontmatter
obsidian daily:path  # returns expected path even if file doesn't exist yet
```

### Tasks

```bash
obsidian tasks [daily] [file=Note] [todo] [done] [status="x"] [total] [verbose]
obsidian task ref=path:line [toggle] [done] [todo] [daily]
```

### Properties and frontmatter

```bash
obsidian properties [active] [file=Note] [total] [counts] [format=yaml|json|tsv]
obsidian property:read name=status [file=Note]
obsidian property:set name=status value=done [file=Note]
obsidian property:remove name=status [file=Note]
```

### Bases (Bases plugin)

```bash
obsidian bases
obsidian base:views [file=base.base]
obsidian base:query [file=base.base] [view=name] [format=json|csv|tsv|md|paths]
obsidian base:create name="Item" content="..." [open] [newtab]
```

## Developer commands

Reload a plugin after code changes — essential for the develop/test cycle:

```bash
obsidian plugin:reload id=my-plugin
obsidian eval code="app.vault.getFiles().length"
obsidian dev:screenshot path=screenshot.png
obsidian dev:dom selector=".cm-editor" [text] [attr=class]
obsidian dev:css selector=".cm-editor" [prop=color]
obsidian dev:console [clear] [limit=10] [level=log|warn|error]
obsidian dev:errors [clear]
```

## Quick reference

| Task                       | Command                                      |
| -------------------------- | -------------------------------------------- |
| List commands              | `obsidian help`                              |
| Open daily note            | `obsidian daily`                             |
| Append to daily            | `obsidian daily:append content="- [ ] Task"` |
| Search vault               | `obsidian search query="text"`               |
| Read active/specified file | `obsidian read` or `obsidian read file=Note` |
| Create from template       | `obsidian create name="Title" template=Name` |
| List tags with counts      | `obsidian tags counts`                       |
| List tasks from daily      | `obsidian tasks daily`                       |
| Find broken wikilinks      | `obsidian unresolved counts`                 |
| Find orphan notes          | `obsidian orphans`                           |

## References

- `obsidian help` — full command list (always up to date)
- `obsidian help <command>` — help for a specific command
- [Obsidian CLI docs (Obsidian)](https://raw.githubusercontent.com/obsidianmd/obsidian-help/refs/heads/master/en/Extending%20Obsidian/Obsidian%20CLI.md)

Overview

This skill exposes a terminal-first interface to control Obsidian for automating vault workflows, notes, searches, tasks, and plugin development tasks. It works by sending commands to the running Obsidian app (it will launch the app if needed) and accepts parameters, flags, and file/vault targeting. Use it to script note creation, modify frontmatter, run developer tools, and integrate Obsidian into CI or local automation.

How this skill works

Commands follow the form obsidian <command> with param=value pairs and boolean flags. Target a specific vault with vault=<name>, a note by file=<name> (wikilink resolution) or path=<relative/path.md>, and pass multiline content with \n. Many commands require the Obsidian app to be running; the first CLI invocation starts it when necessary.

When to use it

  • Automate creating, appending, or updating notes from scripts or agents.
  • Run batch searches, list files, or extract metadata for external tools.
  • Manage tasks, tags, backlinks, and frontmatter programmatically.
  • Drive plugin development and debugging using dev: and eval commands.
  • Trigger daily notes, workspaces, or vault-level operations from CI or cron jobs.

Best practices

  • Prefer path=<path> for precise file targeting when duplicates or similar names exist.
  • Quote param values that contain spaces and use \n for newlines in content=.
  • Use flags like silent and overwrite intentionally; avoid overwrite on important notes.
  • For automation, combine search, read, and create commands with exit codes to detect failures.
  • Use dev:console, dev:errors and dev:screenshot for reproducible plugin debugging steps.

Example use cases

  • Create a meeting note from a template: obsidian create name="Meeting" template=Meetings content="..."
  • Append a todo to today's daily note: obsidian daily:append content="- [ ] Call vendor"
  • Export a list of files in a folder for external processing: obsidian files folder=projects ext=md format=json
  • Toggle a task by file reference: obsidian task ref=notes/project.md:42 toggle
  • Run a plugin reload during development: obsidian plugin:reload id=plugin-id

FAQ

Do I need Obsidian open to use the CLI?

Most commands require the app to be running; the first CLI call will launch Obsidian if it isn't already open.

How do I target a specific note reliably?

Use path=<relative/path.md> for exact targeting. file=<name> resolves wikilinks and is convenient but can match multiple notes.