shelbi init

shelbi init [OPTIONS]

shelbi init has two setup paths:

• Run it normally for the existing config-location and pick-up workflows.
• Add -y to detect the same plan as first-run shelbi, accept it without a prompt, and write the standard global project layout.

The -y path performs the full prerequisite and project validation before it writes anything. It uses the current directory by default, detects the Git root, branch, origin, and runner, then creates the same project and Welcome card as Enter on the interactive setup card. If the directory isn't a Git repository yet, -y initializes one with git init -b main first (interactive setup asks before doing so). Running init -y again in a directory that already belongs to a project prints ✓ Project <name> is already configured. and changes nothing.

The -y path creates the project with an empty workspace pool; the orchestrator sets the pool up on first boot by asking how many workspaces and which naming scheme you want, then creating each one with shelbi workspace add. Run shelbi interactively for that first-boot interview. The config-location path (without -y) instead writes a starter pool of two hub workspaces: dev and a review-tagged review slot.

Every setup path also installs a pre-commit hook in the repository that blocks commits to the default branch from inside Shelbi's agent sessions only; your own shell is unaffected. Shelbi prints a notice the first time it installs the hook, and an existing hook of your own is left untouched (with a warning). Manage or remove it with shelbi guard.

Where your issues live

Interactive setup asks where the project's board should live:

• GitHub Issues stores each card as a GitHub issue, so teammates and contributors can see and file them. It is pre-selected, with the owner/repo pre-filled, when the origin remote is a GitHub repo. Choosing it runs a preflight first: gh must be installed and authenticated, and your account must be able to read issues and create labels on the repo (Issues enabled plus push access). On a preflight failure the setup explains the fix and lets you retry or fall back to File system, so a GitHub config that would not load is never written. On success, Shelbi creates shelbi:id/* and shelbi:status/* labels on first use and stores a small metadata block in each issue's body.
• File system keeps the board as private markdown files on this machine under ~/.shelbi/projects/<name>/tasks/. No GitHub needed. It's pre-selected when the origin isn't on GitHub, and it's what -y uses unless you pass --issue-tracker github.

The choice is written as an issue_tracker: block in the project config: the shared project.yaml for in-repo mode, or ~/.shelbi/projects/<name>.yaml for global mode. To move an existing board between backends later, use shelbi issue-store migrate. Setup never switches the backend of a project that already has issues without pointing you there first.

Automation

From a repository with exactly one supported runner on PATH, this is the copy-pasteable zero-prompt setup:

shelbi init -y

If both Claude Code and Codex are installed, runner selection is ambiguous. Disambiguate it explicitly:

shelbi init -y --runner codex

For a different checkout or CI workspace:

shelbi init -y --root /workspace/myapp --runner claude

--runner selects the runner for the workspaces the orchestrator later creates and is also the default orchestrator runner. Use --orchestrator-runner only when those should differ. The selected runners must be installed on PATH.

Detected-plan options

--runner, --default-branch, --github-url, --orchestrator-runner, --issue-tracker, and --github-repo require -y; without it they fail with a detected-plan overrides require shelbi init -y error. --project and --root work on both paths. The -y path cannot be combined with --mode or --pick-up. Without --issue-tracker, -y keeps the file_system default so existing scripted setups are unchanged. The chosen backend is printed in the plan summary.

Create a project whose board is GitHub Issues without prompts:

shelbi init -y --issue-tracker github --github-repo acme/myapp

Config-location and pick-up options

Without -y, shelbi init uses the explicit config-mode workflow:

Register an existing in-repo project like this:

git clone git@github.com:acme/myapp.git && cd myapp
shelbi init --pick-up

See Config modes for the shared/local file split and migration path.

See also

• Set up your first project for the visible preflight and one-confirmation experience.
• shelbi wizard for the explicit interactive entry point.
• shelbi project for adding or migrating projects.
• shelbi guard for the default-branch commit guard setup installs.