Introduction
# 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.