# How to Initialize Beads in Standard Mode: Interactive Setup Guide

> Initialize Beads in standard mode using the interactive setup wizard. Run "bd init" in your Git repo root to create a .beads directory, embed a Dolt database, and configure your project role.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: how-to-guide
- Published: 2026-04-27

---

**Run `bd init` without any flags in your Git repository root to launch the interactive setup wizard, which creates a `.beads/` directory with an embedded Dolt database and configures your project role.**

To initialize Beads in standard mode in the gastownhall/beads project, you run a single command that launches an interactive wizard. This standard initialization flow sets up the embedded database, configures your role as either a maintainer or contributor, and optionally installs Git synchronization hooks. Unlike automated deployments, standard mode provides a guided experience that ensures proper configuration for collaborative issue tracking.

## Understanding Standard Mode

Standard mode refers to running `bd init` without non-interactive flags such as `--quiet`, `--non-interactive`, or `--server`. According to the source code in [`cmd/bd/init.go`](https://github.com/gastownhall/beads/blob/main/cmd/bd/init.go), this mode triggers the `runInitWizard` function, which presents interactive prompts to configure your local environment. The command definition shows that when the `quiet` flag remains false (lines 68-71), the wizard proceeds with role selection and hook installation rather than using defaults.

## Running the Standard Initialization

### Basic Command Execution

Navigate to your Git repository root and execute the initialization command:

```bash
cd my-project
bd init

```

This launches the interactive wizard defined in [`cmd/bd/init.go`](https://github.com/gastownhall/beads/blob/main/cmd/bd/init.go). The function checks that no `--quiet` flag is present before invoking the full setup sequence.

### The Interactive Wizard Flow

The wizard performs several configuration steps through user prompts handled by the `internal/ui/` package:

- **Role Selection**: Asks "Contributing to someone else's repo? [y/N]" to set the `beads.role` configuration to either *contributor* or *maintainer* (documented in [`website/docs/getting-started/quickstart.md`](https://github.com/gastownhall/beads/blob/main/website/docs/getting-started/quickstart.md) lines 84-90).
- **Git Hooks**: Prompts "Install Git hooks? (recommended) [Y/n]" to optionally install automatic synchronization triggers via `setupHooks`.
- **Issue Import**: Automatically imports existing Git issues into the new Beads database via `importExistingIssues`.

Typical output looks like this:

```bash
$ bd init
Welcome to Beads! 🎉
Contributing to someone else's repo? [y/N]  N
Install Git hooks? (recommended) [Y/n]    Y
...
Beads has been initialized in .beads/

```

## Technical Implementation Details

### Embedded Database Creation

During initialization, Beads creates a `.beads/` directory containing an **embedded Dolt database** (`embeddeddolt`). The storage engine is implemented in `internal/storage/embeddeddolt/` and provides a SQL-compatible interface for local issue management. This replaces traditional file-based issue tracking with a relational database structure that supports versioning.

### Configuration Management

The wizard writes settings to [`config.yaml`](https://github.com/gastownhall/beads/blob/main/config.yaml) through utilities in `internal/config/`. Your selected role determines default permissions for issue modifications and database synchronization. The configuration persists across sessions and affects how `bd` commands behave in your repository.

### Git Integration Setup

When you opt into hook installation, the `setupHooks` function (located in [`cmd/bd/hooks.go`](https://github.com/gastownhall/beads/blob/main/cmd/bd/hooks.go)) installs scripts that automatically sync Beads data during Git operations. These hooks ensure that your local embedded database stays synchronized with remote collaborators when you push or pull changes.

## Advanced Standard Mode Scenarios

### Forcing Interactive Mode in Automation Scripts

If you need to run standard mode within a script while preserving the interactive flow (for example, on fresh developer machines), force a TTY allocation:

```bash
script -q -c "bd init"

```

This technique ensures stdin remains a TTY, preventing automatic fallback to non-interactive mode. Do not set `BD_NON_INTERACTIVE=1` or pass `--quiet` when using this approach.

### Verifying the Database Structure

After initialization completes, inspect the created database schema to confirm proper setup:

```bash
bd sql "SHOW TABLES"

```

You should see Beads-specific tables including `issues`, `comments`, and `dependencies` stored within the embedded Dolt engine.

## Summary

- **Standard mode** requires running `bd init` without `--quiet`, `--non-interactive`, or `--server` flags in the gastownhall/beads repository.
- The interactive wizard in [`cmd/bd/init.go`](https://github.com/gastownhall/beads/blob/main/cmd/bd/init.go) configures your **role** (maintainer/contributor), installs optional **Git hooks** via `setupHooks`, and imports existing issues through `importExistingIssues`.
- Beads creates a `.beads/` directory containing an **embedded Dolt database** (`embeddeddolt`) for local issue storage.
- Configuration persists in [`config.yaml`](https://github.com/gastownhall/beads/blob/main/config.yaml) through the `internal/config/` package utilities.
- Use `script -q -c "bd init"` to maintain interactivity within automation scripts that lack a TTY.

## Frequently Asked Questions

### What is the difference between standard mode and non-interactive mode in Beads?

Standard mode launches an interactive wizard that prompts for role selection and Git hook installation, while non-interactive mode (triggered by `--non-interactive`, `--quiet`, or `BD_NON_INTERACTIVE=1`) skips all prompts and uses default values. The non-interactive variant is designed for CI/CD pipelines and automated deployments where terminal input is unavailable.

### Where does Beads store its database files?

Beads stores all data in a `.beads/` directory at your repository root. This directory contains an embedded Dolt database managed by the `internal/storage/embeddeddolt/` package. The database uses the Dolt storage format, providing Git-like versioning capabilities for your issues while keeping data local and portable.

### Can I initialize Beads in a subdirectory instead of the Git root?

No, you should run `bd init` from the root of your Git repository. The command creates the `.beads/` directory and configures Git hooks relative to the repository root. Initializing in a subdirectory would break the integration with Git operations and issue synchronization, as the tool expects to find the `.git` directory at the same level as `.beads/`.

### How do I change my role from contributor to maintainer after initialization?

You can modify your role by editing the `beads.role` value in the `.beads/` configuration or by using the `bd config` command to update settings manually. Since `bd init` is typically run once per repository, manual configuration changes are the preferred method for updating permissions without reinitializing the embedded database.