bd linear

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

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

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