> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticket-rs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Sync tk issues with Linear

# Linear Integration

Sync your tk issues with [Linear](https://linear.app/) 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](https://linear.app/settings/api) and create a personal API key.

### 2. Configure tk

```bash theme={null}
tk config set linear.api_key lin_api_xxxxx
```

Or use an environment variable:

```bash theme={null}
export LINEAR_API_KEY=lin_api_xxxxx
```

### 3. Select a Team

List available teams:

```bash theme={null}
tk linear teams
```

Set the team to sync with:

```bash theme={null}
tk config set linear.team_id <TEAM_ID>
```

***

## Sync Issues

### Pull from Linear

Import Linear issues into tk:

```bash theme={null}
tk linear sync --pull
```

### Push to Linear

Push local tk issues to Linear:

```bash theme={null}
tk linear sync --push
```

### Bidirectional Sync

Sync both directions:

```bash theme={null}
tk linear sync
```

***

## Mapping

| tk Field              | Linear Field      |
| --------------------- | ----------------- |
| `title`               | Issue title       |
| `description`         | Issue description |
| `status: open`        | Backlog/Todo      |
| `status: in_progress` | In Progress       |
| `status: closed`      | Done              |
| `priority: 0`         | Urgent            |
| `priority: 1`         | High              |
| `priority: 2`         | Medium            |
| `priority: 3`         | Low               |
| `labels`              | Labels            |

***

## Check Status

View sync status:

```bash theme={null}
tk linear status
```

***

## Configuration Options

```bash theme={null}
# 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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Authentication failed">
    Verify your API key:

    ```bash theme={null}
    tk config get linear.api_key
    ```

    Make sure it starts with `lin_api_`.
  </Accordion>

  <Accordion title="Team not found">
    List available teams:

    ```bash theme={null}
    tk linear teams
    ```

    Then set the correct team ID.
  </Accordion>

  <Accordion title="Status mapping issues">
    Linear has custom workflow states. tk maps to the closest standard state. Check `tk linear status` for details.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="GitHub Sync" icon="github" href="/integrations/github">
    Sync with GitHub Issues.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli-reference/commands">
    Full command documentation.
  </Card>
</CardGroup>