Back to Details

linear

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Linear API

Linear API

Use the Linear API via direct 
curl
calls to manage issues, projects, and teams with GraphQL queries and mutations.
Official docs: 
https://linear.app/developers
通过直接调用
curl
使用Linear API，借助GraphQL查询和变更来管理issue、项目和团队。
官方文档：
https://linear.app/developers

When to Use

使用场景

Use this skill when you need to:
  • Query issues from Linear workspaces
  • Create new issues with title, description, and assignments
  • Update issue status and properties
  • List teams and projects in an organization
  • Add comments to issues
  • Search issues with filters
当你需要执行以下操作时使用本技能：
  • 从Linear工作空间查询issue
  • 创建带标题、描述和分配人的新issue
  • 更新issue状态和属性
  • 列出组织内的团队和项目
  • 为issue添加评论
  • 通过筛选条件搜索issue

Prerequisites

前置条件

Go to vm0.ai Settings → Connectors and connect Linear. vm0 will automatically inject the required 
LINEAR_TOKEN
environment variable.
前往vm0.ai 设置 → 连接器 页面绑定Linear，vm0会自动注入所需的
LINEAR_TOKEN
环境变量。

Rate Limits

速率限制

Linear's API is rate-limited to ensure fair usage. Limits may vary based on your plan.
Important: When using 
$VAR
in a command that pipes to another command, wrap the command containing 
$VAR
in 
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
Linear API设有速率限制以保障公平使用，限制阈值会根据你使用的套餐有所不同。
重要提示： 当你在需要通过管道传递给其他命令的指令中使用
$VAR
时，请将包含
$VAR
的命令包裹在
bash -c '...'
中。由于Claude Code的一个bug，直接使用管道时环境变量会被静默清空。
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'

How to Use

使用方法

All examples below assume you have 
LINEAR_TOKEN
set.
Base URL: 
https://api.linear.app/graphql
Linear uses GraphQL for all API operations. Queries retrieve data, mutations modify data.
以下所有示例都假定你已经配置好
LINEAR_TOKEN
。
基础URL：
https://api.linear.app/graphql
Linear所有API操作都使用GraphQL：查询操作用于获取数据，变更操作用于修改数据。

1. List Teams

1. 获取团队列表

