Cursor Code CLIの使い方・モデル設定と導入前の確認点

Cursor Code CLIの正式な位置づけ

「Cursor Code CLI」は検索で使われる呼び方で、公式ドキュメントの見出しは「Cursor CLI」です。実際に端末から起動するコマンドはcursor-agentで、会話しながらコードを調べ、提案を確認し、必要な変更を進めます。CursorのデスクトップエディタにあるAgent機能をそのまま端末へ表示するというより、端末で使うために整理された別の入口と考えると分かりやすいでしょう。公式のCursor CLI概要も、端末からエージェントを使い、コードを書き、レビューし、変更する道具として説明しています。

もう一つ注意したいのが、Cursorのリポジトリ機能を扱うOrigin CLIとの混同です。Origin CLIはリポジトリの作成、取得、同期などを扱う別のコマンドで、端末のAIエージェントを動かすCursor Agent CLIとは役割が異なります。公式のOrigin CLIコマンド一覧にも両者は別の入口として説明されているため、検索結果で「Cursor CLI」を見つけたときは、コードを読むエージェントなのか、リポジトリを操作するCLIなのかを先に確認してください。

検索語のCursor Code CLIを公式名称に置き換える

記事や社内メモでは、最初に「検索語はCursor CLI、実行ファイルはcursor-agent」と書いておくと、後からコマンドを探しやすくなります。検索語をそのまま製品名だと決めつけると、Cursorのエディタ、Web版、Cloud Agents、Origin CLIの説明が混ざりやすいからです。公式ページへのリンクと実際のコマンドを同じ行に残し、どの入口を試したかを記録すると、別の端末で同じ確認をやり直すときにも役立ちます。

Cursor CLIを試す目的も一文で定めます。たとえば「既存リポジトリの構成を読む」「一つの関数の修正案を出す」「変更後のテスト結果を要約する」のように、最初から大きな実装を頼まないことが大切です。端末で動くことと、作業を最後まで任せられることは別の判定なので、入口、読み取り、変更、確認を分けて見ます。

なぜ今、端末版を見直すのか

2026年8月時点のCursor公式CLIページは、端末から使うエージェント、複数のモデル、MCP、Shell Mode、Headless CLIへの入口を一つにまとめています。Cursor CLIの公式ページでは、端末で同じエージェントを使う考え方と、モデルを選ぶ画面が案内されています。エディタに閉じた補助機能としてではなく、調査やレビューの入口として端末版を検討しやすい時期です。

また、Cursor公式Changelogには、2026年8月17日付で、サブエージェントを別の実行環境で扱う機能や、長く続く目的を与える機能などが案内されています。これはすべてがCursor CLIの機能だという意味ではありませんが、Cursor全体で「どこから依頼し、どの結果を確認するか」が広がっていることは示します。端末版を選ぶときも、エディタの見た目ではなく、作業の入口と確認方法を見る必要があります。

導入前に決める三つの境界

Cursor CLIは、入力した依頼に対してファイルを読み、必要に応じてコマンドを実行し、変更案を返します。便利さを先に求めると、意図より広いフォルダを読ませたり、確認前に変更を進めたりしやすいため、導入前に境界を三つ決めます。作業フォルダ、参照してよい情報、変更やコマンド実行を許す範囲です。

最初の課題は、空の練習用リポジトリか、変更を戻しやすいブランチで行います。既存の重要な設定や本番データを含む場所で、いきなり端末エージェントの権限を広げる必要はありません。Cursor公式のUsing Agent in CLIも、依頼文で「コードを書かない」と明示して結果を読む使い方を紹介しています。

どのフォルダを仕事場にするか

端末でcursor-agentを起動する場所は、依頼の文脈と結果の見え方を左右します。リポジトリのルートから始めれば全体を調べやすい一方、対象が広くなります。単一パッケージの修正なら、そのフォルダや検証用のコピーから始めるほうが、返ってきた差分を読みやすくできます。

