{"_id":"iterm2-node","name":"iterm2-node","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"iterm2-node","version":"0.1.0","description":"Node.js client library for the iTerm2 API, inspired by github.com/tmc/it2.","main":"src/index.js","types":"index.d.ts","sideEffects":false,"repository":{"type":"git","url":"git+https://github.com/mmun/iterm2-node.git"},"bugs":{"url":"https://github.com/mmun/iterm2-node/issues"},"homepage":"https://github.com/mmun/iterm2-node#readme","exports":{".":{"types":"./index.d.ts","require":"./src/index.js"}},"scripts":{"test":"npm run test:unit","test:unit":"node --test test/*.test.js","test:e2e":"node --test test/e2e/*.test.js"},"keywords":["iterm2","terminal","automation","websocket","protobuf"],"license":"MIT","dependencies":{"protobufjs":"^7.4.0","ws":"^8.18.0"},"engines":{"node":">=18"},"_id":"iterm2-node@0.1.0","gitHead":"474ec65e9abea0966d913358eda74bd5fd89cea5","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-i7CwG0r6v5CKtCp78xrgTlmj0NGvGbUr3qguFL3t/agzh0nNdm+aULxqKGW8BXx6D4g1TkDQihZl+ynQr4WXuA==","shasum":"b2c8a79adf5328de1ddb69bc99d77e023a6f2f4f","tarball":"https://registry.npmjs.org/iterm2-node/-/iterm2-node-0.1.0.tgz","fileCount":12,"unpackedSize":145719,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDrDQUmAeygtv/yA7JkYfZ8L3K4lzqyjlo+QqorqGtW/wIgSCuQiMSySgnUVwkIuFAkU4re/+V0mqmKG72LRvXDsAg="}]},"_npmUser":{"name":"mmun","email":"im.mmun@gmail.com"},"directories":{},"maintainers":[{"name":"mmun","email":"im.mmun@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/iterm2-node_0.1.0_1777414147719_0.1397149879718047"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-28T22:09:07.594Z","0.1.0":"2026-04-28T22:09:07.871Z","modified":"2026-04-28T22:09:08.132Z"},"maintainers":[{"name":"mmun","email":"im.mmun@gmail.com"}],"description":"Node.js client library for the iTerm2 API, inspired by github.com/tmc/it2.","homepage":"https://github.com/mmun/iterm2-node#readme","keywords":["iterm2","terminal","automation","websocket","protobuf"],"repository":{"type":"git","url":"git+https://github.com/mmun/iterm2-node.git"},"bugs":{"url":"https://github.com/mmun/iterm2-node/issues"},"license":"MIT","readme":"# iterm2-node\n\nNode.js client library for the iTerm2 API.\n\nThis package is library-only. It does not ship a CLI.\n\n## Relationship To tmc/it2\n\nThis project is inspired by and informed by\n[`github.com/tmc/it2`](https://github.com/tmc/it2), Travis Cline's Go project\nfor controlling iTerm2 sessions, splits, text I/O, buffers, tabs, and windows.\n\nThe overlap is intentional at the workflow/API-concept level: sessions, tabs,\nwindows, splits, text input, buffer reads, variables, profiles, colors, and\nauthentication are exposed with names that should feel familiar to users of the\nGo project.\n\nThis is not a line-for-line port of `tmc/it2`, and it is not an official Node\npackage from that project. The implementation is written in JavaScript for\nNode.js and intentionally omits the Go project's CLI, plugin system, agent\nstate detection, broadcast helpers, and higher-level terminal workflow tools.\n\n`tmc/it2` is MIT licensed. The license for this package keeps the Travis Cline\ncopyright notice alongside the `iterm2-node` contributor notice.\n\n## Requirements\n\n- Node.js 18+\n- macOS with iTerm2 3.3.0+\n- iTerm2 Python API enabled:\n  `iTerm2 Settings > General > Magic > Enable Python API`\n\n## Configure iTerm2\n\n`iterm2-node` talks to the same local API server used by iTerm2's Python API. You\ndo not need to install Python packages, but iTerm2's API server must be enabled.\niTerm2 documents this in its Python API docs and its Python API security page,\nwhich describes the local Unix domain socket and cookie-based authentication\nmodel.\n\n1. Open iTerm2.\n2. Open `iTerm2 > Settings`.\n3. Go to `General > Magic`.\n4. Enable `Enable Python API` or `Enable Python API server`, depending on the\n   iTerm2 version.\n5. Keep iTerm2 running while your Node process connects.\n\nOn the first connection from an external app, iTerm2 may ask macOS for\nAutomation permission so that the calling terminal app can request an API\ncookie. Allow that prompt. The client stores the returned `ITERM2_COOKIE` and\n`ITERM2_KEY` in the current process environment and sends them as iTerm2 API\nheaders.\n\nYou can verify configuration from this repository with:\n\n```bash\nnode -e \"const { auth } = require('.'); auth.checkAutomationEnabled().then(() => auth.requestAuthentication()).then(() => console.log('iTerm2 API ready'))\"\n```\n\nFor an installed package, use `require('iterm2-node')` instead of `require('.')`.\n\nYou can also enable the API server programmatically:\n\n```bash\nnode -e \"require('iterm2-node').auth.enableAutomation()\"\n```\n\nIf iTerm2 is already running and the socket is not created, quit and reopen\niTerm2 after changing the setting.\n\nBy default this client connects to iTerm2's Unix socket at:\n\n```text\n~/Library/Application Support/iTerm2/private/socket\n```\n\nIf that socket is unavailable, it falls back to `ws://localhost:1912`.\n\nOptional: install iTerm2 shell integration if you use prompt-related APIs such\nas `getPrompt()` or `listPrompts()`. In iTerm2 3.5+, this can be enabled with\n`Settings > Profiles > General > Command > Load shell integration automatically`\nfor supported shells. You can also use `iTerm2 > Install Shell Integration`.\n\nCommon setup failures:\n\n- `iTerm2 API automation is not enabled`: enable the Python API setting above.\n- `authentication required`: allow the macOS Automation prompt, or pass valid\n  `ITERM2_COOKIE` and `ITERM2_KEY` values in the Node process environment.\n- `ECONNREFUSED` or socket errors: make sure iTerm2 is running, then reopen\n  iTerm2 if you just enabled the API server.\n\nOfficial iTerm2 references:\n\n- [Python API](https://iterm2.com/python-api/)\n- [Python API security](https://iterm2.com/python-api-auth.html)\n- [Python API example script](https://iterm2.com/python-api/tutorial/example.html)\n- [Shell integration](https://iterm2.com/documentation-shell-integration.html)\n\n## Install\n\n```bash\nnpm install iterm2-node\n```\n\nFor local development in this repository:\n\n```bash\nnpm install\n```\n\n## Quick Start\n\n```js\nconst { createClient } = require('iterm2-node');\n\nasync function main() {\n  const client = createClient();\n  await client.connect();\n\n  try {\n    const sessions = await client.listSessions();\n    const session = sessions[0];\n\n    await client.sendText(session.sessionId, 'echo hello from node\\n');\n\n    const screen = await client.getScreenText(session.sessionId);\n    console.log(screen);\n  } finally {\n    await client.close();\n  }\n}\n\nmain().catch((err) => {\n  console.error(err);\n  process.exitCode = 1;\n});\n```\n\nBy default the client uses iTerm2's Unix socket at\n`~/Library/Application Support/iTerm2/private/socket` and falls back to\n`ws://localhost:1912`.\n\n## Public API\n\nThe package root intentionally exposes only the library entry points:\n\n- `createClient(options)`\n- `ITerm2Client`\n- `auth`\n- `proto`\n- error classes\n\nEverything else is accessed through a client instance.\n\n## Client Methods\n\nConnection and protocol:\n\n- `connect(options)`\n- `close()`\n- `sendRequest(payload, options)`\n- `invokeFunction(invocation, options)`\n- `subscribeToNotification(type, options)`\n- `unsubscribeFromNotification(type, options)`\n- `readNotification(options)`\n- `notifications(options)`\n\nSessions:\n\n- `listSessions(options)`\n- `listSessionsRaw(options)`\n- `sendText(sessionId, text, options)`\n- `splitPane(sessionId, options)`\n- `moveSession(sourceSessionId, destSessionId, options)`\n- `closeSessions(sessionIds, options)`\n- `activateSession(sessionId, options)`\n- `restartSession(sessionId, options)`\n- `setSessionName(sessionId, name, options)`\n- `setSessionBadge(sessionId, badge, options)`\n- `getSessionBadge(sessionId, options)`\n- `clearSessionBadge(sessionId, options)`\n- `getPrompt(sessionId, options)`\n- `getPromptById(sessionId, uniquePromptId, options)`\n- `listPrompts(sessionId, options)`\n\nScreen and buffer:\n\n- `getScreenContents(sessionId, options)`\n- `getScreenText(sessionId, options)`\n- `getBuffer(sessionId, options)`\n- `getBufferWithStyles(sessionId, options)`\n- `getBufferText(sessionId, options)`\n- `getContents(sessionId, firstLine, numLines, options)`\n- `clearBuffer(sessionId, options)`\n- `findText(sessionId, pattern, options)`\n\nVariables and properties:\n\n- `getVariable(sessionId, name, options)`\n- `setVariable(sessionId, name, value, options)`\n- `getVariableWithScope(scope, id, name, options)`\n- `getMultipleVariablesWithScope(scope, id, names, options)`\n- `setVariableWithScope(scope, id, name, value, options)`\n- `listVariablesWithScope(scope, id, options)`\n- `deleteVariableWithScope(scope, id, name, options)`\n- `getSessionProperty(sessionId, property, options)`\n- `setSessionProperty(sessionId, property, value, options)`\n- `getSessionProfileProperty(sessionId, key, options)`\n- `setSessionProfileProperty(sessionId, key, value, options)`\n\nTabs and windows:\n\n- `createTab(options)`\n- `closeTabs(tabIds, options)`\n- `activateTab(tabId, options)`\n- `reorderTabs(assignments, options)`\n- `setTabTitle(tabId, title, options)`\n- `getTabTitle(tabId, options)`\n- `clearTabTitle(tabId, options)`\n- `setTabLayout(tabId, rootNode, options)`\n- `setTabColor(tabId, red, green, blue, options)`\n- `getTabColor(tabId, options)`\n- `clearTabColor(tabId, options)`\n- `createWindow(profileName, options)`\n- `closeWindows(windowIds, options)`\n- `activateWindow(windowId, options)`\n- `listWindows(options)`\n- `setWindowTitle(windowId, title, options)`\n- `getWindowTitle(windowId, options)`\n- `clearWindowTitle(windowId, options)`\n- `getWindowProperty(windowId, property, options)`\n- `setWindowProperty(windowId, property, value, options)`\n\nProfiles, colors, preferences, and other iTerm2 features:\n\n- `listProfiles(options)`\n- `listProfilesDetailed(options)`\n- `getProfile(profileName, options)`\n- `getProfileProperty(profileName, key, options)`\n- `setProfileProperty(profileName, key, value, options)`\n- `setProfileProperties(profileName, properties, options)`\n- `listColorPresets(options)`\n- `getColorPreset(name, options)`\n- `applyColorPreset(presetName, profileName, options)`\n- `getPreference(key, options)`\n- `setPreference(key, value, options)`\n- `getPreferences(keys, options)`\n- `setPreferences(preferences, options)`\n- `saveArrangement(name, windowId, options)`\n- `restoreArrangement(name, options)`\n- `listArrangements(options)`\n- `getBroadcastDomains(options)`\n- `setBroadcastDomains(domains, options)`\n- `listTmuxConnections(options)`\n- `sendTmuxCommand(connectionId, command, options)`\n\nInput, selection, and focus:\n\n- `injectData(sessionIds, data, options)`\n- `getCursor(sessionId, options)`\n- `setCursor(sessionId, x, y, options)`\n- `setGridSize(sessionId, width, height, options)`\n- `getSelection(sessionId, options)`\n- `setSelectionRange(sessionId, startX, startY, endX, endY, mode, options)`\n- `setSelection(sessionId, start, end, options)`\n- `clearSelection(sessionId, options)`\n- `copySelection(options)`\n- `pasteFromClipboard(sessionId, options)`\n- `getFocus(options)`\n\nID resolution helpers:\n\n- `resolveSessionId(sessionId, options)`\n- `resolveTabId(tabId, options)`\n- `resolveWindowId(windowId, options)`\n\n## Authentication Helpers\n\nAuthentication operations are exported under `auth`:\n\n- `auth.requestAuthentication(options)`\n- `auth.checkAutomationEnabled()`\n- `auth.enableAutomation()`\n- `auth.disableAutomation()`\n- `auth.hasAuthentication(env)`\n- `auth.clearAuthentication(env)`\n- `auth.defaultSocketPath()`\n- `auth.socketExists(socketPath)`\n\nThe client can request authentication automatically unless\n`autoRequestAuth: false` is passed to `createClient()`.\n\n## Raw Protobuf Access\n\nThe iTerm2 API protobuf schema is included at `proto/api.proto`. Protocol\nutilities are exported as `proto`:\n\n```js\nconst { proto } = require('iterm2-node');\n\nconst bytes = proto.encodeClientMessage({\n  id: 1,\n  listSessionsRequest: {}\n});\n```\n\nUse `sendRequest()` for raw request payloads when the high-level client does not\ncover an iTerm2 API call yet.\n\n## Tests\n\n```bash\nnpm test\nnpm run test:unit\nnpm run test:e2e\n```\n\n`npm test` runs the unit suite.\n\n`test:unit` is limited to protocol/computational behavior such as protobuf\nencoding, request matching, ID resolution, text expansion, text chunking, and\nsession tree flattening.\n\n`test:e2e` runs live iTerm2 tests. It creates, renames, splits, moves,\nreorders, and closes temporary iTerm2 windows/tabs/sessions. It does not send\nshell input or explicitly activate iTerm2 windows.\n\nSet `ITERM2_NODE_E2E_KEEP=1` to leave the temporary session open for\ndebugging.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\nCredit to Travis Cline and the\n[`tmc/it2`](https://github.com/tmc/it2) project for the original Go iTerm2\nautomation work that informed this package.\n","readmeFilename":"README.md","_rev":"1-1f7ccedb0adf515f5ab73b981eea6492"}