shelbi project
View as markdownshelbi project <COMMAND> [OPTIONS]shelbi project groups the commands for managing which repos Shelbi knows
about. Use it to onboard an additional project after your first, or to move an
existing project from per-user global config into committed in-repo config.
Every subcommand accepts the global --root <PATH> (override the Shelbi root
directory, else $SHELBI_ROOT, else the install-time default) and
-p, --project <PROJECT> (defaults to $SHELBI_PROJECT or the registered
project whose work_dir contains the current directory) flags.
Commands
| Command | Description |
|---|---|
add | Run the same preflight and one-confirmation setup as first-run Shelbi, then launch the new project's dashboard. |
migrate-to-in-repo | Migrate an existing global-mode project into in-repo mode. |
add
shelbi project add [OPTIONS]Set up a new project interactively. Shelbi detects the current Git repository,
runner, tmux, and workspace recommendation, then shows the same setup card as
first-run onboarding. Press Enter to create the project and launch its TUI, or
press c to customize the prefilled values first.
migrate-to-in-repo
shelbi project migrate-to-in-repo [OPTIONS]Migrate an existing global-mode project into
in-repo mode. It splits
~/.shelbi/projects/<name>.yaml into a committed shared half at
<repo>/.shelbi/project.yaml and a per-machine
~/.shelbi/projects/<name>/local.yaml, and moves workflows/, agents/, and
the workspace-settings template from the state dir into the repo. State
(state.json, tasks/, HANDOFF.md, .claude/, workspaces/, events.log)
stays under ~/.shelbi/ in both modes.
The migration is idempotent: safe to re-run on an already-migrated project (a
no-op) or a half-migrated one (it completes the missing steps). It prints a
.gitignore snippet for the repo root and, outside --dry-run, offers to
auto-append it.
One-way migration
There is no migrate-to-global command. Reverting means git revert on the
migration commit (which restores <repo>/.shelbi/ to its pre-migration state)
plus manually moving local.yaml back to
~/.shelbi/projects/<name>.yaml. A merged migration commit is expensive to
undo. Run --dry-run first if you're unsure.
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | flag | off | Print the plan without touching disk — every write, move, and delete the real run would perform, in order, so a reviewer can vet it first. |
--yes | flag | off | Skip the interactive prompt and auto-append the .gitignore snippet. Useful for scripts and headless runs with no TTY. Ignored under --dry-run. |
Examples
Onboard a second project from inside its repo:
shelbi project addPreview an in-repo migration without writing anything:
shelbi project migrate-to-in-repo --dry-runRun the migration non-interactively, appending the .gitignore snippet:
shelbi project migrate-to-in-repo --yesSee also
- Config modes — the global vs in-repo model, the
full on-disk layout, and the
.gitignorelistmigrate-to-in-repoprints. shelbi init— first-time scaffolding, including the--pick-upflow for cloning a teammate's in-repo config.shelbi wizard: the detected one-confirmation setup.