Obfuscidian is a Python CLI for encrypted Obsidian vault backups. It stores individual Fernet-encrypted files and an encrypted path manifest in a separate mirror, then authenticates and restores the complete snapshot. Notes and binary attachments retain their exact bytes. The CLI is the supported public interface.
Obfuscidian 1.0.1 is a stable maintenance release and requires Python 3.12 or newer. The tested matrix covers Linux, macOS and Windows on Python 3.12–3.14. Linux/macOS support backup and restore writes. Native Windows supports key creation, verification and read-only planning; vault mutation/recovery and existing-log append fail closed. See supported environments.
Python 3.12+ is required. For use directly from Bash, zsh or PowerShell without activating an environment, pipx is recommended. With pipx installed, run in a POSIX shell:
python3.12 --version
pipx ensurepath
pipx install --python python3.12 obfuscidianReopen your terminal after PATH setup, then run obfuscidian --version and
obfuscidian --help from any folder. pipx manages an isolated Python environment
internally; you do not activate it. See installation
for pipx prerequisites, PowerShell commands, pip --user installation outside
a venv, local wheels and developer setup. For unattended use, follow
scheduled jobs and automation.
Alternatively, install into a venv:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install obfuscidian
obfuscidian --helppython -m obfuscidian offers the same behavior when that Python interpreter
contains the package; your primary Python may not contain a pipx installation.
Keep the CLI current to receive features, fixes and security patches. Update the installation you actually run:
| Installation | Update command |
|---|---|
| pipx, originally installed from PyPI | pipx upgrade obfuscidian |
| pipx, switching a source/wheel install to PyPI | pipx runpip obfuscidian install --upgrade obfuscidian |
| pip user install, outside a venv | python3 -m pip install --user --upgrade obfuscidian |
| Activated venv | python -m pip install --upgrade obfuscidian |
Use the original installation's Python; in PowerShell a user install may use
py -3.12 -m pip install --user --upgrade obfuscidian. Afterward, run
obfuscidian --version in your usual shell and check the exact executable used
by scheduled jobs. pipx needs no activation. A source/wheel pipx install normally
retains its original source for pipx upgrade; use runpip again for subsequent
PyPI updates, or follow the local-source instructions in
Updating Obfuscidian.
The CLI checks PyPI for newer stable versions and displays an advisory on stderr,
also recording it when an optional private operational log opens. Set
OBFUSCIDIAN_SUPPRESS_UPDATE_NOTICE=true or 1 to disable the request and notice.
Checks never install updates. Subscribe to repository releases through GitHub
Watch → Custom → Releases and read the changelog.
The notice links to update instructions.
The update guide covers all installation
methods, failed checks and competing PATH entries.
New to command-line backups? Start with What is Obfuscidian? and the Quickstart. The beginner pages introduce keys, backup choices and restore steps one topic at a time.
Follow the complete synthetic rehearsal before using a real vault. It creates a private key outside both vaults, previews and writes a fresh backup, verifies every object, restores to a new location and compares all bytes and directories.
For existing synthetic locations and their external key:
obfuscidian shroud fresh --origin ./vault --mirror ./mirror \
--key ./keys/obfuscidian-demo.key --non-interactive --dry-run
obfuscidian verify --mirror ./mirror --key ./keys/obfuscidian-demo.key --non-interactive
obfuscidian unshroud fresh --mirror ./mirror --origin ./restored \
--key ./keys/obfuscidian-demo.key --non-interactive --dry-runThe mirror must exist for verify and restore. Replace --dry-run with an intended
write only after review. --non-interactive never supplies replacement consent;
--yes does, without bypassing validation. Pause editing and sync during writes.
Keep a separate offline key backup: key loss prevents decryption, with no recovery
bypass. shroud merge retains deleted/renamed/excluded historical entries, so
those notes can return on restore. Fresh replacement retains previous payloads
outside the vault and Git; restore rollback contains sensitive plaintext.
Verification and dry runs create no application files or logs. Git merge restore
creates a separate review branch/worktree with differences left uncommitted;
Obfuscidian never stages, commits, merges or pushes them.
- Configuration and key custody
- Fresh/additive backup, verification and restore
- Command reference and output/privacy/logging
- Security and limits, private reporting policy and troubleshooting
- Contributor guide and changelog
Build the local Sphinx/reST/MyST site with the PyData theme (dark by default, with a reader-selectable light mode):
poetry install --with dev,docs
poetry run sphinx-build -W --keep-going -E -a -b html docs docs/_build/html
poetry run python .github/scripts/check_docs.py docs/_build/htmlOpen docs/_build/html/index.html. See documentation maintenance
for tutorial tests, rendered/accessibility review and optional external link checks.
This build does not publish or configure hosting.
Use Poetry 2.2 or newer, below 3.0. Runtime dependencies have one authoritative
list in pyproject.toml; poetry.lock records developer and optional docs tools.
The normal pytest suite is offline and uses only synthetic temporary fixtures.
poetry install --with dev
poetry check --lock --strict
poetry run ruff check .
poetry run ruff format --check .
poetry run pytest -q
poetry run bandit -r src/obfuscidian
poetry buildRead AGENTS.md and CONTRIBUTING.md before changing code. Keep work within the requested task and leave changes reviewable. Git history and publication actions require separate maintainer authorization. The project is licensed under Apache-2.0.
This utility is considered unofficial and is in no way endorsed or supported by Obsidian.