commit ef59d2651e5ad4cdabdbd51e3289172bea6c459b
parent 9f80cf0e279e36a90325eb617588ebcb65d77392
Author: 442811 <42714028+dronesflier@users.noreply.github.com>
Date: Fri, 20 Feb 2026 13:11:51 +0100
Add README for obsidian sync CLI tool
Initial commit of README.md for obsidian sync CLI tool, detailing installation, setup, usage, systemd integration, configuration, and encryption.
Diffstat:
| A | README.md | | | 147 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 147 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -0,0 +1,147 @@
+# obsidian sync cli tool
+
+a tool that does what the obsidian client does with obsidian sync but without said obsidian client
+
+
+
+## mandatory please dont scream at me or the robotgirls
+
+i have to disclose something. this project was not programmed by hand. do not trust a single line of code written. if you actually lose data because you trusted a robot's code guided by a human who barely skimmed through it, then i really can't show too much sympathy.
+
+*at some point once i have vetted this project enough i will make this notice less obstrusive. <3*
+
+## that being said!
+
+that being said, i am actively using this and it works quite well. it's a cli plus systemd wrapper so you can just plug it into systemdearest and it'll sync in the background. it supports multiple (encrypted) vaults, logging into your account, and all the standard obsidian pushy pully just-a-fancy-git-repo-wrapper stuffies :b
+
+## installation
+
+```
+pip install .
+```
+
+you'll also need `watchdog` for file watching (it's somehow not in the requirements file, oops):
+
+```
+pip install watchdog
+```
+
+requires python 3.11+.
+
+## setup
+
+the easiest way to get started is the interactive tui:
+
+```
+python setup_tui.py
+```
+
+it'll walk you through logging in, picking a vault, setting a local path, and optionally installing a systemd service.
+
+if you prefer doing things by hand:
+
+```
+obsidian-sync login
+obsidian-sync setup
+```
+
+`login` will prompt for your email and password (and mfa code if you have that enabled (please dont have mfa enabled)). `setup` will list your vaults and ask which one you want, where to put it locally, your encryption password, and a device name.
+
+## usage
+
+```
+obsidian-sync login # log in to your obsidian account
+obsidian-sync logout # log out and delete stored credentials
+obsidian-sync info # show account info
+obsidian-sync vaults # list all vaults on your account
+obsidian-sync setup # configure a vault for syncing
+obsidian-sync run <config.json> # run the sync daemon for a vault
+obsidian-sync status <config> # show storage usage for a vault
+```
+
+for verbose output when running the daemon:
+
+```
+obsidian-sync run ~/.config/obsidian-sync/MyVault.json -v
+```
+
+## systemd
+
+### user service (recommended)
+
+the tui's "service" screen will generate and install a user service for you automatically. to do it manually, create `~/.config/systemd/user/obsidian-sync.service`:
+
+```ini
+[Unit]
+Description=Obsidian Sync Daemon
+After=network-online.target
+
+[Service]
+ExecStart=obsidian-sync run /home/yourname/.config/obsidian-sync/MyVault.json
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+```
+
+then:
+
+```
+systemctl --user daemon-reload
+systemctl --user enable --now obsidian-sync
+```
+
+for multiple vaults, the tui generates a small shell script that runs each vault's daemon in the background and waits on them, and points the service at that.
+
+### system service
+
+a system-level template unit is included at `obsidian-sync@.service`. install it and enable it per-user:
+
+```
+sudo cp obsidian-sync@.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now obsidian-sync@yourname
+```
+
+this expects the config at `~/.config/obsidian-sync/vault.json` and the binary at `/usr/local/bin/obsidian-sync`.
+
+view logs either way with:
+
+```
+journalctl --user -u obsidian-sync -f
+```
+
+## configuration
+
+vault configs live at `~/.config/obsidian-sync/<VaultName>.json`. the fields:
+
+| field | description |
+|---|---|
+| `vault_path` | local directory to sync into |
+| `vault_password` | your end-to-end encryption password |
+| `device_name` | how this device shows up in obsidian |
+| `sync_images` | sync image files (default false) |
+| `sync_audio` | sync audio files (default false) |
+| `sync_video` | sync video files (default false) |
+| `sync_pdf` | sync pdf files (default false) |
+| `sync_app_settings` | sync `.obsidian/` settings folder (default true) |
+| `ignore_folders` | list of folder paths to skip |
+
+markdown, canvas, and base files are always synced. everything else is opt-in.
+
+sync state is persisted to `<vault_path>/.obsidian/sync-state.json` between restarts so it doesn't have to re-examine everything from scratch each time.
+
+## encryption
+
+encryption is handled on-device using the same scheme as the obsidian client (reverse engineered from the 1.11.7 appimage). file contents are encrypted with aes-gcm and file paths with aes-siv, both keyed from your password via scrypt. the server never sees plaintext anything. encryption versions 0, 2, and 3 are all supported.
+
+if you enter the wrong password during setup, the tui will warn you by comparing your derived key hash against the one the server has on record.
+
+## notes
+
+- `.obsidian/workspace.json` and `.obsidian/workspace-mobile.json` are never synced (same behavior as the official client)
+- hidden directories other than `.obsidian` at the vault root are skipped
+- `node_modules` is always ignored
+- the daemon reconnects automatically with exponential backoff (up to 5 minutes between retries) if the connection drops
+- a token expiry error will stop the daemon permanently — just re-run `obsidian-sync login` and restart
