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),
-p, --project <PROJECT> (defaults to $SHELBI_PROJECT or the registered
project whose work_dir contains the current directory), and -y, --yes
flags. project add always shows the interactive setup card, even with -y;
for a prompt-free setup use shelbi init -y.
migrate-to-in-repo has its own long-only --yes (no -y after the
subcommand) and renders the project flag's value name as <NAME>.
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, and workspace recommendation, then shows the same setup card as
first-run onboarding. Press Enter to create the project and launch its TUI,
press c to customize the prefilled values first, or press q (or Esc) to quit
without writing anything. If the current directory isn't inside a Git
repository, the plan initializes one.
The new project is registered at ~/.shelbi/projects/<name>.yaml (global mode).
Run migrate-to-in-repo afterwards to commit its config to the repo. On a clone
that already has a committed .shelbi/project.yaml, use
shelbi init --pick-up instead.
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. |
The command prints a header naming the project's repo, state dir, and in-repo
dir, any ⚠ warnings, then a Plan: list of actions. A real run ends with
✓ applied N actions and the shared and local config paths; a dry run ends with
(dry-run — no files were written) and the .gitignore snippet. An
already-migrated project prints Nothing to do and still offers the snippet.
Without a TTY and without --yes, the snippet is only printed, not appended.
Re-run with --yes to append it.
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.