{"_id":"terminal-query","_rev":"4109492","name":"terminal-query","description":"Send escape sequences to the terminal and read back responses","dist-tags":{"latest":"0.1.1"},"maintainers":[{"name":"sindresorhus","email":""}],"time":{"modified":"2026-01-23T00:54:08.000Z","created":"2026-01-05T19:12:43.255Z","0.1.1":"2026-01-10T22:58:33.978Z","0.1.0":"2026-01-05T19:12:43.255Z"},"users":{},"author":{"name":"Sindre Sorhus","email":"sindresorhus@gmail.com","url":"https://sindresorhus.com"},"repository":{"type":"git","url":"git+https://github.com/sindresorhus/terminal-query.git"},"versions":{"0.1.1":{"name":"terminal-query","version":"0.1.1","description":"Send escape sequences to the terminal and read back responses","license":"MIT","repository":{"type":"git","url":"git+https://github.com/sindresorhus/terminal-query.git"},"funding":"https://github.com/sponsors/sindresorhus","author":{"name":"Sindre Sorhus","email":"sindresorhus@gmail.com","url":"https://sindresorhus.com"},"type":"module","exports":{"types":"./index.d.ts","default":"./index.js"},"sideEffects":false,"engines":{"node":">=20"},"scripts":{"test":"xo && ava"},"keywords":["terminal","query","ansi","escape","tty","response","xtversion","xtgettcap","terminfo","iterm","capability","console"],"devDependencies":{"ava":"^6.4.1","xo":"^1.2.3"},"gitHead":"81c4b6b1c671f0bfb7b91253e1ecd173bcbc01df","types":"./index.d.ts","_id":"terminal-query@0.1.1","bugs":{"url":"https://github.com/sindresorhus/terminal-query/issues"},"homepage":"https://github.com/sindresorhus/terminal-query#readme","_nodeVersion":"24.12.0","_npmVersion":"11.6.1","dist":{"shasum":"fc70e6b8d266ba2ed65f8abdec90c58ceb3d0ed5","size":5923,"noattachment":false,"key":"/terminal-query/-/terminal-query-0.1.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/terminal-query/download/terminal-query-0.1.1.tgz"},"_npmUser":{"name":"sindresorhus","email":"sindresorhus@gmail.com"},"directories":{},"maintainers":[{"name":"sindresorhus","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/terminal-query_0.1.1_1768085913781_0.08781492679599201"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2026-01-10T22:58:33.978Z","publish_time":1768085913978,"_source_registry_name":"default","_cnpm_publish_time":1768085913978},"0.1.0":{"name":"terminal-query","version":"0.1.0","description":"Send escape sequences to the terminal and read back responses","license":"MIT","repository":{"type":"git","url":"git+https://github.com/sindresorhus/terminal-query.git"},"funding":"https://github.com/sponsors/sindresorhus","author":{"name":"Sindre Sorhus","email":"sindresorhus@gmail.com","url":"https://sindresorhus.com"},"type":"module","exports":{"types":"./index.d.ts","default":"./index.js"},"sideEffects":false,"engines":{"node":">=20"},"scripts":{"test":"xo && ava"},"keywords":["terminal","query","ansi","escape","tty","response","xtversion","xtgettcap","terminfo","iterm","capability","console"],"devDependencies":{"ava":"^6.4.1","xo":"^1.2.3"},"gitHead":"b761ba37b6456f4b654fba0e2316ff6d176d938b","types":"./index.d.ts","_id":"terminal-query@0.1.0","bugs":{"url":"https://github.com/sindresorhus/terminal-query/issues"},"homepage":"https://github.com/sindresorhus/terminal-query#readme","_nodeVersion":"24.12.0","_npmVersion":"11.6.1","dist":{"shasum":"7a1b9820b08e3447cc858d00b60d17331f09114f","size":5843,"noattachment":false,"key":"/terminal-query/-/terminal-query-0.1.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/terminal-query/download/terminal-query-0.1.0.tgz"},"_npmUser":{"name":"sindresorhus","email":"sindresorhus@gmail.com"},"directories":{},"maintainers":[{"name":"sindresorhus","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/terminal-query_0.1.0_1767640363062_0.6768012616802692"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2026-01-05T19:12:43.255Z","publish_time":1767640363255,"_source_registry_name":"default","_cnpm_publish_time":1767640363255}},"readme":"# terminal-query\n\n> Send escape sequences to the terminal and read back responses\n\nMany terminals support a request-response protocol where you can query for information like the terminal name, version, supported features, and capabilities. This package provides a simple way to send these queries and capture the terminal's response, with built-in helpers for common queries like XTVERSION, XTGETTCAP, and device attributes.\n\nThis is useful for CLI apps that need to detect terminal capabilities, adapt behavior based on the terminal emulator, or enable features only when supported.\n\n## Install\n\n```sh\nnpm install terminal-query\n```\n\n## Usage\n\n```js\nimport {queryTerminal} from 'terminal-query';\n\nconst response = await queryTerminal('\\u001B[>q', {timeoutMilliseconds: 100});\nconsole.log(response);\n```\n\n## Use cases\n\n- Query terminal name and version (XTVERSION) with `queryXTVERSION`\n- Query terminfo capabilities using XTGETTCAP (`DCS + q ... ST`) with `queryXTGETTCAP`\n- Query primary device attributes (DA1) with `queryDeviceAttributes`\n- Query terminal feature reporting where supported (for example iTerm2's `OSC 1337;Capabilities`) with `queryITermFeatures` and read `TERM_FEATURES` separately if needed\n- Query other terminal-specific responses that follow a request/response pattern\n\n## Notes\n\n- XTVERSION is a standard query for terminal name and version. See [fish terminal compatibility](https://fishshell.com/docs/4.1/terminal-compatibility.html).\n- XTGETTCAP is a DCS query used to request terminfo capabilities, and terminals use a hex-encoded request/response format for capability names and values. See [xterm control sequences](https://www.xfree86.org/current/ctlseqs.html) and [fish terminal compatibility](https://fishshell.com/docs/4.1/terminal-compatibility.html).\n- fish notes that XTGETTCAP is supported across multiple terminals (kitty, foot, wezterm, contour, ghostty). See [fish terminal compatibility](https://fishshell.com/docs/4.1/terminal-compatibility.html).\n- iTerm2 feature reporting is documented via `OSC 1337;Capabilities`. `TERM_FEATURES` is an environment variable you can read separately. See [iTerm2 feature reporting](https://iterm2.com/feature-reporting/).\n- The synchronous helpers open `/dev/tty`, which is Unix-only. Windows uses `conin$`/`conout$` instead, so the sync helpers are not supported there.\n- Some terminals use BEL (`\\x07`) as an alternative String Terminator (ST) for OSC sequences instead of `ESC \\`. The default `responseTerminator` uses `ESC \\`, but you can provide a regex like `/\\x07|\\x1B\\\\/` if you need to match both.\n\n## API\n\n### queryTerminal(query, options?)\n\nSend an escape sequence to the terminal and return the response.\n\nReturns a `Promise<string | undefined>` with the terminal response, or `undefined` if not in a TTY or no response is received.\n\n```js\nimport {queryTerminal} from 'terminal-query';\n\nconst response = await queryTerminal('\\u001B[>q', {timeoutMilliseconds: 100});\nconsole.log(response);\n```\n\n### queryXTVERSION(options?)\n\nQuery terminal name and version (XTVERSION).\n\nReturns a `Promise<string | undefined>` with the terminal response payload (the text between `DCS >|` and `ST`) when available. If parsing fails, it returns `undefined`.\n\n```js\nimport {queryXTVERSION} from 'terminal-query';\n\nconst version = await queryXTVERSION();\nconsole.log(version);\n//=> 'iTerm2 3.5.0'\n```\n\n### queryXTGETTCAP(capabilityNames, options?)\n\nQuery terminfo capabilities (XTGETTCAP).\n\nReturns a `Promise<string | undefined>` with the terminal response.\n\nThrows a `TypeError` if `capabilityNames` is empty.\n\n`capabilityNames` are terminfo capability names (for example `indn`), which are hex-encoded in the XTGETTCAP request.\n\n```js\nimport {queryXTGETTCAP} from 'terminal-query';\n\nconst response = await queryXTGETTCAP('indn');\nconsole.log(response);\n```\n\n### queryDeviceAttributes(options?)\n\nQuery primary device attributes (DA1).\n\nReturns a `Promise<string | undefined>` with the terminal response.\n\nThis sends the primary device attributes query (`ESC [ c`).\n\n```js\nimport {queryDeviceAttributes} from 'terminal-query';\n\nconst response = await queryDeviceAttributes();\nconsole.log(response);\n```\n\n### queryITermFeatures(options?)\n\nQuery iTerm2 feature reporting (`OSC 1337;Capabilities`).\n\nReturns a `Promise<string | undefined>` with the terminal response.\n\n```js\nimport {queryITermFeatures} from 'terminal-query';\n\nconst response = await queryITermFeatures();\nconsole.log(response);\n```\n\n### queryTerminalSync(query, options?)\n\nSend an escape sequence to the terminal and return the response synchronously.\n\nReturns a `string | undefined` with the terminal response, or `undefined` if not in a TTY or no response is received.\n\n```js\nimport {queryTerminalSync} from 'terminal-query';\n\nconst response = queryTerminalSync('\\u001B[>q', {timeoutMilliseconds: 100});\nconsole.log(response);\n```\n\n### queryXTVERSIONSync(options?)\n\nQuery terminal name and version (XTVERSION) synchronously.\n\nReturns a `string | undefined` with the terminal response payload (the text between `DCS >|` and `ST`) when available. If parsing fails, it returns `undefined`.\n\n```js\nimport {queryXTVERSIONSync} from 'terminal-query';\n\nconst version = queryXTVERSIONSync();\nconsole.log(version);\n//=> 'iTerm2 3.5.0'\n```\n\n### queryXTGETTCAPSync(capabilityNames, options?)\n\nQuery terminfo capabilities (XTGETTCAP) synchronously.\n\nReturns a `string | undefined` with the terminal response.\n\nThrows a `TypeError` if `capabilityNames` is empty.\n\n`capabilityNames` are terminfo capability names (for example `indn`), which are hex-encoded in the XTGETTCAP request.\n\n```js\nimport {queryXTGETTCAPSync} from 'terminal-query';\n\nconst response = queryXTGETTCAPSync('indn');\nconsole.log(response);\n```\n\n### queryDeviceAttributesSync(options?)\n\nQuery primary device attributes (DA1) synchronously.\n\nReturns a `string | undefined` with the terminal response.\n\nThis sends the primary device attributes query (`ESC [ c`).\n\n```js\nimport {queryDeviceAttributesSync} from 'terminal-query';\n\nconst response = queryDeviceAttributesSync();\nconsole.log(response);\n```\n\n### queryITermFeaturesSync(options?)\n\nQuery iTerm2 feature reporting (`OSC 1337;Capabilities`) synchronously.\n\nReturns a `string | undefined` with the terminal response.\n\n```js\nimport {queryITermFeaturesSync} from 'terminal-query';\n\nconst response = queryITermFeaturesSync();\nconsole.log(response);\n```\n\n#### options\n\nFor the helper methods (`queryXTVERSION`, `queryXTGETTCAP`, `queryDeviceAttributes`, `queryITermFeatures`, and sync variants), the options are the same as `queryTerminal`/`queryTerminalSync` except `responseTerminator`, which is fixed internally.\n\n##### timeoutMilliseconds\n\nType: `number`\\\nDefault: `100`\n\nTime to wait for a response before resolving.\n\n##### responseTerminator\n\nType: `string | RegExp`\\\nDefault: `\\u001B\\\\`\n\nWhen the buffer matches the terminator, the query finishes early.\n\n##### stdin\n\nType: `NodeJS.ReadStream`\\\nDefault: `process.stdin`\n\nInput stream to read from. Only available for `queryTerminal`. The synchronous functions read directly from `/dev/tty` instead.\n\n##### stdout\n\nType: `NodeJS.WriteStream`\\\nDefault: `process.stdout`\n\nOutput stream to write to.\n","_attachments":{},"homepage":"https://github.com/sindresorhus/terminal-query#readme","bugs":{"url":"https://github.com/sindresorhus/terminal-query/issues"},"license":"MIT"}