# shelbi init

Create a project from Shelbi's detected setup plan, interactively or without prompts for automation.

```text
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, runner, and tmux, then creates the same project and
Welcome card as Enter on the interactive setup card.

The project is created with an **empty workspace pool**. `shelbi init` no longer
provisions workspaces; the orchestrator sets them up on first boot by asking how
many workspaces and which naming scheme you want, then creating each one with
[`shelbi workspace add`](/docs/cli/workspace). Run `shelbi` interactively for that
first-boot interview.

## Automation

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

```bash
shelbi init -y
```

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

```bash
shelbi init -y --runner codex
```

For a different checkout or CI workspace:

```bash
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`.

<Callout type="warning" title="Do not omit --runner when both are installed">

`shelbi init -y` will stop rather than guess between Claude Code and Codex.
Pass `--runner claude` or `--runner codex` to make automation deterministic.

</Callout>

## Detected-plan options

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `-y, --yes` | flag | off | Accept the detected plan without prompts. This is a global flag and may appear before or after `init`. |
| `--project <PROJECT>` | string | project-root basename | Override the generated project name. |
| `--root <ROOT>` | path | current directory with `-y` | Repository Shelbi will manage. |
| `--runner <RUNNER>` | `claude` \| `codex` | the only detected runner | Runner for the workspaces the orchestrator creates on first boot. Required when both supported runners are installed. |
| `--default-branch <BRANCH>` | string | detected branch, then `main` | Override the detected default branch. `--branch` is an alias. |
| `--github-url <URL>` | string | detected origin | Override the detected origin URL. `--remote` is an alias; pass an empty value to omit it. |
| `--orchestrator-runner <RUNNER>` | `claude` \| `codex` | selected `--runner` | Use a different installed runner for the orchestrator. |

Detected-plan overrides require `-y`. The `-y` path cannot be combined with
`--mode` or `--pick-up`.

## Config-location and pick-up options

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

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--mode <MODE>` | `in-repo` \| `global` | asked interactively | Choose committed in-repo config or per-user global config. Required for this path when stdin is not a TTY. |
| `--pick-up` | flag | off | Register an existing committed `<repo>/.shelbi/project.yaml` after cloning a teammate's project. |

Register an existing in-repo project like this:

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

See [Config modes](/docs/concepts/config-modes) for the shared/local file split
and migration path.

## See also

- [Set up your first project](/docs/guides/getting-started/first-project) for
  the visible preflight and one-confirmation experience.
- [`shelbi wizard`](/docs/cli/wizard) for the explicit interactive entry point.
- [`shelbi project`](/docs/cli/project) for adding or migrating projects.