linear

# Linear Manage issues, check project status, and stay on top of your team's work. ## Setup ```bash export LINEAR_API_KEY="your-api-key" # Optional: default team key used when a command needs a team export LINEAR_DEFAULT_TEAM="TEAM" ``` Discover team keys: ```bash {baseDir}/scripts/linear.sh teams ``` If `LINEAR_DEFAULT_TEAM` is set, you can omit the team key in `team` and call: ```bash {baseDir}/scripts/linear.sh create "Title" ["Description"] ``` ## Quick Commands ```bash # My stuff {baseDir}/scripts/linear.sh my-issues # Your assigned issues {baseDir}/scripts/linear.sh my-todos # Just your Todo items {baseDir}/scripts/linear.sh urgent # Urgent/High priority across team # Browse {baseDir}/scripts/linear.sh teams # List available teams {baseDir}/scripts/linear.sh team <TEAM_KEY> # All issues for a team {baseDir}/scripts/linear.sh project <name> # Issues in a project {baseDir}/scripts/linear.sh issue <TEAM-123> # Get issue details {baseDir}/scripts/linear.sh branch <TEAM-123> # Get branch name for GitHub # Actions {baseDir}/scripts/linear.sh create <TEAM_KEY> "Title" ["Description"] {baseDir}/scripts/linear.sh comment <TEAM-123> "Comment text" {baseDir}/scripts/linear.sh status <TEAM-123> <todo|progress|review|done|blocked> {baseDir}/scripts/linear.sh assign <TEAM-123> <userName> {baseDir}/scripts/linear.sh priority <TEAM-123> <urgent|high|medium|low|none> # Overview {baseDir}/scripts/linear.sh standup # Daily standup summary {baseDir}/scripts/linear.sh projects # All projects with progress ``` ## Common Workflows ### Morning Standup ```bash {baseDir}/scripts/linear.sh standup ``` Shows: your todos, blocked items across team, recently completed, what's in review. ### Quick Issue Creation (from chat) ```bash {baseDir}/scripts/linear.sh create TEAM "Fix auth timeout bug" "Users getting logged out after 5 min" ``` ### Triage Mode ```bash {baseDir}/scripts/linear.sh urgent # See what needs attention ``` ## Git Workflow (Linear ↔ GitHub Integration) **Always use Linear-derived branch names** to enable automatic issue status tracking. ### Getting the Branch Name ```bash {baseDir}/scripts/linear.sh branch TEAM-212 # Returns: dev/team-212-fix-auth-timeout-bug ``` ### Creating a Worktree for an Issue ```bash # 1. Get the branch name from Linear BRANCH=$({baseDir}/scripts/linear.sh branch TEAM-212) # 2. Pull fresh main first (main should ALWAYS match origin) cd /path/to/repo git checkout main && git pull origin main # 3. Create worktree with that branch (branching from fresh origin/main) git worktree add .worktrees/team-212 -b "$BRANCH" origin/main cd .worktrees/team-212 # 4. Do your work, commit, push git push -u origin "$BRANCH" ``` **⚠️ Never modify files on main.** All changes happen in worktrees only. ### Why This Matters - Linear's GitHub integration tracks PRs by branch name pattern - When you create a PR from a Linear branch, the issue **automatically moves to "In Review"** - When the PR merges, the issue **automatically moves to "Done"** - Manual branch names break this automation - Keeping main clean = no accidental pushes, easy worktree cleanup ### Quick Reference ```bash # Full workflow example ISSUE="TEAM-212" BRANCH=$({baseDir}/scripts/linear.sh branch $ISSUE) # Always start from fresh main cd ~/workspace/your-repo git checkout main && git pull origin main # Create worktree (inside .worktrees/) git worktree add .worktrees/${ISSUE,,} -b "$BRANCH" origin/main cd .worktrees/${ISSUE,,} # ... make changes ... git add -A && git commit -m "fix: implement $ISSUE" git push -u origin "$BRANCH" gh pr create --title "$ISSUE: <title>" --body "Closes $ISSUE" ``` ## Priority Levels | Level | Value | Use for | |-------|-------|---------| | urgent | 1 | Production issues, blockers | | high | 2 | This week, important | | medium | 3 | This sprint/cycle | | low | 4 | Nice to have | | none | 0 | Backlog, someday | ## Teams (cached) Team keys and IDs are discovered via the API and cached locally after the first lookup. Use `linear.sh teams` to refresh and list available teams. ## Notes - Uses GraphQL API (api.linear.app/graphql) - Requires `LINEAR_API_KEY` env var - Issue identifiers are like `TEAM-123` ## Attribution Inspired by [schpet/linear-cli](https://github.com/schpet/linear-cli) by Peter Schilling (ISC License). This is an independent bash implementation for Clawdbot integration.