# Configuration System Last reviewed: 2026-05-08 Freshness source: `cmd/bd/main.go`, `cmd/bd/config.go`, and `internal/configfile/`. bd has two complementary configuration systems: 1. **Tool-level configuration** (Viper): startup settings, flags, output format, and other CLI behaviour 2. **Project-level configuration** (`bd config`): integration data and project-specific settings; startup-sensitive keys are routed to `config.yaml` ## Tool-Level Configuration (Viper) ### Overview Tool preferences control how `bd` behaves globally or per-user. These are stored in config files or environment variables and managed by [Viper](https://github.com/spf13/viper). **Configuration precedence** (highest to lowest): 1. Command-line flags (`--json`, `--dolt-auto-commit`, etc.) 2. Environment variables (`BD_JSON`, `BD_DOLT_AUTO_COMMIT`, etc.) 3. Merged config files (`~/.beads/config.yaml`, `~/.config/bd/config.yaml`, `.beads/config.yaml`, and `BEADS_DIR/config.yaml`) 4. Defaults ### Config File Locations Config files are merged from lowest to highest priority: 1. `~/.beads/config.yaml` - legacy user settings 2. `~/.config/bd/config.yaml` - user settings; this path is checked explicitly even on platforms whose native user-config directory differs 3. `.beads/config.yaml` - project-specific tool settings, discovered by walking up from the current directory 4. `BEADS_DIR/config.yaml` - highest-priority runtime workspace override when `BEADS_DIR` points at a different `.beads` directory When a project config exists, `.beads/config.local.yaml` is merged last for machine-specific overrides that should not be committed. ### Supported Settings Common tool-level settings you can configure: | Setting | Flag | Environment Variable | Default | Description | |---------|------|---------------------|---------|-------------| | `json` | `--json` | `BD_JSON` | `false` | Output in JSON format | | `no-push` | `--no-push` | `BD_NO_PUSH` | `false` | Skip pushing to remote in `bd dolt push` | | `federation.remote` | - | `BD_FEDERATION_REMOTE` | (none) | Dolt remote URL for federation | | `federation.sovereignty` | - | `BD_FEDERATION_SOVEREIGNTY` | (none) | Data sovereignty tier: `T1`, `T2`, `T3`, `T4` | | `dolt.auto-commit` | `--dolt-auto-commit` | `BD_DOLT_AUTO_COMMIT` | `on` | (Dolt backend) Automatically create a Dolt commit after successful write commands | | `create.require-description` | - | `BD_CREATE_REQUIRE_DESCRIPTION` | `false` | Require description when creating issues | | `validation.on-create` | - | `BD_VALIDATION_ON_CREATE` | `none` | Template validation on create: `none`, `warn`, `error` | | `validation.on-sync` | - | `BD_VALIDATION_ON_SYNC` | `none` | Template validation before sync: `none`, `warn`, `error` | | `git.author` | - | `BD_GIT_AUTHOR` | (none) | Override commit author for beads commits | | `git.no-gpg-sign` | - | `BD_GIT_NO_GPG_SIGN` | `false` | Disable GPG signing for beads commits | | `directory.labels` | - | - | (none) | Map directories to labels for automatic filtering | | `external_projects` | - | - | (none) | Map project names to paths for cross-project deps | | `backup.enabled` | - | `BD_BACKUP_ENABLED` | `false` | Enable periodic Dolt-native backup to `.beads/backup/` | | `backup.interval` | - | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups | | `dolt.auto-push` | - | `BD_DOLT_AUTO_PUSH` | `false` | Auto-push to Dolt remote after writes (explicit opt-in) | | `dolt.auto-push-interval` | - | `BD_DOLT_AUTO_PUSH_INTERVAL` | `5m` | Minimum time between auto-pushes | | `dolt.auto-push-timeout` | - | `BD_DOLT_AUTO_PUSH_TIMEOUT` | `30s` | Timeout for a single auto-push attempt | | `dolt.shared-server` | `--shared-server` | `BEADS_DOLT_SHARED_SERVER` | `false` | Share a single Dolt server across all projects at `~/.beads/shared-server/` | | `db` | `--db` | `BD_DB` | (auto-discover) | Database path | | `actor` | `--actor` | `BEADS_ACTOR` | `git config user.name` | Actor name for audit trail (see below) | **Backend note:** Dolt is the only storage backend. By default, Dolt runs in embedded mode (in-process, no server). Use `bd init --server` or `BEADS_DOLT_SERVER_MODE=1` for server mode. See [DOLT.md](DOLT.md) for details. ### Dolt Auto-Commit (SQL commit vs Dolt commit) When using the **Dolt backend**, there are two different kinds of “commit”: - **SQL transaction commit**: what happens when a `bd` command updates tables successfully (durable in the Dolt *working set*). - **Dolt version-control commit**: what records those changes into Dolt’s *history* (visible in `bd vc log`, push/pull/merge workflows). By default, `bd` is configured to **auto-commit Dolt history after each successful write command**: - **Default**: `dolt.auto-commit: on` - **Disable for a single command**: ```bash bd --dolt-auto-commit off create "No commit for this one" ``` - **Disable in config** (`.beads/config.yaml` or `~/.config/bd/config.yaml`): ```yaml dolt: auto-commit: off ``` **Caveat:** enabling this creates **more Dolt commits** over time (one per write command). This is intentional so changes are not left only in the working set. ### Auto-Backup Periodic Dolt-native backup to `.beads/backup/` provides an off-machine recovery path. Local Dolt snapshots (via `dolt.auto-commit`) remain the primary safety net; backup is a secondary layer. ```yaml backup: enabled: true # Enable auto-backup after write commands interval: 15m # Minimum time between auto-backups ``` **How it works:** - After each write command (in PersistentPostRun), `bd` checks the Dolt HEAD commit hash against the last backup state - If data changed and the throttle interval has passed, a Dolt-native backup is synced to `.beads/backup/` - Full commit history is preserved in the backup - State is tracked in `.beads/backup/backup_state.json` **Manual commands:** - `bd backup init ` — register a backup destination (filesystem or DoltHub URL) - `bd backup sync` — push to the configured backup destination - `bd backup restore [path]` — restore from a backup (`--force` to overwrite) - `bd backup remove` — unregister the backup destination - `bd backup status` — show backup configuration and last sync time ### Dolt Auto-Push By default, `bd` does not push automatically after write commands. Auto-push is explicit opt-in because concurrent pushes to git-protocol Dolt remotes can corrupt or strand remote history when multiple writers race. ```yaml dolt: auto-push: false # Explicit opt-in only; set true for single-writer setups auto-push-interval: 5m # Minimum time between auto-pushes auto-push-timeout: 30s # Bound one push attempt when the remote is unreachable ``` **How it works:** - After each write command (in PersistentPostRun, after auto-commit and auto-backup), `bd` checks whether a push is due - Pushes are debounced: skipped if the last push was less than `dolt.auto-push-interval` ago - Change detection: skipped if the Dolt HEAD commit hasn't changed since last push - Push failures are warnings only (non-fatal) - Last push time and commit are tracked in the metadata table **Opt in:** ```yaml dolt: auto-push: true ``` ### Actor Identity Resolution The actor name (used for `created_by` in issues and audit trails) is resolved in this order: 1. `--actor` flag (explicit override) 2. `BEADS_ACTOR` environment variable 3. `BD_ACTOR` environment variable (deprecated alias, kept for backwards compatibility) 4. `git config user.name` 5. `$USER` environment variable (system username fallback) 6. `"unknown"` (final fallback) For most developers, no configuration is needed - beads will use your git identity automatically. This ensures your issue authorship matches your commit authorship. To override, set `BEADS_ACTOR` in your shell profile: ```bash export BEADS_ACTOR="my-github-handle" ``` ### Sync Mode Configuration The sync mode controls how beads synchronizes data with git and/or Dolt remotes. #### Sync Mode Beads uses `dolt-native` sync mode exclusively. Dolt remotes handle sync directly with cell-level merge. Use `bd export` for issue portability, and `bd backup init` / `bd backup sync` / `bd backup restore` for Dolt-native backups. #### Federation Configuration - `federation.remote`: Dolt remote URL (e.g., `dolthub://org/beads`, `gs://bucket/beads`, `s3://bucket/beads`, `az://account.blob.core.windows.net/container/beads`) - `federation.sovereignty`: Data sovereignty tier: - `T1`: Full sovereignty - data never leaves controlled infrastructure - `T2`: Regional sovereignty - data stays within region/jurisdiction - `T3`: Provider sovereignty - data with trusted cloud provider - `T4`: No restrictions - data can be anywhere #### Example Configuration ```yaml # .beads/config.yaml # Optional: Dolt federation federation: remote: dolthub://myorg/beads sovereignty: T2 ``` ### Example Config File `~/.config/bd/config.yaml`: ```yaml # Default to JSON output for scripting json: true # Dolt auto-commit (creates Dolt history commit after each write) dolt: auto-commit: on ``` `.beads/config.yaml` (project-specific): ```yaml # Require descriptions on all issues (enforces context for future work) create: require-description: true # Template validation settings (bd-t7jq) # Validates that issues include required sections based on issue type # Values: none (default), warn (print warning), error (block operation) validation: on-create: warn # Warn when creating issues missing sections on-sync: none # No validation on sync (backwards compatible) # Git commit signing options (GH#600) # Useful when you have Touch ID commit signing that prompts for each commit git: author: "beads-bot " # Override commit author no-gpg-sign: true # Disable GPG signing # Directory-aware label scoping for monorepos (GH#541) # When running bd ready/list from a matching directory, issues with # that label are automatically shown (as if --label-any was passed) directory: labels: packages/maverick: maverick packages/agency: agency packages/io: io # Feedback title formatting for mutating commands (GH#1384) # 0 = hide titles, N > 0 = truncate to N characters output: title-length: 255 # Cross-project dependency resolution (bd-h807) # Maps project names to paths for resolving external: blocked_by references # Paths can be relative (from cwd) or absolute external_projects: beads: ../beads other-project: /path/to/other-project ``` ### Why Two Systems? **Tool settings (Viper)** are user preferences: - How should I see output? (`--json`) - Should Dolt auto-commit? (`--dolt-auto-commit`) - How should the CLI behave? **Project config (`bd config`)** is project data: - What's our Jira URL? - What are our Linear tokens? - How do we map statuses? This separation is correct: **tool settings are user-specific, project config is team-shared**. Agents benefit from `bd config`'s structured CLI interface over manual YAML editing. ## Project-Level Configuration (`bd config`) ### Overview Project configuration is: - **Per-project**: Isolated to each `.beads/` database - **Version-control-friendly**: Stored in the database, queryable and scriptable - **Machine-readable**: JSON output for automation - **Namespace-based**: Organized by integration or purpose ## Commands ### Set Configuration ```bash bd config set bd config set --json # JSON output ``` Examples: ```bash bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set jira.status_map.todo "open" ``` ### Get Configuration ```bash bd config get bd config get --json # JSON output ``` Examples: ```bash bd config get jira.url # Output: https://company.atlassian.net bd config get --json jira.url # Output: {"key":"jira.url","value":"https://company.atlassian.net"} ``` ### List All Configuration ```bash bd config list bd config list --json # JSON output ``` Example output: ``` Configuration: compact_tier1_days = 90 compact_tier1_dep_levels = 2 jira.project = PROJ jira.url = https://company.atlassian.net ``` JSON output: ```json { "compact_tier1_days": "90", "compact_tier1_dep_levels": "2", "jira.project": "PROJ", "jira.url": "https://company.atlassian.net" } ``` ### Unset Configuration ```bash bd config unset bd config unset --json # JSON output ``` Example: ```bash bd config unset jira.url ``` ## Namespace Convention Configuration keys use dot-notation namespaces to organize settings: ### Core Namespaces - `compact_*` - Compaction settings (used by `bd admin compact`) - `issue_prefix` - Issue ID prefix (managed by `bd init`) - `issue_id_mode` - ID generation mode: `hash` (default) or `counter` (sequential integers) - `max_collision_prob` - Maximum collision probability for adaptive hash IDs (default: 0.25) - `min_hash_length` - Minimum hash ID length (default: 4) - `max_hash_length` - Maximum hash ID length (default: 8) - `import.orphan_handling` - How to handle hierarchical issues with missing parents during import (default: `allow`) - `export.auto` - Refresh the git-tracked JSONL file after every write command (default: `true`) - `export.path` - Output filename relative to `.beads/` (default: `issues.jsonl`) - `export.interval` - Minimum time between auto-exports (default: `60s`) - `export.git-add` - Run `git add` on the export file after writing (default: `true`) - `export.error_policy` - Error handling strategy for exports (default: `strict`) - `export.retry_attempts` - Number of retry attempts for transient errors (default: 3) - `export.retry_backoff_ms` - Initial backoff in milliseconds for retries (default: 100) - `export.skip_encoding_errors` - Skip issues that fail JSON encoding (default: false) - `export.write_manifest` - Write .manifest.json with export metadata (default: false) - `auto_export.error_policy` - Override error policy for auto-exports (default: `best-effort`) - `sync.branch` - Name of the dedicated sync branch for beads data (see docs/PROTECTED_BRANCHES.md) - `sync.require_confirmation_on_mass_delete` - Require interactive confirmation before pushing when >50% of issues vanish during a merge AND more than 5 issues existed before (default: `false`) ### Integration Namespaces Use these namespaces for external integrations: - `jira.*` - Jira integration settings - `linear.*` - Linear integration settings - `github.*` - GitHub integration settings - `ado.*` - Azure DevOps integration settings - `custom.*` - Custom integration settings ### Status and Type Customization - `status.custom` - Custom issue statuses with optional categories (comma-separated) - `types.custom` - Custom issue types (comma-separated) **Custom statuses** support category annotations that control behavior: ```bash # Format: name:category (category is optional) bd config set status.custom "in_review:active,qa_testing:wip,on_hold:frozen,archived:done" # Categories: active, wip, done, frozen # - active: shows in bd ready, included in default bd list # - wip: excluded from bd ready, included in default bd list # - done: excluded from bd ready AND default bd list (terminal) # - frozen: excluded from bd ready AND default bd list (on hold) # - (none): excluded from bd ready, included in default bd list (backward compatible) ``` **Custom types:** ```bash bd config set types.custom "agent,molecule,event" ``` See `bd statuses` and `bd types` commands to list all configured statuses and types. ### Example: Sequential Counter IDs (issue_id_mode=counter) By default, beads generates hash-based IDs (e.g., `bd-a3f2`, `bd-7f3a8`). For projects that prefer short sequential IDs (e.g., `bd-1`, `bd-2`, `bd-3`), enable counter mode: ```bash bd config set issue_id_mode counter ``` **Valid values:** | Value | Behavior | |-------|----------| | `hash` | (default) Hash-based IDs, adaptive length, collision-safe | | `counter` | Sequential integers per prefix: `bd-1`, `bd-2`, `bd-3`, ... | **Counter mode behavior:** - Each prefix (`bd`, `plug`, etc.) has its own independent counter - Counter is stored atomically in the database; concurrent creates within a single Dolt session are safe - Explicit `--id` flag always overrides counter mode (the counter is not incremented) **Enabling counter mode:** ```bash bd config set issue_id_mode counter # Now new issues get sequential IDs bd create "First issue" -p 1 # → bd-1 bd create "Second issue" -p 2 # → bd-2 ``` **Migration warning:** If you switch an existing repository to counter mode, seed the counter to avoid collisions with existing IDs. Find your highest current integer ID and set the counter accordingly: ```bash # Check your highest existing sequential ID (if any) bd list --json | jq -r '.[].id' | grep -E '^bd-[0-9]+$' | sort -t- -k2 -n | tail -1 # Seed the counter (e.g., if highest existing ID is bd-42) bd config set issue_id_mode counter # The counter auto-initializes at 0; new issues start at 1 # If you already have bd-1 through bd-42, manually set counter: # (no direct CLI for seeding — use bd dolt sql or create/delete N issues) ``` For fresh repositories switching to counter mode before any issues exist, no seeding is needed. **Per-prefix counter isolation:** Each issue prefix maintains its own counter independently. In multi-repo or routed setups, `bd-*` issues and `plug-*` issues each start at 1: ```bash # Prefix "bd" and prefix "plug" have independent counters bd create "Core task" -p 1 # → bd-1 bd create "Plugin task" -p 1 # → plug-1 (if prefix is "plug") ``` **Tradeoff — hash vs. counter:** | | Hash IDs | Counter IDs | |---|---|---| | Human readability | Lower (e.g., `bd-a3f2`) | Higher (e.g., `bd-1`) | | Distributed/concurrent safety | Excellent (collision-free across branches) | Needs care (counters can diverge on parallel branches) | | Predictability | Unpredictable | Sequential | | Best for | Multi-agent, multi-branch workflows | Single-writer or project-management UIs | Counter IDs are well-suited for linear project-management workflows and human-facing issue tracking. Hash IDs are safer when multiple agents or branches create issues concurrently, since each hash is independently unique without coordination. See [ADAPTIVE_IDS.md](ADAPTIVE_IDS.md) for full documentation on hash-based ID generation. ### Example: Adaptive Hash ID Configuration ```bash # Configure adaptive ID lengths (see docs/ADAPTIVE_IDS.md) # Default: 25% max collision probability bd config set max_collision_prob "0.25" # Start with 4-char IDs, scale up as database grows bd config set min_hash_length "4" bd config set max_hash_length "8" # Stricter collision tolerance (1%) bd config set max_collision_prob "0.01" # Force minimum 5-char IDs for consistency bd config set min_hash_length "5" ``` See [ADAPTIVE_IDS.md](ADAPTIVE_IDS.md) for detailed documentation. ### Example: Export Error Handling Controls how export operations handle errors when fetching issue data (labels, comments, dependencies). ```bash # Strict: Fail fast on any error (default for user-initiated exports) bd config set export.error_policy "strict" # Best-effort: Skip failed operations with warnings (good for auto-export) bd config set export.error_policy "best-effort" # Partial: Retry transient failures, skip persistent ones with manifest bd config set export.error_policy "partial" bd config set export.write_manifest "true" # Required-core: Fail on core data (issues/deps), skip enrichments (labels/comments) bd config set export.error_policy "required-core" # Customize retry behavior bd config set export.retry_attempts "5" bd config set export.retry_backoff_ms "200" # Skip individual issues that fail JSON encoding bd config set export.skip_encoding_errors "true" # Auto-export uses different policy (background operation) bd config set auto_export.error_policy "best-effort" ``` **Policy details:** - **`strict`** (default) - Fail immediately on any error. Ensures complete exports but may block on transient issues like database locks. Best for critical exports and migrations. - **`best-effort`** - Skip failed batches with warnings. Continues export even if labels or comments fail to load. Best for auto-exports and background sync where availability matters more than completeness. - **`partial`** - Retry transient failures (3x by default), then skip with manifest file. Creates `.manifest.json` alongside JSONL documenting what succeeded/failed. Best for large databases with occasional corruption. - **`required-core`** - Fail on core data (issues, dependencies), skip enrichments (labels, comments) with warnings. Best when metadata is secondary to issue tracking. **When to use each mode:** - Use `strict` (default) for production backups and critical exports - Use `best-effort` for auto-exports (default via `auto_export.error_policy`) - Use `partial` when you need visibility into export completeness - Use `required-core` when labels/comments are optional **Context-specific behavior:** User-initiated exports (`bd dolt push`, manual export commands) use `export.error_policy` (default: `strict`). Auto-exports (git hook sync) use `auto_export.error_policy` (default: `best-effort`), falling back to `export.error_policy` if not set. **Example: Different policies for different contexts:** ```bash # Critical project: strict everywhere bd config set export.error_policy "strict" # Development project: strict user exports, permissive auto-exports bd config set export.error_policy "strict" bd config set auto_export.error_policy "best-effort" # Large database with occasional corruption bd config set export.error_policy "partial" bd config set export.write_manifest "true" bd config set export.retry_attempts "5" ``` ### Example: Import Orphan Handling Controls how imports handle hierarchical child issues when their parent is missing from the database: ```bash # Strictest: Fail import if parent is missing (safest, prevents orphans) bd config set import.orphan_handling "strict" # Auto-resurrect: Search JSONL history and recreate missing parents as tombstones bd config set import.orphan_handling "resurrect" # Skip: Skip orphaned issues with warning (partial import) bd config set import.orphan_handling "skip" # Allow: Import orphans without validation (default, most permissive) bd config set import.orphan_handling "allow" ``` **Mode details:** - **`strict`** - Fails immediately if a child's parent is missing. Use when database integrity is critical. - **`resurrect`** - Searches for missing parents and recreates them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis. - **`skip`** - Skips orphaned children with a warning. Partial import succeeds but some issues are excluded. - **`allow`** - Imports orphans without parent validation. Most permissive. **This is the default** because it ensures all data is imported even if hierarchy is temporarily broken. These modes apply when bootstrapping a database with `bd init --from-jsonl` or when `bd dolt pull` merges remote data: ```bash # Override config for a single pull bd config set import.orphan_handling "resurrect" bd dolt pull # Respects import.orphan_handling setting ``` **When to use each mode:** - Use `allow` (default) for daily sync - ensures no data loss - Use `resurrect` when pulling from remotes that had parent deletions - Use `strict` only when you need to guarantee parent existence - Use `skip` rarely - only when you want to selectively import a subset ### Example: Sync Safety Options Controls for the sync branch workflow (see docs/PROTECTED_BRANCHES.md): ```bash # Configure sync branch (required for protected branch workflow) bd config set sync.branch beads-sync # Enable mass deletion protection (optional, default: false) # When enabled, if >50% of issues vanish during a merge AND more than 5 # issues existed before the merge, bd dolt push will: # 1. Show forensic info about vanished issues # 2. Prompt for confirmation before pushing bd config set sync.require_confirmation_on_mass_delete "true" ``` **When to enable `sync.require_confirmation_on_mass_delete`:** - Multi-user workflows where accidental mass deletions could propagate - Critical projects where data loss prevention is paramount - When you want manual review before pushing large changes **When to keep it disabled (default):** - Single-user workflows where you trust your local changes - CI/CD pipelines that need non-interactive sync - When you want hands-free automation ### Example: Jira Integration ```bash # Configure Jira connection bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set jira.projects "PROJ1,PROJ2" # Multiple projects (comma-separated) bd config set jira.api_token "YOUR_TOKEN" # Map bd statuses to Jira statuses bd config set jira.status_map.open "To Do" bd config set jira.status_map.in_progress "In Progress" bd config set jira.status_map.closed "Done" # Map bd issue types to Jira issue types bd config set jira.type_map.bug "Bug" bd config set jira.type_map.feature "Story" bd config set jira.type_map.task "Task" ``` ### Example: Linear Integration Linear integration provides bidirectional sync between bd and Linear via GraphQL API. **Required configuration:** ```bash # API Key (recommended: use environment variable to avoid git exposure) export LINEAR_API_KEY="lin_api_YOUR_API_KEY" # add to ~/.secrets or ~/.zshrc # Team ID (find in Linear team settings or URL) bd config set linear.team_id "team-uuid-here" # Multiple team IDs (comma-separated; can also use LINEAR_TEAM_IDS env var) bd config set linear.team_ids "uuid-team-1,uuid-team-2" ``` When `linear.team_ids` is set, `bd linear sync` fetches issues from all listed teams. For push operations with multiple teams, use the `--team` flag to specify the target. The singular `linear.team_id` is still supported for backward compatibility. **Getting your Linear credentials:** 1. **API Key**: Go to Linear → Settings → API → Personal API keys → Create key 2. **Team ID**: Go to Linear → Settings → General → Team ID (or extract from URLs) **Priority mapping (Linear 0-4 → Beads 0-4):** Linear and Beads both use 0-4 priority scales, but with different semantics: - Linear: 0=no priority, 1=urgent, 2=high, 3=medium, 4=low - Beads: 0=critical, 1=high, 2=medium, 3=low, 4=backlog Default mapping (configurable): ```bash bd config set linear.priority_map.0 4 # No priority -> Backlog bd config set linear.priority_map.1 0 # Urgent -> Critical bd config set linear.priority_map.2 1 # High -> High bd config set linear.priority_map.3 2 # Medium -> Medium bd config set linear.priority_map.4 3 # Low -> Low ``` **State mapping (Linear state types → Beads statuses):** Map Linear workflow state types to Beads statuses: ```bash bd config set linear.state_map.backlog open bd config set linear.state_map.unstarted open bd config set linear.state_map.started in_progress bd config set linear.state_map.completed closed bd config set linear.state_map.canceled closed # For custom workflow states, use lowercase state name: bd config set linear.state_map.in_review in_progress bd config set linear.state_map.blocked blocked bd config set linear.state_map.on_hold blocked ``` **Label to issue type mapping:** Infer bd issue type from Linear labels: ```bash bd config set linear.label_type_map.bug bug bd config set linear.label_type_map.defect bug bd config set linear.label_type_map.feature feature bd config set linear.label_type_map.enhancement feature bd config set linear.label_type_map.epic epic bd config set linear.label_type_map.chore chore bd config set linear.label_type_map.maintenance chore bd config set linear.label_type_map.task task ``` **Relation type mapping (Linear relations → Beads dependencies):** ```bash bd config set linear.relation_map.blocks blocks bd config set linear.relation_map.blockedBy blocks bd config set linear.relation_map.duplicate duplicates bd config set linear.relation_map.related related ``` Relation import is opt-in when pulling: ```bash bd linear sync --pull --relations ``` **Sync commands:** ```bash # Bidirectional sync (pull then push, with conflict resolution) bd linear sync # Pull only (import from Linear) bd linear sync --pull # Pull only if data is stale (skip if fresh) bd linear sync --pull-if-stale # Pull with custom staleness threshold (default 20m) bd linear sync --pull-if-stale --threshold 5m # Pull issues and Linear relations as bd dependencies bd linear sync --pull --relations # Pull and rebuild Linear project milestones as local epic parents bd linear sync --pull --milestones # Push only (export to Linear) bd linear sync --push # Dry run (preview without changes) bd linear sync --dry-run # Conflict resolution options bd linear sync --prefer-local # Local version wins on conflicts bd linear sync --prefer-linear # Linear version wins on conflicts # Default: newer timestamp wins # Check sync status bd linear status ``` **Staleness detection:** After each successful pull, `bd` writes the current timestamp to `.beads/last_pull`. This enables ambient staleness detection: - **`--pull-if-stale`**: Only pull if data is older than the threshold (default 20m). When data is fresh, prints "Linear data is fresh" and exits. In `--json` mode, includes `"is_fresh": true/false`. - **`--threshold`**: Override the default 20-minute staleness threshold (e.g., `--threshold 5m`). - **Debounce**: A 5-minute debounce prevents agent loops — if a pull completed within the last 5 minutes, data is always treated as fresh regardless of the threshold. - **`bd prime` auto-pull**: When `LINEAR_API_KEY` is set and data is stale, `bd prime` automatically pulls from Linear before emitting orientation output. - **Per-session warning**: On any `bd` command, if data is stale, a one-time warning is emitted to stderr: `⚠ Linear data is 45m stale — run 'bd linear sync --pull' to refresh`. Suppressed in subsequent commands within the same shell session. **Automatic sync tracking:** The `linear.last_sync` config key is automatically updated after each sync, enabling incremental sync (only fetch issues updated since last sync). ### Example: GitHub Integration ```bash # Configure GitHub connection bd config set github.org "myorg" bd config set github.repo "myrepo" bd config set github.token "YOUR_TOKEN" # Map bd labels to GitHub labels bd config set github.label_map.bug "bug" bd config set github.label_map.feature "enhancement" ``` ### Example: Azure DevOps (ADO) Integration Azure DevOps integration provides bidirectional sync between bd and ADO work items. **Required configuration:** ```bash # Personal access token (can also use AZURE_DEVOPS_PAT environment variable) bd config set ado.pat "YOUR_PAT" # Organization name (can also use AZURE_DEVOPS_ORG environment variable) bd config set ado.org "myorg" # Project name (can also use AZURE_DEVOPS_PROJECT environment variable) bd config set ado.project "MyProject" # Multiple projects (comma-separated; can also use AZURE_DEVOPS_PROJECTS env var) bd config set ado.projects "Project1,Project2" ``` When `ado.projects` is set, `bd ado sync` fetches work items from all listed projects in a single WIQL query. The singular `ado.project` is still supported for backward compatibility. **Optional configuration:** ```bash # Custom base URL for Azure DevOps Server (on-prem) instances # (can also use AZURE_DEVOPS_URL environment variable) # When set, ado.org is not required — the URL replaces the default dev.azure.com base. bd config set ado.url "https://ado.internal.example.com/DefaultCollection" ``` **Getting your Azure DevOps PAT:** 1. Go to Azure DevOps → User Settings (top-right icon) → Personal access tokens 2. Click "New Token" 3. Select the organization and set an expiration 4. Grant **Work Items: Read & Write** scope (minimum for sync) 5. Copy the token — it is only shown once **State mapping (ADO Agile template defaults → Beads statuses):** ADO uses process-template-specific states (Agile, Scrum, CMMI). The defaults use the Agile template. Override with `ado.state_map.*` for your process: ```bash # Default Agile mapping (built-in, no config needed): # New → open # Active → in_progress # Resolved → closed # Closed → closed # Removed → deferred # Override for Scrum template: bd config set ado.state_map.open "New" bd config set ado.state_map.in_progress "Committed" bd config set ado.state_map.blocked "Committed" bd config set ado.state_map.deferred "Removed" bd config set ado.state_map.closed "Done" ``` **Type mapping (ADO work item types ↔ Beads issue types):** ```bash # Default mapping (built-in, no config needed): # Bug → bug # User Story → feature # Product Backlog Item → feature # Task → task # Epic → epic # Override for your process template: bd config set ado.type_map.bug "Bug" bd config set ado.type_map.feature "Feature" bd config set ado.type_map.task "Task" bd config set ado.type_map.epic "Epic" bd config set ado.type_map.chore "Task" ``` **Priority mapping (ADO 1-4 → Beads 0-4):** ADO uses a 1-4 scale; Beads uses 0-4. The mapping is: - ADO 1 (Critical) → Beads 0 (Critical) - ADO 2 (High) → Beads 1 (High) - ADO 3 (Medium) → Beads 2 (Medium) - ADO 4 (Low) → Beads 3 (Low) - Beads 4 (Backlog) → ADO 4 (lossy: backlog collapses to low) Priority mapping is not configurable — it is handled automatically. **Environment variables:** All ADO config keys have environment variable equivalents: | Config Key | Environment Variable | |----------------|--------------------------| | `ado.pat` | `AZURE_DEVOPS_PAT` | | `ado.org` | `AZURE_DEVOPS_ORG` | | `ado.project` | `AZURE_DEVOPS_PROJECT` | | `ado.projects` | `AZURE_DEVOPS_PROJECTS` | | `ado.url` | `AZURE_DEVOPS_URL` | Environment variables take effect when the corresponding `bd config` key is not set. **Sync commands:** ```bash # Bidirectional sync (pull then push, with conflict resolution) bd ado sync # Pull only (import from Azure DevOps) bd ado sync --pull-only # Push only (export to Azure DevOps) bd ado sync --push-only # Dry run (preview without changes) bd ado sync --dry-run # Conflict resolution options bd ado sync --prefer-local # Local version wins on conflicts bd ado sync --prefer-ado # Azure DevOps version wins on conflicts bd ado sync --prefer-newer # Most recent version wins (default) # Check sync status and configuration bd ado status # List accessible projects (useful for finding your project name) bd ado projects --json ``` **Automatic sync tracking:** The `ado.last_sync` config key is automatically updated after each sync, enabling incremental sync (only fetch work items updated since last sync). ## Use in Scripts Configuration is designed for scripting. Use `--json` for machine-readable output: ```bash #!/bin/bash # Get Jira URL JIRA_URL=$(bd config get --json jira.url | jq -r '.value') # Get all config and extract multiple values bd config list --json | jq -r '.["jira.project"]' ``` Example Python script: ```python import json import subprocess def get_config(key): result = subprocess.run( ["bd", "config", "get", "--json", key], capture_output=True, text=True ) data = json.loads(result.stdout) return data["value"] def list_config(): result = subprocess.run( ["bd", "config", "list", "--json"], capture_output=True, text=True ) return json.loads(result.stdout) # Use in integration jira_url = get_config("jira.url") jira_project = get_config("jira.project") ``` ## Best Practices 1. **Use namespaces**: Prefix keys with integration name (e.g., `jira.*`, `linear.*`) 2. **Hierarchical keys**: Use dots for structure (e.g., `jira.status_map.open`) 3. **Document your keys**: Add comments in integration scripts 4. **Security**: Store tokens in config, but ensure `.beads/dolt/` and `.beads/*.db` are in `.gitignore` (bd does this automatically) 5. **Per-project**: Configuration is project-specific, so each repo can have different settings ## Integration with bd Commands Some bd commands automatically use configuration: - `bd admin compact` uses `compact_tier1_days`, `compact_tier1_dep_levels`, etc. - `bd init` sets `issue_prefix` External integration scripts can read configuration to sync with Jira, Linear, GitHub, etc. ## See Also - [README.md](../README.md) - Main documentation - [ADVANCED.md](ADVANCED.md) - Extensible Database section and other advanced topics