依頼の最初に、対象、触れてよい範囲、触れない範囲、完了条件を一文ずつ書きます。「src/profileだけを調べ、変更はしない。関係するテスト名と原因候補を説明する」のようにすれば、読み取りの評価と変更の評価を分けられます。フォルダを広くしたい場合も、なぜ必要かを先に説明してもらうと判断しやすくなります。

アカウントとモデルの確認方法

ログインが済んでいるかと、どのモデルを使うかは別に確認します。ログインできたからといって、期待するモデルが選ばれているとは限りません。Cursor CLIのパラメータには--modelがあり、モデル名を明示して起動できます。利用できるモデルや利用量は契約や時期で変わるため、固定の金額や一覧を記事やメモに写すときは、Cursor公式のモデル・料金案内を同時に確認してください。

検証では、同じモデル名を指定したつもりでも、利用できるプラン、モデルの提供状況、アカウントの状態が異なる場合があります。結果を比べるなら、実行日、コマンド、表示されたモデル名、依頼文を残します。モデルの優劣を先に決めず、同じ条件で同じ作業をしたときに、説明の分かりやすさと差分の確認しやすさを見ます。

変更とコマンドをどこまで許すか

Cursor CLIは、ファイル操作やShellコマンドを扱えるため、読み取りだけの依頼と、変更を含む依頼を分けるのが安全です。対話モードでは、コマンド実行前に確認する流れを使い、変更を頼むときも対象ファイルを指定します。非対話のprintモードでは、--forceを付けると変更を許す設定になるため、公式のHeadless CLI資料を読んでから使います。

「動けばよい」ではなく、変更の前後を比較できる状態を作ります。作業前の差分を保存し、読み取り依頼、変更依頼、テスト実行の順に分け、最後に人が差分を確認します。広いフォルダで--forceを使うより、狭い範囲で一度提案を受けてから、必要な場合だけ許可を広げるほうが、原因を追いやすくなります。

インストールから初回起動まで

Cursor CLIの導入は、コマンドを貼り付けて終わりではありません。インストール先のOS、ログイン方法、起動するフォルダ、最初に出す依頼をそろえて確認します。公式ページに掲載された方法と、手元の端末で表示された版やメッセージが一致するかも記録しておくと、更新後の違いを説明しやすくなります。

導入の確認を「起動できた」で終わらせず、読み取りだけの依頼が通ること、現在のアカウントとモデルが分かること、変更前の差分を保てることまでを初回の到達点にします。この三つを先に見ておけば、後で機能を追加したときに、導入の問題と設定の問題を分けて考えられます。

Step 1: 公式の導入方法を確認する

Cursor公式CLIページには、シェルからインストールする例として次のコマンドが掲載されています。

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

この例がそのまま使えるかは、OS、シェル、権限、社内の端末ルールによって変わります。Windowsでは公式のCursor CLI導入案内から対象環境の手順を選び、表示された内容を確認してから実行してください。導入後はcursor-agent --versionまたはcursor-agent -vで、コマンドが解決されるかを見ます。

Step 2: ログイン状態を確認する

初回はブラウザを使うログインが基本です。公式認証ガイドにあるcursor-agent loginで認証画面を開き、完了後にcursor-agent statusで状態を確かめます。ログイン先が想定したアカウントか、利用できるモデルや契約が想定と一致するかを確認し、不要な端末ではcursor-agent logoutで状態を消します（出典: Cursor CLI認証公式ガイド）。

認証情報を端末間で手作業に貼り付ける必要はありません。APIキーを使う場合は、公式の認証方法と保管場所を読み、共有端末の履歴やログに残らない扱いにします。記事やチームのメモには実値を書かず、確認した方法と公式URLだけを残してください。

Step 3: 変更しない依頼で初回起動する

初回は次のように、構成を説明させるだけの依頼から始めます。

