Back to Details

cyrus-setup-linear

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
CRITICAL: Never use 
Read
, 
Edit
, or 
Write
tools on 
~/.cyrus/.env
or any file inside 
~/.cyrus/
. Use only 
Bash
commands (
grep
, 
printf >>
, etc.) to interact with env files — secrets must never be read into the conversation context. Never scrape, extract, or read secret values from web pages — guide the user to copy them manually.
重要提示：切勿对
~/.cyrus/.env
或
~/.cyrus/
目录下的任何文件使用
Read
、
Edit
或
Write
工具。仅使用
Bash
命令（
grep
、
printf >>
等）操作环境变量文件——密钥绝对不能被读取到对话上下文内。切勿爬取、提取或读取网页上的密钥值——请引导用户手动复制。

Setup Linear

Linear配置

Creates a Linear OAuth application and configures credentials so Cyrus can receive webhooks and respond to issues.
创建Linear OAuth应用并配置凭证，让Cyrus可以接收webhook并响应issue。

Step 1: Check Existing Configuration

步骤1：检查现有配置

bash
grep -E '^LINEAR_CLIENT_ID=' ~/.cyrus/.env 2>/dev/null
If 
LINEAR_CLIENT_ID
is already set, check if OAuth is also complete:
bash
grep -q '"workspaces"' ~/.cyrus/config.json 2>/dev/null && echo "configured" || echo "not configured"
If both are set, inform the user:
Linear is already configured. Skipping this step. To reconfigure, remove 
LINEAR_CLIENT_ID
, 
LINEAR_CLIENT_SECRET
, and 
LINEAR_WEBHOOK_SECRET
from 
~/.cyrus/.env
and re-run.
Skip to completion.
bash
grep -E '^LINEAR_CLIENT_ID=' ~/.cyrus/.env 2>/dev/null
如果
LINEAR_CLIENT_ID
已经设置，检查OAuth是否也已配置完成：
bash
grep -q '"workspaces"' ~/.cyrus/config.json 2>/dev/null && echo "configured" || echo "not configured"
如果两个配置都已存在，告知用户：
Linear已完成配置，跳过此步骤。 如果需要重新配置，请从
~/.cyrus/.env
中删除
LINEAR_CLIENT_ID
、
LINEAR_CLIENT_SECRET
和
LINEAR_WEBHOOK_SECRET
后重新运行。
直接跳转到完成部分。

Step 2: Get CYRUS_BASE_URL

步骤2：获取CYRUS_BASE_URL

Read the base URL from the env file (set by 
setup-endpoint
):
bash
grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-
This is needed for the callback and webhook URLs.
从环境变量文件中读取基础URL（由
setup-endpoint
设置）：
bash
grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-
回调地址和webhook地址需要用到这个参数。

Step 3: Create Linear OAuth App

步骤3：创建Linear OAuth应用

Determine which browser automation mode to use (see orchestrator rules):
  1. If 
    claude-in-chrome
    MCP tools are available → use Path A-1 (claude-in-chrome)
  2. If 
    agent-browser
    is installed (
    which agent-browser
    ) and a Chrome debug session is connected → use Path A-2 (agent-browser)
  3. Otherwise → use Path B (manual)
确定要使用的浏览器自动化模式（参见编排规则）：
  1. 如果有
    claude-in-chrome
    MCP工具可用 → 使用路径A-1（claude-in-chrome）
  2. 如果已安装
    agent-browser
    （
    which agent-browser
    可找到）且已连接Chrome调试会话 → 使用路径A-2（agent-browser）
  3. 其他情况 → 使用路径B（手动）

Path A-1: claude-in-chrome Automation

路径A-1：claude-in-chrome自动化

Use the 
mcp__claude-in-chrome__*
tools to navigate and interact with the user's existing Chrome browser. The user is likely already signed in to Linear.
Navigate to the Linear API settings page and proceed with form filling and credential capture using the chrome MCP tools (navigate, click, fill, screenshot, javascript_tool, etc.). Follow the same form fields and credential scraping logic as Path A-2 below, but using MCP tools instead of CLI commands.
使用
mcp__claude-in-chrome__*
工具导航并操作用户现有的Chrome浏览器，用户大概率已经登录了Linear账号。
导航到Linear API设置页面，使用Chrome MCP工具（navigate、click、fill、screenshot、javascript_tool等）完成表单填写和凭证获取。遵循下方路径A-2相同的表单字段和凭证获取逻辑，仅将CLI命令替换为MCP工具即可。

Path A-2: agent-browser Automation

路径A-2：agent-browser自动化

If 
agent-browser
is connected to a Chrome debug session, automate the Linear app creation.
如果
agent-browser
已连接到Chrome调试会话，可自动化完成Linear应用创建。

3a. Navigate to Linear API settings

3a. 导航到Linear API设置页面

