OpenVault Documentation

Install and initialize

OpenVault is a pip package that installs on macOS, Linux, and Windows. You'll have a working version control system in under a minute.

Install OpenVault:

pip install openvault

Navigate to the folder where your engineering files live (CAD models, drawings, BOMs, simulations, schematics, anything the team produces), then initialize:

openvault init

This creates an OpenVault repository in your current directory. You're ready to start tracking files.

Add your first file:

openvault add bracket.sldprt

Commit it with a message:

openvault commit -m "Initial bracket design"

That's the core workflow. Every file you add and commit becomes part of the history. You can see what you've done, when you did it, and why.

Core commands

openvault add

Stage a file for the next commit. You can add a single file or a pattern:

openvault add bracket.sldprt
openvault add *.step
openvault add .

openvault commit

Finalize the changes you've staged. Every commit gets a timestamp, your name, and a message explaining what you changed and why:

openvault commit -m "Bracket wall thickness reduced to 2mm per stress analysis"

openvault status

See what's changed since the last commit:

openvault status

Output shows modified files, untracked files, and files staged for the next commit. Check it before you commit so you know exactly what you're versioning.

openvault log

View the full history of your repository. Newest commits first:

openvault log

Each entry shows the commit message, author, timestamp, and a unique identifier. This is your audit trail. When someone asks what changed on a specific date, the log answers it directly.

openvault branch

Create a separate line of development. Use branches to explore design variants or try a refactor without touching the main design:

openvault branch redesign

Work in the branch, commit changes, and when you're confident, merge it back to main. If you decide against the approach, delete the branch and the main design is untouched.

openvault diff

Compare two revisions. See exactly what changed:

openvault diff HEAD~1 HEAD

For text-based files (drawings, specs, simulation scripts), diff shows line-by-line changes. For binary files (STEP, SolidWorks parts), OpenVault shows a summary of the differences and flags when a manual review is needed.

Working with large CAD files

SolidWorks parts, FreeCAD assemblies, STEP files, and other engineering outputs can be hundreds of megabytes. Storing hundreds of megabytes in every commit would make the repository huge and slow.

OpenVault uses Git LFS (Large File Storage) to handle this automatically. When you add a CAD file, OpenVault recognizes its type and routes it through LFS. The repository stays fast and clean while your files are tracked faithfully.

No configuration needed. OpenVault knows which file types are engineering binaries:

• SolidWorks: .sldprt, .sldasm
• STEP/IGES: .step, .stp, .iges, .ige
• FreeCAD: .FCStd
• STL: .stl
• Parasolid: .x_t, .x_b
• KiCad: .kicad_pcb, .kicad_sch
• Altium: .PcbDoc, .SchDoc
• And more

Add the file as normal:

openvault add assembly.sldasm

Commit and sync as usual. The file is stored efficiently while keeping its full revision history.

Security and data ownership

OpenVault is open source under the MIT license. The code is auditable. You can read it, inspect it, and verify exactly what it does with your files.

You control where your repository lives. OpenVault stores everything locally in a .openvault folder inside your project directory. You own that folder. You can keep it on your own machines, push it to a private Git server you run, or sync it to a cloud storage service of your choice. There's no account signup, no vendor lock-in, and no service that holds your data hostage.

Git's content-addressed history makes tampering evident. Every commit is identified by a hash of its contents. If someone modifies a file in an old commit, the hash changes, and the tampering becomes obvious. The entire history is interlocked so a change to any commit invalidates all subsequent commits. This isn't a security guarantee. It's a transparency guarantee. You can always verify the integrity of your history.

When your team grows and you want shared cloud repositories with web access, role-based permissions, and managed backups, Tool Crib Cloud adds that layer. But it's optional. The CLI works entirely offline and locally. You decide when and if you need cloud features.