CLI reference
Run these from your repository. New to Riftri? Start with riftri setup.
Create a worktree
riftri doctor --destination ../app-auth
riftri worktree add ../app-auth -b feature/auth mainReplace main with any starting branch or commit. The result is a normal
Git worktree; uncommitted changes in the original are not copied.
| Option | Use it to |
|---|---|
-b <branch> | Create a new branch |
--detach | Work without creating a branch |
--sparse-dir <dir> | Include selected directories; see sparse checkout |
Inspect
riftri worktree list
riftri statusstatus adds shared bases, storage use, and anything needing attention.
Move or remove
riftri worktree move ../app-auth ../app-login
riftri worktree remove ../app-login- Moves must stay on the same volume; mounted OverlayFS worktrees cannot be moved.
- Removal refuses local changes;
--forcediscards them.
Recover and reclaim space
| Command | Does |
|---|---|
riftri repair | Resume or roll back an interrupted operation; riftri status shows recovery guidance |
riftri gc | Preview unused-base cleanup; apply with riftri gc --apply only after reviewing the plan |
riftri worktree compact <path> | Reclaim private storage in a pristine, full native-clone worktree; refuses untracked and ignored files |
Machine-readable output
Every command that reports or changes state accepts --json and prints one
versioned report on stdout — doctor, backends, status, repair, gc,
and every worktree subcommand. Any command accepts --json-errors, which
emits one failure receipt on stderr instead of human text.
riftri worktree add ../app-auth -b feature/auth --jsonExit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Operational failure — Git, storage, journal, or I/O |
2 | Usage error — bad flag or argument |
3 | Policy refusal — Riftri declined; nothing changed |
Code 3 is deterministic: the request was refused before anything was
touched, so retrying the same command fails identically. Scripts can branch
on the status alone without parsing JSON. See the
custom harness guide for driving these from a runner.
More options
--help works with every command, and riftri man <dir> writes a man page
per command. Complete flag, JSON, and recovery contracts: View .md.