CLI Reference
CLI Reference
Complete reference for all 60+ Dits commands covering core Git operations, creative workflows, enterprise features, and advanced version control for large binary assets.
Important
Local commands work today; networked commands are roadmap. The local Dits CLI (init, add, commit, branch, diff, log, VFS, video, and the rest) is implemented and covered by 469 automated tests. The networked commands —
push, pull, fetch, sync, clone, remote, and p2p — are on the roadmap and not built: they print placeholders and transfer no data. Rows marked roadmap in the table below are not yet available.Global Options
These options can be used with any command:
-v, --verbose Increase output verbosity (use -vv for debug)
-q, --quiet Suppress non-essential output
--no-color Disable colored output
--json Output in JSON format (for scripting)
-C <path> Run as if dits was started in <path>
--config <key=val> Override config value for this command
-h, --help Show help for command
--version Show dits versionCommand Categories
Commands are organized into logical categories. Click on a category to see detailed documentation for each command.
Quick Reference Table
All commands at a glance. Use the category pages above for detailed documentation with examples and options.
| Command | Description | Category | Status |
|---|---|---|---|
| init | Initialize a new repository | Repository | stable |
| clone | Clone a repository (networked — roadmap, prints a placeholder) | Repository | roadmap |
| remote | Manage remote repositories (networked — roadmap) | Repository | roadmap |
| status | Show working tree status | Repository | stable |
| add | Add files to staging area | Files | stable |
| restore | Restore working tree files | Files | stable |
| diff | Show changes between commits | Files | stable |
| commit | Record changes to the repository | History | stable |
| log | Show commit history | History | stable |
| show | Show various types of objects | History | stable |
| tag | Create, list, or delete tags | History | stable |
| branch | List, create, or delete branches | Branches | stable |
| switch | Switch to a branch | Branches | stable |
| checkout | Switch branches or restore files | Branches | stable |
| merge | Merge branches | Branches | stable |
| stash | Stash changes temporarily | Branches | stable |
| reset | Reset HEAD to a specific state | Branches | stable |
| rebase | Rebase commits | Advanced Git | stable |
| cherry-pick | Apply specific commits | Advanced Git | stable |
| bisect | Binary search for bugs | Advanced Git | stable |
| reflog | Show reference logs | Advanced Git | stable |
| blame | Show authorship by line | Advanced Git | stable |
| show | Show various types of objects | Advanced Git | stable |
| grep | Search repository content | Advanced Git | stable |
| worktree | Manage multiple worktrees | Advanced Git | stable |
| sparse-checkout | Check out only specified paths | Advanced Git | stable |
| hooks | Manage Git hooks | Advanced Git | stable |
| archive | Create archives | Advanced Git | stable |
| describe | Describe commits with tags | Advanced Git | stable |
| shortlog | Summarize git log output | Advanced Git | stable |
| maintenance | Run maintenance tasks | Advanced Git | stable |
| completions | Generate shell completions | Advanced Git | stable |
| push | Push changes to remote (networked — roadmap, prints a placeholder and transfers no data) | Remotes | roadmap |
| pull | Fetch and integrate changes (networked — roadmap, prints a placeholder and transfers no data) | Remotes | roadmap |
| fetch | Download objects and refs (networked — roadmap, prints a placeholder and transfers no data) | Remotes | roadmap |
| sync | Bi-directional sync (networked — roadmap, prints a placeholder and transfers no data) | Remotes | roadmap |
| lock | Lock files for exclusive editing | Locks | stable |
| unlock | Release file locks | Locks | stable |
| locks | List active locks | Locks | stable |
| mount | Mount repository as VFS | VFS | stable |
| unmount | Unmount virtual filesystem | VFS | stable |
| cache-stats | Show VFS cache statistics | VFS | stable |
| inspect | Inspect MP4/MOV structure | Video | stable |
| inspect-file | Inspect file dedup stats | Video | stable |
| segment | Segment video into chunks | Video | stable |
| assemble | Reassemble segmented video | Video | stable |
| roundtrip | Test MP4 deconstruct/reconstruct | Video | stable |
| video-init | Initialize video timeline project | Video | stable |
| video-add-clip | Add clip to video timeline | Video | stable |
| video-show | Show a video timeline | Video | stable |
| video-list | List all video projects | Video | stable |
| proxy-generate | Generate proxy files for videos | Proxies | stable |
| proxy-status | Show proxy generation status | Proxies | stable |
| proxy-list | List all generated proxies | Proxies | stable |
| proxy-delete | Delete generated proxies | Proxies | stable |
| meta-scan | Scan and extract file metadata | Metadata | stable |
| meta-show | Show metadata for a file | Metadata | stable |
| meta-list | List all stored metadata | Metadata | stable |
| dep-check | Check project file dependencies | Dependencies | stable |
| dep-graph | Show dependency graph | Dependencies | stable |
| dep-list | List all project files | Dependencies | stable |
| freeze-init | Initialize lifecycle tracking | Storage | stable |
| freeze-status | Show storage tier status | Storage | stable |
| freeze | Move chunks to colder storage | Storage | stable |
| thaw | Restore chunks from cold storage | Storage | stable |
| freeze-policy | Set or view lifecycle policy | Storage | stable |
| encrypt-init | Initialize repository encryption | Encryption | stable |
| encrypt-status | Show encryption status | Encryption | stable |
| login | Login to unlock encryption keys | Encryption | stable |
| logout | Logout and clear cached keys | Encryption | stable |
| change-password | Change encryption password | Encryption | stable |
| audit | Show audit log | Audit | stable |
| audit-stats | Show audit statistics | Audit | stable |
| audit-export | Export audit log to JSON | Audit | stable |
| gc | Run garbage collection | Maintenance | stable |
| fsck | Verify repository integrity | Maintenance | stable |
| repo-stats | Show repository statistics | Maintenance | stable |
| config | Get and set configuration | Maintenance | stable |
| telemetry enable | Enable telemetry data collection | Telemetry | stable |
| telemetry disable | Disable telemetry data collection | Telemetry | stable |
| telemetry status | Show current telemetry settings | Telemetry | stable |
Environment Variables
Dits behavior can be customized through environment variables. These are useful for scripting, CI/CD pipelines, and advanced configuration.
| Variable | Description | Example |
|---|---|---|
| DITS_DIR | Override .dits directory location | /custom/path/.dits |
| DITS_WORK_TREE | Override working tree location | /path/to/worktree |
| DITS_CACHE_DIR | Override cache directory | ~/.cache/dits |
| DITS_CONFIG_GLOBAL | Override global config path | ~/.config/dits/config |
| DITS_EDITOR | Editor for commit messages | vim |
| DITS_PAGER | Pager for output | less -R |
| DITS_TOKEN | Authentication token for remotes | dits_xxxxx |
| DITS_SERVER | Default server URL | https://dits.example.com |
| DITS_DEBUG | Enable debug output | 1 |
| DITS_TRACE | Enable trace logging | 1 |
Exit Codes
Dits uses standardized exit codes for scripting and automation. These codes help identify what type of error occurred.
| Code | Meaning | Example Scenario |
|---|---|---|
| 0 | Success | Command completed successfully |
| 1 | General error | Unspecified failure |
| 2 | Command line usage error | Invalid arguments or options |
| 3 | Authentication error | Invalid credentials or expired token |
| 4 | Network error | Connection failed or timed out |
| 5 | Repository error | Not a dits repository or corrupt data |
| 6 | Lock conflict | File is locked by another user |
| 7 | Merge conflict | Conflicting changes need resolution |
| 128+ | Fatal error | Signal number + 128 (e.g., SIGKILL = 137) |
Common Workflows
Initial Setup
# Configure your identity
dits config --global user.name "Your Name"
dits config --global user.email "you@example.com"
# Clone a repository
dits clone https://dits.example.com/team/project
cd project
# Or initialize a new one
dits init my-new-project
cd my-new-projectDaily Workflow
# Start day: get latest changes
dits pull
# Check what's changed
dits status
# Lock file before editing (for binary files)
dits lock footage/scene01.mov
# Work on your files...
# Stage and commit changes
dits add footage/scene01.mov
dits commit -m "Color grade scene 1"
# Push changes to remote
dits push
# Unlock when done
dits unlock footage/scene01.movUsing Virtual Filesystem
# Mount repository as virtual drive
dits mount /mnt/project
# Files appear instantly, hydrate on-demand
ls /mnt/project/footage/
# Open files directly in NLE (streams on demand)
# Edit as normal - no full download required
# When done
dits unmount /mnt/projectWorking with Video
# Inspect video structure
dits inspect footage/hero.mov
# Check deduplication stats
dits inspect-file footage/hero.mov
# Generate proxy files for offline editing
dits proxy-generate --resolution 1080p footage/
# Check proxy status
dits proxy-statusNeed Help?
Use
dits help <command> or dits <command> --help to get detailed help for any command directly in your terminal.Related Topics
- Getting Started - Quick start guide
- Configuration - Configure Dits behavior
- Core Concepts - Understanding how Dits works