Command Reference
Complete reference for all Ivaldi commands.
Quick Reference Table
| Command | Purpose | Git Equivalent |
|---|---|---|
| forge | Initialize repository | git init |
| gather | Stage files | git add |
| seal | Create commit | git commit |
| status | Show repository status | git status |
| whereami | Show current position | (custom) |
| log | View commit history | git log |
| diff | Compare changes | git diff |
| reset | Unstage or reset | git reset |
| timeline | Manage timelines | git branch / git checkout |
| butterfly | Experimental timelines | (custom) |
| shift | Squash commits interactively | git rebase -i (squash) |
| travel | Interactive time travel | (interactive git log + checkout) |
| fuse | Merge timelines | git merge |
| auth | Authenticate with GitHub | (similar to gh auth) |
| portal | Manage GitHub connections | git remote |
| download | Clone repository | git clone |
| upload | Push to GitHub | git push |
| scout | Discover remote branches | git fetch (metadata) |
| harvest | Fetch branches | git fetch (data) |
| config | Configure settings | git config |
| exclude | Ignore files | (edit .gitignore) |
| submodule | Manage submodules | git submodule (auto) |
Commands by Category
Repository Management
- forge - Initialize a new Ivaldi repository
- status - Display working directory status
- whereami - Show current timeline and position
- config - View and modify configuration
File Operations
- gather - Stage files for the next seal
- seal - Create a commit with staged files
- reset - Unstage files or reset changes
- exclude - Add patterns to
.ivaldiignore
History and Inspection
- log - View commit history
- diff - Compare file changes
- travel - Interactively browse and navigate history
- shift - Squash commits for cleaner history
Timeline Management
- timeline - Create, switch, list, and remove timelines
- butterfly - Create and manage experimental timelines
- fuse - Merge timelines together
Remote Operations
- auth - Authenticate with GitHub using OAuth
- portal - Manage GitHub repository connections
- download - Clone a repository from GitHub
- upload - Push commits to GitHub
- scout - Discover available remote timelines
- harvest - Download specific remote timelines
Submodule Management
- submodule - Automatic Git submodule conversion and management
Command Details
Click on any command above to see detailed documentation including:
- Syntax and options
- Examples and use cases
- Related commands
- Troubleshooting tips
Common Workflows
Daily Development
ivaldi status # Check what's changed
ivaldi gather . # Stage changes
ivaldi seal "Description" # Commit
ivaldi upload # Push to GitHub
Feature Development
ivaldi timeline create feature-name # Create timeline
# ... make changes ...
ivaldi gather . # Stage
ivaldi seal "Add feature" # Commit
ivaldi timeline switch main # Switch to main
ivaldi fuse feature-name to main # Merge
Experimental Development with Butterflies
ivaldi timeline butterfly experiment # Create experimental timeline
# ... make experimental changes ...
ivaldi seal "Try new approach" # Commit changes
ivaldi timeline butterfly up # Merge to parent if successful
# Or: ivaldi timeline butterfly down # Pull parent changes
Clean History Before Push
ivaldi shift --last 5 # Squash last 5 commits
# Enter clean commit message
ivaldi upload # Push clean history
Collaboration
ivaldi scout # See remote branches
ivaldi harvest branch-name # Fetch branch
ivaldi timeline switch branch-name # Switch to it
# ... review or contribute ...
ivaldi upload # Push changes
Global Options
These flags are available on all commands:
–verbose, -v
Show detailed output including debug information:
ivaldi --verbose status
ivaldi -v download owner/repo
–quiet, -q
Suppress non-essential output:
ivaldi --quiet gather .
ivaldi -q seal "Quick commit"
Verbose and quiet are mutually exclusive. If both are specified, verbose takes precedence.
Getting Help
Each command supports the --help flag:
ivaldi <command> --help
For additional help, see: