やす研究所 AI Lab
戻る

Cursor CLIをターミナルで使い倒す手順2026:agent -pとPlanモード実践

Cursor CLIをターミナルで使い倒す手順2026:agent -pとPlanモード実践

IDE を開かずにターミナルからエージェントを走らせたい。SSH 越しのサーバーで直接コードを直したい。CI から呼び出したい。そんな用途にドンピシャで刺さるのが Cursor CLI です。

私は先週、Astro 製の個人サイトのリファクタリングをまるっと Cursor CLI 側に寄せてみました。結論から言うと、エディタを開くのは最終レビューだけで済む場面が想像以上に多かったんです。

この記事では、2026年1月の大型アップデート以降の Cursor CLI の使い方を、インストールから agent -p のヘッドレス実行、Plan/Ask モード、GitHub Actions 連携までまとめて解説します。

結論:Cursor CLI は「エディタを開かない Cursor」

まず全体像から。Cursor CLI はエディタ画面を持たない Cursor エージェントで、シェルから直接叩けます。用途を一言で言うなら、インタラクティブ編集は IDE、自動化と長時間実行は CLI という棲み分けです。

公式ドキュメントでも、CLI はエディタを置き換えるものではなく補完する位置づけとされています。ターミナルで agent と打てばエージェントが起動し、スラッシュコマンドでモデル切替や MCP、ルールを操作できる、というのが基本形。

私が2週間使って便利だと感じたのは次の3パターンでした。

この3つを回すだけで、IDE の起動回数がだいぶ減りました。正直、これは思ったより効きます。

5分でインストール:agent コマンドの最短セットアップ

まずはインストール。macOS / Linux ならワンライナーで入ります。

curl https://cursor.com/install -fsS | bash

入ったらシェルを開き直して agent と打つだけ。2026年1月のアップデートで cursor-agent から agent がプライマリコマンドに変わりました。旧コマンドも一応残っていますが、これから覚えるなら agent で統一しておくのが無難です。

Windows は WSL 経由が現実解

Windows ユーザーは素の PowerShell ではなく WSL2 上で動かすのが現実的です。Ubuntu 22.04 あたりに上のワンライナーを流せば、macOS とほぼ同じ体験になります。ネイティブ Windows 対応は執筆時点で発展途上なので、無理をせず WSL に寄せた方が沼が浅いです。

認証は Cursor アカウントの OAuth

初回起動時にブラウザが開き、Cursor アカウントにサインインします。Pro プランのクレジットがそのまま CLI 側でも消費される仕組みなので、既に Cursor を使っている人は追加課金なしで始められます。

Plan/Ask モードで暴走を防ぐ:2026年1月アップデートの主役

従来の CLI はいきなり書き換えに走る挙動が目立ちましたが、2026年1月のアップデートで Plan モードと Ask モードが正式に CLI に降ってきました。ここが今回の目玉です。

Cursor 公式フォーラムの1月16日のリリース告知によると、この更新でエージェントモード(Plan と Ask)、バックグラウンドタスクへの Cloud handoff、そしてワンクリックでの MCP 認証が CLI 側で使えるようになりました。

実務での使い分けは、私の場合こんな感じに落ち着きました。

特に Plan モードは、大きめのリファクタで効きます。いきなり10ファイル書き換えられて後戻りできなくなる事故を、一段階噛ませることで避けられるんですよね。

モード切替は起動後にスラッシュメニューから、あるいは /plan /ask のようにコマンドで直接指定できます。

agent -p でヘッドレス実行:CI とスクリプトに組み込む

CLI の真骨頂は非対話モードです。agent -p "..." の形で叩くと、UI なしでプロンプトを一発実行し、標準出力に結果を返します。

# 現在のブランチをレビューさせる
agent -p 'main との差分をレビュー。セキュリティとパフォーマンスに絞って指摘' \
  --output-format text

# JSON で受け取ってスクリプトから処理
agent -p 'このリポジトリの依存関係の脆弱性を洗い出せ' \
  --output-format json

--output-format には text(デフォルト)・json・stream-json の3つが用意されています。他プロセスにパイプしたいときは JSON、CI のログにそのまま出したいときは text が扱いやすいです。

ハマりどころ:TTY が無いと固まる

一つ大きな罠があります。CLI は実 TTY を要求するので、subprocess から素朴に呼ぶと 無限に固まります。私は最初これを知らず、GitHub Actions のジョブが30分タイムアウトするまで気づきませんでした。

