linear-graphql-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Linear GraphQL Skill

Linear GraphQL 技能

Use this skill to run Linear GraphQL API operations through

uxc

Reuse the

uxc

skill guidance for discovery, schema inspection, auth lifecycle, and error recovery.

使用本技能可通过

uxc

执行Linear GraphQL API操作。

关于发现、架构检查、认证生命周期和错误恢复，请复用

uxc

技能的相关指南。

Prerequisites

前提条件

```
uxc
```
is installed and available in
```
PATH
```
.
Network access to
```
https://api.linear.app/graphql
```
.
Linear API key or OAuth credentials available.

```
uxc
```
已安装且可在
```
PATH
```
中访问。
能够访问
```
https://api.linear.app/graphql
```
网络。
拥有Linear API密钥或OAuth凭证。

Authentication

认证方式

Linear supports two authentication methods:

Linear支持两种认证方式：

Option 1: Personal API Key (Recommended for development)

选项1：个人API密钥（推荐用于开发环境）

Get your API key from Linear: https://linear.app/settings/api

Set credential with custom Authorization header:

bash

uxc auth credential set linear-graphql \
  --auth-type api_key \
  --header "Authorization:{{secret}}" \
  --secret "lin_api_XXX"

Or use environment variable:

bash

export LINEAR_API_KEY="lin_api_XXX"
uxc auth credential set linear-graphql \
  --auth-type api_key \
  --header "Authorization:{{secret}}" \
  --secret-env LINEAR_API_KEY

Bind endpoint:

bash

uxc auth binding add \
  --id linear-graphql \
  --host api.linear.app \
  --path-prefix /graphql \
  --scheme https \
  --credential linear-graphql \
  --priority 100

Important (Personal API Key only): Linear API keys require

Authorization: lin_api_XXX

format (no

Bearer

prefix). The

--header "Authorization:{{secret}}"

configuration above is required for API key auth. For OAuth access tokens, use standard

Authorization: Bearer <token>

semantics (handled by the OAuth credential flow in

uxc

Credential/binding IDs in this skill use

linear-graphql

by convention; IDs are local aliases and can be changed if needed.

从Linear获取API密钥：https://linear.app/settings/api

设置带有自定义Authorization头的凭证：

bash

uxc auth credential set linear-graphql \
  --auth-type api_key \
  --header "Authorization:{{secret}}" \
  --secret "lin_api_XXX"

或使用环境变量：

bash

export LINEAR_API_KEY="lin_api_XXX"
uxc auth credential set linear-graphql \
  --auth-type api_key \
  --header "Authorization:{{secret}}" \
  --secret-env LINEAR_API_KEY

绑定端点：

bash

uxc auth binding add \
  --id linear-graphql \
  --host api.linear.app \
  --path-prefix /graphql \
  --scheme https \
  --credential linear-graphql \
  --priority 100

重要提示（仅适用于个人API密钥）：Linear API密钥要求采用

Authorization: lin_api_XXX

格式（无需

Bearer

前缀）。上述

--header "Authorization:{{secret}}"

配置是API密钥认证的必要条件。对于OAuth访问令牌，请使用标准的

Authorization: Bearer <token>

规则（由

uxc

中的OAuth凭证流程处理）。

本技能中的凭证/绑定ID默认使用

linear-graphql

；这些ID是本地别名，可根据需要修改。

Option 2: OAuth 2.0 (For production/user-delegated access)

选项2：OAuth 2.0（用于生产环境/用户委托访问）

Create an OAuth app in Linear: https://linear.app/settings/api

Start OAuth login:

bash

uxc auth oauth start linear-graphql \
  --endpoint https://api.linear.app/graphql \
  --redirect-uri http://127.0.0.1:8788/callback \
  --scope read \
  --scope write

After approval, complete it with:

bash

uxc auth oauth complete linear-graphql \
  --session-id <session_id> \
  --authorization-response 'http://127.0.0.1:8788/callback?code=...&state=...'

Bind endpoint:

bash

uxc auth binding add \
  --id linear-graphql \
  --host api.linear.app \
  --path-prefix /graphql \
  --scheme https \
  --credential linear-graphql \
  --priority 100

在Linear中创建OAuth应用：https://linear.app/settings/api

启动OAuth登录：

bash

uxc auth oauth start linear-graphql \
  --endpoint https://api.linear.app/graphql \
  --redirect-uri http://127.0.0.1:8788/callback \
  --scope read \
  --scope write

授权完成后，执行以下命令完成认证：

bash

uxc auth oauth complete linear-graphql \
  --session-id <session_id> \
  --authorization-response 'http://127.0.0.1:8788/callback?code=...&state=...'

绑定端点：

bash

uxc auth binding add \
  --id linear-graphql \
  --host api.linear.app \
  --path-prefix /graphql \
  --scheme https \
  --credential linear-graphql \
  --priority 100

Core Workflow

核心工作流

Use fixed link command by default:
- ```
command -v linear-graphql-cli
```
- If the command exists, confirm it is the expected
```
uxc link
```
  for this skill before using it.
- If a command conflict is detected and cannot be safely reused, stop and ask skill maintainers for guidance instead of dynamically renaming the command.
- If missing, create it:
```
uxc link linear-graphql-cli https://api.linear.app/graphql
```
- ```
linear-graphql-cli -h
```
Discover operations:
- ```
linear-graphql-cli -h
```
- Returns hundreds of GraphQL operations

Inspect specific operation:

```
linear-graphql-cli query/issues -h
```

linear-graphql-cli mutation/issueCreate -h

Execute queries:

bash

# Query issues (simple)
linear-graphql-cli query/issues '{"first":10}'

# Query issues with explicit selection set for useful fields
linear-graphql-cli query/issues '{"first":10,"_select":"nodes { identifier title url state { name } assignee { name } }"}'

# Query teams
linear-graphql-cli query/teams '{"first":10}'

# Create issue (requires write scope)
linear-graphql-cli mutation/issueCreate '{
  "input": {
    "teamId": "TEAM_ID",
    "title": "New Issue Title",
    "description": "Issue description"
  }
}'