このリポジトリの構成を短く説明してください。ファイルは変更せず、最初に確認したディレクトリと実行したコマンドを示してください。

返答に、対象と関係のないフォルダが含まれていないか、変更が発生していないか、コマンド実行の確認が表示されたかを見ます。ここで問題がなければ、次に一つのファイルの説明、次に小さな修正案という順で進めます。初回起動を成功とみなす条件を「返答があった」だけにせず、フォルダ、モデル、操作範囲の三点まで確認してください。

基本操作：対話、print、resumeを使い分ける

Cursor CLIには、人が会話を見ながら進める使い方と、入力を渡して結果を端末へ出す使い方があります。両者は同じエージェントを使っていても、確認を入れる場所と、結果を保存する方法が異なります。最初は対話モードで挙動を読み、依頼が固まってからprintモードを試すと、設定の違いを把握しやすいでしょう。

どちらのモードでも、依頼文、使用モデル、出力、変更の有無を後から確かめられる状態にします。対話モードは判断を挟みやすく、printモードは同じ形式の結果を集めやすいという違いがあります。目的に合わないモードを選ぶと、返答が正しくても確認の手間が増えます。

対話モードで調査の順番を見る

引数なしのcursor-agentで起動すると、端末上で依頼を送り、返答や確認を見ながら次の指示を出せます。最初の依頼は「原因候補を挙げ、まだ変更しないでください」のように、調査と変更を分けます。返答を読んでから対象ファイルを追加し、必要ならテストの実行を一つずつ許可します。

対話モードのよさは、AIがどのファイルを読み、どのコマンドを提案したかをその場で確かめられる点です。依頼が広すぎる、前提を誤っている、関係のないファイルを見ているといった問題を、変更前に止められます。短い依頼を重ねるときも、各回の目的と完了条件を残すと、会話が長くなった後の見直しが楽になります。

printモードで結果の形式をそろえる

公式パラメータ一覧では、-pと--printが非対話の出力モードとして案内されています。人が端末で会話を続けるのではなく、依頼文を渡して、結果をtext、json、stream-jsonのいずれかで受け取るときに使います。読み取りだけなら、次のように変更を許す指定を付けずに試します。

cursor-agent -p --output-format text "このリポジトリのテスト構成を説明してください。ファイルは変更しないでください。"

printモードは結果を別の確認表へ渡しやすい一方、会話中に人が判断する機会が少なくなります。ファイル変更を伴う場合は、まず提案だけを返させ、差分と対象を読んでから、必要な場面だけ--forceを検討します。--forceは「品質を保証するスイッチ」ではなく、確認なしに変更を許すための指定です。

resumeで長い作業を再開する

Cursor CLIのセッションは、一覧を見たり、前回の会話を再開したりできます。公式資料にあるcursor-agent ls、cursor-agent resume、--resume [chatId]を使うと、最初から同じ説明を入力し直さずに済みます。再開前には、現在のブランチ、作業フォルダ、前回から変わったファイルを確認してください。

再開は過去の判断をそのまま正しいとする操作ではありません。依存パッケージ、モデル、作業対象が変わっていれば、前提も変わります。「前回の変更後に何が変わったかを確認し、まだ変更しない」と頼んでから続けると、古い文脈のまま修正が進むのを防げます。会話を再開できたことと、作業状態が同じことを分けて考えます。

ファイル、Shell、MCPを扱うときの確認点

端末エージェントの結果は、モデルだけでなく、どのファイルや設定を文脈に入れたかで変わります。Cursor CLI公式資料には、@によるファイル選択、ルール、MCP、Shellに関する入口が示されています。便利な設定を一度に全部有効にするより、ファイル参照、コマンド実行、外部接続をそれぞれ単独で確認したほうが、問題が起きたときの切り分けが早くなります。

