mirror of
https://github.com/gastownhall/beads.git
synced 2026-09-14 20:17:24 +08:00
Chris Sells
d2f87d50de
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a regeneration from main's source onto the PR branch, so the squash landed a contradictory mix — the release-aligned hand-written docs plus a CLI reference re-documenting unreleased commands and flags, with docs.json referencing four pages (heartbeat, migrate-personal, reclaim, unclaim) whose files do not exist. That broken nav fails the docsync guard on main and on every branch cut from it. This restores the intended end state of #4874 and lands the pin that prevents the race from recurring. - Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's canonical pure-Go build), removing the unreleased commands/flags and fixing the dangling nav entries. - docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh builds and caches a canonical pure-Go bd from that tag, fetching the tag first in shallow CI checkouts. - generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh resolve bd through the pin and ignore a supplied binary while pinned (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot now enforce docs-match-release instead of docs-match-main. - tools/docsmint detects the pre-overhaul Docusaurus staging layout that bd <= v1.1.0 emits and converts it to the generic form before its normal Mintlify transform (tested); removable once the pin reaches a release whose emitter writes build/cli-docs. - check-doc-flags.sh: run without timeout(1) on macOS instead of failing Check 4. - Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the beads-docs skill §8 updated to match. * lint: annotate gosec G705 false positive in the docsmint legacy bridge Same class as the existing nav-splice annotation: a developer tool writing repo Markdown, not a web-output sink.
212 lines
8.0 KiB
Markdown
212 lines
8.0 KiB
Markdown
---
|
|
title: "bd linear"
|
|
description: "Synchronize issues between beads and Linear."
|
|
---
|
|
|
|
{/* AUTO-GENERATED: do not edit manually */}
|
|
|
|
Generated from `bd help --doc linear`.
|
|
|
|
Synchronize issues between beads and Linear.
|
|
|
|
Configuration:
|
|
bd config set linear.api_key "YOUR_API_KEY"
|
|
bd config set linear.team_id "TEAM_ID"
|
|
bd config set linear.team_ids "TEAM_ID1,TEAM_ID2" # Multiple teams (comma-separated)
|
|
bd config set linear.project_id "PROJECT_ID" # Optional: sync only this project
|
|
|
|
Environment variables (alternative to config):
|
|
LINEAR_API_KEY - Linear API key (for individual developers)
|
|
LINEAR_TEAM_ID - Linear team ID (UUID, singular)
|
|
LINEAR_TEAM_IDS - Linear team IDs (comma-separated UUIDs)
|
|
|
|
OAuth (for CI workers / automated sync):
|
|
LINEAR_OAUTH_CLIENT_ID - OAuth app client ID
|
|
LINEAR_OAUTH_CLIENT_SECRET - OAuth app client secret
|
|
|
|
When both OAuth env vars are set, OAuth client_credentials flow is used
|
|
instead of the API key. This allows CI workers to authenticate as an
|
|
application (actor=application) rather than impersonating a user.
|
|
Precedence: OAuth > LINEAR_API_KEY > config file.
|
|
|
|
Data Mapping (optional, sensible defaults provided):
|
|
Priority mapping (Linear 0-4 to Beads 0-4):
|
|
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 type to Beads status):
|
|
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
|
|
bd config set linear.state_map.my_custom_state in_progress # Custom state names
|
|
|
|
Label to issue type mapping:
|
|
bd config set linear.label_type_map.bug bug
|
|
bd config set linear.label_type_map.feature feature
|
|
bd config set linear.label_type_map.epic epic
|
|
|
|
Relation type mapping (Linear relations to Beads dependencies):
|
|
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
|
|
|
|
ID generation (optional, hash IDs to match bd/Jira hash mode):
|
|
bd config set linear.id_mode "hash" # hash (default)
|
|
bd config set linear.hash_length "6" # hash length 3-8 (default: 6)
|
|
|
|
Examples:
|
|
bd linear sync --pull # Import issues from Linear
|
|
bd linear sync --push # Export issues to Linear
|
|
bd linear sync # Bidirectional sync (pull then push)
|
|
bd linear sync --dry-run # Preview sync without changes
|
|
bd create "Fix login" --external-ref https://linear.app/team/issue/TEAM-123
|
|
# Link a local issue to an existing Linear issue
|
|
bd linear status # Show sync status
|
|
|
|
```
|
|
bd linear [flags]
|
|
```
|
|
|
|
## bd linear pull
|
|
|
|
Pull one or more items from Linear.
|
|
|
|
Accepts bead IDs or external references as positional arguments.
|
|
Equivalent to: bd linear sync --pull --issues <refs>
|
|
|
|
```
|
|
bd linear pull [refs...] [flags]
|
|
```
|
|
|
|
**Flags:**
|
|
|
|
```
|
|
--dry-run Preview pull without making changes
|
|
--relations Import Linear relations as bd dependencies when pulling
|
|
```
|
|
|
|
## bd linear push
|
|
|
|
Push one or more beads issues to Linear.
|
|
|
|
Accepts bead IDs as positional arguments.
|
|
Equivalent to: bd linear sync --push --issues <ids>
|
|
|
|
```
|
|
bd linear push [bead-ids...] [flags]
|
|
```
|
|
|
|
**Flags:**
|
|
|
|
```
|
|
--dry-run Preview push without making changes
|
|
```
|
|
|
|
## bd linear status
|
|
|
|
Show the current Linear sync status, including:
|
|
- Last sync timestamp
|
|
- Configuration status
|
|
- Number of issues with Linear links
|
|
- Issues pending push (no external_ref)
|
|
|
|
```
|
|
bd linear status [flags]
|
|
```
|
|
|
|
## bd linear sync
|
|
|
|
Synchronize issues between beads and Linear.
|
|
|
|
Modes:
|
|
--pull Import issues from Linear into beads
|
|
--push Export issues from beads to Linear
|
|
--pull-if-stale Pull only if data is stale (skip if fresh)
|
|
(no flags) Bidirectional sync: pull then push, with conflict resolution
|
|
|
|
Staleness (--pull-if-stale):
|
|
--threshold 20m How old data must be before pulling (default 20m)
|
|
A 5-minute debounce prevents agent loops: if a pull completed within 5 minutes,
|
|
data is always treated as fresh regardless of the threshold.
|
|
|
|
Team Selection:
|
|
--team ID1,ID2 Override configured team IDs for this sync
|
|
Multiple teams can be configured via linear.team_ids (comma-separated).
|
|
Falls back to linear.team_id for backward compatibility.
|
|
Push requires explicit --team when multiple teams are configured.
|
|
|
|
Pull Options:
|
|
--milestones Reconstruct Linear project milestones as local epic parents
|
|
|
|
Type Filtering (--push only):
|
|
--type task,feature Only sync issues of these types
|
|
--exclude-type wisp Exclude issues of these types
|
|
--include-ephemeral Include ephemeral issues (wisps, etc.); default is to exclude
|
|
--parent TICKET Only push this ticket and its descendants
|
|
--relations Import Linear relations as bd dependencies on pull
|
|
|
|
Conflict Resolution:
|
|
By default, newer timestamp wins. Override with:
|
|
--prefer-local Always prefer local beads version
|
|
--prefer-linear Always prefer Linear version
|
|
|
|
Examples:
|
|
bd linear sync --pull # Import from Linear
|
|
bd linear sync --pull-if-stale # Pull only if data is stale
|
|
bd linear sync --pull-if-stale --threshold 5m # Pull if older than 5 minutes
|
|
bd linear sync --pull --relations # Import Linear blocking relations as bd deps
|
|
bd linear sync --push --create-only # Push new issues only
|
|
bd linear sync --push --type=task,feature # Push only tasks and features
|
|
bd linear sync --push --exclude-type=wisp # Push all except wisps
|
|
bd linear sync --push --parent=bd-abc123 # Push one ticket tree
|
|
bd linear sync --dry-run # Preview without changes
|
|
bd linear sync --prefer-local # Bidirectional, local wins
|
|
|
|
```
|
|
bd linear sync [flags]
|
|
```
|
|
|
|
**Flags:**
|
|
|
|
```
|
|
--create-only Only create new issues, don't update existing
|
|
--dry-run Preview sync without making changes
|
|
--exclude-type strings Exclude issues of these types (can be repeated)
|
|
--include-ephemeral Include ephemeral issues (wisps, etc.) when pushing to Linear
|
|
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
|
|
--milestones Reconstruct Linear project milestones as local epic parents when pulling
|
|
--no-wait Fail immediately if another sync is running instead of waiting
|
|
--parent string Limit push to this beads ticket and its descendants
|
|
--prefer-linear Prefer Linear version on conflicts
|
|
--prefer-local Prefer local version on conflicts
|
|
--pull Pull issues from Linear
|
|
--pull-if-stale Pull only if Linear data is stale (skip if fresh)
|
|
--push Push issues to Linear
|
|
--relations Import Linear relations as bd dependencies when pulling
|
|
--state string Issue state to sync: open, closed, all (default "all")
|
|
--team strings Team ID(s) to sync (overrides configured team_id/team_ids)
|
|
--threshold duration Staleness threshold for --pull-if-stale (default 20m) (default 20m0s)
|
|
--type strings Only sync issues of these types (can be repeated)
|
|
--update-refs Update external_ref after creating Linear issues (default true)
|
|
```
|
|
|
|
## bd linear teams
|
|
|
|
List all teams accessible with your Linear API key.
|
|
|
|
Use this to find the team ID (UUID) needed for configuration.
|
|
|
|
Example:
|
|
bd linear teams
|
|
bd config set linear.team_id "12345678-1234-1234-1234-123456789abc"
|
|
|
|
```
|
|
bd linear teams [flags]
|
|
```
|