Linear Batch Update Script

A powerful Rust-based CLI tool for batch creating and updating issues in Linear using their GraphQL API. This tool supports both JSON and CSV input formats and includes comprehensive validation, dry-run mode, and efficient batch processing capabilities.

Features

• 🚀 Batch Creation: Create multiple Linear issues in a single operation
• 📁 Multiple Input Formats: Support for both JSON and CSV files
• ✅ Validation: Validate your data before sending to Linear
• 🔍 Dry Run Mode: Test your batch without creating actual issues
• 📦 Configurable Batching: Control batch size for large datasets
• 🎯 Comprehensive Field Support: Supports all Linear issue fields
• ⚡ Fast & Efficient: Written in Rust for optimal performance
• 🔒 Secure: API key stored in environment variables

Installation

Prerequisites

• Rust 1.70 or higher
• Linear API key (get it from Linear Settings)

Build from Source

# Clone the repository
git clone https://github.com/SeanningTatum/linear-batch-update-script
cd linear-batch-update-script

# Build the project
cargo build --release

# The binary will be available at target/release/linear-batch-update-script

Configuration

1. Create a .env file in the project root (or copy from env.example):

   cp env.example .env
   

2. Add your Linear API key to the .env file:

   LINEAR_API_KEY=lin_api_YOUR_API_KEY_HERE
   

Getting Linear IDs (Team, Labels, Users, etc.)

⚠️ IMPORTANT: Linear uses UUIDs for all IDs (teams, labels, users, states, projects, etc.). These look like: 12345678-1234-1234-1234-123456789012

Option 1: Use the Helper Script (Recommended)

We provide a Python helper script to fetch all IDs from your Linear workspace:

# Install Python dependencies
pip install requests python-dotenv

# Run the helper script (make sure LINEAR_API_KEY is set)
python examples/fetch_linear_ids.py

This script will:

• Display all teams, labels, users, workflow states, and projects
• Save the data to linear_ids.json for reference
• Create an example_issues_with_ids.json file with real IDs from your workspace

Option 2: Manual Lookup

1. Team ID: Go to Linear Settings → Teams → Click on your team → Check the URL
2. Label IDs: You'll need to use Linear's API or GraphQL explorer
3. User IDs: Use the API or check user profile URLs
4. State IDs: Use the API to get workflow states for your team
5. Project IDs: Check project URLs or use the API

Common ID Format Issues

• ❌ "teamId": "YOUR_TEAM_ID" - Placeholder, won't work
• ❌ "labelIds": ["bug", "feature"] - Label names, not IDs
• ✅ "teamId": "b5a51e4e-2f3e-4d8a-9c1b-1a2b3c4d5e6f" - Correct UUID format
• ✅ "labelIds": ["a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"] - Correct label UUID

Usage

Basic Commands

# Create issues from JSON file with team ID
./target/release/linear-batch-update-script create --file examples/issues.json --team-id YOUR_TEAM_ID

# Create issues from JSON file with team ID and project ID
./target/release/linear-batch-update-script create --file examples/issues.json --team-id YOUR_TEAM_ID --project-id YOUR_PROJECT_ID

# Create issues from CSV file
./target/release/linear-batch-update-script create-from-csv --file examples/issues.csv --team-id YOUR_TEAM_ID

# Create issues from CSV file with project ID
./target/release/linear-batch-update-script create-from-csv --file examples/issues.csv --team-id YOUR_TEAM_ID --project-id YOUR_PROJECT_ID

# Validate JSON file without creating issues
./target/release/linear-batch-update-script validate --file examples/issues.json

# Dry run (validate without creating)
./target/release/linear-batch-update-script create --file examples/issues.json --team-id YOUR_TEAM_ID --dry-run

# Custom batch size (default is 50)
./target/release/linear-batch-update-script create --file examples/issues.json --team-id YOUR_TEAM_ID --batch-size 25

Command-Line Options

Required Environment Variable:

• LINEAR_API_KEY - Your Linear API key (set in .env file)

Required Flags:

• --file or -f - Path to the JSON or CSV file containing issues
• --team-id or -t - Linear team UUID (e.g., b5a51e4e-2f3e-4d8a-9c1b-1a2b3c4d5e6f)

Optional Flags:

• --project-id or -p - Linear project UUID to assign all issues to a project
• --dry-run or -d - Validate without creating issues
• --batch-size or -b - Number of issues to create per batch (default: 50)

Example with all flags:

./target/release/linear-batch-update-script create \
  --file examples/issues.json \
  --team-id b5a51e4e-2f3e-4d8a-9c1b-1a2b3c4d5e6f \
  --project-id a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d \
  --batch-size 25 \
  --dry-run

JSON Format

Create a JSON file with an array of issues. Each issue must have at least teamId and title:

