# terminal-query

> Send escape sequences to the terminal and read back responses

Latest version **0.1.1** (published 2026-01-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install terminal-query
pnpm add terminal-query
yarn add terminal-query
bun add terminal-query
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2026-01-10 |
| First published | 2026-01-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 25.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 15 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | terminal, query, ansi, escape, tty, response, xtversion, xtgettcap, terminfo, iterm, capability, console |

## Links

- npm: https://www.npmjs.com/package/terminal-query
- Repository: https://github.com/sindresorhus/terminal-query
- Homepage: https://github.com/sindresorhus/terminal-query#readme
- Issues: https://github.com/sindresorhus/terminal-query/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/terminal-query

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 0.1.1 (latest) — 2026-01-10
- 0.1.0 — 2026-01-05

## README

# 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

```sh
npm install terminal-query
```

## Usage

```js
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](https://fishshell.com/docs/4.1/terminal-compatibility.html).
- 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).
- 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).
- 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/).
- 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.

```js
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`.

```js
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.

```js
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`).

```js
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.

```js
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.

```js
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`.

```js
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.

```js
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`).

```js
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.

```js
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.

---
_Source: https://npm.io/package/terminal-query · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._