# iTerm2

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-6e55e9f09cf011f6e50402da3fd79342b5162668%2FKeeper%2BiTerm2.png?alt=media" alt=""><figcaption></figcaption></figure>

iTerm2のPassword ManagerにKeeper Securityを組み込んで利用できます。本連携は、[Keeperコマンダー](https://docs.keeper.io/jp/keeperpam/commander-cli)を[サービスモード](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api)で起動したインスタンスのREST APIと通信します。サービスは**ローカル** (例: お使いのMac上) で実行するか、**トンネル** (例: Ngrok / Cloudflare) 経由で公開できます。APIキーとサービスURLはmacOSのキーチェーンに保存され、キーは環境が許す場合はTouch ID / Face IDまたはデバイスのパスコードで保護されます。API URLはiTerm2の設定 (ユーザーデフォルト) に保存されます。

### 機能 <a href="#features" id="features"></a>

* **ボルトレコードの一覧** — **\[Password Manager]** の画面からKeeperのボルトを参照・検索
* **パスワードの取得** — ターミナル上のプロンプト (例: SSH、sudo、ログイン) へパスワードを送信
* **ユーザー名の取得** — **\[Enter username]** 選択時にレコードのログインフィールドを送信
* **パスワードの編集** — iTerm2からレコードのパスワードを更新
* **レコードの追加と削除** — **\[Password Manager]** からログインレコードの新規作成・削除
* **安全な保存** — APIキーはmacOSのキーチェーンに保存。利用可能な場合はデータ保護付きキーチェーン (Touch ID / Face IDまたはパスコード) を利用。API URLはユーザーデフォルトに保存
* **同期** — アダプターの設定シートで接続テストおよびボルトレコードの同期

{% hint style="info" %}
KeeperコマンダーのサービスモードのセットアップとAPIの詳細は、[サービスモードREST API](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api)のドキュメントをご参照ください。
{% endhint %}

### 要件 <a href="#prerequisites" id="prerequisites"></a>

**Keeperコマンダーの要件**

| 要件          | 説明                                                                                                                |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| Keeperコマンダー | [インストール済み](https://docs.keeper.io/jp/keeperpam/commander-cli/commander-installation-setup)でログイン済み                 |
| サービスモード     | REST API (v2) を有効にした [サービスモード](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api)でコマンダーが動作中 |
| APIキー       | サービスを作成または構成するときに生成されるAPIキー (例: `service-create` による発行)                                                           |
| 許可コマンド      | サービス構成でiTerm2が使用するコマンドを許可。`ls`、`get`、`record-update`、`record-add`、`rm`、`sync-down`および環境で使うエイリアス                   |

**iTerm2の要件**

* Keeper SecurityのPassword Manager連携を含むiTerm2のビルド
* macOS 12以降

### 構成 <a href="#configuration" id="configuration"></a>

iTerm2では次の2つの値が必要です。いずれも **\[Keeper Security Settings]** で指定します。**\[Password Manager]** で **\[Keeper Security]** を選ぶと当該設定が開きます。

| 設定          | 説明                                                                                                                                                                                                                                             |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API URL** | <p>KeeperコマンダーサービスのベースURL。末尾に <code>/api/v2/</code> を含む。<br><strong>ローカル</strong>の例: <code><http://127.0.0.1:8900/api/v2/></code><br><strong>トンネル</strong>の例: <code><https://your-subdomain.ngrok.io/api/v2/></code> またはCloudflareトンネルのURL</p> |
| **API Key** | Keeperコマンダーのサービスモード構成で発行したAPIキー                                                                                                                                                                                                                |

{% hint style="info" %}
**注:** API URLには `/api/v2/` を含めてください。iTerm2はv2 (非同期) APIを使用します。ローカルサービスでは `http`、トンネル経由では `https` を使用してください。
{% endhint %}

### セットアップ手順 <a href="#setup-guide" id="setup-guide"></a>

**手順1: Keeperコマンダーのサービスモードを開始する**

1. [Keeperコマンダー](https://docs.keeper.io/jp/keeperpam/commander-cli/commander-installation-setup)をインストールしてログインします (例: `keeper shell` のあと生体認証または永続ログイン)。
2. iTerm2が利用するコマンドを含めてサービスを作成し、起動します。

   **ローカル (このマシンのみ):** ポート8900、localhostにバインドする例。

   ```bash
   service-create -p 8900 -f json -aip 127.0.0.1 -c 'ls,get,record-update,record-add,rm,sync-down'
   ```

   **トンネル (NgrokまたはCloudflare):** [サービスモード](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api)のドキュメントに記載のオプション (例: `-ng`、`-cf`) を指定し、パブリックURLからサービスへ到達できるようにします。iTerm2の**API URL**は、そのトンネルURLに`/api/v2/`を付与したURLになります。

   コマンド一覧に `ls`、`get`、`record-update`、`record-add`、`rm`、`sync-down` が含まれていることを確認してください。
3. 構成後に表示される**APIキー**をメモするか、ボルト内のサービスモード用レコードから読み取ります。
4. サービスがすでに構成済みの場合は、次のコマンドで起動します。

   ```bash
   service-start
   ```
5. 指定する**API URL** (ローカルなら例: `http://127.0.0.1:8900/api/v2/`、トンネルなら例: `https://your-subdomain.ngrok.io/api/v2/`) にアクセスし、サービスが応答することを確認します。

**手順2: iTerm2を構成する**

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-47f813a58d56d747e04e540f80d776ffbef9a9d2%2Fimage%20(258)-ja.png?alt=media" alt=""><figcaption></figcaption></figure>

1. iTerm2で **\[Password Manager]** を開きます (メニューまたはショートカット)。
2. データソースを **\[Keeper Security]** に設定します。
3. 以下を入力します。

   * **API URL:** KeeperコマンダーサービスのURL (ローカルの例: `http://127.0.0.1:8900/api/v2/`、トンネルの例: `https://your-subdomain.ngrok.io/api/v2/`)。

   <figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-803d3c77fa253a31e688b2fd01ebcc363efe6884%2Fimage%20(255)-ja.png?alt=media" alt=""><figcaption></figcaption></figure>

   * **API Key:** 手順1で取得したAPIキー

   <figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-e7b3b54300ce0234616b4f005fbeb9661ee809e7%2Fimage%20(257)-ja.png?alt=media" alt=""><figcaption></figcaption></figure>
4. **\[Ok]** をクリックして接続をテストし、必要に応じて同期します。接続すると認証情報はキーチェーンに保存されます。

**手順3: Password Managerを使う**

* **アカウントの取得:** **\[Password Manager]** にボルトのレコードを一覧表示 (`ls -R -l`の結果に基づく)。フィルターで検索可能
* **パスワードの入力:** レコードを選び、**\[Fill Password]** (または同等) でターミナルへパスワードを送信
* **ユーザー名の入力:** **\[Enter username]** でログイン値のみを送信
* **パスワードの更新:** 新パスワードの設定およびiTerm2による `record-update` の実行 (新しい値の送信)
* **追加 / 削除:** **\[Password Manager]** の画面からログインレコードの追加・既存レコードの削除

#### クイックスタートの概要 <a href="#quick-start-summary" id="quick-start-summary"></a>

1. Keeperコマンダーのサービスモードを開始します (ローカルまたはトンネル)。ローカルの例: `service-create -p 8900 -f json -aip 127.0.0.1 -c 'ls,get,record-update,record-add,rm,sync-down'` のあと、必要なら `service-start` を実行します。
2. iTerm2 → **\[Password Manager]** → **\[Keeper Security]** の順に選ぶと、API URLのダイアログが表示されます。
3. **API URL**にサービスURLを入力します (ローカルなら例: `http://127.0.0.1:8900/api/v2/`、トンネルなら `/api/v2/` 付きのトンネルURL)。**\[Ok]** をクリックすると**API Key**のダイアログが続くので、サービスモードのAPIキーを入力し、**\[Ok]** をクリックします。
4. **\[Password Manager]** でレコードの一覧、入力、更新、追加、削除を行います。

### セキュリティのベストプラクティス <a href="#security-best-practices" id="security-best-practices"></a>

| 項目                   | 説明                                                                            |
| -------------------- | ----------------------------------------------------------------------------- |
| ローカルではlocalhostにバインド | ローカル利用時は `-aip 127.0.0.1`。コマンダーAPIを自マシンからのみ到達可能に                              |
| トンネルではHTTPSを使う       | Ngrok / CloudflareのトンネルURLはHTTPS。URLの秘匿とアクセス主体の制限                             |
| コマンドを必要最小限に          | iTerm2が必要とするコマンドのみ許可。`ls`、`get`、`record-update`、`record-add`、`rm`、`sync-down` |
| キーチェーンへの保存           | APIキーとURLはmacOSのキーチェーンに保存。可能ならデータ保護付きキーチェーン (Touch ID / Face IDまたはパスコード) を利用  |
| 信頼できる環境              | コマンダーのサービスモードは信頼できるマシンで実行。リモート利用時はアクセス制御付きトンネル                                |
| トークンの有効期限            | コマンダーのサービス構成でAPIキーの有効期限を任意設定し、定期的なキーローテーション                                   |

### トラブルシューティング <a href="#troubleshooting" id="troubleshooting"></a>

**よくある問題**

| 現象                                             | 原因                                | 対処                                                                                                                                  |
| ---------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **API URL is required**                        | iTerm2にAPI URLが未保存                | **\[Keeper Security Settings]** を開き、API URLを設定 (ローカルまたはトンネル。例: `http://127.0.0.1:8900/api/v2/`または`https://your-tunnel-url/api/v2/`) |
| **Connection / “Could not connect to Keeper”** | サービス未起動、URL誤り、またはAPIキーが無効         | コマンダーサービスの稼働、URLに `/api/v2/` が含まれること、APIキーとサービス構成の一致を確認。トンネル利用時はトンネルの有効性と到達性を確認                                                     |
| **No records listed**                          | 未同期、キー誤り、またはコマンドが未許可              | “ok” (同期) を実行。サービスのコマンド一覧に`ls`および (同期する場合は) `sync-down` が含まれることを確認                                                                  |
| **Password or login not filled**               | レコードにパスワード / ログインがない、または`get`が未許可 | レコード種別にパスワード / ログインがあること、そのAPIキーで `get` が許可されていることを確認                                                                               |
| **Touch ID / Keychain prompt**                 | 初回利用または再起動後                       | プロンプトに従いTouch IDまたはMacのパスワードで解除。APIキーはデータ保護付きキーチェーンから読み取り                                                                           |

**サービスとURLの確認**

1. コマンダーサービスが動いていることを確認します (例: コマンダーシェルで `service-status`)。
2. 到達性の確認: ローカルなら `curl http://127.0.0.1:8900/health`、トンネルならブラウザまたは `curl` でトンネルのベースURLに `/health` を付与したURLを開く。
3. iTerm2のAPI URLに `/api/v2/` が含まれることを確認します (ローカルなら例: `http://127.0.0.1:8900/api/v2/`、トンネルなら例: `https://your-tunnel-host/api/v2/`)。

**iTerm2のKeeper構成をリセットする**

保存した認証情報を消して最初からやり直す場合は、以下を実施します。

1. **\[Password Manager]** を開き、**\[Keeper Security]** を選びます。
2. **\[Password Manager]** のデータソースに対して **\[Reset Keeper Security configuration]** を実行します。

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-5591e83dad188d6969066b9820f46f702061b879%2Fimage%20(261)-ja.png?alt=media" alt=""><figcaption></figcaption></figure>

3. **\[Keeper Security]** を選んだあとに表示される設定で、API URLとAPIキーを再入力し、**\[Ok]** をクリックします。

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-0269f6f08981d8b0849fbfa1afb122ec37c3a6bd%2Fimage%20(2)-ja.png?alt=media" alt=""><figcaption></figcaption></figure>

4. **\[Keeper Security]** を選んだ状態で **\[Password Manager]** の **\[Sync Down]** を実行し、ボルト一覧をKeeperの内容に同期します。

#### 参考資料 <a href="#references" id="references"></a>

* [Keeperコマンダーのインストールとセットアップ](https://docs.keeper.io/jp/keeperpam/commander-cli/commander-installation-setup)
* [サービスモードREST API](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api)
* [APIの利用](https://docs.keeper.io/jp/keeperpam/commander-cli/service-mode-rest-api/api-usage)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/jp/keeperpam/secrets-manager/integrations/iterm2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.