bash
agent-browser navigate "https://linear.app/settings/api/applications/new"
Wait for page to load. Take a screenshot to verify you're on the right page and logged in.
bash
agent-browser navigate "https://linear.app/settings/api/applications/new"
等待页面加载，截图确认你处于正确页面且已登录。

3b. Fill the form

3b. 填写表单

bash
agent-browser fill "input[name='name']" "<AGENT_NAME>"
agent-browser fill "input[name='developerName']" "Self-hosted"
agent-browser fill "input[name='developerUrl']" "https://github.com/ceedaragents/cyrus"
For the callback URL field:
bash
agent-browser fill "input[name='redirectUrls']" "<CYRUS_BASE_URL>/callback"
Enable webhooks and fill webhook URL:
bash
agent-browser fill "input[name='webhookUrl']" "<CYRUS_BASE_URL>/webhook"
Check the required event types:
  • Agent session events (REQUIRED)
  • Inbox notifications
  • Permission changes
  • Issues
Click "Create".
After creation, Linear redirects to the app settings page. Do NOT screenshot credential pages or attempt to scrape secrets. Proceed to Step 4.
bash
agent-browser fill "input[name='name']" "<AGENT_NAME>"
agent-browser fill "input[name='developerName']" "Self-hosted"
agent-browser fill "input[name='developerUrl']" "https://github.com/ceedaragents/cyrus"
填写回调地址字段：
bash
agent-browser fill "input[name='redirectUrls']" "<CYRUS_BASE_URL>/callback"
启用webhook并填写webhook地址：
bash
agent-browser fill "input[name='webhookUrl']" "<CYRUS_BASE_URL>/webhook"
勾选所需的事件类型：
  • Agent会话事件（必填）
  • 收件箱通知
  • 权限变更
  • Issues
点击「Create」。
创建完成后，Linear会跳转到应用设置页面。不要对凭证页面截图，也不要尝试爬取密钥。 直接进入步骤4。

Path A-1: claude-in-chrome Automation

路径A-1：claude-in-chrome自动化

Use the 
mcp__claude-in-chrome__*
tools to navigate and interact with the user's existing Chrome browser.
Navigate to the Linear API settings page (
https://linear.app/settings/api/applications/new
) and fill in the form with the same fields as Path A-2 above. Click "Create". Do NOT screenshot credential pages or attempt to scrape secrets. Proceed to Step 4.
使用
mcp__claude-in-chrome__*
工具导航并操作用户现有的Chrome浏览器。
导航到Linear API设置页面（
https://linear.app/settings/api/applications/new
），按照上述路径A-2的字段要求填写表单，点击「Create」。不要对凭证页面截图，也不要尝试爬取密钥。 直接进入步骤4。

Path B: Manual Guided Setup

路径B：引导式手动设置

Guide the user through manual creation:

Create a Linear OAuth Application

  1. Go to your Linear workspace settings:
    • Click your workspace name (top-left) → Settings
    • Navigate to API in the left sidebar
    • Scroll to OAuth Applications → Click Create new
  2. Fill in the form:
    • Application name: 
      <AGENT_NAME>
    • Developer name: Your name or org
    • Developer URL: 
      https://github.com/ceedaragents/cyrus
    • Redirect callback URLs: 
      <CYRUS_BASE_URL>/callback
    • Webhook URL: 
      <CYRUS_BASE_URL>/webhook
    • Webhook: ✓ enabled
    • Event types: ✓ Agent session events, ✓ Inbox notifications, ✓ Permission changes, ✓ Issues
    • Public: ✗ leave disabled (this is a private self-hosted app)
  3. Click Create
Proceed to Step 4.
引导用户手动完成创建：

创建Linear OAuth应用

  1. 进入你的Linear工作区设置：
    • 点击左上角的工作区名称 → 设置
    • 在左侧边栏导航到API
    • 滚动到OAuth Applications → 点击Create new
  2. 填写表单：
    • 应用名称： 
      <AGENT_NAME>
    • 开发者名称： 你的名称或组织名
    • 开发者URL： 
      https://github.com/ceedaragents/cyrus
    • 重定向回调地址： 
      <CYRUS_BASE_URL>/callback
    • Webhook地址： 
      <CYRUS_BASE_URL>/webhook
    • Webhook： ✓ 启用
    • 事件类型： ✓ Agent会话事件、✓ 收件箱通知、✓ 权限变更、✓ Issues
    • 公开： ✗ 保持禁用（这是私有的自托管应用）
  3. 点击Create
进入步骤4。

Step 4: Collect Credentials

步骤4：收集凭证

The agent must NOT scrape, read, or extract secrets from the page. The user copies them manually into the env file.
Agent绝对不能爬取、读取或提取页面上的密钥。 由用户手动将密钥复制到环境变量文件中。

4a. Add credential placeholders

4a. 添加凭证占位符

