A powerful command-line tool for managing and maintaining Obsidian vaults. Keep your knowledge base clean, organized, and healthy!
- 🧹 Smart Cleaning: Remove empty directories, temporary files, and short/orphaned files
- 📊 Analytics: Generate comprehensive vault analysis reports with statistics, tags, and file insights
- 🔄 Undo System: 30-day operation history with safe rollback capability
- 💾 Git Integration: Automatic backup before destructive operations
- 🎯 Interactive Mode: Git-style interactive file selection for precise control
- 🔍 Health Check: Validate vault structure and detect potential issues
- 📝 YAML Metadata: Preview and manage frontmatter across your vault
Option 1: Auto Install (Recommended)
# Clone into your vault's _vaultcli directory
cd /path/to/your/vault
mkdir -p _vaultcli
cd _vaultcli
git clone https://github.com/macshion/vault-janitor.git .
# Run installer (handles dependencies and alias)
chmod +x install.sh
./install.shOption 2: Manual Install
# Clone anywhere you like
git clone https://github.com/macshion/vault-janitor.git
cd vault-janitor
# Install dependencies
pip3 install -r requirements.txt
# Create alias (replace with your actual path)
echo 'alias vault="python3 $(pwd)/vault.py"' >> ~/.zshrc
source ~/.zshrc# Navigate to your Obsidian vault
cd /path/to/your/vault
# Check vault health
vault check
# View statistics
vault stats
# Optional: Customize configuration
cp _vaultcli/vault.config.yaml _vaultcli/vault.config.yaml.custom
vim _vaultcli/vault.config.yaml.custom# View vault statistics
vault stats
# Check vault health
vault check
# Generate analysis report (Markdown + JSON)
vault report
vault report -f json # JSON only
vault report -f both -o # Both formats and open
# Clean your vault (with preview)
vault --dry-run clean
# Interactive cleaning (Git-style selection)
vault clean -i
# Create Git backup
vault backupThe clean command helps you maintain a tidy vault:
- Empty directories: Removes directories without any files
- Temporary files: Deletes system files (.DS_Store, .tmp, .swp, etc.)
- Short files: Identifies files with less than 100 characters (configurable)
# Preview what will be cleaned
vault --dry-run clean
# Interactive mode - choose what to clean
vault clean -i
# Skip Git backup (not recommended)
vault clean --no-backupEvery destructive operation creates an undo log (kept for 30 days):
# List available undo logs
vault undo --list
# Undo a specific operation
vault undo undo_clean_2025-11-29_21-30-02.json
# Force undo even if conflicts exist
vault undo <log_file> --force
# Clean expired undo logs
vault undo --cleanGenerate comprehensive vault analysis:
vault reportReport includes:
- 📊 Overall statistics (file count, size, word count)
- 📝 Document metadata (YAML coverage, tag usage)
- 📁 File type distribution
- 🏷️ Top 30 most used tags
- 📂 Directory statistics
- 📈 Largest files (Top 20)
- 🕒 Recently modified files (Top 20)
Create vault.config.yaml in your vault root:
global:
dry_run: false # Global dry-run mode
auto_backup: true # Auto Git backup before changes
generate_undo_log: true # Generate undo logs
undo_retention_days: 30 # Keep undo logs for 30 days
auto_clean_undo: true # Auto-clean expired logs
git:
enabled: true
remote_url: "git@github.com:username/vault.git"
auto_push: true # Auto push after backup
clean:
delete_extensions: # File extensions to delete
- .DS_Store
- .gdoc
- .gsheet
- .icloud
- .swp
- .tmp
- .bak
short_file_threshold: 100 # Files with fewer chars
exclude_dirs: # Directories to skip
- .obsidian
- .trash
- .git
- node_modules
folder_structure: # Expected vault structure
- "01_Inbox"
- "03_Knowledge"
- "04_Projects"
- "05_Content"
- "06_IdeaVault"
- "assets"
- "_z_logs"| Command | Description | Options |
|---|---|---|
vault stats |
Display vault statistics | - |
vault check |
Verify vault health | - |
vault clean |
Clean vault | -i interactive, -d dry-run |
vault report |
Generate analysis report | -f format, -o open |
vault backup |
Create Git backup | - |
vault undo |
Manage undo operations | --list, --clean, -f force |
Available for all commands:
--dry-run, -d # Preview mode, no actual changes
--yes, -y # Skip confirmation prompts
--force, -f # Force operation, overwrite conflicts
--no-backup # Skip automatic Git backup
--interactive, -i # Interactive modevault-janitor/
├── vault.py # Main CLI entry point
├── vault.config.yaml # Configuration template
├── commands/ # Command implementations
│ ├── clean.py # Cleaning operations
│ ├── report.py # Report generation
│ └── undo.py # Undo operations
├── core/ # Core modules
│ ├── cleaner.py # Vault cleaning logic
│ ├── git_manager.py # Git integration
│ ├── undo_manager.py # Undo system
│ └── interactive.py # Interactive selector
├── config/
│ └── settings.py # Configuration loader
├── README.md
├── QUICKSTART.md
└── LICENSE
- Dry-run mode: Preview all operations before execution
- Undo logs: All destructive operations are logged and reversible
- Git backup: Automatic commits before making changes
- Protected directories: Never deletes
.obsidian,.git,_vaultcli, etc. - Path validation: Ensures operations stay within vault boundaries
- Python 3.7+
- click >= 8.0.0
- pyyaml >= 6.0
- Git (for backup features)
Install dependencies:
pip install click pyyamlContributions are welcome! Here's how you can help:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Inspired by the Obsidian community
- Built with Click framework
- Git-style interactive selection inspired by
git add -p
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Plugin system for custom cleaners
- Link validation and orphan detection
- Bulk file renaming utilities
- Export to PDF/HTML
- Graph analysis tools
- Multi-vault support
⭐ Star this repo if you find it useful!
Made with ❤️ for the Obsidian community