默认使用固定链接命令：
- ```
command -v linear-graphql-cli
```
- 如果该命令存在，在使用前确认它是本技能对应的
```
uxc link
```
  。
- 如果检测到命令冲突且无法安全复用，请停止操作并向技能维护者寻求指导，不要动态重命名命令。
- 如果命令不存在，创建链接：
```
uxc link linear-graphql-cli https://api.linear.app/graphql
```
- ```
linear-graphql-cli -h
```
发现操作：
- ```
linear-graphql-cli -h
```
- 返回数百种GraphQL操作

检查特定操作：

```
linear-graphql-cli query/issues -h
```

linear-graphql-cli mutation/issueCreate -h

执行查询：

bash

# 查询问题（简单版）
linear-graphql-cli query/issues '{"first":10}'

# 查询问题并指定有用字段的选择集
linear-graphql-cli query/issues '{"first":10,"_select":"nodes { identifier title url state { name } assignee { name } }"}'

# 查询团队
linear-graphql-cli query/teams '{"first":10}'

# 创建问题（需要write权限）
linear-graphql-cli mutation/issueCreate '{
  "input": {
    "teamId": "TEAM_ID",
    "title": "New Issue Title",
    "description": "Issue description"
  }
}'

Available Operations

可用操作

Queries

查询类

```
query/issues
```
- List and filter issues
```
query/issue
```
- Get single issue
```
query/teams
```
- List teams
```
query/team
```
- Get single team
```
query/projects
```
- List projects
```
query/workflowStates
```
- List workflow states

```
query/issues
```
- 列出并筛选问题
```
query/issue
```
- 获取单个问题
```
query/teams
```
- 列出团队
```
query/team
```
- 获取单个团队
```
query/projects
```
- 列出项目
```
query/workflowStates
```
- 列出工作流状态

Mutations

变更类

```
mutation/issueCreate
```
- Create new issue
```
mutation/issueUpdate
```
- Update issue
```
mutation/issueArchive
```
- Archive issue
```
mutation/commentCreate
```
- Add comment

```
mutation/issueCreate
```
- 创建新问题
```
mutation/issueUpdate
```
- 更新问题
```
mutation/issueArchive
```
- 归档问题
```
mutation/commentCreate
```
- 添加评论

Usage Examples

使用示例

List recent issues

列出近期问题

bash

linear-graphql-cli query/issues '{"first":20,"_select":"nodes { identifier title url state { name } assignee { name } }"}'

bash

linear-graphql-cli query/issues '{"first":20,"_select":"nodes { identifier title url state { name } assignee { name } }"}'

Get issue by ID

通过ID获取问题

bash

linear-graphql-cli query/issue id=ISSUE_ID

bash

linear-graphql-cli query/issue id=ISSUE_ID

List teams

列出团队

bash

linear-graphql-cli query/teams

bash

linear-graphql-cli query/teams

Create issue

创建问题

bash

linear-graphql-cli mutation/issueCreate '{"input":{"teamId":"YOUR_TEAM_ID","title":"Fix bug"}}'

bash

linear-graphql-cli mutation/issueCreate '{"input":{"teamId":"YOUR_TEAM_ID","title":"Fix bug"}}'

Troubleshooting

故障排查

Authentication Errors

认证错误

