linear-cli

Linear CLI

一個從命令列管理 Linear 議題的 CLI，支援 git 和 jj 整合。

前置需求

linear 指令必須在 PATH 中可用。檢查方式：

linear --version

若未全域安裝，可透過 npx 執行而不需安裝：

npx @schpet/linear-cli --version

後續所有指令都可以用 npx @schpet/linear-cli 取代 linear。否則，請依照安裝說明進行安裝：
https://github.com/schpet/linear-cli?tab=readme-ov-file#install

Markdown 內容的最佳實務

當處理包含 markdown 的議題描述或留言內容時，請優先使用檔案型參數，而非將內容直接作為命令列引數傳遞：

• 在 issue create 和 issue update 指令中使用 --description-file
• 在 comment add 和 comment update 指令中使用 --body-file

為什麼使用檔案型參數：

• 確保在 Linear 網頁介面中格式正確
• 避免換行和特殊字元的 shell 跳脫問題
• 防止 markdown 中出現字面上的 \n 序列
• 更容易處理多行內容

範例工作流程：

# 將 markdown 寫入暫存檔
cat > /tmp/description.md <<'EOF'
## 摘要

- 第一項
- 第二項

## 詳細資訊

這是格式正確的詳細說明。
EOF

# 使用檔案建立議題
linear issue create --title "我的議題" --description-file /tmp/description.md

# 或是在留言中使用
linear issue comment add ENG-123 --body-file /tmp/comment.md

僅在簡單的單行內容時才使用行內參數（--description、--body）。

可用指令

精簡指令列表，由 linear --help 產生：

linear api

linear auth
linear auth default
linear auth list
linear auth login
linear auth logout
linear auth migrate
linear auth token
linear auth whoami

linear config

linear cycle
linear cycle list
linear cycle view

linear document
linear document create
linear document delete
linear document list
linear document update
linear document view

linear initiative
linear initiative add-project
linear initiative archive
linear initiative create
linear initiative delete
linear initiative list
linear initiative remove-project
linear initiative unarchive
linear initiative update
linear initiative view

linear initiative-update
linear initiative-update create
linear initiative-update list

linear issue
linear issue agent-session
linear issue agent-session list
linear issue agent-session view
linear issue attach
linear issue comment
linear issue comment add
linear issue comment delete
linear issue comment list
linear issue comment update
linear issue commits
linear issue create
linear issue delete
linear issue describe
linear issue id
linear issue link
linear issue mine
linear issue pull-request
linear issue query
linear issue relation
linear issue relation add
linear issue relation delete
linear issue relation list
linear issue start
linear issue title
linear issue update
linear issue url
linear issue view

linear label
linear label create
linear label delete
linear label list

linear milestone
linear milestone create
linear milestone delete
linear milestone list
linear milestone update
linear milestone view

linear project
linear project create
linear project delete
linear project list
linear project update
linear project view

linear project-update
linear project-update create
linear project-update list

linear schema

linear team
linear team autolinks
linear team create
linear team delete
linear team id
linear team list
linear team members

參考文件

• api - 發送原始 GraphQL API 請求
• auth - 管理 Linear 驗證
• config - 互動式產生 .linear.toml 設定檔
• cycle - 管理 Linear 團隊週期
• document - 管理 Linear 文件
• initiative - 管理 Linear 倡議
• initiative-update - 管理倡議狀態更新（時間軸貼文）
• issue - 管理 Linear 議題
• label - 管理 Linear 議題標籤
• milestone - 管理 Linear 專案里程碑
• project - 管理 Linear 專案
• project-update - 管理專案狀態更新
• schema - 將 GraphQL schema 輸出到標準輸出
• team - 管理 Linear 團隊

如需組織功能（倡議、標籤、專案、批次操作）的精選範例，請參閱 organization-features。

探索選項

若要查看可用的子指令和參數，請在任何指令上執行 --help：

linear --help
linear issue --help
linear issue list --help
linear issue create --help

每個指令都有詳細的說明輸出，描述所有可用的參數和選項。

有些指令有不明顯的必要參數。值得注意的範例：

• issue list 需要排序方式——透過 --sort（有效值：manual、priority）、issue_sort 設定選項或 LINEAR_ISSUE_SORT 環境變數提供。同時需要 --team <key>，除非團隊可從目錄推斷——若未知，請先執行 linear team list。
• --no-pager 僅支援 issue list——將其傳遞給其他指令（如 project list）會產生錯誤。

直接使用 Linear GraphQL API

所有支援的操作請優先使用 CLI。 api 指令僅應作為 CLI 未涵蓋查詢的備用方案。

檢查 schema 以取得可用的型別和欄位

將 schema 寫入暫存檔，然後搜尋：

linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"

發送 GraphQL 請求

重要： 包含非空型別標記（例如 String 後接驚嘆號）的 GraphQL 查詢必須透過 heredoc 標準輸入傳遞，以避免跳脫問題。沒有這些標記的簡單查詢可以直接行內傳遞。

# 簡單查詢（無型別標記，因此行內即可）
linear api '{ viewer { id name email } }'

# 帶變數的查詢——使用 heredoc 避免跳脫問題
linear api --variable teamId=abc123 <<'GRAPHQL'
query($teamId: String!) { team(id: $teamId) { name } }
GRAPHQL

# 依文字搜尋議題
linear api --variable term=onboarding <<'GRAPHQL'
query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }
GRAPHQL

# 數值和布林變數
linear api --variable first=5 <<'GRAPHQL'
query($first: Int!) { issues(first: $first) { nodes { title } } }
GRAPHQL

# 透過 JSON 傳遞複雜變數
linear api --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}' <<'GRAPHQL'
query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }
GRAPHQL

# 透過管道傳給 jq 進行過濾
linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'

進階：直接使用 curl

對於需要完整 HTTP 控制的情況，請使用 linear auth token：

curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $(linear auth token)" \
  -d '{"query": "{ viewer { id } }"}'