beads/docs/cli-reference/linear.md
Chris Sells de0200ff77 docs(emitter): Cobra-accurate usage lines, published global flags, MDX ESM guard
Three generated-content defects from the adversarial review, all
structurally invisible to the drift gate (generated-vs-generated):

- Usage lines now mirror Cobra's help template: a runnable command shows
  its UseLine, a command with subcommands shows '<path> [command]', both
  when both apply. Previously bare UseLine() stamped 'bd mol [flags]' on
  30 parent pages — a line the binary never prints.
- The generated CLI index publishes the Global Flags block; the binary
  prints it on every --help but no page carried it.
- docsmint neutralizes prose lines that Mintlify's prebuild would dedent
  into MDX ESM blocks (a line beginning 'export'/'import' outside a
  fence gets wrapped in a code span). This is why /cli-reference/mail
  returned HTTP 200 while rendering only a parse-error placeholder —
  reproduced, fixed, and covered by a planted-hazard test; fenced
  content stays verbatim.

Also rewords check-cli-docs-drift.sh's early-PASS message, which
asserted 'the supplied binary differs' as the cause when uncommitted
local edits produce the same result.

All 113 pages + docs/CLI_REFERENCE.md regenerated through the pipeline;
TDD'd in cmd/bd/help_all_test.go and tools/docsmint/docsmint_test.go.
Verified live: /cli-reference/mail renders real content, zero parse
errors; generate-cli-docs.sh --check, docsync, freshness, and
mint broken-links all pass on this tree.
2026-07-12 10:37:17 -07:00

223 lines
8.7 KiB
Markdown

---
title: "bd linear"
description: "Linear integration commands"
---
{/* AUTO-GENERATED: do not edit manually */}
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 &gt; LINEAR_API_KEY &gt; 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 -&gt; Backlog
bd config set linear.priority_map.1 0 # Urgent -&gt; Critical
bd config set linear.priority_map.2 1 # High -&gt; High
bd config set linear.priority_map.3 2 # Medium -&gt; Medium
bd config set linear.priority_map.4 3 # Low -&gt; 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 &lt;refs&gt;
```
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 &lt;ids&gt;
```
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]
```