linear-cli

Linear CLI

コマンドラインから Linear の課題を管理する 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

よく使うタスク

頻繁に使うワークフローを、そのままコピーして使えるレシピとして紹介します。専用コマンドがある場合は linear api よりもそちらを優先し、専用コマンドやフラグで対応できない場合に限って GraphQL による代替手段を使ってください。

フィルターを使って課題を検索する

issue query はすべての担当者を対象に検索し、組み合わせ可能な構造化フィルターをサポートします。

linear issue query --team ENG --state started --json
linear issue query --project "Mobile App" --state backlog --state triage --unassigned
linear issue query --assignee sam --label bug --updated-after 2026-01-01

注：linear issue list（エイリアス issue mine）は、デフォルトで_自分の_課題を表示します。他のユーザーやチーム／プロジェクト全体を対象にする場合は、issue query を使ってください。

自分の課題を一覧表示する

linear issue list --state started --sort priority

課題を作成する

linear issue create --team ENG --title "Fix login redirect" \
  --description-file ./description.md --no-input

複数行の Markdown はファイルに書き込み、--description-file を渡してください（下記の Markdown のセクションを参照）。--no-input を指定すると、スクリプトから使用する際に不足している情報の入力を求めず、コマンドが失敗します。

課題の状態、担当者、またはラベルを更新する

linear issue update ENG-123 --state "In Review" --assignee sam
linear issue update ENG-123 --unassign
linear issue update ENG-123 --delegate linear                # hand to an agent; separate from the assignee
linear issue update ENG-123 --clear-delegate
linear issue update ENG-123 --add-label security             # add, keep existing labels
linear issue update ENG-123 --remove-label sprint-42         # detach; does not delete the label
linear issue update ENG-123 --remove-label sprint-42 --add-label sprint-43  # atomic swap
linear issue update ENG-123 --label infra --label security   # replaces the label set

テンプレートから課題またはプロジェクトを作成する

linear template list --type issue --team ENG              # find the template a team expects
linear template view "Bug report"                         # see what it pre-fills (title, fields, body, sub-issues)
linear issue create --team ENG --template "Bug report" --title "Login fails on Safari"
linear project create --name "Q3 launch" --team ENG --template "Kickoff"

明示的に指定したフラグはテンプレートの値より優先され、--label はテンプレートのラベルに追加され、--description はテンプレートの本文を置き換えます（本文を維持する場合は省略してください）。ドキュメントテンプレートは API 経由では適用できません。

コメントを追加する

linear issue comment add ENG-123 --body-file ./comment.md

インラインで表示できるように画像やスクリーンショットを添付する

linear issue comment add ENG-123 --attach ./screenshot.png

画像をアップロードしてコメントに埋め込むため、Linear ではインラインで表示されます。画像を表示する必要がある場合は linear issue attach を使わないでください。このコマンドではサイドバーにリンク添付が作成され、画像はインライン表示されません。

コメントスレッドを解決または再開する

linear issue comment list ENG-123 --unresolved            # open threads only, with their replies
linear issue comment resolve <COMMENT> <COMMENT>          # resolve threads by their top-level comment IDs
linear issue comment resolve <COMMENT> --with <REPLY>     # record the reply that resolved the thread
linear issue comment unresolve <COMMENT>                  # reopen a thread

スレッドはトップレベルコメントの ID で指定してください。返信の ID を指定すると拒否されます。comment list --json では、解決済みスレッドのトップレベルコメントにのみ resolvedAt が設定され、返信には parent.resolvedAt にスレッドの状態が格納されます。未解決スレッドの ID は jq -r '.[] | select(.parent == null and .resolvedAt == null) | .id' で取得できます。

課題を表示する／URL を取得する

linear issue view ENG-123          # details incl. comments
linear issue view ENG-123 --json   # structured output
linear issue url ENG-123           # print just the URL

課題をクローズ、削除、またはアーカイブする

linear issue update ENG-123 --state Done       # or Canceled; Linear auto-archives closed issues later
linear issue delete ENG-123                    # trash; restorable in Linear for 30 days
linear issue archive ENG-123 --yes             # rarely appropriate, see below

アーカイブよりも、クローズまたは削除を優先してください。Linear のドキュメントには「アーカイブは手動で項目をアーカイブする方法がなく、自動的に行われます」（https://linear.app/docs/delete-archive-issues）と記載されています。クローズ済みの課題はチームで設定した期間が経過すると自動的にアーカイブされます。また、ユーザーがゴミ箱のように使っていたため、Linear はアプリから手動アーカイブ機能を削除しました。issue archive は issueArchive ミューテーションを直接呼び出し、未解決の親課題、サブ課題、サイクル、プロジェクトに対する自動アーカイブのチェックを回避します。また、--include-archived を指定しない限り、アーカイブ済みの課題は issue list、issue query、検索結果に表示されなくなります。ユーザーから明示的に依頼された場合にのみ、アーカイブしてください。

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

Markdown を含む課題の説明やコメント本文を扱う場合は、コンテンツをコマンドライン引数として渡すのではなく、必ずファイルベースのフラグを優先して使用してください。

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

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

• Linear のウェブ UI で適切な書式が保たれます
• 改行や特殊文字に関するシェルのエスケープ問題を回避できます
• Markdown 内に文字列 \n がそのまま表示されるのを防げます
• 複数行のコンテンツを扱いやすくなります

ワークフローの例：

# Write markdown to a temporary file
cat > /tmp/description.md <<'EOF'
## Summary

- First item
- Second item

## Details

This is a detailed description with proper formatting.
EOF

# Create issue using the file
linear issue create --title "My Issue" --description-file /tmp/description.md

# Or for comments
linear issue comment add ENG-123 --body-file /tmp/comment.md