特に、ファイルを読む操作と外部へ接続する操作は、同じ「便利な設定」としてまとめて扱わないでください。どの設定がどの結果に影響したかを残すため、最初は参照範囲を固定し、次にShell、最後にMCPという順で一つずつ有効性を見ます。

@で参照範囲を小さくする

Cursor CLIでは、依頼文からファイルやフォルダを指定する@の使い方が案内されています。リポジトリ全体を読ませる代わりに、まず関係する実装、テスト、設定の三つに絞り、「この三つ以外はまだ変更しない」と書きます。対象を広げる必要がある場合は、広げる理由と追加されたファイルを返答に含めてもらうと、文脈の増え方を追えます。

ファイルを指定しても、依存関係や設定が不足すれば、説明は不完全になります。最初の依頼で「不足している前提があれば、修正せずに列挙してください」と伝え、必要なファイルを一つずつ追加します。見せる量を増やすより、何を判断するための文脈かを明確にするほうが、短い会話でも結果を読みやすくします。

ルールファイルの読み込みを確認する

公式の利用ガイドでは、Cursor CLIが.cursor/rulesのルールを読み、プロジェクト直下のAGENTS.mdやCLAUDE.mdも適用対象として扱うことが説明されています（出典: Cursor CLI利用ガイド）。ここに書かれた方針が実際に読まれたかは、最初の依頼で「見つけたルールファイル名と要点を、まだ変更せずに示して」と確認できます。

ルールファイルに長い説明や古い手順が残っていると、返答の根拠が分かりにくくなります。対象、禁止事項、検証方法を短く保ち、機密性の高い値や個人の認証情報は置きません。ルールの更新前後で同じ読み取り依頼を出し、どの差が結果に表れたかを比べると、設定が効いているかを判断できます。

ShellとMCPは一つずつ確認する

Shellコマンドを使わせる場合は、コマンドの目的、対象、出力だけを確認し、破壊的な操作を避けます。ファイルの削除、外部への送信、広い範囲への書き込みを含む依頼は、端末エージェントにまとめて任せず、個別の確認を入れます。MCPを使う場合も、まず接続先の名前、読み取り可能な範囲、返ってくるデータの形を確かめてから、作業へ組み込みます。

公式ガイドでは、CLIがmcp.jsonの設定を検出し、IDEで使っているMCPサーバーを利用できると説明されています。設定があるだけで、接続先の内容や権限まで安全だと判断しないことが大切です。初回は「接続先を列挙するが、外部データの変更や送信はしない」と依頼し、実際の出力を確認します。

Codex CLIとの使い分け

Cursor CLIとCodex CLIは、どちらも端末でコードを扱えるため、コマンドの名前だけを比べると似て見えます。実際には、Cursor側のルール、モデル、ログイン状態を使うCursor CLIと、OpenAI側のモデル、設定、サンドボックス、承認方針を使うCodex CLIです。OpenAIのCodex CLI公式資料とCodex公式リポジトリを読み、製品ごとの設定を混ぜないようにします。

Cursor CLIを選ぶ場合

すでにCursorのエディタやルールを使っていて、その文脈を端末でも使いたいなら、Cursor CLIから試すと準備が少なく済みます。cursor-agentで対話し、必要なファイルを@で示し、同じモデル選択の考え方で短い修正やレビューを進められます。Cursorの公式ページが示すように、MCPやShellにも入口があるため、既存のCursor環境を端末へ広げたい人に向きます。

ただし、Cursorのエディタ画面を開かずに使えることと、すべての機能が同じ表示になることは別です。モデルの一覧、利用量、ルールの適用、差分の確認場所は、CLIの表示を基準に見ます。エディタで見える結果を端末にも同じ形で期待せず、まず一つの課題で実際の出力を確認してください。

Codex CLIを選ぶ場合

