Skip to main content

​
Linear Integration

Sync your tk issues with Linear for team collaboration. Keep your local Markdown issues in sync with Linear’s project management.

​
Setup

​
1. Create a Linear API Key

Go to Linear Settings → API and create a personal API key.

​
2. Configure tk

tk config set linear.api_key lin_api_xxxxx
Or use an environment variable: 
export LINEAR_API_KEY=lin_api_xxxxx

​
3. Select a Team

List available teams: 
tk linear teams
Set the team to sync with: 
tk config set linear.team_id <TEAM_ID>

​
Sync Issues

​
Pull from Linear

Import Linear issues into tk: 
tk linear sync --pull

​
Push to Linear

Push local tk issues to Linear: 
tk linear sync --push

​
Bidirectional Sync

Sync both directions: 
tk linear sync

​
Mapping

tk FieldLinear Field
titleIssue title
descriptionIssue description
status: openBacklog/Todo
status: in_progressIn Progress
status: closedDone
priority: 0Urgent
priority: 1High
priority: 2Medium
priority: 3Low
labelsLabels

​
Check Status

View sync status: 
tk linear status

​
Configuration Options

# Set API key
tk config set linear.api_key <KEY>

# Set team ID
tk config set linear.team_id <TEAM_ID>

# Set project (optional)
tk config set linear.project_id <PROJECT_ID>

​
Workflow Example

# List teams and pick one
tk linear teams
tk config set linear.team_id ENG

# Initial import from Linear
tk linear sync --pull

# Work locally
tk create "Fix performance issue" -t bug -p 1

# Sync back to Linear
tk linear sync --push

​
Troubleshooting

Verify your API key:
tk config get linear.api_key
Make sure it starts with lin_api_.
List available teams:
tk linear teams
Then set the correct team ID.
Linear has custom workflow states. tk maps to the closest standard state. Check tk linear status for details.

​
Next Steps

GitHub Sync

Sync with GitHub Issues.

CLI Reference

Full command documentation.