README.md (5726B)
1 # obsidian sync cli tool 2 3 a tool that does what the obsidian client does with obsidian sync but without said obsidian client 4 5 <img width="368" height="442" alt="grafik" src="https://github.com/user-attachments/assets/8bf43e28-bc42-40e7-b143-b74fce39c57a" /> 6 7 *yes that is my font* 8 9 ## mandatory please dont scream at me or the robotgirls 10 11 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. 12 13 *at some point once i have vetted this project enough i will make this notice less obstrusive. <3* 14 15 ## that being said! 16 17 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 18 19 ### why 20 21 i needed a sync tool for backup reasons and other reasons™️that didnt involve a fucking chromium browser please fix @obsidian 22 23 ## installation 24 25 ``` 26 pip install . 27 ``` 28 29 you'll also need `watchdog` for file watching (it's somehow not in the requirements file, oops): 30 31 ``` 32 pip install watchdog 33 ``` 34 35 requires python 3.11+. 36 37 ## setup 38 39 the easiest way to get started is the interactive tui: 40 41 ``` 42 python setup_tui.py 43 ``` 44 45 it'll walk you through logging in, picking a vault, setting a local path, and optionally installing a systemd service. it looks really cool actually like im shocked at how well textual works i should use it more 46 47 <img width="1098" height="580" alt="grafik" src="https://github.com/user-attachments/assets/57b99ba4-d5e4-45ed-9882-dfff4765aca4" /> 48 49 50 if you prefer doing things by hand: 51 52 ``` 53 obsidian-sync login 54 obsidian-sync setup 55 ``` 56 57 `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 58 59 ## usage 60 61 ``` 62 obsidian-sync login # log in to your obsidian account 63 obsidian-sync logout # log out and delete stored credentials 64 obsidian-sync info # show account info 65 obsidian-sync vaults # list all vaults on your account 66 obsidian-sync setup # configure a vault for syncing 67 obsidian-sync run <config.json> # run the sync daemon for a vault 68 obsidian-sync status <config> # show storage usage for a vault 69 ``` 70 71 for verbose output when running the daemon: 72 73 ``` 74 obsidian-sync run ~/.config/obsidian-sync/MyVault.json -v 75 ``` 76 77 ## systemd 78 79 ### user service (recommended) 80 81 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`: 82 83 ```ini 84 [Unit] 85 Description=Obsidian Sync Daemon 86 After=network-online.target 87 88 [Service] 89 ExecStart=obsidian-sync run /home/yourname/.config/obsidian-sync/MyVault.json 90 Restart=on-failure 91 RestartSec=10 92 93 [Install] 94 WantedBy=default.target 95 ``` 96 97 then: 98 99 ``` 100 systemctl --user daemon-reload 101 systemctl --user enable --now obsidian-sync 102 ``` 103 104 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. 105 106 ### system service 107 108 a system-level template unit is included at `obsidian-sync@.service`. install it and enable it per-user: 109 110 ``` 111 sudo cp obsidian-sync@.service /etc/systemd/system/ 112 sudo systemctl daemon-reload 113 sudo systemctl enable --now obsidian-sync@yourname 114 ``` 115 116 this expects the config at `~/.config/obsidian-sync/vault.json` and the binary at `/usr/local/bin/obsidian-sync`. 117 118 view logs either way with: 119 120 ``` 121 journalctl --user -u obsidian-sync -f 122 ``` 123 124 ## configuration 125 126 vault configs live at `~/.config/obsidian-sync/<VaultName>.json`. the fields: 127 128 | field | description | 129 |---|---| 130 | `vault_path` | local directory to sync into | 131 | `vault_password` | your end-to-end encryption password | 132 | `device_name` | how this device shows up in obsidian | 133 | `sync_images` | sync image files (default false) | 134 | `sync_audio` | sync audio files (default false) | 135 | `sync_video` | sync video files (default false) | 136 | `sync_pdf` | sync pdf files (default false) | 137 | `sync_app_settings` | sync `.obsidian/` settings folder (default true) | 138 | `ignore_folders` | list of folder paths to skip | 139 140 markdown, canvas, and base files are always synced. everything else is opt-in 141 142 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. 143 144 ## encryption 145 146 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. 147 148 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. 149 150 ## notes 151 152 - `.obsidian/workspace.json` and `.obsidian/workspace-mobile.json` are never synced (same behavior as the official client) 153 - hidden directories other than `.obsidian` at the vault root are skipped 154 - `node_modules` is always ignored 155 - the daemon reconnects automatically with exponential backoff (up to 5 minutes between retries) if the connection drops 156 - a token expiry error will stop the daemon permanently — just re-run `obsidian-sync login` and restart