Get all teams in your workspace:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "{ teams { nodes { id name key } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.teams.nodes'
Save a team ID for subsequent queries.
获取工作空间内的所有团队：
写入
/tmp/linear_request.json
：
json
{
  "query": "{ teams { nodes { id name key } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.teams.nodes'
保存团队ID以便后续查询使用。

2. List Issues for a Team

2. 获取指定团队的Issue列表

Get issues from a specific team. Replace 
<your-team-id>
with the actual team ID:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "{ team(id: \"<your-team-id>\") { issues { nodes { id identifier title state { name } assignee { name } } } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.team.issues.nodes'
获取特定团队的issue，将
<your-team-id>
替换为实际的团队ID：
写入
/tmp/linear_request.json
：
json
{
  "query": "{ team(id: \"<your-team-id>\") { issues { nodes { id identifier title state { name } assignee { name } } } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.team.issues.nodes'

3. Get Issue by Identifier

3. 通过编号查询Issue

Fetch a specific issue by its identifier (e.g., 
ENG-123
):
Write to 
/tmp/linear_request.json
:
json
{
  "query": "{ issue(id: \"ENG-123\") { id identifier title description state { name } priority assignee { name } createdAt } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issue'
通过编号获取指定issue（例如
ENG-123
）：
写入
/tmp/linear_request.json
：
json
{
  "query": "{ issue(id: \"ENG-123\") { id identifier title description state { name } priority assignee { name } createdAt } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issue'

4. Search Issues

4. 搜索Issue

Search issues with filters:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "{ issues(filter: { state: { name: { eq: \"In Progress\" } } }, first: 10) { nodes { id identifier title assignee { name } } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issues.nodes'
通过筛选条件搜索issue：
写入
/tmp/linear_request.json
：
json
{
  "query": "{ issues(filter: { state: { name: { eq: \"In Progress\" } } }, first: 10) { nodes { id identifier title assignee { name } } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issues.nodes'

5. Create Issue

5. 创建Issue

Create a new issue in a team. Replace 
<your-team-id>
with the actual team ID:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "mutation { issueCreate(input: { title: \"Bug: Login button not working\", description: \"Users report the login button is unresponsive on mobile.\", teamId: \"<your-team-id>\" }) { success issue { id identifier title url } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issueCreate'
在指定团队中创建新issue，将
<your-team-id>
替换为实际的团队ID：
写入
/tmp/linear_request.json
：
json
{
  "query": "mutation { issueCreate(input: { title: \"Bug: Login button not working\", description: \"Users report the login button is unresponsive on mobile.\", teamId: \"<your-team-id>\" }) { success issue { id identifier title url } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issueCreate'

6. Create Issue with Priority and Labels

6. 创建带优先级和标签的Issue

Create an issue with additional properties. Replace 
<your-team-id>
and 
<your-label-id>
with actual IDs:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "mutation { issueCreate(input: { title: \"High priority task\", teamId: \"<your-team-id>\", priority: 1, labelIds: [\"<your-label-id>\"] }) { success issue { id identifier title priority } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issueCreate'
Priority values: 0 (No priority), 1 (Urgent), 2 (High), 3 (Medium), 4 (Low)
创建携带额外属性的issue，将
<your-team-id>
和
<your-label-id>
替换为实际ID：
写入
/tmp/linear_request.json
：
json
{
  "query": "mutation { issueCreate(input: { title: \"High priority task\", teamId: \"<your-team-id>\", priority: 1, labelIds: [\"<your-label-id>\"] }) { success issue { id identifier title priority } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issueCreate'
优先级取值： 0（无优先级）、1（紧急）、2（高）、3（中）、4（低）

7. Update Issue

7. 更新Issue

Update an existing issue. Replace 
<your-issue-id>
with the actual issue ID:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "mutation { issueUpdate(id: \"<your-issue-id>\", input: { title: \"Updated title\", priority: 2 }) { success issue { id identifier title priority } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issueUpdate'
更新已存在的issue，将
<your-issue-id>
替换为实际的issue ID：
写入
/tmp/linear_request.json
：
json
{
  "query": "mutation { issueUpdate(id: \"<your-issue-id>\", input: { title: \"Updated title\", priority: 2 }) { success issue { id identifier title priority } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issueUpdate'

8. Change Issue State

8. 修改Issue状态

Move an issue to a different state (e.g., "Done"). Replace 
<your-issue-id>
and 
<your-state-id>
with actual IDs:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "mutation { issueUpdate(id: \"<your-issue-id>\", input: { stateId: \"<your-state-id>\" }) { success issue { id identifier state { name } } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issueUpdate'
将issue切换到其他状态（例如「已完成」），将
<your-issue-id>
和
<your-state-id>
替换为实际ID：
写入
/tmp/linear_request.json
：
json
{
  "query": "mutation { issueUpdate(id: \"<your-issue-id>\", input: { stateId: \"<your-state-id>\" }) { success issue { id identifier state { name } } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.issueUpdate'

9. List Workflow States

9. 获取工作流状态列表

Get available states for a team. Replace 
<your-team-id>
with the actual team ID:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "{ team(id: \"<your-team-id>\") { states { nodes { id name type } } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.team.states.nodes'
获取指定团队可用的工作流状态，将
<your-team-id>
替换为实际的团队ID：
写入
/tmp/linear_request.json
：
json
{
  "query": "{ team(id: \"<your-team-id>\") { states { nodes { id name type } } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.team.states.nodes'

10. Add Comment to Issue

10. 为Issue添加评论

Add a comment to an existing issue. Replace 
<your-issue-id>
with the actual issue ID:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "mutation { commentCreate(input: { issueId: \"<your-issue-id>\", body: \"This is a comment from the API.\" }) { success comment { id body createdAt } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.commentCreate'
为已存在的issue添加评论，将
<your-issue-id>
替换为实际的issue ID：
写入
/tmp/linear_request.json
：
json
{
  "query": "mutation { commentCreate(input: { issueId: \"<your-issue-id>\", body: \"This is a comment from the API.\" }) { success comment { id body createdAt } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.commentCreate'

11. List Projects

11. 获取项目列表

Get all projects in the workspace:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "{ projects { nodes { id name state progress targetDate } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.projects.nodes'
获取工作空间内的所有项目：
写入
/tmp/linear_request.json
：
json
{
  "query": "{ projects { nodes { id name state progress targetDate } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.projects.nodes'

12. Get Current User

12. 获取当前用户信息

Get information about the authenticated user:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "{ viewer { id name email admin } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.viewer'
获取已认证用户的相关信息：
写入
/tmp/linear_request.json
：
json
{
  "query": "{ viewer { id name email admin } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.viewer'

13. List Labels

13. 获取标签列表

Get available labels for a team. Replace 
<your-team-id>
with the actual team ID:
Write to 
/tmp/linear_request.json
:
json
{
  "query": "{ team(id: \"<your-team-id>\") { labels { nodes { id name color } } } }"
}
Then run:
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.team.labels.nodes'
获取指定团队可用的标签，将
<your-team-id>
替换为实际的团队ID：
写入
/tmp/linear_request.json
：
json
{
  "query": "{ team(id: \"<your-team-id>\") { labels { nodes { id name color } } } }"
}
然后执行：
bash
bash -c 'curl -s -X POST "https://api.linear.app/graphql" -H "Content-Type: application/json" -H "Authorization: ${LINEAR_TOKEN}" -d @/tmp/linear_request.json' | jq '.data.team.labels.nodes'

Finding IDs

查找ID

To find IDs for teams, issues, projects, etc.:
  1. Open Linear app
  2. Press 
    Cmd/Ctrl + K
    to open command menu
  3. Type "Copy model UUID"
  4. Select the entity to copy its ID
Or use the queries above to list entities and extract their IDs.
要获取团队、issue、项目等实体的ID，可以按以下步骤操作：
  1. 打开Linear应用
  2. 按下
    Cmd/Ctrl + K
    打开命令菜单
  3. 输入「Copy model UUID」
  4. 选择对应实体即可复制其ID
你也可以使用上面的查询接口列出实体并提取对应的ID。

Guidelines

使用规范

  1. Use GraphQL variables: For production, use variables instead of string interpolation for better security
  2. Handle pagination: Use 
    first
    , 
    after
    , 
    last
    , 
    before
    for paginated results
  3. Check for errors: GraphQL returns 200 even with errors; always check the 
    errors
    array
  4. Rate limiting: Implement backoff if you receive rate limit errors
  5. Batch operations: Combine multiple queries in one request when possible
  6. Issue identifiers: You can use either UUID or readable identifier (e.g., 
    ENG-123
    ) for most queries
  1. 使用GraphQL变量：生产环境中建议使用变量而非字符串拼接，安全性更高
  2. 处理分页：对于分页结果使用
    first
    、
    after
    、
    last
    、
    before
    参数进行查询
  3. 错误检查：即使请求返回200状态码GraphQL也可能存在错误，请始终检查
    errors
    数组
  4. 速率限制：如果收到速率限制错误，请实现退避重试逻辑
  5. 批量操作：尽可能将多个查询合并到单次请求中
  6. Issue编号：大多数查询都支持使用UUID或者可读编号（例如
    ENG-123
    ）作为查询参数