Linear CLI

コマンドラインから Linear の issue を管理する CLI です。git と jj のインテグレーション機能があります。

前提条件

linear コマンドが PATH で利用可能である必要があります。確認方法:

linear --version

グローバルにインストールされていない場合は、npx で実行できます:

npx @schpet/linear-cli --version

以降のコマンドはすべて linear の代わりに npx @schpet/linear-cli を使用できます。インストール方法については以下を参照してください:
https://github.com/schpet/linear-cli?tab=readme-ov-file#install

Markdown コンテンツのベストプラクティス

issue の説明やコメント本文に Markdown を含む場合、コマンドライン引数でコンテンツを渡すのではなく、ファイルベースのフラグを使用することを強く推奨します:

• issue create および issue update コマンドでは --description-file を使用
• comment add および comment update コマンドでは --body-file を使用

ファイルベースのフラグを使用する理由:

• Linear の web UI で適切にフォーマットされることが保証される
• 改行や特殊文字でシェルのエスケープ問題を回避できる
• markdown に文字どおりの \n シーケンスが表示されるのを防ぐ
• 複数行のコンテンツを扱いやすくなる

使用例:

# markdown を一時ファイルに書き込む
cat > /tmp/description.md <<'EOF'
## Summary

- First item
- Second item

## Details

This is a detailed description with proper formatting.
EOF

# ファイルを使用して issue を作成
linear issue create --title "My Issue" --description-file /tmp/description.md

# またはコメント用
linear issue comment add ENG-123 --body-file /tmp/comment.md

インラインフラグ (--description, --body) は、シンプルな 1 行のコンテンツのみに使用してください。

利用可能なコマンド

linear --help から生成された簡潔なコマンドリスト:

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

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

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

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

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

linear cycle
linear cycle list
linear cycle view

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

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

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

linear label
linear label list
linear label create
linear label delete

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

linear config

linear schema

linear api

リファレンスドキュメント

• auth - Linear 認証を管理
• issue - Linear issue を管理
• team - Linear チームを管理
• project - Linear プロジェクトを管理
• project-update - プロジェクトの状態更新を管理
• cycle - Linear チームのサイクルを管理
• milestone - Linear プロジェクトのマイルストーンを管理
• initiative - Linear イニシアティブを管理
• initiative-update - イニシアティブの状態更新を管理 (タイムラインポスト)
• label - Linear issue ラベルを管理
• document - Linear ドキュメントを管理
• config - インタラクティブに .linear.toml 設定を生成
• schema - GraphQL スキーマを stdout に出力
• api - raw GraphQL API リクエストを実行

組織の機能 (イニシアティブ、ラベル、プロジェクト、一括操作) の厳選された例については、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 がサポートするすべての操作に CLI を優先してください。 api コマンドは、CLI でカバーされていないクエリの代替手段としてのみ使用してください。

スキーマから利用可能な型とフィールドを確認

スキーマを一時ファイルに書き込み、検索します:

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 リクエストを実行

重要: 非 null 型マーカー (例: String の後に感嘆符) を含む GraphQL クエリは、エスケープ問題を回避するため、heredoc stdin で渡す必要があります。これらのマーカーを持たないシンプルなクエリはインラインで渡すことができます。

# シンプルなクエリ (型マーカーがないため、インラインで OK)
linear api '{ viewer { id name email } }'

# 変数付きクエリ — heredoc を使用してエスケープ問題を回避
linear api --variable teamId=abc123 <<'GRAPHQL'
query($teamId: String!) { team(id: $teamId) { name } }
GRAPHQL

# テキストで issue を検索
linear api --variable term=onboarding <<'GRAPHQL'
query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }
GRAPHQL

# 数値と boolean 変数
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 } }"}'