Cursor CLIは、エディタを開かずにターミナルからコーディングエージェントを動かす実行系です。公式ドキュメントが示す主コマンドはagentで、2026年1月8日のリリースを境にcursor-agentから主エントリが移りました。以前の記事どおりに打つとコマンドが見つからない、という詰まり方をする箇所です。この記事では、OS別のインストールから対話セッションの操作、-pによる非対話実行、GitHub Actionsへの組み込み、ルールとMCPの読み込み先、Pro 月20ドルからの料金区分までを、2026年9月時点の公式ドキュメントの記述に沿って手順の形で整理しました。
まとめ：Cursor CLIを単体で回す条件と、エディタ側に残す作業の線引き
先に結論を置きます。CLIへ寄せて効くのは、リポジトリを横断する定型作業、SSH越しのサーバー作業、そしてCIの中で走らせる検査です。設計を相談しながら詰める作業は、差分を目で追えるエディタ側に残したほうが速く終わります。
導入でいちばん事故を避けるのは、権限の設計です。-pだけの実行は提案を返すだけで、--forceを付けて初めてファイルが書き換わります。CIではエージェントにgit操作を任せず、ファイル変更までをエージェント、commitとpushとPRコメントは後段の決め打ちステップ、という分割にしてください。この順番を守らないと、エージェントの判断でブランチが増え、レビュー前のpushが走ります。
インストールから初回起動までの手順｜OS別コマンドとagent updateでの更新
導入は1コマンドで終わります。バイナリはユーザーのホーム配下に入り、管理者権限は要りません。
macOS・Linux・WSLとWindowsネイティブで分かれるインストール手順
公式のインストール手順は、macOS・Linux・WSL向けにインストールスクリプトを、Windowsネイティブ向けにPowerShell経由の取得を示しています。WSLを使っている場合は前者と同じ扱いで、Linux側のシェルに入れます。両者を混在させるとPATHが二重になり、どちらのバイナリが呼ばれているか分からなくなるため、片方に寄せてください。
導入先は$HOME/.cursor/binです。CIコンテナのように非対話シェルでPATHが引き継がれない環境では、このディレクトリを明示的に足す必要があります。
# macOS / Linux / WSL
curl https://cursor.com/install -fsS | bash
# Windows（PowerShell）
irm 'https://cursor.com/install?win32=true' | iex
# 導通確認と更新
agent --version
agent updateagent –versionでの導通確認と自動更新・agent updateの扱い
入ったかどうかはagent --versionで判定します。ここで「command not found」が返るなら、PATHに$HOME/.cursor/binが入っていません。シェルの設定ファイルへ追記するか、CIなら実行ステップの中でPATHへ足します。
更新はagent updateです。公式ドキュメントは自動更新が既定で有効だと明記しており、手元の端末では放っておいても版が上がります。問題になるのはCI側で、ジョブごとに最新版を取りに行く構成だと、昨日通っていたプロンプトが今日は別の挙動になる可能性があります。CLIのチェンジログは2026年8月26日の更新で永続セッション、セルフホストワーカーの改善、デスクトップ共有の追加を挙げており、更新の頻度そのものは高い部類です。CIで安定させたいなら、インストール直後に版を記録し、失敗時に版の差を突き合わせられる形にしておいてください。
対話セッションの操作手順｜スラッシュコマンドとモード切替・実行承認の流れ
ここからは手元のターミナルで動かす側の操作です。エディタのチャット欄と同じ概念が、キー操作に置き換わっています。
初回セッションの起動とagent ls・resumeによる会話の再開
概要ドキュメントが示す起動形は3つです。引数なしのagentで対話セッションに入り、agent "このリポジトリのビルド手順を調べて"のように初期プロンプトを付けて開始することもできます。過去の会話はagent lsで一覧でき、agent resumeが直近の会話を、--resume="chat-id"が特定の会話を開きます。直前の続きだけなら--continueです。
この再開機能があるため、長い調査を途中でターミナルごと閉じても続きから戻れます。セッションIDを控える運用にしておくと、翌日に別のターミナルから同じ文脈を引き継ぐことが可能です。エディタ側のCursorが何をするツールなのかを先に押さえたい場合は、Cursorとは？AIコードエディタの機能・料金・使い方で本体側の機能を整理しています。
プランモードとaskモードの切り替え｜Shift+Tabと–mode指定
モードは3系統です。2026年1月16日のCLIリリースでプランモードとaskモードがCLIにも入り、/planまたは--mode=planで実装前に計画を立てさせ、/askまたは--mode=askでコードを変更せずに質問と探索だけを行えます。セッション中の切り替えはShift+Tabで、押すたびにモードが回ります。
コンテキストが伸びてきたときは/summarizeで圧縮します。/compressは同じ処理の別名です。同じリリースで/listが/resumeへ、/modelsが/modelへ置き換わっている点にも注意してください。古い解説記事のスラッシュコマンドをそのまま打つと、廃止済みの名前を叩くことになります。
ターミナル実行前の承認プロンプトとCtrl+Rでの差分レビュー
安全側の挙動は明快です。CLIでのエージェント操作は、ターミナルコマンドを実行する前に許可（y）か拒否（n）を尋ねると記載しています。対話セッションでは、この確認が既定の歯止めになります。
変更内容の確認はCtrl+Rです。語単位のインライン差分が表示され、どの行のどの語が書き換わったかを追えます。改行はCtrl+J、終了はCtrl+D、直前のメッセージの呼び出しは上矢印キーです。ファイルやフォルダをコンテキストへ入れるときは@で指定します。承認プロンプトが挟まるのは対話セッションだからで、次章の非対話実行では前提が変わります。
非対話モードでの実行｜-pと–forceの境界とjson出力をCIで受ける書き方
スクリプトや自動化へ入れる場合は、対話を挟まないモードを使います。ここが権限設計の分かれ目です。
-pだけでは提案止まり｜–forceを付けて初めて走るファイル変更
ヘッドレス実行のドキュメントは、-p（--print）を非対話のスクリプトと自動化ワークフロー向けと位置づけています。通常は提案を返すだけで、ファイルには手を付けません。実際に書き換えさせるには--forceが要ります。公式の説明は「確認なしで直接ファイル変更を可能にする」で、printモードでの自動変更に必須のフラグです。
この2段構えを把握していないと、2種類の失敗が起きます。--forceを付け忘れて「何も起きない」と悩む失敗と、検証前のブランチで--forceを付けて広範囲を書き換える失敗です。運用としては、まず-pだけで出力を読み、意図どおりなら同じプロンプトへ--forceを足して流す順序をおすすめします。認証はセッションではなくCURSOR_API_KEYの環境変数で通ります。
json・stream-json出力の受け方とCIの合否判定への組み込み方
出力形式は3種類あります。既定のtext、構造化された解析向けのjson、逐次追跡向けのstream-jsonです。stream-jsonは--stream-partial-outputと組み合わせると、生成の途中経過を流しながら受け取れます。CIのログへ進捗を出したいときに効きます。
合否判定へ通すなら、json出力をパースして終了コードへ落とす形が扱いやすい構造です。下は、変更前の検査だけをエージェントに任せ、結果の文字列で後続ステップを止める書き方の例になります。
# 提案だけ受け取り、結果をJSONで保存する
agent -p "このリポジトリで未使用の依存を列挙し、無ければ NONE とだけ返す" \
--output-format json > agent_result.json
# 結果を取り出してCIのゲートにする
RESULT=$(jq -r '.result' agent_result.json)
if [ "$RESULT" != "NONE" ]; then
echo "未使用の依存を検出: $RESULT"
exit 1
fiGitHub Actionsへの組み込み手順とgit操作を渡さない制限自律の設定
CIへ載せる手順は公式ドキュメントに型があります。素直に真似るより、権限の配り方を先に決めてください。
CURSOR_API_KEYの登録とPATH追加までのワークフロー記述
GitHub Actionsの手順は、インストールスクリプトの実行とPATHへの追加、CURSOR_API_KEYをシークレットとして渡す形を示しています。キーはCursorのダッシュボードで発行し、リポジトリのSettingsからSecrets and variables、Actionsの順で登録します。GitHub CLIから登録しても同じです。
ランナー上ではシェルの設定ファイルが読まれないため、インストール後に$HOME/.cursor/binを$GITHUB_PATHへ書き出す1行が要ります。この行を落とすと、次のステップでagentが見つかりません。ghコマンドと併用する場面も多いので、ghコマンド（GitHub CLI）のインストール方法と使い方と合わせて読むと、PR操作まで一本の流れで書けます。
git操作をエージェントへ渡さない制限自律パターンの分割手順
公式は2つのアプローチを並べています。git操作もPRコメントもエージェントに任せる完全自律と、ファイル変更だけを任せて公開処理を別ステップへ出す制限自律です。受託開発の現場で採るべきは後者だと考えています。理由は再現性で、commitメッセージやブランチ名がプロンプトの解釈で毎回変わると、後から履歴を追えなくなるためです。
制限自律では、プロンプト自体に「ブランチを作らない、commitしない、pushしない、PRコメントを書かない」と明示し、公開は決め打ちのシェルステップで行います。
- name: Install Cursor CLI
run: |
curl https://cursor.com/install -fsS | bash
echo "$HOME/.cursor/bin" >> $GITHUB_PATH
- name: Generate changes (restricted)
env:
CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
run: |
agent -p --force "ブランチ作成・commit・push・PRコメントは行わない。作業ディレクトリのファイル変更だけ行う"
- name: Publish (deterministic)
run: |
git checkout -B "bot/${{ github.head_ref }}"
git add -A
git commit -m "chore: apply agent changes"
git push origin "bot/${{ github.head_ref }}"ルール・AGENTS.md・mcp.jsonの読み込みとプロジェクト設定の置き場所
CLIはエディタ側の資産をそのまま読みます。設定を二重に持たなくて済む反面、読み込み対象を誤解しやすい箇所です。
.cursor配下のルールとAGENTS.md・CLAUDE.mdの読み込み対象
CLIが参照するのは.cursor/rulesディレクトリのルールと、プロジェクトルートのAGENTS.mdおよびCLAUDE.mdです。エディタで整備したコーディング規約がそのまま効くため、CLI用に書き直す必要はありません。
注意したいのは旧形式です。ルートに置く単一ファイルの.cursorrulesは旧世代の書式で、現行はディレクトリ分割型に移っています。書式の差と移行のしかたは.cursorrulesとProject Rules（.cursor/rules）の違い・書き方で整理しました。ルールの新規作成と編集は、セッション中に/rulesから呼び出せます。定型プロンプトを登録する/commandsも同じ2026年1月8日のリリースで入りました。
mcp.jsonの自動検出と/mcpでのサーバー有効化・認証の流れ
MCPサーバーの設定は自動で拾われます。公式ドキュメントは「CLIはmcp.jsonの設定を自動的に検出して尊重する」と記載しており、エディタで接続済みのサーバーはCLIからも同じ定義で見えます。セッション内の管理は/mcp enableと/mcp disable、一覧は/mcp listです。
認証の手間は2026年1月16日のリリースで減りました。/mcp listからワンクリックで認証でき、コールバックが自動処理されるため、認証直後からツールを呼べます。外部サービスと接続する前提のエージェントをCIで動かす場合、この認証がインタラクティブに走る点は設計上の制約になります。規格そのものの仕組みは関連記事のMCP解説に譲りますが、CI側では認証済みトークンを環境変数で渡せるサーバーを選ぶのが現実的です。
料金と使用量の数え方｜Pro・Pro Plus・UltraとAPIキー従量実行の切り分け
CLIはプランの上に乗る道具で、単体の値付けは公表されていません。判断材料はモデルの区分と従量課金の扱いです。
Pro20ドル・Pro Plus60ドル・Ultra200ドルとモデルプールの区分
モデルと料金のドキュメントが示す個人向けは、Pro 月20ドル、Pro Plus 月60ドル、Ultra 月200ドルの3段です（インド向けのStartプランは別建て）。モデルは2つのプールに分かれ、Cursor Models側にGrok 4.6・Grok 4.5・Composer 2.5が、Other Models側にOpenAIやAnthropicなど第三者のモデルが入ります。
| プラン | 月額 | Cursor Models | Other Models |
|---|---|---|---|
| Pro | 20ドル | 含む | 含む |
| Pro Plus | 60ドル | 含む | 含む |
| Ultra | 200ドル | 含む | 含む |
Other Models側はAPIレートでの課金が基準で、含まれる分を超えたら従量で足す構造です。プランごとの詳しい内訳や無料版との差はCursor Proとは｜料金プラン・無料版との違い・できることにまとめています。
CURSOR_API_KEYでの従量実行とチームへ配る際の費用の掴み方
CIで走らせる分は、人の席とは別の勘定になります。ワークフローから叩く場合はAPIキーでの認証になるため、誰が使ったかではなく、どのリポジトリのどのジョブが使ったかで積み上がる形です。夜間バッチでリポジトリ全体を舐めさせる設計にすると、想定より早く消費します。
公式の料金ページは、CLI単体の無料枠や月間の実行本数を数値で示していません。したがって稟議に載せる金額は、プラン単価に加えて「CIの実行回数×1回あたりの想定トークン」を自前で見積もる必要があります。実務では、最初の1か月を-pのみ（提案だけ）で回して消費量を測り、翌月から--forceを含む自動修正へ広げる進め方は、費用の読み違いを防ぐための手順です。エージェントを前提とした開発体制の設計から相談したい場合は、生成AI開発・AI受託開発で受けています。
Claude Code・Codex CLIとの違いとCursor CLIを見送る条件
ターミナル常駐のエージェントは複数あり、どれも似た機能一覧を持ちます。分かれるのは前提となる資産です。
Claude Code・Codex CLIとの守備範囲の違いと選び分け
Cursor CLIの強みは、エディタ側で育てたルールとMCP設定をそのまま引き継げる点にあります。.cursor/rulesを整備済みのチームなら、CLIを入れた日から同じ規約でコードが書かれる仕組みです。逆に、Cursorをエディタとして使っていない現場では、この利点が丸ごと消えます。
| 比較軸 | Cursor CLI | Claude Code |
|---|---|---|
| 主コマンド | agent | claude |
| 指示書 | .cursorとAGENTS.md | CLAUDE.md |
| 非対話実行 | -pと–force | -pと権限設定 |
| 前提資産 | エディタ側の設定 | CLI単体で完結 |
設計相談と長い調査が中心ならClaude Code側が扱いやすく、判断材料はClaude Codeとは？できること・使い方・料金とコード解析の実力にあります。OpenAI系の資産を持つならCodex CLIが候補です。3つを同時に契約する必要はありません。
Cursor CLIを採用しない条件｜席が無い現場と監査要件の壁
見送るべき条件を2つ挙げます。1つ目は、開発者がCursorのエディタ契約を持っていない現場です。CLIだけを目当てにPro 月20ドルを人数分契約しても、ルールもMCP設定も空の状態から始めることになり、他のCLIツールに対する優位が残りません。
2つ目は、実行ログの完全な保全を監査で求められる現場です。承認プロンプトは対話セッションの機能で、--forceを使うCIの経路には介在しません。誰の判断でどのファイルが変わったかを事後に再構成する仕組みは、別途組む前提になります。金融や医療のように変更管理が厳格な案件では、この不足がそのまま導入停止の理由になります。逆に、社内向けツールの保守や検証環境の整備であれば、この2条件に当たらない限り入れて損はないはずです。
よくある質問
導入前に問い合わせの多い点を、公式ドキュメントの記述に沿って答えます。
Cursorのエディタを入れていなくてもCLIだけ使えますか？
インストール自体はエディタと独立しており、スクリプト1本で導入できます。ただし実行にはアカウントとプランが必要で、ルールやMCP設定といったエディタ側の資産は引き継がれません。CLI単体で使う前提なら、Claude CodeやCodex CLIとの比較で決めたほうが判断を誤りにくい構成です。
cursor-agentコマンドは今も使えますか？
2026年1月8日のリリースでagentが主エントリになり、cursor-agentは後方互換のエイリアスとして残ると公式に明記されています。既存のスクリプトはそのまま動きますが、新しく書く分はagentに寄せてください。手順を共有する際は、どちらの名前で書いたかを明示しておくと混乱が減ります。
非対話モードで実行してもファイルが変わらないのはなぜですか？
-pは既定で提案を返すだけの動きで、ファイルには触れません。書き換えまで行わせるには--forceを足します。安全側に倒した設計のため、CIで「ログには出ているのに差分が無い」という現象が起きたら、まずこのフラグの有無を確認してください。
GitHub ActionsのAPIキーはどこで発行しますか？
Cursorのダッシュボードで発行し、リポジトリのSettingsからSecrets and variables、Actionsと進んでCURSOR_API_KEYの名前で登録します。GitHub CLIからシークレットを登録する方法も公式手順に記載があります。ワークフロー側ではenvで渡し、ログへ出力しない形にしてください。
WindowsではWSLとネイティブのどちらで入れるべきですか？
公式は両方の手順を示しています。手元の開発環境がWSL中心なら、Linux向けのインストールスクリプトをWSL側で実行するほうが、パス表記やシェル互換の面で揃います。PowerShellで完結させたい場合はネイティブ版で構いません。片方に決め、PATHを二重に通さないことだけ守ってください。
関連記事
- Cursorとは？AIコードエディタの機能・料金・使い方を開発会社が解説：エディタ側の機能と全体像です
- Claude Codeとは？できること・使い方・料金とコード解析の実力：比較相手となるCLIエージェントです
- Codexとは？OpenAIの自律型AIコーディングエージェントの使い方・料金・モデルを解説：OpenAI系の選択肢です
- Antigravity CLI（agy）の使い方｜Linux・SSHでの導入から実行モード・無料枠まで：別系統のCLIの導入手順です
- ghコマンド（GitHub CLI）とは？インストール方法と使い方・主要コマンド一覧：CI連携で併用するコマンドです
