Send escape sequences to the terminal and read back responses
Many 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.
This is useful for CLI apps that need to detect terminal capabilities, adapt behavior based on the terminal emulator, or enable features only when supported.
npm install terminal-query
import {queryTerminal} from 'terminal-query';
const response = await queryTerminal('\u001B[>q', {timeoutMilliseconds: 100});
console.log(response);
queryXTVERSIONDCS + q ... ST) with queryXTGETTCAPqueryDeviceAttributesOSC 1337;Capabilities) with queryITermFeatures and read TERM_FEATURES separately if neededOSC 1337;Capabilities. TERM_FEATURES is an environment variable you can read separately. See iTerm2 feature reporting./dev/tty, which is Unix-only. Windows uses conin$/conout$ instead, so the sync helpers are not supported there.\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.Send an escape sequence to the terminal and return the response.
Returns a Promise<string | undefined> with the terminal response, or undefined if not in a TTY or no response is received.
import {queryTerminal} from 'terminal-query';
const response = await queryTerminal('\u001B[>q', {timeoutMilliseconds: 100});
console.log(response);
Query terminal name and version (XTVERSION).
Returns a Promise<string | undefined> with the terminal response payload (the text between DCS >| and ST) when available. If parsing fails, it returns undefined.
import {queryXTVERSION} from 'terminal-query';
const version = await queryXTVERSION();
console.log(version);
//=> 'iTerm2 3.5.0'
Query terminfo capabilities (XTGETTCAP).
Returns a Promise<string | undefined> with the terminal response.
Throws a TypeError if capabilityNames is empty.
capabilityNames are terminfo capability names (for example indn), which are hex-encoded in the XTGETTCAP request.
import {queryXTGETTCAP} from 'terminal-query';
const response = await queryXTGETTCAP('indn');
console.log(response);
Query primary device attributes (DA1).
Returns a Promise<string | undefined> with the terminal response.
This sends the primary device attributes query (ESC [ c).
import {queryDeviceAttributes} from 'terminal-query';
const response = await queryDeviceAttributes();
console.log(response);
Query iTerm2 feature reporting (OSC 1337;Capabilities).
Returns a Promise<string | undefined> with the terminal response.
import {queryITermFeatures} from 'terminal-query';
const response = await queryITermFeatures();
console.log(response);
Send an escape sequence to the terminal and return the response synchronously.
Returns a string | undefined with the terminal response, or undefined if not in a TTY or no response is received.
import {queryTerminalSync} from 'terminal-query';
const response = queryTerminalSync('\u001B[>q', {timeoutMilliseconds: 100});
console.log(response);
Query terminal name and version (XTVERSION) synchronously.
Returns a string | undefined with the terminal response payload (the text between DCS >| and ST) when available. If parsing fails, it returns undefined.
import {queryXTVERSIONSync} from 'terminal-query';
const version = queryXTVERSIONSync();
console.log(version);
//=> 'iTerm2 3.5.0'
Query terminfo capabilities (XTGETTCAP) synchronously.
Returns a string | undefined with the terminal response.
Throws a TypeError if capabilityNames is empty.
capabilityNames are terminfo capability names (for example indn), which are hex-encoded in the XTGETTCAP request.
import {queryXTGETTCAPSync} from 'terminal-query';
const response = queryXTGETTCAPSync('indn');
console.log(response);
Query primary device attributes (DA1) synchronously.
Returns a string | undefined with the terminal response.
This sends the primary device attributes query (ESC [ c).
import {queryDeviceAttributesSync} from 'terminal-query';
const response = queryDeviceAttributesSync();
console.log(response);
Query iTerm2 feature reporting (OSC 1337;Capabilities) synchronously.
Returns a string | undefined with the terminal response.
import {queryITermFeaturesSync} from 'terminal-query';
const response = queryITermFeaturesSync();
console.log(response);
For the helper methods (queryXTVERSION, queryXTGETTCAP, queryDeviceAttributes, queryITermFeatures, and sync variants), the options are the same as queryTerminal/queryTerminalSync except responseTerminator, which is fixed internally.
Type: number
Default: 100
Time to wait for a response before resolving.
Type: string | RegExp
Default: \u001B\\
When the buffer matches the terminator, the query finishes early.
Type: NodeJS.ReadStream
Default: process.stdin
Input stream to read from. Only available for queryTerminal. The synchronous functions read directly from /dev/tty instead.
Type: NodeJS.WriteStream
Default: process.stdout
Output stream to write to.