Sync a folder with venom globe sync
Keep a local folder of markdown, such as an Obsidian vault, and a Venom Notes vault in step both ways. Edits on both sides are merged three ways, overlapping edits keep both copies, and deletes only go to a trash.
venom globe sync keeps a folder of markdown files on your machine and a Venom Notes vault in step. You can write in
Obsidian, VS Code or any editor, and the same notes stay in Notes for your team and your assistants. It works in both
directions: a change made here goes up, and a change made in Notes comes down.
venom cloud login # once: the key the sync uses
venom globe sync ~/notes --vault me # first run: links ~/notes to your personal vault
venom globe sync ~/notes # later runs remember the vault
venom globe sync ~/notes --watch # keep syncing until Ctrl-C
venom globe sync ~/notes --dry-run # show what would happen, change nothingOptions
| Flag | What it does |
|---|---|
[dir] |
The folder to sync. Defaults to the current directory |
--vault me|org |
me is your personal vault and org is the organisation's. You must give it on the first run; later runs read it from the folder. Changing the org vault needs org:manage, so without it the org vault syncs down only |
--once |
Sync once and exit. This is the default |
--watch |
Keep running. A sync starts when a file in the folder changes, or when the vault changes (the cloud is checked every --interval seconds, 15 by default, at least 5) |
--dry-run |
Print the plan (push, pull, merge, create, rename, delete) and change nothing on either side |
--delete |
When you delete a file here, move its note to the trash in Notes. Without it, the deletion is only reported |
The exit code is 0 when the sync finished, 1 when an operation failed, and 2 for a usage error, a missing login,
or a folder that is linked somewhere else.
The first run
The first run links the folder to the vault. It writes .venom-globe/state.json inside the folder. The file names the
cloud and the vault, and for each note it keeps the note id, the path, the version Notes had at the last sync, and a
hash of the content. .venom-globe/base/ holds the text of each note as it was at the last sync, which is the base
for the next merge. Do not edit either by hand. To link the folder to a different vault, delete .venom-globe.
On the first run:
- A file with no note at the same path in the vault is created there.
- A note with no file here is downloaded to
<path>.md, with its properties written as YAML frontmatter. - When a file and a note share a path, they are linked if their content is the same. If the content differs, both are kept: the file gets the vault's text, and your text is saved beside it as a conflict copy (see below).
Only .md files sync. Attachments such as images and PDFs are left alone in both directions. Notes keep their links
to uploads, and local image files are not uploaded. Hidden files and folders are skipped, including .obsidian, .git
and .trash, and so is node_modules. A file the vault cannot hold is skipped, and the reason is printed: a name with
\ : * ? " < > | # ^ [ ], or a body over 200 KB. Notes also refuses text that looks like a secret (an API key, a token,
a private key), and the sync reports that file as failed.
How changes move
Each run compares three things for every note: the file here, the note in Notes, and the base from the last sync.
| Here | In Notes | What happens |
|---|---|---|
| changed | unchanged | pushed |
| unchanged | changed | pulled |
| changed | changed | merged (see below) |
| renamed or moved | — | the note is renamed in Notes, and Notes rewrites the [[links]] that pointed to it |
| — | renamed or moved | the file is moved to match |
| deleted | unchanged | reported. With --delete, the note goes to the trash in Notes, where it stays for 30 days |
| deleted | changed | the vault's version is restored here |
| unchanged | deleted | the file is moved to .venom-globe/trash/<date>/ |
| changed | deleted | your file is uploaded again as a new note |
Renames are followed by note id, so a note keeps its history, backlinks and comments when you move it. In Notes a rename is always tracked. In the folder, a rename is recognised when the file shows up at its new path with the same content. A file that was renamed and edited in the same sync looks like a deletion plus a new file. If both sides renamed the same note, the folder's name wins.
Nothing is overwritten blindly. Every push sends the text it expects to replace, along with the version it saw, and Notes checks both under the note's lock. If someone changed the note in the meantime, through the editor, the API, MCP or another machine, the push is refused and the next pass merges the change instead. Writes go through the same save path as the editor and the API, so links, search, versions and the audit trail all update, and anyone who has the note open in Notes sees the change arrive live. In the note's history the change shows as your key's name "via venom globe sync".
Conflicts
When a note changed on both sides, the sync merges the two against the base, line by line, the way git merge does.
Edits to different lines are combined. When both sides made the same edit, it is kept once. Frontmatter properties
merge key by key.
When both sides changed the same lines in different ways, the merge is not clean, and the sync keeps both:
Note.mdgets the vault's version, so the people working in Notes see no change.- Your version is saved next to it as
Note (conflict 2026-11-08).md. If that name is taken, the copy gets a number:Note (conflict 2026-11-08 2).md.
The conflict copy is an ordinary file, so the same run uploads it as a note of its own. Neither side's text is lost.
To resolve the conflict, copy what you want into Note.md and delete the copy. If you sync without --delete, also
delete the copy's note in Notes.
Under the hood
The sync talks only to your own Venom Cloud, the URL venom cloud login saved (or VENOM_CLOUD_URL with
VENOM_CLOUD_KEY), and only while the command runs. It uses the key that login saved, which acts as you. A team key
has no personal vault and cannot sync me.
| Route | What |
|---|---|
GET /globe/api/sync?vault=me |
{ vault, canWrite, cursor, notes: [{ id, path, version }] }, the vault's notes without their text |
GET /globe/api/sync?vault=me&after=<cursor> |
{ cursor, more, changed, removed }: only the notes changed since the cursor (from the change log), and the ids that left the vault |
GET /globe/api/sync?vault=me&ids=a,b |
up to 50 notes in full: { notes: [{ id, path, version, body, properties }] } |
POST /globe/api/sync |
{ vault, ops }: 1 to 25 operations, applied in order, each succeeding or failing on its own. Answers { results: [{ ref?, id, ok, note?, error? }] } |
The operations are:
{ "op": "create", "ref": "Projects/Plan", "path": "Projects/Plan", "body": "…", "properties": { "tags": ["venom"] } }
{ "op": "update", "id": "…", "body": "…", "properties": {}, "path": "Projects/Moved/Plan", "expect": { "body": "the text you last saw", "version": "2026-11-08T10:00:00.000Z" } }
{ "op": "delete", "id": "…", "expect": { "version": "…" } }An update without expect.body is refused with 400. A stale update or delete returns 409 in its result,
with the code body_changed or version_conflict. A delete moves the note to the trash. The route takes
Authorization: Bearer <Venom API key> and never a cookie. It shares the Notes MCP server's limit of 120 requests a
minute per key. Past it the answer is 429 with Retry-After, and the CLI waits and retries.