Linear CLI

linear cli

linear イシュートラッカーでイシューの一覧表示、開始、作成を行う CLI です。git と jj に対応しており、Linear で適切なビューを表示できます。gh と同様に、Web アプリや Linear デスクトップアプリを開けます。

AI エージェントとの相性も抜群です — CLI にはスキルが含まれており、エージェントがイシューの作成やステータスの更新を行い、コードと併せて Linear のワークフローを管理できます。

使い方は次のとおりです。

linear config               # setup your repo, it writes a config file

linear issue list           # list unstarted issues assigned to you
linear issue query --all-teams  # query issues across all teams
linear issue query --search "login bug"  # search issues in your configured team
linear issue start          # choose an issue to start, creates a branch
linear issue start ABC-123  # start a specific issue
linear issue view           # see current branch's issue as markdown
linear issue pr             # makes a PR with title/body preset, using gh cli
linear issue create         # create a new issue

Web アプリやデスクトップアプリを補完し、対話形式またはスクリプト形式でコマンドラインから操作できることを目指しています。

スクリーンキャストのデモ

linear issue create -i

linear issue start

インストール

homebrew

brew install schpet/tap/linear

npm / bun / pnpm

プロジェクトでバージョンを固定するには、開発依存関係としてインストールします。

npm install -D @schpet/linear-cli
# or
bun add -D @schpet/linear-cli
# or
pnpm add -D @schpet/linear-cli

続いて、パッケージマネージャー経由で実行します。

npx linear issue list
bunx linear issue list

注： このパッケージにはビルド済みバイナリが含まれています

npm のパッケージ： @schpet/linear-cli

シェルインストーラー

macOS および Linux 向け：

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/schpet/linear-cli/releases/latest/download/linear-installer.sh | sh

バイナリ

https://github.com/schpet/linear-cli/releases/latest

ソースからインストール

rust toolchain をインストールしたうえで、次を実行します。

cargo install --locked --git https://github.com/schpet/linear-cli linear

2.x からアップグレードしますか？変更履歴の2.x からのアップグレードを参照してください。

セットアップ

1. linear.app/settings/account/security¹ で API キーを作成します。

2. CLI で認証します。

   linear auth login
   

3. プロジェクトを設定します。

   cd my-project-repo
   linear config
   

複数のワークスペースへの対応やその他の認証方法については、docs/authentication.md を参照してください。

この CLI は git と jj の両方のバージョン管理システムで動作します。

• git：ブランチ名に Linear のイシュー ID が含まれている場合に最適に動作します（例：eng-123-my-feature）。linear issue start を使うか、Linear UI の「copy git branch name」ボタンと関連する自動化機能を利用してください。
• jj：コミットの説明に含まれる Linear-issue トレーラーからイシューを検出します。linear issue start を使うとトレーラーが自動的に追加されます。または、jj describe で手動追加することもできます（例：jj describe "$(linear issue describe ABC-123)"）。

コマンド

イシューコマンド

現在のイシューは、次の情報から判定されます。

• git：現在のブランチ名に含まれるイシュー ID（例：eng-123-my-feature）
• jj：現在のコミットまたは祖先コミットに含まれる Linear-issue トレーラー

Linear の GitHub 連携では git ブランチ名が提案されることに注意してください。