bash
grep -q '^LINEAR_CLIENT_ID=' ~/.cyrus/.env || echo 'LINEAR_CLIENT_ID=' >> ~/.cyrus/.env
grep -q '^LINEAR_CLIENT_SECRET=' ~/.cyrus/.env || echo 'LINEAR_CLIENT_SECRET=' >> ~/.cyrus/.env
grep -q '^LINEAR_WEBHOOK_SECRET=' ~/.cyrus/.env || echo 'LINEAR_WEBHOOK_SECRET=' >> ~/.cyrus/.env
bash
grep -q '^LINEAR_CLIENT_ID=' ~/.cyrus/.env || echo 'LINEAR_CLIENT_ID=' >> ~/.cyrus/.env
grep -q '^LINEAR_CLIENT_SECRET=' ~/.cyrus/.env || echo 'LINEAR_CLIENT_SECRET=' >> ~/.cyrus/.env
grep -q '^LINEAR_WEBHOOK_SECRET=' ~/.cyrus/.env || echo 'LINEAR_WEBHOOK_SECRET=' >> ~/.cyrus/.env

4b. Open env file for editing

4b. 打开环境变量文件进行编辑

bash
undefined
bash
undefined

macOS

macOS

code --new-window ~/.cyrus/.env 2>/dev/null || open -a TextEdit ~/.cyrus/.env
code --new-window ~/.cyrus/.env 2>/dev/null || open -a TextEdit ~/.cyrus/.env

Linux

Linux

code --new-window ~/.cyrus/.env 2>/dev/null || xdg-open ~/.cyrus/.env
undefined
code --new-window ~/.cyrus/.env 2>/dev/null || xdg-open ~/.cyrus/.env
undefined

4c. Guide the user

4c. 引导用户操作

Tell the user:
I've opened 
~/.cyrus/.env
. You need to paste three values from your Linear app settings page:
  1. Client ID — copy it and paste after 
    LINEAR_CLIENT_ID=
  2. Client Secret — click the copy button next to it (it's masked with dots), paste after 
    LINEAR_CLIENT_SECRET=
  3. Webhook Signing Secret — click the copy button next to it, paste after 
    LINEAR_WEBHOOK_SECRET=
Save and close the file when done.
告知用户：
我已经打开了
~/.cyrus/.env
文件，你需要从Linear应用设置页面复制三个值粘贴到对应位置：
  1. Client ID — 复制后粘贴到
    LINEAR_CLIENT_ID=
    后面
  2. Client Secret — 点击旁边的复制按钮（值会用圆点隐藏），粘贴到
    LINEAR_CLIENT_SECRET=
    后面
  3. Webhook Signing Secret — 点击旁边的复制按钮，粘贴到
    LINEAR_WEBHOOK_SECRET=
    后面
完成后保存并关闭文件。

4d. Verify

4d. 验证配置

After the user confirms they've saved:
bash
grep -c '^LINEAR_CLIENT_ID=.' ~/.cyrus/.env
grep -c '^LINEAR_CLIENT_SECRET=.' ~/.cyrus/.env
grep -c '^LINEAR_WEBHOOK_SECRET=.' ~/.cyrus/.env
All three must return 1 (the 
.
after 
=
ensures the value is not empty). If any are 0, ask the user to check the file.
用户确认保存完成后执行：
bash
grep -c '^LINEAR_CLIENT_ID=.' ~/.cyrus/.env
grep -c '^LINEAR_CLIENT_SECRET=.' ~/.cyrus/.env
grep -c '^LINEAR_WEBHOOK_SECRET=.' ~/.cyrus/.env
三个命令都必须返回1（
=
后面的
.
确保值非空）。如果任意一个返回0，要求用户检查文件内容。

Step 5: Authorize with Linear

步骤5：授权Linear访问

Run the OAuth authorization flow:
bash
cyrus self-auth
This will:
  1. Start a temporary OAuth callback server
  2. Open the browser to Linear's authorization page
  3. After the user clicks Authorize, save tokens to 
    ~/.cyrus/config.json
Verify authorization succeeded:
bash
cat ~/.cyrus/config.json | grep -c '"workspaces"'
If the count is 0, authorization failed. Ask the user to check their credentials and try again.
运行OAuth授权流程：
bash
cyrus self-auth
这个命令会：
  1. 启动临时OAuth回调服务
  2. 打开浏览器跳转到Linear授权页面
  3. 用户点击Authorize后，将token保存到
    ~/.cyrus/config.json
验证授权是否成功：
bash
cat ~/.cyrus/config.json | grep -c '"workspaces"'
如果计数为0，说明授权失败，要求用户检查凭证后重试。

Completion

完成

✓ Linear OAuth application created ✓ Credentials saved to 
~/.cyrus/.env
✓ Workspace authorized via 
cyrus self-auth
✓ Linear OAuth应用已创建 ✓ 凭证已保存到
~/.cyrus/.env
✓ 工作区已通过
cyrus self-auth
完成授权