Obfuscidian

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.

Version and supported environments

Obfuscidian 1.0.0 is the first stable 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.

Install

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 obfuscidian

Reopen 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 --help

python -m obfuscidian offers the same behavior when that Python interpreter contains the package; your primary Python may not contain a pipx installation.

Update to a newer stable version

Keep the CLI current to receive features, fixes and security patches. Update the installation you actually run:

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.

First backup and restore

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-run

The 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.

Documentation

• 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/html

Open 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.

Development

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 build

Read 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.