linear issue view      # view current issue details in terminal
linear issue view ABC-123
linear issue view 123
linear issue view -w   # open issue in web browser
linear issue view -a   # open issue in Linear.app
linear issue id        # prints the issue id from current branch (e.g., "ENG-123")
linear issue title     # prints just the issue title
linear issue url       # prints the Linear.app URL for the issue
linear issue pr        # creates a GitHub PR with issue details via `gh pr create`
linear issue list      # list your issues in a table view (supports -s/--state and --sort)
linear issue list --project "My Project" --milestone "Phase 1"  # filter by milestone
linear issue list -w   # open issue list in web browser
linear issue list -a   # open issue list in Linear.app
linear issue query --search "login bug"  # search issues by text in your configured team
linear issue query --search "oauth timeout" --team ENG --json  # structured search output for agents
linear issue query --team "Engineering" --state "In Review" --json  # teams by key, name, or ID; states by type, name, or ID
linear issue query --all-teams --json --limit all  # export all issues as JSON
linear issue start     # create/switch to issue branch and mark as started
linear issue create    # create a new issue, asking for the title
linear issue create -i # create a new issue, asking for every field
linear issue create -t "title" -d "description"  # create with flags
linear issue create --project "My Project" --milestone "Phase 1"  # create with milestone
linear issue create --template "Bug report" -t "Login fails"  # create from a template (see template commands)
linear issue update ENG-123 -s started  # change only the fields you pass
linear issue update ENG-123 --milestone "Phase 2"  # set milestone on existing issue
linear issue update ENG-123 --clear-due-date --clear-parent  # remove values (also --clear-estimate, --clear-project, --clear-milestone, --clear-cycle, --unassign)
linear issue archive ENG-123 --yes  # archive an issue (Linear normally auto-archives closed issues; see docs/usage.md)
linear issue archive --yes --bulk ENG-123 ENG-124  # archive several issues
linear issue delete    # delete an issue
linear issue comment list          # list comments on current issue
linear issue comment add           # add a comment to current issue
linear issue comment add --reply-to <id>   # reply to a comment (-p / --parent are aliases)
linear issue comment list --json   # comments as JSON, with quotedText and parent for inline comments and replies
linear issue comment update <id>   # update a comment
linear issue commits               # show all commits for an issue (jj only)

ファイルの添付

イシューまたはコメントにファイルを添付します。アップロードはデフォルトで非公開であり、Linear Web アプリと同様に、ワークスペースのメンバーのみが読み取りできます。

linear issue attach ENG-123 ./screenshot.png            # attach a file to an issue
linear issue attach ENG-123 ./doc.pdf -t "Spec"         # custom attachment title
linear issue attach ENG-123 ./img.png -c "see this"     # add a linked comment
linear issue comment add ENG-123 -a ./screenshot.png    # attach a file to a comment
linear issue comment add ENG-123 -a ./a.png -a ./b.png  # attach multiple files

添付ファイルはデフォルトで非公開です。--public を渡すと、ラスター画像（png/jpeg/gif/webp/bmp/tiff）を、認証なしで誰でも読み取れる公開 public.linear.app URL にアップロードできます。ワークスペース外との共有に便利ですが、ワークスペースのアクセス制御を迂回するため、警告が表示されます。画像以外のファイルは公開できません。

linear issue attach ENG-123 ./screenshot.png --public           # public image URL
linear issue comment add ENG-123 -a ./screenshot.png --public   # public image URL

チームコマンド

linear team list       # list teams
linear team list --json  # as JSON, e.g. to map a team name to its key or id in scripts
linear team id         # print the configured team key (e.g. for scripts)
linear team members    # list team members
linear team members --all --json  # include inactive members, as JSON
linear team create     # create a new team
linear team autolinks  # configure GitHub repository autolinks for Linear issues

ユーザーコマンド

linear user list        # list everyone in the workspace
linear user list --all  # include deactivated members
linear user list --json # machine-readable output

プロジェクトコマンド

linear project list    # list projects
linear project view https://linear.app/acme/project/mobile-launch-272f50ef9250  # paste a URL from Linear
linear project view    # pick from a searchable list of projects
linear project view <projectId>   # overview, milestones, resources, documents, related projects
linear project view "Mobile launch"   # a UUID, slug ID, or exact name all work
linear project view <projectId> --json  # project details as JSON
linear project create --name "API v2" --team ENG --content-file overview.md
linear project create --name "Mobile launch" --team APP --priority high --label Launch --member [email protected]
linear project create --name "Q3 launch" --team APP --template "Kickoff"  # create from a project template
linear project update <projectId> --content-file overview.md  # replace the project's overview body
linear project update <projectId> --clear-lead --clear-target-date  # remove values (also --clear-start-date)
linear project update <projectId> --add-team OPS --remove-label Launch --add-initiative "Q4 Bets"  # change teams, labels, initiatives incrementally
linear project update <projectId> --team ENG --team OPS   # replace the whole team set (--label and --initiative replace likewise)
linear project comment list <project>                         # list the project's discussion thread (UUID, slug, or name)
linear project comment add <project> --body "Kickoff Monday"  # comment on a project
linear project comment add <project> --body "+1" --reply-to <commentId>  # reply in a thread