OpenAIのモデルを中心に、ターミナルでリポジトリの調査、複数ファイルの変更、テストの実行までを一つの作業として進めたいなら、Codex CLIが候補になります。公式資料ではcodexで対話し、codex execで非対話の実行を行う入口が案内されています。config.toml、モデル、推論の深さ、サンドボックス、承認方針を自分の作業に合わせて設定できる点も特徴です。

Codex CLIの導入方法や認証は、Cursor CLIとは別に確認します。OpenAIの認証ガイドと設定リファレンスを基準にし、Cursorの環境変数や設定ファイルをそのまま流用しないでください。どちらも端末からファイルを扱えるからこそ、ログイン状態、モデル名、変更許可を製品別に記録することが重要です。

同じ課題で比べる

比較するときは、製品ごとに別の大きな課題を渡さないことが大切です。単一ファイルの読み取り、原因候補の説明、小さなテスト追加という三つを、同じリポジトリの同じ状態から始めます。指示文を同じ意味にそろえ、モデル名、版、実行時間、変更ファイル、テスト結果、最終確認にかかった時間を残します。

この表は優劣を決めるものではなく、確認場所をそろえるためのものです。Cursor CLIで得たセッションや設定をCodex CLIへ引き継げるわけではありません。結果を比べるときも、返答の印象だけでなく、変更が狭いか、根拠を説明できるか、テストを再現できるかまで見ます。

小さなタスクで自分に合うか確かめる

Cursor Code CLIを導入するか迷うときは、機能一覧を読むより、短い課題を同じ条件で試すほうが判断しやすくなります。目的は最も長い依頼を成功させることではなく、どの場面で人の確認が楽になり、どの場面で手戻りが増えるかを知ることです。結果を後から読み直せるように、依頼文と差分を保存します。

次の順番で試します。

1. 変更のないリポジトリを用意し、作業フォルダと現在の差分を記録する。
2. 構成説明だけを頼み、参照したファイルと実行したコマンドを確認する。
3. 一つの関数について、修正案だけを求め、まだファイルを変更しない。
4. 変更範囲と完了条件を指定して、テストを一つ追加する。
5. 差分、テスト結果、返答の根拠を人が読み、次に使う設定を決める。

記録する項目

最低限、実行日、製品名、CLIの版、ログイン方法、モデル名、依頼文、作業フォルダ、変更ファイル、実行したテスト、結果を記録します。Cursor CLIでは--output-format textの出力を保存し、Codex CLIでは対話の要約と差分を保存すると、返答の形式が違っても比べやすくなります。利用量を確認できる画面がある場合は、画面に表示された値をそのまま写し、推測で料金へ換算しません。

記録には「確認できた」「確認できない」「次に確認する」の三つの欄を置きます。たとえば「指定したモデルが表示された」は確認できた事実ですが、「このモデルが常に最も安い」は別の調査です。事実と評価を同じ欄に混ぜないことで、モデルや料金が更新された後も記録を再利用できます。

結果の読み方

短い課題で比べるときは、返答が長いかどうかより、必要な根拠がそろっているかを見ます。対象ファイルを正しく読んだか、変更範囲が依頼どおりか、テストが成功したか、失敗時に次の確認を説明したかが主要な判定です。返答が速くても、前提を誤っていれば再作業が増えます。

逆に、最初の返答が慎重で、追加の確認を求める場合もあります。それは使いにくさではなく、作業範囲や許可が不足している合図かもしれません。Cursor CLIとCodex CLIのどちらを選ぶ場合も、確認の回数をゼロにするのではなく、重要な確認を短く保てるほうを選ぶと、長期的な使いやすさにつながります。

よくある詰まりと切り分け

端末エージェントの問題は、コマンドが見つからない、ログインできない、モデルが選べない、変更が適用されない、結果が大きすぎるという層に分けると見通しがよくなります。いきなり再インストールや設定の全削除をせず、表示されたメッセージ、版、作業フォルダ、実行した引数を記録してから一つずつ確認します。

