bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify form (frontmatter title as H1, extensionless root-relative links, JSX auto-generated markers since Mintlify parses .md through MDX) and rewrites the CLI Reference pages array inside docs/docs.json via a textual splice that leaves the rest of the file byte-identical — the ~113 nav entries are never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md, website/docs/cli-reference/, versioned snapshots) are unchanged. generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/ into its scratch root and diffs both; check-cli-docs-drift.sh adds them to GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh allowlists the new generated paths; check-doc-flags.sh scans the new docs/ subdirectories and requires command coverage in docs/cli-reference/. Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus sidebar IA) and the generated docs/cli-reference/ pages. TDD: new emitter behavior covered in cmd/bd/help_all_test.go (Mintlify page format, nav splice correctness + idempotence, bare-root generation without docs.json).
223 lines
8.7 KiB
Markdown
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 > 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 [flags]
|
|
```
|
|
|
|
## 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]
|
|
```
|