How to Initialize Beads in Standard Mode: Interactive Setup Guide

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, 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:

cd my-project
bd init

This launches the interactive wizard defined in 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 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:

$ 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 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) 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:

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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}