イニシアチブコマンド

linear initiative list                                            # list initiatives
linear initiative view <initiative>                               # view an initiative (UUID, slug, or name)
linear initiative comment list <initiative>                       # list the initiative's discussion thread
linear initiative comment add <initiative> --body-file note.md   # comment on an initiative
linear initiative comment add <initiative> --body "+1" --reply-to <commentId>  # reply in a thread

サイクルコマンド

linear cycle list --team ENG          # list a team's cycles (--team takes a key, name, or ID)
linear cycle list --team ENG --json   # as JSON
linear cycle view 12 --team ENG       # view a cycle by number or name
linear cycle view 12 --team ENG --json  # cycle details and its issues, as JSON

マイルストーンコマンド

linear milestone list --project <projectId>     # list milestones for a project
linear m list --project <projectId>             # list milestones (alias)
linear milestone list --project <projectId> --json  # as JSON
linear milestone view <milestoneId>             # view milestone details
linear m view <milestoneId>                     # view milestone (alias)
linear milestone view <milestoneId> --all       # list every issue, not just the first 10
linear milestone view <milestoneId> --json      # milestone with every issue, as JSON
linear milestone create --project <projectId> --name "Q1 Goals" --target-date "2026-03-31"  # create a milestone
linear m create --project <projectId>           # create a milestone, asking for its name
linear milestone update <milestoneId> --name "New Name"  # update milestone name
linear m update <milestoneId> --target-date "2026-04-15"  # update target date
linear milestone delete <milestoneId>           # delete a milestone
linear m delete <milestoneId> --yes             # delete without confirmation

ドキュメントコマンド

コマンドラインから Linear のドキュメントを管理します。各ドキュメントは、プロジェクト、イシュー、イニシアチブ、チーム、サイクル、リリースのいずれか1つに必ず紐付けられます（Linear の API で必須です）。

# list documents
linear document list                            # list all accessible documents
linear docs list                                # alias for document
linear document list --project <project>        # filter by project (UUID, slug ID, or name)
linear document list --issue TC-123             # filter by issue
linear document list --team ENG                 # filter by team
linear document list --initiative <initiative>  # filter by initiative
linear document list --team ENG --cycle active  # filter by cycle (team scopes the lookup)
linear document list --release <release>        # filter by release (UUID, name, or version)
linear document list --json                     # output as JSON

# view a document
linear document view <slug>                     # view document rendered in terminal
linear document view <slug> --raw               # output raw markdown (for piping)
linear document view <slug> --web               # open in browser
linear document view <slug> --json              # output as JSON, including document comments

# comment on a document
linear document comment list <slug>             # list comments; inline comments show the text they quote
linear document comment list <slug> --json      # comments as JSON (quotedText, parent, ...)
linear document comment add <slug> --body "Looks good"              # add a top-level comment
linear document comment add <slug> --body-file note.md --reply-to <commentId>  # reply in a thread

# create a document (exactly one attachment target is required)
linear document create --title "Doc" --project <project>              # attach to project
linear document create --title "Notes" --issue TC-123                 # attach to issue
linear document create --title "Handbook" --team ENG                  # attach to team
linear document create --title "Brief" --initiative <initiative>      # attach to initiative
linear document create --title "Sprint" --team ENG --cycle next       # attach to cycle
linear document create --title "Notes" --release 2026.8               # attach to release
linear document create --title "Spec" --content-file ./spec.md --project <project>  # content from file
cat spec.md | linear document create --title "Spec" --project <project>             # content from stdin

