Editing the config in the app

The desktop app’s Vault config editor edits .cuaderno/config.toml without leaving the app. It reads the file, edits it two ways, validates every change before it touches disk, and reloads the live vault the moment the config changes — whether the change came from the app or from your editor.

This page covers using the editor. For what each key means, see Configuration and the Configuration reference.

Open it with ⌘, and pick Vault config from the settings rail. Configuration is not content, so it lives in Settings rather than in the sidebar beside your notes.

Raw and Form

The editor opens on a Raw / Form toggle:

• Raw is the whole config.toml in a text editor. Everything is editable here, byte for byte — it is the escape hatch for anything the Form doesn’t cover.
• Form is a structured view of the parts that have a fixed shape: note types, their schema extensions, and the template variables block. You add, rename, and remove custom note types and required frontmatter fields with inputs and toggles instead of hand-writing TOML. Each schema field’s row also exposes its setter behaviour: Settable (whether set_frontmatter may change the field) and Log changes to daily (auto-log each change to the daily note — available once the field is settable). The Template variables section edits the two variable maps: Static (values available in every template) and Prompted (asked for interactively when a template uses them).

Switch freely between them; both edit the same file. What the Form can’t represent stays in Raw (see What the Form doesn’t edit below).

The never-brick save

A vault whose config.toml fails to parse or validate won’t open — so the editor is built so you cannot save it into that state from the app.

Every save, from either view, runs the exact validation the app runs when it opens a vault: the TOML is parsed, the ignore globs are compiled, and the type registry is validated. Only if all three pass does the save proceed. A failure is reported inline — with the line and column for a syntax slip — and nothing is written. The file on disk is never the broken version.

The Raw view also has a Check button that dry-runs the same validation without saving, so you can confirm a hand-edit before you commit to it.

Edits are surgical

Saving from the Form does not rewrite the whole file. It applies a targeted edit to just the table you changed, so your comments, key order, and formatting elsewhere survive untouched. Adding a required field rewrites only that one table; renaming a note type removes the old table and writes the new one — nothing else is touched.

Conflict detection

If the file changed on disk between the app reading it and your save — say you edited it in your editor in the meantime — the save is refused rather than silently overwriting the other change. The app tells you the file moved under it; reload to pick up the on-disk version, then reapply your edit.

Live reload

The app watches .cuaderno/config.toml. When it changes on disk — you edited it in nvim, ran a CLI command, or another tool touched it — the app rebuilds the vault against the new config and refreshes every view, no restart needed. The status line confirms the reload.

If an external edit leaves the config invalid, the app keeps the last good vault live and shows the validation error instead of the reload, so a bad hand-edit never takes the app down with it — fix the file and the next save reloads cleanly.

What the Form doesn’t edit

The Form covers note types, schema extensions, and template variables. A few things stay Raw-only by design:

• max_active_projects under [vault], and the top-level ignore globs — edit these in Raw.

Everything Raw-only is still covered by the never-brick save and live reload; only the structured inputs are absent.

This is not the only thing that writes the config

A stewardship’s trend charts carry a chart-type picker that persists into [tracking.<activity>.metrics.<name>], so a control that looks like a view setting makes a durable change to .cuaderno/config.toml. It stages locally and writes nothing until you use its explicit save, and that save runs through everything on this page — validation, the compare-and-swap against what is on disk, and the live reload afterwards. See the desktop app tour for what the picker does.

The reason it goes through the same gate rather than writing directly is the one this page is about: there is a single way config reaches disk, so an edit made from a chart cannot skip a check an edit made here would have to pass.

Next: the concepts behind these keys in Configuration, or the hands-on Customising templates and frontmatter tutorial.