linear

Linear

Manage issues, check project status, and stay on top of your team's work.

Setup

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:

{baseDir}/scripts/linear.sh teams

If LINEAR_DEFAULT_TEAM is set, you can omit the team key in team and call:

{baseDir}/scripts/linear.sh create "Title" ["Description"]

Quick Commands

# 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

{baseDir}/scripts/linear.sh standup

Shows: your todos, blocked items across team, recently completed, what's in review.

Quick Issue Creation (from chat)

{baseDir}/scripts/linear.sh create TEAM "Fix auth timeout bug" "Users getting logged out after 5 min"

Triage Mode

{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

{baseDir}/scripts/linear.sh branch TEAM-212
# Returns: dev/team-212-fix-auth-timeout-bug

Creating a Worktree for an Issue

# 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

# 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 by Peter Schilling (ISC License). This is an independent bash implementation for Clawdbot integration.