FAQ
Common questions from people using Vellum in beta. For a linear first day, start with Getting started.
Getting oriented
What is Vellum?
A local-first notes app that combines an outliner, markdown prose documents, and typed tags (with fields) on nodes — including paragraphs inside documents.
Is there a community?
Yes, a Discord: vellumnotes.app/discord. Release notes show up there first, and it's the fastest place to get a question answered or report something broken.
Is my data local? Is there a Vellum cloud?
Your vault lives on your machine, and there is no Vellum cloud holding your notes. A few things do reach the network, and only when you use them. Capture from your phone travels through Telegram. The assistant sends your question to Claude. Vellum checks for a newer build when it starts.
Is there a web or mobile app?
Desktop only in the private beta (macOS, Windows, and Linux). For capture on the go, see Telegram.
Outline and documents
Outline vs document — what’s the difference?
An outline is a bullet tree. A document is continuous prose (closer to a writing app than to a block editor). A plain note becomes a document from its own menu, with Convert to document.
What is a description?
A dimmed line under a node’s title. It shows up wherever the node does (including search) and is searchable.
Links, tags, and fields
What is a tag?
More than a keyword. A tag can be a plain label, or a schema (fields) plus a tag page that lists everything wearing it, with views. See Dana, our first tag.
Do fields require a tag?
No. Fields can be vault-wide and reused on any node. Tag-owned fields still exist; when names collide you’ll see where they came from, e.g. Author (book) next to Author (article).
What's the difference between Add to, a mirror and a link?
A note lives in one place, the one shown above its title. A move changes that place. Add to puts the note on a shelf on another page and leaves it where you wrote it. A mirror shows the note itself in a second outline, and you can write in either place. A link just points at it, and the note lists it under Mentioned in. Where a note lives walks through all four with one example.
Search and queries
How does search work?
Cmd+P / Ctrl+P opens the search palette. Details and patterns are in Jump anywhere with Cmd-P; keys are on Keyboard shortcuts.
What are saved searches / live queries?
Reusable searches defined by rules. They can live in the sidebar, sit on a note as a saved search field (and unfold live results there), or narrow what a reference field’s picker offers (“Narrow to”).
How do I find everything under a note, or everything that links to it?
In a saved search, Under a note… (the Note hierarchy rule) finds everything nested under a note, however deep, mirrors included. Links to a note… (the Note links rule) finds every note whose words link to it. Note hierarchy and Note links walks through both, gathering a project's tasks from wherever they were written.
Daily notes, tasks, and capture
How do I jump to today?
Cmd+D / Ctrl+D.
What’s special about tasks?
#task is first-class. New tasks land on today by default, dates and priorities are fields, and a project page rolls up every task pointing at it. Checkbox rows and task tags work together, and heavier work often uses a project that collects tasks through a reference field.
What do the Tasks and Projects links open, and can I change them?
They open your #task and #project pages, and either can be pointed at another tag. Tasks and Projects explains what makes a tag a task tag (its Planning section) and how to point each link elsewhere.
Can a task repeat?
Yes. Type the repeat into the task's When box, like every mon, wed and fri, every month on the 1st or 7 days after done, or pick one from the calendar beside it. Repeating tasks covers setting, moving, pausing and stopping a repeat, and what to do when a day doesn't go to plan.
How do I capture from my phone?
Use the Telegram integration:
- Create a bot with BotFather and copy the token into Settings → Capture in Vellum.
- Open the bot chat and send the one-time security code Vellum shows you.
- After pairing, messages (and images / voice) go into your vault — by default on today. You can aim them with
@placeand#tagin the message.
Vellum must be running to ingest. If it’s closed, Telegram keeps messages for a while; when Vellum captures one it adds a thumbs-up in the chat.
Install, data in and out
Which platforms are supported?
macOS, Windows, and Linux desktops in the private beta.
How do updates work ?
When an update is available, you’ll receive an in-app notification. Click the link to download the latest version, then install it manually. Quit Vellum before updating and replace the old app with the new one. Your data will remain safe.
Mac says it can’t verify the app
Common with unsigned or frequently updated beta builds. Use your usual Gatekeeper bypass for apps you trust (for example open via right-click → Open the first time). You may need to do this again after each download until signing is sorted.
How to reset Vellum from scratch
- backup your existing stuff because a reset will obviously blow away all your data
- quit vellum (otherwise the database will not close cleanly)
- delete the vellum folder
- Mac: ~/Library/Application Support/Vellum
- Windows: %APPDATA%\Vellum (usually C:\Users<you>\AppData\Roaming\Vellum)
- Linux: ~/.local/share/vellum
- relaunch vellum - you'll get a new starter vault (be sure you've got your beta invite token handy)
How do I import notes?
Paste is the main path today. Vellum reads indentation and bullet markers, so nesting survives the trip. Flat markdown paragraphs tend to land as prose documents instead.
How do I export or back up?
Two things run automatically, and they do different jobs.
Your notes, written out as markdown files. In Settings > Markdown export, pick a folder and choose how often it runs: every 15 minutes, every hour, every six hours, or once a day. Hourly is the default. You can also run it by hand any time you want a fresh copy.
A copy of the vault itself. Vellum sets one aside every time it starts, without you doing anything.
Beta and product
How do I get into the beta?
Sign up at vellumnotes.app/beta.
Something wrong or missing? Open an issue or suggest an edit on the page.