iTerm2

List, fill, and manage vault credentials from the iTerm2 application.

This integration allows you to use Keeper Security as the password manager inside iTerm2. The integration talks to Keeper Commander running in Service Mode.

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.

For Keeper Commander Service Mode setup and API details, see the Service Mode REST API documentation.

Prerequisites

Keeper Commander Requirements

Requirement	Description
Keeper Commander	Installed and logged in.
Service Mode	Commander running in Service Mode 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.

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.

Setup Guide

Step 1: Start Keeper Commander Service Mode

1. Install and log in to Keeper Commander (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:

   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 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:

   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

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/).

   

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

   
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.

1. 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.

1. 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

• Service Mode REST API

• API Usage