Automation & Scripts

Last reviewed: 2026-10-22

Plainva has no plugin system that runs third-party code. Instead the vault itself is the extension interface: your notes are plain Markdown, databases are plain YAML (.base), and the OKF conventions give every file a predictable structure. Anything that can read and write files — a shell script, a Python program, a CLI tool, a scheduled job or an AI agent — can extend, generate or reorganize your vault without a single Plainva-specific API.

This page explains how to do that safely. The exact byte-level format of every file is documented separately in the File Format Reference; this page is the practical companion: the rules, the workflow, and what to hand an AI assistant.

Why files instead of a plugin sandbox

Security. A code-plugin system runs someone else’s program inside your editor with access to your notes. Plain files need no such trust: a script only ever touches the folder you point it at, with your operating system’s normal permissions.
Longevity. The format outlives the app. A Markdown file you generated with a script five years ago still opens today — in Plainva, in Obsidian, in any text editor. There is no plugin API to deprecate.
The format is the contract. Because the on-disk format is open and documented, the “API” is stable and inspectable. You can diff it, version it in Git, and reason about it.

If you want something Plainva does not do out of the box, you do not wait for a plugin — you write a small script against the files.

Reading a vault safely

Everything is UTF-8 text:

Notes (.md) — an optional YAML frontmatter block (between two --- lines at the very top) holds the properties; the Markdown body follows. Parse the frontmatter with any YAML library.
Databases (.base) — plain YAML describing views over notes. The values are never in the .base; they live in the notes’ frontmatter.
Structure — tags are #tag in the body or tags: in frontmatter; links are [[Note]] (wiki links) or [text](path.md). Tasks are - [ ] / - [x] list items.

Reading never needs care — text files cannot be “corrupted” by reading them. The rules below are all about writing.

Writing a vault safely

Follow these rules and Plainva (and Obsidian) will accept your changes cleanly. Plainva watches the vault folder: an external write is picked up and re-indexed automatically, usually within a second.

Write UTF-8. Give a new file LF line endings and no BOM — that is what Plainva writes. A file that already has CRLF line endings or a BOM may keep them: Plainva reads both and leaves them as they are, also when the note is edited or synced. The exception is a carriage return on its own as a line ending — what old Mac files have: Plainva reads such a file, but saves it with LF the first time it changes it. What it cannot read is another encoding — UTF-16 or Windows-1252, which some Windows tools write by default. Plainva does not open such a file: it shows This file is not text and offers it to the system’s program (Open in default app; on the phone Share), and nothing in Plainva writes a text over it — no save, no property, no link a rename rewrites. The Version history keeps it byte for byte, and restoring or duplicating it copies its bytes. To edit it in Plainva, save it as UTF-8 in the other program. If another program saves a file in another encoding while you have unsaved changes in it, Plainva keeps your changes beside it as a .CONFLICT file; the comparison then offers Replace current file with conflict copy, Keep both files and Delete conflict copy. A sync carries it over intact all the same — byte for byte, like an image: it is not merged, and if two devices changed it at the same time, your version is kept as a .CONFLICT file.
Write atomically. Write to a temporary file in the same folder, then rename it over the target. A half-written note (for example after a crash) is worse than no change. Plainva itself writes every note this way.
Preserve OKF frontmatter and unknown keys. Keep type and okf_version when you rewrite a note, and never drop frontmatter keys you do not recognize — round-trip them unchanged. Do not “tidy” keys you do not understand.
Never touch .plainva/. That folder holds Plainva’s device-local index, backups, graph pins and sync state. It is not part of your content and must never be written, synced or committed to Git by your scripts.
Respect the .base rules. A .base uses only Obsidian’s four top-level keys (filters, formulas, properties, views); every view needs a name; filters are single-rooted. All Plainva-specific data goes under nested plainva: sub-keys. The File Format Reference has the full contract, including a two-sided relations example.
Don’t fight the editor. If a note is open and has unsaved edits in Plainva, prefer not to rewrite it from a script at the same moment. Plainva has a conflict resolver as a safety net, but the cleanest path is to let the app save first (or edit notes that are not currently open).

Patterns

A few common jobs, all just file operations:

Bulk-create notes — generate .md files with an OKF frontmatter block (type, ideally generated: { by: <your-tool>/<version>, at: … }, plus your own properties) and a Markdown body. Since OKF 0.2, okf_version belongs in the root index.md only, not in the notes. Plainva indexes them as they appear.
Daily-note or report generators — a scheduled script that writes a dated note into your daily-notes folder, filled from another source.
Property sweeps — read every note’s frontmatter, transform a field, write it back (atomically, preserving unknown keys).
Export / publish — read the vault and render it to HTML, a static site or a PDF. Reading only — no rules to worry about.
Link maintenance — rescan [[Note]] links and tags: and produce a report, or fix them in place.

Keep scripts idempotent where you can: running twice should not duplicate content.

Handing the vault to an AI assistant

An AI agent with read/write access to a vault folder is exactly the case this design is built for. To let it work correctly:

Give it the File Format Reference. It is written for a machine reader: the OKF frontmatter contract, the property→YAML serialization, the full .base schema with its hard Obsidian rules, the index.md contract and the safety rules — everything an agent needs to edit files without breaking them.
Point it at the vault folder, not the .plainva/ folder. State clearly that .plainva/ is off-limits.
Ask for atomic, minimal edits. An agent that rewrites a whole note to change one property should preserve the rest of the frontmatter and body verbatim.

Because the contract is a document, not a live API, the same instructions work with any assistant, offline or online.

Safety recap

UTF-8, no BOM, LF.
Write atomically (temp file + rename).
Preserve type, okf_version and unknown keys.
Never write into .plainva/.
.base: four top-level keys, named views, single-rooted filters, plainva: sub-keys for everything else.
The vault is watched — external changes appear in Plainva automatically.