# update a document
linear document update <slug> --title "New Title"                     # update title
linear document update <slug> --content-file ./updated.md             # update content
linear document update <slug> --edit                                  # open in $EDITOR
linear document update <slug> --team ENG                              # re-point attachment (replaces current)
linear document update <slug> --content-file ./updated.md --force     # bypass comment-anchor guard

# delete a document
linear document delete <slug>                   # soft delete (move to trash)
linear document delete --bulk <slug1> <slug2>   # bulk delete

ドキュメントにアクティブなインライン Linear コメントがある場合、Markdown を置き換えるとコメントのアンカーが外れたり非表示になったりする可能性があるため、デフォルトではコンテンツの更新を拒否します。ドキュメントの最上位にあるコメントは更新を妨げません。まずインラインコメントを確認し、それでもコンテンツを置き換える場合は --force を指定して再実行してください。

テンプレートコマンド

linear template list                       # every issue, project, and document template in the workspace
linear template list --type issue --team ENG  # ENG's issue templates plus workspace-level ones
linear template list --json                # the raw template objects (templateData is a JSON-encoded string)
linear template view "Bug report"          # what the template pre-fills: title, priority, labels, body, sub-issues, ...
linear template view <template-id> --json  # raw GraphQL object; `jq '.templateData | fromjson'` decodes the data

# apply a template on create (name or ID). Linear fills the template in server-side.
linear issue create --team ENG --template "Bug report"                    # the template supplies the title
linear issue create --team ENG --template "Bug report" -t "Login fails" -l security  # flags override, labels merge
linear project create --name "Q3 launch" --team APP --template "Kickoff"

--template はチームのデフォルトテンプレートの代わりに使われるため、--no-use-default-template を指定する必要はありません（両方を指定しても問題ありません）。明示的に指定した内容はテンプレートの値より優先されます。--label はテンプレートのラベルに追加され、--description はテンプレートの本文を置き換えるため、本文をそのまま使うには省略してください。ドキュメントテンプレートの一覧表示と閲覧はできますが、Linear の API にはドキュメントの作成時にテンプレートを適用する方法がありません。

その他のコマンド

linear --help          # show all commands
linear --version       # show version
linear config          # setup the project
linear completions     # generate shell completions

設定オプション

CLI は、環境変数または .linear.toml 設定ファイルによる設定に対応しています。環境変数は設定ファイルの値より優先されます。

オプション	環境変数	TOML キー	例	説明
チーム ID	LINEAR_TEAM_ID	team_id	"ENG"	操作のデフォルトのチーム
ワークスペース	LINEAR_WORKSPACE	workspace	"mycompany"	Web／アプリの URL に使用するワークスペースのスラッグ
課題の並べ替え	LINEAR_ISSUE_SORT	issue_sort	"priority" or "manual"	課題リストの並べ替え方法
プロジェクトの確認	LINEAR_ISSUE_CREATE_ASK_PROJECT	issue_create_ask_project	true or false	対話型の issue create でプロジェクトを確認するかどうか
自分への割り当て	LINEAR_ISSUE_CREATE_ASSIGN_SELF	issue_create_assign_self	"always", "auto", or "never"	課題作成時に自分へ割り当てるデフォルトの動作を制御します
VCS	LINEAR_VCS	vcs	"git" or "jj"	バージョン管理システム（デフォルト：git）
画像のダウンロード	LINEAR_DOWNLOAD_IMAGES	download_images	true or false	課題の表示時に画像をダウンロードするかどうか
PR テンプレート	LINEAR_PR_TEMPLATE	pr_template	".github/pull_request_template.md"	issue pr の本文に使用するテンプレートファイル（Linear の課題 URL が追加されます。--no-template でスキップできます）

設定は、プロジェクトファイルとグローバルファイルの 2 つの設定ファイルから読み込まれます。各オプションには、次の順序で最初に見つかった値が使用されます。

1. コマンドに指定されたコマンドラインフラグ
2. シェルまたは .env ファイルの環境変数（シェルの値が優先されます）
3. プロジェクト設定ファイル：リポジトリのルートにある ./linear.toml、./.linear.toml、linear.toml、.linear.toml、.config/linear.toml のうち、最初に見つかったファイル
4. グローバル設定ファイル：macOS と Linux では $XDG_CONFIG_HOME/linear/linear.toml（または ~/.config/linear/linear.toml）、Windows では %APPDATA%\linear\linear.toml

