linearis

linearis

linearis CLI を使って、シェルから Linear.app を操作します（出力は JSON のみです。linear はエイリアスです）。コマンドの仕様を推測しないでください。CLI 自体に説明があり、このスキルではフラグではなくプロトコルを説明します。

事前確認（状況に応じて実施 — CLI 自身の出力に応じて対応し、毎ターン確認を事前実行しないでください）

• 未インストール — シェルがコマンドが見つからないと報告した場合、linearis がインストールされていないことをユーザーに伝え、npm install -g linearis を提案します。インストールしない場合の代替手段として、コマンドの先頭に npx linearis@latest を付けます（初回起動が遅くなり、呼び出しごとにネットワークが必要です。デフォルトではなく代替手段です）。黙って npm install -g を実行しないでください。
• 認証が必要 — どのコマンドも、stderr に次の形式で出力し、終了コード 42 で失敗する場合があります。 { "error": "AUTHENTICATION_REQUIRED", "action": "USER_ACTION_REQUIRED", "instruction": "Run 'linearis auth login' …", "exit_code": 42 }。 exit_code === 42 / error === "AUTHENTICATION_REQUIRED"（言い換えたテキストではありません）で検出し、CLI 自身の instruction を提示します。linearis auth login は対話式のブラウザーフローであり、あなたには完了できないため、ユーザーに実行してもらいます。
• 無効な呼び出し — 不明なコマンドまたはオプション、引数の数の誤り、サブコマンドを指定せずにコマンドグループを指定した場合は、stderr に終了コード 2 を出力して失敗します。 { "error": "UNKNOWN_COMMAND", "message": "…", "suggestion": "Did you mean read?", "command": "linearis issues", "available_commands": [...], "instruction": "Run 'linearis issues usage' …", "exit_code": 2 }。 推測せず、出力形式の情報に基づいて対応します。available_commands から選ぶか、instruction を実行してください。error は UNKNOWN_COMMAND、UNKNOWN_OPTION、MISSING_ARGUMENT、MISSING_REQUIRED_OPTION、MISSING_OPTION_ARGUMENT、TOO_MANY_ARGUMENTS、MISSING_SUBCOMMAND、INVALID_USAGE のいずれかです。サブコマンドのないグループ（linearis issues）は失敗であり、ヘルプのリクエストではありません。
• アップデート（任意、処理を妨げない） — 必要に応じて linearis version check を一度実行します → { current, latest, channel, updateAvailable }。updateAvailable が true の場合はその旨を伝え、npm install -g linearis@latest の実行前にユーザーに確認します。channel を尊重してください（next のユーザーを latest に移行させないでください）。npm が応答しなくなったり、レート制限されたりすることがあります。タイムアウトやエラーが発生した場合は、インストール済みのバージョンでそのまま続行してください。インストール済みのバージョンをプレーンな形式で確認するには、--version ではなく linearis version（JSON）を使用します。

確認してから実行

1. ドメインの一覧（issues、projects、cycles、…）を確認するため、linearis usage を一度実行します。
2. 実行前に、ドメインのコマンドとフラグの完全なリファレンスを確認するため、linearis <domain> usage を実行します。
3. フラグやサブコマンドを決して作り出さないでください。usage が正式かつ常に最新の情報源です。

出力

すべてのコマンドは stdout に JSON を出力します。グローバルオプション --fields identifier,title,state.name と --compact を使って、出力元で整形してください。外部バイナリは不要で、Windows や新規コンテナーでも動作します。複雑な整形に限り jq を使用し、jq がなければ生の JSON を使用してください。

知っておくべき不変条件（それ以外はすべて usage に記載）

• ID の指定は柔軟です。UUID、チームキー（ENG）、課題識別子（ABC-123）、名前を相互に使用できます。チケットは識別子で参照してください。
• issues create には --team が必要です。一部のフィルターにはスコープフラグが必要です。暗記するのではなく、usage で確認してください。
• スレッド形式のディスカッションは issues discuss / discussions / replies / reply の配下にあります。トップレベルの comments ドメインは非推奨のファサードですが、引き続き動作します。issues のディスカッションコマンドを優先してください。重要な進捗はディスカッションスレッドに記録し、ステータス変更時には説明と同期させてください。
• files download <url> は Linear のストレージ URL（uploads.linear.app）のみを取得します。files upload は埋め込み可能な assetUrl を返します。issues read --with-attachments は関連付けられたリソース（PR、ドキュメント、URL）を一覧表示しますが、これらは参照情報であり、必ずしもダウンロードできるファイルではありません。

ここに記載されていない事項については、linearis <domain> usage を参照してください。