website/docs/cli-reference/linear.md
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 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
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
Show the current Linear sync status, including:
bd linear status
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)
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