そのため、グローバルファイルには issue_sort などのデフォルト値を設定でき、リポジトリの .linear.toml でそのプロジェクトの設定を上書きできます。上位の設定で上書きされる値も含め、すべての値が検証されます。無効な値がある場合は、そのファイル名とキーを示すエラーになります。

終了ステータス

スクリプトは、エラーメッセージを解析しなくても、終了ステータスからコマンドが失敗した理由を判断できます。

ステータス	意味
0	成功
1	その他の失敗。linear api での無効なクエリなど、GraphQL エラーも含みます
2	使用方法のエラー。不正なフラグや値が指定され、Linear に何も送信される前に拒否されました
3	見つかりません。コマンドが検索したイシュー、チーム、プロジェクト、その他のエンティティが存在しません
4	認証エラー。使用可能な API キーがないか、Linear に拒否されました（取り消し済み、入力ミス、またはアクセス権がありません）
5	利用不可。Linear に接続できなかった、タイムアウトした、リクエストがレート制限された、またはサーバーエラーが発生しました。後で再試行すれば成功する場合がありますが、作成や更新がすでに反映されている可能性もあります
130	プロンプトまたはエディターでキャンセルされました

複数の理由で失敗するバルクコマンド（--bulk）は、そのうち 4、5、1、3 の最初のステータスで終了します。そのため、3 はすべての失敗が項目の欠落によるものだという意味です。linear --help にもステータスが記載されています。

スキル

linear-cli には、AI エージェントが CLI を効果的に使えるよう支援するスキルが含まれています。CLI の範囲外のユースケース向けには、認証を含め、GraphQL API と直接やり取りするための手順も含まれています。

claude code

claude code のプラグインシステムを使ってスキルをインストールします。

# from claude code
/plugin marketplace add schpet/linear-cli
/plugin install linear-cli@linear-cli

# from bash
claude plugin marketplace add schpet/linear-cli
claude plugin install linear-cli@linear-cli

# to update
claude plugin marketplace update linear-cli
claude plugin update linear-cli@linear-cli

その他のエージェント向けの skills.sh

skills.shを使ってスキルをインストールします。

npx skills add schpet/linear-cli

skills.sh/schpet/linear-cli/linear-cliでスキルを確認できます。

開発

linear-cli は Rust で書かれており、ツールチェーンは rust-toolchain.toml で固定されています。一般的なタスクは justfile に記載されています。

just dev issue list   # run the cli from source (cargo run -- issue list)
just install          # install this checkout as `linear`
just check            # cargo fmt --check, clippy, and tests, as CI runs them

スキルのドキュメントを更新する

スキルのコマンド一覧と skills/linear-cli/references/ は、CLI のヘルプから生成されます。skills/linear-cli/SKILL.template.md を編集してから、再生成します。

just skill-docs

GraphQL スキーマを更新する

graphql/schema.graphql は Linear の API スキーマで、すべてのクエリをコンパイル時に型チェックするために使われます。ログイン済みの CLI で更新します。

just sync-schema

開発の理由

Linear の UI は非常に優れていますが、作業の妨げになります。次のようなことが頻繁に起こるのは、かなり煩わしいです。

• リポジトリから Linear にコンテキストを切り替える
• Linear を開いたとき、適切なビューが表示されていない
• Linear が Git ブランチを提案しても、そのブランチの作成や切り替えは自分で行わなければならない
• Linear が提案する Git ブランチでは、そのブランチがすでに存在するか、マージ済みのプルリクエストがあるかが考慮されない

この CLI はこうした問題を解決します。作業中の内容を把握し（Git ブランチまたは jj のコミットトレーラーを利用）、バージョン管理の状態を管理し、プルリクエストの詳細も作成します。

Footnotes

1. API キーの作成にはメンバーアクセスが必要です。ゲストアカウントでは利用できません。 ↩