切り分けの記録には、問題が起きた時刻、直前に変えた設定、再現する最小の依頼も加えます。同じ症状でも、導入直後なのか、モデルを変更した後なのか、前回の会話を再開した後なのかで原因が変わるためです。まず事実を固定し、次に公式資料の該当箇所と照らし合わせます。

コマンドが見つからない場合

cursor-agentが見つからないときは、導入が完了したか、実行ファイルの場所がPATHに含まれているか、別のシェルを開いていないかを確認します。まずcursor-agent --versionを実行し、次に公式の導入案内と手元のインストール結果を照合します。別名のcursorやOrigin CLIを実行していないかも見ます。

更新後だけ失敗する場合は、以前の実行ファイルが残っていないか、シェルのキャッシュが古くないかを確認します。複数の導入方法を重ねると、表示される版と実際に呼ばれる版がずれることがあります。環境を変更する前に、現在の実行ファイルの場所と版を残しておくと、戻すべき対象を誤りません。

ログインやモデル指定で止まる場合

ログイン画面が開かない場合は、cursor-agent loginを実行した端末とブラウザが同じアカウントを見ているか、ブラウザの完了後に端末へ戻ったかを確認します。状態はcursor-agent statusで見て、アカウントや利用可能なモデルを決めつけません。認証の問題とモデルの問題を別の依頼で確認すると、切り分けやすくなります。

モデル指定でエラーになる場合は、--modelの綴り、利用できるモデル名、契約上の利用可能範囲を公式のモデル案内で確認します。以前のメモにあるモデル名が現行の端末で使えるとは限らないため、エラーメッセージを省略せずに残します。Codex CLIを併用している場合も、片方のモデル名をもう片方の引数へ移さないでください。

変更が適用されない場合

対話モードで承認を待っている、printモードで--forceを付けていない、作業フォルダが想定と違う、ルールが変更を制限している、といった原因があります。まず「変更しないで説明する」依頼で対象を確認し、次に一つのファイルへ限定した変更案を求めます。変更が必要だと判断できた場合だけ、公式資料に沿って許可範囲を調整します。

変更後は、エージェントの返答だけでなく、実際の差分とテスト結果を確認します。変更がないこと自体が失敗とは限りません。対象が見つからない、条件を満たす修正が不要、実行前の許可が不足しているという情報かもしれないため、返答に理由が書かれているかを読みます。

結果が大きすぎる場合

対象ファイルを@で絞り、出力形式をtextにし、要約の長さと必要な項目を指定します。「すべて説明して」ではなく、「原因候補を三つ、根拠ファイルと確認コマンド付きで示す」のように頼むと、次の判断に必要な情報だけを受け取りやすくなります。長い会話を再開する場合は、前提を短くまとめてから続けます。

結果が短すぎる場合は、モデルをすぐ変更する前に、対象、期待結果、再現方法、テストの場所を追加します。端末エージェントは不足した前提を推測するため、強い設定だけで情報不足を埋めることはできません。必要な文脈を追加し、それでも不足する箇所だけを別の依頼に分けるのが基本です。

まとめ：入口を固定し、確認できる仕事から任せる

Cursor Code CLIとして検索される対象は、公式名称ではCursor CLI、実行コマンドではcursor-agentです。最初にOrigin CLIと分け、アカウント、作業フォルダ、モデル、変更許可を確認してから、読み取りだけの依頼を実行します。対話モードで挙動を読み、-pや--printは結果の形式をそろえたいときに使い、--forceは変更範囲を確認した後に限定して検討します。

Codex CLIと比べる場合は、同じ課題、同じ条件、同じ確認項目で試します。Cursor側のルールやモデル入口を重視するのか、OpenAI側の設定やサンドボックスを重視するのかで、選びやすい入口は変わります。大きな実装をいきなり任せるのではなく、構成説明、小さな修正、テスト確認の順で、差分と根拠を読める範囲から始めることが、端末エージェントを長く使うための最短ルートです。