# iTerm2

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FfollKOWWqjH5MDIi3g0A%2FKeeper%2BiTerm2.png?alt=media&#x26;token=a887544e-a14a-4740-a893-fad090581ccb" alt=""><figcaption></figcaption></figure>

This integration allows you to use Keeper Security as the password manager inside iTerm2. The integration talks to [Keeper Commander](https://docs.keeper.io/en/keeperpam/commander-cli) running in [Service Mode](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api).&#x20;

You can run the service **locally** (e.g. on your Mac) or expose it via **tunneling** (e.g. Ngrok or Cloudflare). Your API key and service URL are stored in macOS Keychain; the API key can be protected by Touch ID, Face ID, or device passcode when available. and the API URL in iTerm2’s preferences (user defaults).

#### Features

* **List vault records** — Browse and search your Keeper vault from the iTerm2 Password Manager window.
* **Fetch password** — Fill passwords into the terminal (e.g. SSH, sudo, or login prompts).
* **Fetch username** — Sends the record’s login field  when you choose “Enter username”.
* **Edit password** — Update a record’s password from iTerm2.
* **Add and delete records** — Create new login records or remove them from the Password Manager.
* **Secure storage** — API key are stored in macOS Keychain; API key uses data-protection Keychain (Touch ID/Face ID or passcode) when available. And API URL is stored in user default.
* **Sync** — Test connection and sync vault records from the adapter settings sheet.

{% hint style="info" %}
For Keeper Commander Service Mode setup and API details, see the [Service Mode REST API](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api) documentation.
{% endhint %}

#### Prerequisites

**Keeper Commander Requirements**

| Requirement      | Description                                                                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keeper Commander | [Installed](https://docs.keeper.io/en/keeperpam/commander-cli/commander-installation-setup) and logged in.                                           |
| Service Mode     | Commander running in [Service Mode](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api) with the REST API (v2) enabled.         |
| API key          | API key generated when you create or configure the service (e.g. via `service-create` )                                                              |
| Allowed commands | Service config must allow the commands iTerm2 uses: `ls`, `get`, `record-update`, `record-add`, `rm`, `sync-down` (and any aliases your setup uses). |

**iTerm2 Requirements**

* iTerm2 build that includes the Keeper Security password manager integration.
* macOS 12 or later.

#### Configuration

iTerm2 needs two values. Both are set in **Keeper Security Settings** (opened from the Password Manager when Keeper Security integration is selected):

| Setting     | Description                                                                                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API URL** | Base URL of the Keeper Commander service, including `/api/v2/`. **Local:** e.g. `http://127.0.0.1:8900/api/v2/`. **Tunneling:** e.g. `https://your-subdomain.ngrok.io/api/v2/` or your Cloudflare tunnel URL. |
| **API Key** | The API key from your Commander Service Mode configuration.                                                                                                                                                   |

{% hint style="info" %}
**Note:** Use `/api/v2/` in the API URL. iTerm2 uses the v2 (asynchronous) API. Use `http` for local services and `https` when using a tunnel.
{% endhint %}

#### Setup Guide

**Step 1: Start Keeper Commander Service Mode**

1. Install and log in to [Keeper Commander](https://docs.keeper.io/en/keeperpam/commander-cli/commander-installation-setup) (e.g. `keeper shell` then biometric or persistent login).
2. Create and start the service with commands that iTerm2 needs.

   **Local (this machine only):** Example with port 8900, bind to localhost:

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

   **With tunneling (Ngrok or Cloudflare):** Use the options from the [Service Mode](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api) docs (e.g. `-ng`, `-cf`) so the service is reachable at a public URL. Your API URL in iTerm2 will be that tunnel URL plus `/api/v2/`.

   Ensure the command list includes: `ls`, `get`, `record-update`, `record-add`, `rm`, and `sync-down`.
3. Note the **API key** printed after configuration (or read it from the Commander Service Mode record in your vault).
4. If the service is already configured, start it with:

   ```bash
   service-start
   ```
5. Confirm the service is reachable at your **API URL** (local, e.g. `http://127.0.0.1:8900/api/v2/`, or tunnel URL, e.g. `https://your-subdomain.ngrok.io/api/v2/`).

**Step 2: Configure iTerm2**

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fp0TrU0m8PlyMv0ukTXHF%2Fimage.png?alt=media&#x26;token=b4cc54cb-31d5-4fbc-94eb-1b22a744c038" alt=""><figcaption></figcaption></figure>

1. In iTerm2, open **Password Manager** (e.g. from the menu or shortcut).
2. In the password manager window, set the data source to **Keeper Security**.
3. Then Enter:

   * **API URL:** Your Commander service URL (local, e.g. `http://127.0.0.1:8900/api/v2/`, or tunnel, e.g. `https://your-subdomain.ngrok.io/api/v2/`).

   <figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FF5IKngxE1cvTFjTBpkJ6%2Fimage.png?alt=media&#x26;token=f6a5f53a-3131-425c-9a75-8f62feec0e8a" alt=""><figcaption></figcaption></figure>

   * **API Key:** Then enter the API key from Step 1

   <figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fxiv1zj5yo0nXs7TkjkIX%2Fimage.png?alt=media&#x26;token=afb74b7b-4258-49fa-b8b0-abe3509f6ebe" alt=""><figcaption></figcaption></figure>
4. Click **Ok** to test the connection and optionally sync. Credentials are saved in Keychain when you connect.

**Step 3: Use the Password Manager**

* **Fetch accounts:** The password manager lists vault records (from `ls -R -l`). Use the filter to search.
* **Fill password:** Select a record and use “Fill Password” (or the equivalent action) to send the password to the terminal.
* **Enter username:** Use “Enter username” to send only the record’s login value.
* **Update password:** Use the option to set a new password for a record; iTerm2 calls `record-update` with the new value.
* **Add/delete:** Add new login records or delete existing ones from the Password Manager UI.

#### Quick Start Summary

1. Start Commander Service Mode (local or with tunneling). For local: `service-create -p 8900 -f json -aip 127.0.0.1 -c 'ls,get,record-update,record-add,rm,sync-down'` then `service-start` if needed.
2. In iTerm2 → Password Manager → choose **Keeper Security** → then API URL pop-up will open.
3. Set **API URL** to your service URL (e.g. `http://127.0.0.1:8900/api/v2/` for local, or your tunnel URL with `/api/v2/`) then **click ok** and After that **API Key** pop-up will trigger to ask for your service mode API key → **click ok**.
4. Use the Password Manager to list, fill, update, add, and delete records.

#### Security Best Practices

| Practice                 | Description                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| Local: bind to localhost | For local use, use `-aip 127.0.0.1` so the Commander API is only reachable from your machine.                 |
| Tunneling: use HTTPS     | When using Ngrok or Cloudflare, the tunnel URL uses HTTPS; keep it private and restrict who can access it.    |
| Limit commands           | Only allow the commands iTerm2 needs: `ls`, `get`, `record-update`, `record-add`, `rm`, `sync-down`.          |
| Keychain storage         | API key and URL are stored in macOS Keychain; prefer data-protection Keychain (Touch ID/Face ID or passcode). |
| Trusted environment      | Run Commander Service Mode on trusted machines; for remote access, use tunneling with access controls.        |
| Token expiration         | Optionally set API key expiration in Commander service config and rotate keys periodically.                   |

#### Troubleshooting

**Common Issues**

| Issue                                          | Cause                                                  | Solution                                                                                                                                                      |
| ---------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API URL is required**                        | No API URL saved in iTerm2.                            | Open Keeper Security Settings and set the API URL (local or tunnel, e.g. `http://127.0.0.1:8900/api/v2/` or `https://your-tunnel-url/api/v2/`).               |
| **Connection / “Could not connect to Keeper”** | Service not running, wrong URL, or invalid API key.    | Ensure Commander service is running, URL has `/api/v2/`, and the API key matches the service config. For tunnels, confirm the tunnel is active and reachable. |
| **No records listed**                          | Service not synced, wrong key, or command not allowed. | Run “ok” (sync); ensure `ls` (and `sync-down` if you sync) are in the service command list.                                                                   |
| **Password or login not filled**               | Record has no password/login or `get` not allowed.     | Confirm the record type has a password/login and that `get` is allowed for the API key.                                                                       |
| **Touch ID / Keychain prompt**                 | First use or after reboot.                             | Unlock with Touch ID or Mac password when prompted; API key is read from data-protection Keychain.                                                            |

**Check Service and URL**

1. Ensure the Commander service is running (e.g. `service-status` in Commander shell).
2. Test reachability: for local, `curl http://127.0.0.1:8900/health`; for a tunnel, open your tunnel base URL plus `/health` in a browser or with `curl`.
3. In iTerm2, ensure the API URL includes `/api/v2/` (e.g. `http://127.0.0.1:8900/api/v2/` for local, or `https://your-tunnel-host/api/v2/` for tunneling).

**Reset iTerm2 Keeper Configuration**

If you need to clear stored credentials and start over:

1. Open Password Manager → select **Keeper Security**.
2. Use the option to **Reset Keeper Security configuration** for the password manager data source.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FyDaVKpWy7uinwmQHKzrb%2Fimage.png?alt=media&#x26;token=34baea8a-4328-4d62-b86c-1ebf11b25343" alt=""><figcaption></figcaption></figure>

3. Re-enter API URL and API key in Settings option provided which will be visible once keeper security is selected and once you update API KEY and API URL then click **Ok**.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fvd2JcLTuY9O5CzP1rr8n%2Fimage.png?alt=media&#x26;token=8d0fca01-6f9d-4990-beda-4a28d7d0f5c1" alt=""><figcaption></figcaption></figure>

4. Also use **Sync Down** in the Password Manager when Keeper Security is selected; it refreshes the vault list so it matches Keeper.

#### References

* [Keeper Commander Installation & Setup](https://docs.keeper.io/en/keeperpam/commander-cli/commander-installation-setup)
* [Service Mode REST API](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api)
* [API Usage](https://docs.keeper.io/en/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/en/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.