terminal-query

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.

Install

npm install terminal-query

Usage

import {queryTerminal} from 'terminal-query';

const response = await queryTerminal('\u001B[>q', {timeoutMilliseconds: 100});
console.log(response);

Use cases

• Query terminal name and version (XTVERSION) with queryXTVERSION
• Query terminfo capabilities using XTGETTCAP (DCS + q ... ST) with queryXTGETTCAP
• Query primary device attributes (DA1) with queryDeviceAttributes
• Query terminal feature reporting where supported (for example iTerm2's OSC 1337;Capabilities) with queryITermFeatures and read TERM_FEATURES separately if needed
• Query other terminal-specific responses that follow a request/response pattern

Notes

• XTVERSION is a standard query for terminal name and version. See fish terminal compatibility.
• 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 and fish terminal compatibility.
• fish notes that XTGETTCAP is supported across multiple terminals (kitty, foot, wezterm, contour, ghostty). See fish terminal compatibility.
• iTerm2 feature reporting is documented via OSC 1337;Capabilities. TERM_FEATURES is an environment variable you can read separately. See iTerm2 feature reporting.
• The synchronous helpers open /dev/tty, which is Unix-only. Windows uses conin$/conout$ instead, so the sync helpers are not supported there.
• 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.

API

queryTerminal(query, options?)

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);

queryXTVERSION(options?)

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'

queryXTGETTCAP(capabilityNames, options?)

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);

queryDeviceAttributes(options?)

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);

queryITermFeatures(options?)

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);

queryTerminalSync(query, options?)

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);

queryXTVERSIONSync(options?)

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'

queryXTGETTCAPSync(capabilityNames, options?)

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);

queryDeviceAttributesSync(options?)

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);

queryITermFeaturesSync(options?)

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);

options

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.

timeoutMilliseconds

Type: number
Default: 100

Time to wait for a response before resolving.

responseTerminator

Type: string | RegExp
Default: \u001B\\

When the buffer matches the terminator, the query finishes early.

stdin

Type: NodeJS.ReadStream
Default: process.stdin

Input stream to read from. Only available for queryTerminal. The synchronous functions read directly from /dev/tty instead.

stdout

Type: NodeJS.WriteStream
Default: process.stdout

Output stream to write to.