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 [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 <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 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]