Linear Source

Fetch specifications from Linear issues to build features from your project management tool.

Authentication

Get your API key from Linear Settings > API > Personal API keys.

ralph-starter config set linear.apiKey lin_api_xxxxxxxxxxxx

Interactive Wizard

The easiest way to get started:

ralph-starter linear

This will:

1. Check your authentication (prompt for API key if needed)
2. Let you select a team, then browse projects or issues
3. Start the build loop automatically

You can also paste a Linear issue URL directly when prompted.

Wizard Options

ralph-starter linear --commit          # Auto-commit after tasks
ralph-starter linear --push            # Push commits to remote
ralph-starter linear --pr              # Create PR when done
ralph-starter linear --agent claude-code  # Use a specific agent

Fallback

If you run --from linear without specifying a project, the wizard launches automatically:

ralph-starter run --from linear        # Launches wizard

Usage

# Fetch issues by label
ralph-starter run --from linear --label "ready-to-build"

# Filter by project
ralph-starter run --from linear --project "Mobile App"

# Filter by status
ralph-starter run --from linear --status "In Progress"

# Combine filters
ralph-starter run --from linear --project "Web App" --label "sprint-1" --limit 10

Options

Option	Description	Default
--project	Project name	None (all projects)
--label	Filter by label	None
--status	Filter by status	None
--limit	Maximum issues to fetch	20

Issue Format

Linear issues are well-suited for ralph-starter because they typically contain:

• Title
• Description (with markdown support)
• Acceptance criteria
• Sub-issues
• Labels and priority

Example Linear Issue

Title: Add user authentication

Description:
Implement email/password authentication for the web app.

## Requirements
- Login page with email/password
- Registration with email verification
- Password reset flow
- Remember me functionality

## Technical Notes
- Use NextAuth.js
- Store sessions in database
- Add rate limiting

## Acceptance Criteria
- [ ] User can register with email
- [ ] User receives verification email
- [ ] User can log in
- [ ] User can reset password

Generated Spec

# Add user authentication

Source: Linear Issue ENG-123
Project: Web App
Labels: feature, authentication
Priority: High

## Description
Implement email/password authentication for the web app.

## Requirements
- Login page with email/password
- Registration with email verification
- Password reset flow
- Remember me functionality

## Technical Notes
- Use NextAuth.js
- Store sessions in database
- Add rate limiting

## Acceptance Criteria
- [ ] User can register with email
- [ ] User receives verification email
- [ ] User can log in
- [ ] User can reset password

Preview Issues

ralph-starter source preview linear --label "ready-to-build"

Test Connection

ralph-starter source test linear

Workflow Integration

Recommended Labels

Create these labels in Linear:

• ralph-ready - Issue is well-specified and ready to build
• ralph-building - Currently being built by ralph-starter
• ralph-done - Built by ralph-starter

Automation Ideas

1. Move issues to "In Progress" when ralph-starter starts
2. Add comments with build progress
3. Close issues when build succeeds

Task Management

Beyond fetching specs, you can create, update, close, and assign Linear issues from the CLI:

# List issues from Linear
ralph-starter task list --source linear

# Create an issue on a specific team
ralph-starter task create --title "Add dark mode" --source linear --priority P1

# Assign an issue (resolves display name to user ID automatically)
ralph-starter task update ENG-42 --assignee ruben

# Update status
ralph-starter task update ENG-42 --status "In Progress"

# Close an issue
ralph-starter task close ENG-42 --comment "Shipped in v1.2"

Assignee resolution is case-insensitive and matches against display name, full name, and email prefix. If no match is found, ralph-starter shows available team members.

See ralph-starter task for full details.

Tips

1. Write detailed issues - Linear's rich markdown support is perfect for detailed specs
2. Use acceptance criteria - Checkboxes become testable requirements
3. Link related issues - Sub-issues provide additional context
4. Add technical notes - Specify tech preferences in the description