Skip to main content
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 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>
Flags:

​
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>
Flags:

​
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 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
Flags:

​
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”