Error: "Bearer token" prefix rejected

Linear API does not accept
```
Authorization: Bearer lin_api_XXX
```

Ensure credential uses

--auth-type api_key --header "Authorization:{{secret}}"

Do not use
```
--auth-type bearer
```

Error: "Credential not found"

Check credential exists:
```
uxc auth credential list
```
Verify binding:
```
uxc auth binding list
```
Create binding if missing (see Authentication section)

OAuth login spans multiple agent turns

Prefer

uxc auth oauth start ...

and

uxc auth oauth complete ...

Use
```
uxc auth oauth login ... --flow authorization_code
```
only when one process can wait for the pasted callback URL

Error: "No binding matched"

Check binding exists:

uxc auth binding match api.linear.app/graphql

If missing, create binding with
```
uxc auth binding add
```
(see Authentication section)

For detailed authentication troubleshooting, see

uxc

skill's

references/auth-configuration.md

错误：“Bearer token”前缀被拒绝

Linear API不接受
```
Authorization: Bearer lin_api_XXX
```
格式

确保凭证配置使用

--auth-type api_key --header "Authorization:{{secret}}"

不要使用
```
--auth-type bearer
```

错误：“Credential not found”

检查凭证是否存在：
```
uxc auth credential list
```
验证绑定：
```
uxc auth binding list
```
如果缺失，创建绑定（请参考认证部分）

OAuth登录需要多轮Agent交互

优先使用

uxc auth oauth start ...

和

uxc auth oauth complete ...

仅当单个进程可以等待粘贴回调URL时，才使用
```
uxc auth oauth login ... --flow authorization_code
```

错误：“No binding matched”

检查绑定是否存在：

uxc auth binding match api.linear.app/graphql

如果缺失，使用
```
uxc auth binding add
```
创建绑定（请参考认证部分）

如需详细的认证故障排查指南，请查看

uxc

技能的

references/auth-configuration.md

。

Common Issues

常见问题

Daemon issues after credential changes

Restart daemon:
```
uxc daemon restart
```
Check status:
```
uxc daemon status
```

Environment variable not found

Ensure variable is exported in daemon's environment
Or use
```
--secret
```
for literal values (less secure)
Or use
```
--secret-op
```
for 1Password (most secure)

凭证变更后守护进程出现问题

重启守护进程：
```
uxc daemon restart
```
检查状态：
```
uxc daemon status
```

未找到环境变量

确保变量已在守护进程的环境中导出
或使用
```
--secret
```
传入字面量值（安全性较低）
或使用
```
--secret-op
```
通过1Password获取（安全性最高）

Guardrails

约束规则

Keep automation on JSON output envelope; do not use
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
data
```
,
```
error
```
.

Prefer positional JSON for non-string and typed arguments (for example:

linear-graphql-cli query/issues '{"first":10}'

and

linear-graphql-cli mutation/issueCreate '{"input":{"teamId":"TEAM_ID","title":"Test"}}'

Use reserved GraphQL argument
```
_select
```
(string) when you need explicit return fields, e.g.
```
{"_select":"nodes { identifier title }"}
```
.
Use
```
linear-graphql-cli
```
as the default command path.

linear-graphql-cli <operation> ...

is equivalent to

uxc https://api.linear.app/graphql <operation> ...

Prefer read operations first (query/), then write operations (mutation/).
For write operations, always confirm user intent before execution.
If auth fails, check credential with
```
uxc auth credential info linear-graphql
```
.

自动化操作需基于JSON输出包，不要使用
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
data
```
、
```
error
```
。

对于非字符串和类型化参数，优先使用位置JSON（例如：

linear-graphql-cli query/issues '{"first":10}'

和

linear-graphql-cli mutation/issueCreate '{"input":{"teamId":"TEAM_ID","title":"Test"}}'

）。

当需要指定返回字段时，使用保留的GraphQL参数
```
_select
```
（字符串类型），例如
```
{"_select":"nodes { identifier title }"}
```
。
默认使用
```
linear-graphql-cli
```
作为命令路径。

linear-graphql-cli <operation> ...

等价于

uxc https://api.linear.app/graphql <operation> ...

。

优先执行读取操作（query/），再执行写入操作（mutation/）。
对于写入操作，执行前务必确认用户意图。
如果认证失败，使用
```
uxc auth credential info linear-graphql
```
检查凭证。

References

参考资料

Linear API Documentation: https://developers.linear.app
GraphQL Schema: https://studio.apollographql.com/public/Linear-API
Invocation patterns:
```
references/usage-patterns.md
```

Linear API文档：https://developers.linear.app
GraphQL架构：https://studio.apollographql.com/public/Linear-API
调用模式：
```
references/usage-patterns.md
```