対策は --force フラグと CURSOR_API_KEY 環境変数の組み合わせです。CI から呼ぶときは必ずこの形にします。

# .github/workflows/review.yml (抜粋)
- name: Cursor Agent Review
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  run: |
    agent -p 'PR の変更点をレビューし、指摘を Markdown で出力' \
      --output-format text \
      --force > review.md

--force を付けると確認プロンプトをすべてスキップして走ります。無人環境では必須ですが、逆に言えば人の目が入らないので、リポジトリへの書き込み権限は最小に絞っておくのが安全です。

MCP とルールを CLI から扱う3つの技

CLI 側でも、IDE と同じ MCP サーバーとルールがそのまま使えます。ここが Claude Code や他のターミナルエージェントに対する Cursor CLI の強みだと感じています。

1. mcp.json は自動読み込み

プロジェクトルート、あるいはグローバル設定の mcp.json は CLI 起動時に自動でロードされます。IDE で GitHub や Context7 の MCP を設定済みなら、CLI 側で追加設定は不要。同じサーバーがそのまま繋がります。

2026年1月のアップデートで ワンクリック MCP 認証が入ったので、OAuth 系のサーバーも /mcp からブラウザ経由でトークンを取れます。以前は環境変数を手で貼る必要があったのが、拍子抜けするほど簡単になりました。

2. /rules で .mdc を直接編集

CLI 上から /rules を叩くと、.cursor/rules/*.mdc の一覧が出て、その場で編集できます。SSH 先で急にコーディング規約を追加したくなったとき、エディタを開かず直せるのは地味に効きます。

3. モデルはタブごとに切り替えて A/B

ターミナルタブを3つ開き、それぞれ別のモデル(例:Composer / Claude Opus 4.x / GPT-5.x)でエージェントを起動し、同じディレクトリに同じ指示を出す。これで3通りの実装がパラレルに出てくるので、diff を見比べて一番良いものだけ採用する、という運用ができます。

IDE でもチャットを分ければ似たことはできますが、ターミナルに並べた方が「同時進行している」感が視覚的にわかりやすい。私はこれで、モデル選定の議論をだいぶ具体的にできるようになりました。

Cloud handoff で長時間タスクを裏に逃がす

1月アップデートのもう一つの目玉が Cloud handoff。長時間走りそうなタスクをローカルからクラウド側の Background Agent に投げ直せる機能です。

手元のシェルで走らせていたエージェントを、/cloud 系のコマンドで裏に回して、続きはブラウザや iOS アプリから確認する、というフロー。ラップトップを閉じても走り続けるので、外出前に大物のリファクタを投げておく使い方が便利でした。

ただしクラウド側は Background Agent のクレジット消費になるので、ローカル完結より若干コストが乗ります。ローカルで15分以上かかりそうな作業だけ Cloud に逃がす、くらいの線引きが実務では丁度いいと感じました。

JetBrains ユーザーにも道はある:ACP 経由の連携

チームに JetBrains 派がいて Cursor に一本化できない、というケースは多いはず。ここについては、Cursor エージェントが Agent Client Protocol(ACP)経由で IntelliJ や PyCharm 側から呼び出せるようになっています。

つまり CLI を入れておけば、IDE は JetBrains のまま、エージェントだけ Cursor というハイブリッドが組めるということ。Windsurf は40以上の IDE にプラグインを提供する広さで勝負していますが、Cursor CLI + ACP という別ルートで JetBrains 対応の穴は徐々に埋まってきています。

まとめ:今日からやる4つのアクション

ここまでの内容をアクションに落とすと、今日からやることは4つです。

  1. curl https://cursor.com/install -fsS | bash で CLI を入れて agent を起動
  2. まずは /ask モードで自分のリポジトリを質問攻めにして挙動を掴む
  3. 慣れたら agent -p '...' --output-format text を Makefile やシェルスクリプトに1本組み込む
  4. GitHub Actions から呼ぶときは --force と CURSOR_API_KEY を必ずセットにする

エディタで完結させていた作業のうち、2〜3割はターミナル側に寄せられるはずです。私も最初は半信半疑でしたが、SSH 越しの小修正をエディタなしで終えられた瞬間、体感がガラッと変わりました。

まずは Ask モードで安全に触ってみて、慣れたら Plan、そして -p でのヘッドレス化。この順で進めるのが事故が少なくておすすめです。

参考リンク

この記事をシェア:
X で共有 Facebook で共有 Telegram で共有
次の記事
Claude Code 暴走対策2026:/forkとsubagent上限で無限ループを止める設定