Obsidian Vault
@magistr/obsidian-vaultv2026.07.27.1
01README
Manage Obsidian vaults headlessly from a mounted directory, or via the official CLI (v1.12+) — notes, search, tags, links, daily notes, frontmatter, corpus digest
02Release Notes
Merge pull request #56 from umag/feat/obsidian-vault-fs-backend
obsidian-vault: headless filesystem backend, bulk frontmatter merge, and corpus digest
03Models
@magistr/obsidian/vaultv2026.07.27.1extensions/models/obsidian_vault.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| vault? | string | Registered Obsidian vault name. Required for the CLI backend; also used to look up vaultRoot in Obsidian's vault registry when vaultRoot is not given. |
| vaultRoot? | string | Absolute path to the vault directory. Setting it enables the headless filesystem backend. Takes precedence over the registry lookup. |
| backend | enum | Which backend to use: 'auto' picks fs when vaultRoot is set and cli otherwise; 'cli' always shells to the Obsidian binary (needs the desktop app running); 'fs' always reads the vault directory and refuses methods that need Obsidian's index. |
| blockDotObsidian | boolean | Refuse to read or write inside .obsidian unless a method is called with allowDotObsidian=true. |
| defaultFileMode | number | Permission mode applied to files the filesystem backend creates. |
| defaultDirectoryMode | number | Permission mode applied to directories the filesystem backend creates. |
fn list(folder?: string, ext?: string, recursive?: boolean, limit?: number, allowDotObsidian?: boolean)
List notes in the vault (filesystem backend when vaultRoot is set)
| Argument | Type | Description |
|---|---|---|
| folder? | string | Filter by folder path |
| ext? | string | Filter by extension (e.g. 'md') |
| recursive? | boolean | Descend into subfolders (filesystem backend; default true) |
| limit? | number | Maximum files to return |
| allowDotObsidian? | boolean | Permit traversal of .obsidian and other hidden directories |
fn read(file: string, allowDotObsidian?: boolean)
Read a note's content
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note (e.g. 'folder/note.md') |
| allowDotObsidian? | boolean | Permit reading inside .obsidian |
fn fileInfo(file: string, allowDotObsidian?: boolean)
Show file metadata. Reports exists=false rather than failing when the note is absent.
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
| allowDotObsidian? | boolean |
fn create(name: string, content?: string, template?: string, overwrite?: boolean, allowDotObsidian?: boolean)
Create or replace a note. Reports created, updated, or unchanged; an unchanged note is not rewritten.
| Argument | Type | Description |
|---|---|---|
| name | string | Path for the note (e.g. 'folder/note.md' or 'note') |
| content? | string | Note content |
| template? | string | Template name to use (CLI backend only) |
| overwrite? | boolean | Overwrite if file exists |
| allowDotObsidian? | boolean |
fn append(file: string, content: string, separator?: string, inline?: boolean, allowDotObsidian?: boolean)
Append content to the end of a note
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
| content | string | Content to append |
| separator? | string | Text inserted between the existing content and the new content. Wins over inline; defaults to a newline. |
| inline? | boolean | Shorthand for separator="" (append with no separator) |
| allowDotObsidian? | boolean |
fn prepend(file: string, content: string, separator?: string, inline?: boolean, allowDotObsidian?: boolean)
Prepend content after the frontmatter
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
| content | string | Content to prepend |
| separator? | string | Text inserted between the new content and the existing content. Wins over inline; defaults to a newline. |
| inline? | boolean | Shorthand for separator="" (prepend with no separator) |
| allowDotObsidian? | boolean |
fn delete(file: string, permanent?: boolean, dryRun?: boolean, allowDotObsidian?: boolean)
Delete a note. Moves it to the vault's .trash by default on both backends.
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
| permanent? | boolean | Permanently delete instead of moving to trash |
| dryRun? | boolean | Report what would be removed without removing it |
| allowDotObsidian? | boolean |
fn move(file: string, to: string)
Move or rename a note, rewriting wikilinks (needs the Obsidian CLI)
| Argument | Type | Description |
|---|---|---|
| file | string | Current path |
| to | string | Destination folder or path |
fn search(query: string, folder?: string, path?: string, regex?: boolean, caseSensitive?: boolean, limit?: number, allowDotObsidian?: boolean)
Full-text search with matching line context
| Argument | Type | Description |
|---|---|---|
| query | string | Search query |
| folder? | string | Limit to folder |
| path? | string | Alias for folder |
| regex? | boolean | Treat the query as a regular expression (filesystem backend only) |
| caseSensitive? | boolean | Match case exactly (filesystem backend only) |
| limit? | number | Max matches to return |
| allowDotObsidian? | boolean |
fn digest(folder?: string, datePrefixes?: array, nameContains?: array, signalKeywords?: array, maxFiles: number, maxBodyChars: number, allowDotObsidian?: boolean)
Scan the vault once and produce a queryable structural digest — headings, wikilinks, tags, refs, word counts, and signal-keyword rollups
| Argument | Type | Description |
|---|---|---|
| folder? | string | Limit the scan to a folder |
| datePrefixes? | array | Only include files whose name starts with one of these prefixes |
| nameContains? | array | Only include files whose name contains one of these substrings |
| signalKeywords? | array | Keywords to count across note bodies, each hit recorded with its line |
| maxFiles | number | Stop after this many files and report truncated=true |
| maxBodyChars | number | Characters of body text to retain per note. Defaults to 0 — raising it copies note content into the swamp datastore. |
| allowDotObsidian? | boolean |
fn tags(counts?: boolean)
List all tags in the vault (needs the Obsidian CLI)
| Argument | Type | Description |
|---|---|---|
| counts? | boolean | Include occurrence counts |
fn tag(name: string)
List files with a specific tag (needs the Obsidian CLI)
| Argument | Type | Description |
|---|---|---|
| name | string | Tag name (e.g. '#swamp' or 'swamp') |
fn links(file: string)
Show outgoing links from a note (needs the Obsidian CLI)
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
fn backlinks(file: string)
Show files linking to a note (needs the Obsidian CLI)
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
fn orphans()
List notes with no incoming links (needs the Obsidian CLI)
fn unresolved(verbose?: boolean)
List unresolved/broken links in the vault (needs the Obsidian CLI)
| Argument | Type | Description |
|---|---|---|
| verbose? | boolean | Include source files |
fn daily()
Open or create today's daily note (needs the Obsidian CLI)
fn dailyRead()
Read today's daily note content (needs the Obsidian CLI)
fn dailyAppend(content: string, separator?: string, inline?: boolean)
Append content to today's daily note (needs the Obsidian CLI)
| Argument | Type | Description |
|---|---|---|
| content | string | Content to append |
| separator? | string | Text inserted before the new content. Wins over inline; defaults to a newline. |
| inline? | boolean | Shorthand for separator="" |
fn dailyPrepend(content: string, separator?: string, inline?: boolean)
Prepend content to today's daily note (needs the Obsidian CLI)
| Argument | Type | Description |
|---|---|---|
| content | string | Content to prepend |
| separator? | string | Text inserted after the new content. Wins over inline; defaults to a newline. |
| inline? | boolean | Shorthand for separator="" |
fn properties(file: string, allowDotObsidian?: boolean)
Read frontmatter properties of a note
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
| allowDotObsidian? | boolean |
fn propertySet(file: string, name: string, value: string, type?: enum, allowDotObsidian?: boolean)
Set a single frontmatter property on a note
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
| name | string | Property name |
| value | string | Property value (use a JSON array for list types, e.g. \ |
| type? | enum | Property type hint |
| allowDotObsidian? | boolean |
fn setProperties(file: string, properties: record, allowDotObsidian?: boolean)
Merge several frontmatter properties into a note in one call
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
| properties | record | Property map to merge. Values may be strings, numbers, booleans, null, or arrays. |
| allowDotObsidian? | boolean |
fn propertyRemove(file: string, name: string, allowDotObsidian?: boolean)
Remove a frontmatter property from a note
| Argument | Type | Description |
|---|---|---|
| file | string | Path to note |
| name | string | Property name to remove |
| allowDotObsidian? | boolean |
Resources
note(infinite)— Single note content and metadata
fileInfo(infinite)— File metadata (existence, size, timestamps)
notes(infinite)— List of notes/files in vault
searchResults(infinite)— Search results with matching context
tags(infinite)— Tag listing
tagFiles(infinite)— Files matching a specific tag
links(infinite)— Links or backlinks for a note
unresolved(infinite)— Unresolved/broken links in vault
dailyNote(infinite)— Daily note content
properties(infinite)— Note frontmatter properties
operationResult(infinite)— Result of mutating operations
corpus(infinite)— Structural digest of the vault: per-note headings, wikilinks, tags, refs and word counts, plus signal-keyword rollups
04Previous Versions
2026.07.16.2
Release 2026.07.16.2 — align model versions with manifests
Maintenance release across the @magistr extensions. For most packages this
carries no functional change: the only edit is the model's version: field,
brought back in line with its manifest version so the published model type
version and the package version no longer drift.
Functional changes in this release are limited to:
anime-cron: normalizeTitle now strips a ": subtitle" suffix and a trailing parenthesized year before comparison, fixing dedup false-misses where the torrent title carries a subtitle or year that the AniList romaji does not.
arckit: first publish. Standalone ArcKit port — a 12-phase architecture governance state machine with 65 bundled templates, driven by a bundled skill.
Also tracks three extensions (kaiten, observability-agent, music-library) that previously existed only as untracked working-tree directories, recovered from stashes.
Added 1, removed 1 models
2026.05.25.1
Merge pull request #4 from umag/extensions/magistr-grade-a-workspace
extensions: stage 15 @magistr extensions as Grade A workspace dirs + wire CI
2026.03.28.2
05Stats
A
100 / 100
Downloads
26
Archive size
101.1 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
Repository
https://github.com/umag/swamp-workspace06Platforms
07Labels