インラインフラグ（--description、--body）は、単純な1行のコンテンツにのみ使用してください。

Linear Markdown の機能

通常の URL で人物やリソースに言及する

Linear は、Markdown 内のリソースの通常の Linear URLをリンク付きのメンションに変換します。リテラルの @name、@[Name](id)、または [Name](url) のような Markdown リンクでは、同じメンションは作成されません。通常の URL をコメントまたは説明に直接記載してください。

https://linear.app/yourworkspace/profiles/someuser could you review this? https://linear.app/yourworkspace/issue/ENG-123 is related.

まず、該当するチーム内で人物を探します。チームは通常、課題の識別子または現在のディレクトリから推測できます。

linear team members ENG --json

選択したメンバーの url フィールドを Markdown にそのまま使用します。対象の人物がそのチームのメンバーでない場合は、そこで中止し、linear user list --json でワークスペース全体を検索する前に確認してください。チーム外の人物への言及は、誤操作の可能性が高いためです。課題の場合は、linear issue url ENG-123 を使用し、その通常の URL を記載してください。

折りたたみ可能なセクションを追加する

+++ [title] で折りたたみ可能なセクションを開き、+++ で閉じます。

+++ [Server log]

Markdown content that is initially hidden.

+++

タイトルを囲む角括弧と、閉じる +++ は必須です。

終了ステータス

終了ステータスはコマンドが失敗した理由を示すため、スクリプトで stderr を解析する必要はありません。

• 0 成功
• 1 その他の失敗。linear api の GraphQL エラーを含みます
• 2 使用方法のエラー。フラグまたは値を修正してください。何も送信されていません
• 3 見つかりません。課題、チーム、またはその他のエンティティが存在しません
• 4 認証エラー。使用可能な API キーがないか、Linear に拒否されました。再試行しても解決しません
• 5 利用不可。ネットワーク障害、タイムアウト、レート制限、またはサーバーエラーです。後で再試行してください。ただし、作成または更新がすでに行われている可能性があります
• 130 キャンセル

使用可能なコマンド

linear --help から生成された、簡潔なコマンド一覧です。

linear api

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

linear config

linear cycle
linear cycle list
linear cycle view

linear document
linear document list
linear document view
linear document create
linear document update
linear document delete
linear document comment
linear document comment add
linear document comment list

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

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

linear issue
linear issue list
linear issue query
linear issue view
linear issue create
linear issue update
linear issue delete
linear issue archive
linear issue start
linear issue id
linear issue title
linear issue url
linear issue describe
linear issue commits
linear issue pull-request
linear issue comment
linear issue comment add
linear issue comment list
linear issue comment update
linear issue comment delete
linear issue comment resolve
linear issue comment unresolve
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 label
linear label list
linear label create
linear label delete

linear markdown

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

linear project
linear project list
linear project view
linear project create
linear project update
linear project delete
linear project comment
linear project comment add
linear project comment list

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

linear schema

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

linear template
linear template list
linear template view

linear user
linear user list

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

• api - Linear API に未加工の GraphQL リクエストを送信します
• auth - ワークスペースにログインし、認証情報を管理します
• config - 現在のリポジトリ用の .linear.toml を作成します
• cycle - チームのサイクルを表示します
• document - ドキュメントを管理します
• initiative - イニシアチブを管理します
• initiative-update - イニシアチブのステータス更新を投稿、一覧表示します
• issue - 課題を管理します
• label - 課題のラベルを管理します
• markdown - メンションや折りたたみ可能なセクションなど、Linear 独自の Markdown 機能について説明します
• milestone - プロジェクトのマイルストーンを管理します
• project - プロジェクトを管理します
• project-update - プロジェクトのステータス更新を投稿、一覧表示します
• schema - Linear GraphQL スキーマを出力します
• team - チームを管理します
• template - 課題、プロジェクト、ドキュメントのテンプレートを参照します
• user - ワークスペースのメンバーを一覧表示します

組織機能（イニシアチブ、ラベル、プロジェクト、一括操作）の厳選された例については、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 を実行してください（linear team list --json では、チーム名とその key および id の対応を確認できます）。
• --no-pager がサポートされているのは issue list、issue query、issue view、project view のみです。project list など、ほかのコマンドに指定するとエラーになります。

Linear GraphQL API を直接使用する

サポートされているすべての操作には 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 リクエストを送信する

linear api は、唯一の位置引数として GraphQL ドキュメントを受け取り、サブコマンドはありません。引用符で囲んだドキュメント内に、先頭の query または mutation キーワードを入れてください。linear api 'query { ... }' のように指定し、linear api query '...' のようには指定しないでください。linear issue query は、イシューを検索するための別の実在するサブコマンドです。

重要： 非 null 型マーカー（例：String の後に続く感嘆符）を含む GraphQL クエリは、エスケープの問題を避けるため、heredoc で標準入力から渡す必要があります。これらのマーカーを含まないシンプルなクエリは、インラインで渡せます。

# Simple query (no type markers, so inline is fine)
linear api '{ viewer { id name email } }'

# Query with variables — use heredoc to avoid escaping issues
linear api --variable teamId=abc123 <<'GRAPHQL'
query($teamId: String!) { team(id: $teamId) { name } }
GRAPHQL

# Search issues by text
linear api --variable term=onboarding <<'GRAPHQL'
query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }
GRAPHQL

# Numeric and boolean variables
linear api --variable first=5 <<'GRAPHQL'
query($first: Int!) { issues(first: $first) { nodes { title } } }
GRAPHQL

# Complex variables via JSON
linear api --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}' <<'GRAPHQL'
query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }
GRAPHQL

# Pipe to jq for filtering
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 } }"}'