[
  {
    "teamId": "YOUR_TEAM_ID",
    "title": "Issue title",
    "description": "Detailed description",
    "priority": 2,
    "estimate": 5,
    "assigneeId": "USER_ID",
    "labelIds": ["bug", "backend"],
    "projectId": "PROJECT_ID",
    "cycleId": "CYCLE_ID",
    "dueDate": "2024-12-31"
  }
]

CSV Format

Create a CSV file with the following columns:

title,description,assigneeId,priority,stateId,labelIds,projectId,cycleId,dueDate,estimate
"Issue title","Description here",,2,,"bug,frontend",PROJECT_ID,CYCLE_ID,2024-12-31,5

Note: When using CSV, you must provide the team ID via command line argument.

Supported Fields

The script supports all Linear issue fields:

Required Fields

• teamId - The team identifier (required)
• title - Issue title (required)

Optional Fields

• description - Issue description in markdown
• assigneeId - User to assign the issue to
• priority - Priority level (0-4: None, Urgent, High, Normal, Low)
• stateId - Workflow state identifier
• labelIds - Array of label identifiers
• projectId - Project identifier
• projectMilestoneId - Project milestone identifier
• cycleId - Cycle identifier
• parentId - Parent issue identifier (for sub-issues)
• dueDate - Due date (YYYY-MM-DD format)
• estimate - Complexity estimate points
• sortOrder - Custom sort order
• boardOrder - Position in board view
• prioritySortOrder - Priority-based sort order
• subscriberIds - Array of subscriber user IDs
• createdAt - Custom creation date (for imports)
• completedAt - Completion date (for imports)
• templateId - Template to use for creation
• useDefaultTemplate - Use team's default template
• createAsUser - Create as specific user (OAuth apps only)
• delegateId - Delegate to agent user
• slaType - SLA day count type

Examples

Example 1: Simple Batch Creation

Create a file my-issues.json:

[
  {
    "teamId": "TEAM_123",
    "title": "Fix login bug",
    "priority": 1
  },
  {
    "teamId": "TEAM_123",
    "title": "Add dark mode",
    "priority": 3,
    "estimate": 5
  }
]

Run:

./target/release/linear-batch-update-script create --file my-issues.json

Example 2: CSV Import with Team Assignment

Create a file sprint-issues.csv:

title,description,assigneeId,priority,estimate
"Update API docs","Document v2 endpoints",USER_123,3,3
"Fix memory leak","Investigate worker process",USER_456,1,5

Run:

./target/release/linear-batch-update-script create-from-csv --file sprint-issues.csv --team-id TEAM_123

Example 3: Large Batch with Custom Size

For large datasets, adjust the batch size:

./target/release/linear-batch-update-script create --file large-dataset.json --batch-size 100

Output

The script provides detailed output for each operation:

🚀 Linear Batch Update Script
📄 Loading issues from: examples/issues.json
📋 Total issues to create: 5
📦 Processing 1 batch(es) of up to 50 issues each

⏳ Processing batch 1/1 (5 issues)...
✅ Batch 1 created successfully!
   📝 Created: PROJ-123 - Fix login bug
   📝 Created: PROJ-124 - Add dark mode

📊 Summary:
   ✅ Successfully created: 5 issues
   ❌ Failed: 0 issues

Error Handling

The script includes comprehensive error handling:

• Validation errors: Issues are validated before sending to API
• API errors: Detailed error messages from Linear API
• Network errors: Retry logic for transient failures
• File errors: Clear messages for file reading issues

Rate Limiting

The script automatically handles rate limiting:

• Batches requests (default: 50 issues per batch)
• Adds delays between batches to prevent rate limit errors
• Configurable batch size via --batch-size flag

Tips

1. Start with dry run: Always test with --dry-run first
2. Use validation: Run validate command to check your data
3. Small batches first: Test with a few issues before large imports
4. Check IDs: Ensure all referenced IDs (team, user, project) exist in Linear
5. CSV for simple data: Use CSV for straightforward imports
6. JSON for complex data: Use JSON when you need all field options

Troubleshooting

Common Issues

1. "LINEAR_API_KEY environment variable not set"

   • Solution: Create .env file with your API key

2. "Invalid team_id"

   • Solution: Verify team ID in Linear settings

3. "Rate limit exceeded"

   • Solution: Reduce batch size with --batch-size 25

4. "Invalid priority"

   • Solution: Use values 0-4 (0=None, 1=Urgent, 2=High, 3=Normal, 4=Low)

Development

Running Tests

cargo test

Building for Release

cargo build --release

Adding New Features

1. Update the IssueInput struct in src/main.rs
2. Add new field to CSV parser if needed
3. Update validation logic
4. Add examples to documentation

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues or questions:

1. Check this README and examples
2. Review Linear API documentation
3. Open an issue on GitHub