> ## Documentation Index > Fetch the complete documentation index at: https://beads.gascity.com/llms.txt > Use this file to discover all available pages before exploring further. # bd linear > Linear integration commands 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](https://linear.app/team/issue/TEAM-123) # Link a local issue to an existing Linear issue bd linear status # Show sync status ``` bd linear [command] ``` ## 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 \ ``` 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 \ ``` 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 Persistent push-direction ID filters (workflow artifacts, sandbox beads, etc.): bd config set linear.exclude\_id\_prefix "hw-mol-" bd config set linear.exclude\_id\_patterns "-wisp-,sandbox-,scratch-" exclude\_id\_prefix is a single case-sensitive prefix on the bead ID. exclude\_id\_patterns is a comma-separated list of case-sensitive substrings (matched anywhere in the ID). Both are combined as a union: a bead matching either rule is skipped from push (no create, no update). Beads with an existing external\_ref that NOW match are silently skipped on future syncs; the Linear-side issue persists — archive/delete it manually if desired. 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] ```