detect-terminal

detect-terminal

Detect the terminal program currently being used, with support for iTerm, Terminal.app, Hyper, iTerm2, ConEmu, Cmde,r Alacritty, Xterm, Terminator, Termux, Kitty, and others. Detection is based on environment variables and process-level indicators to identify the terminal in use. This can't be done reliably in all cases, but it's useful when available.

Install

Install with npm:

$ npm install --save detect-terminal

Usage

import detectTerminal from 'detect-terminal';
// or
import { detectTerminal, detectTerminalDetails } from 'detect-terminal';

console.log(detectTerminal()) //=> "iterm" (or whatever terminal you're using)

console.log(detectTerminalDetails());
//=> {
//=>   terminal: "iterm",
//=>   source: "env",
//=>   isTTY: true,
//=>   isSSH: false,
//=>   isAmbiguous: false,
//=>   supportsColor: true,
//=>   colorLevel: 3,
//=>   supports256Color: true,
//=>   supportsTrueColor: true,
//=>   term: "xterm-256color",
//=>   termProgram: "iTerm.app",
//=>   colorTerm: "truecolor",
//=>   generic: "xterm_256color"
//=> }

Options

import detectTerminal from 'detect-terminal';

// By default, multiplexers like tmux/screen are detected first
console.log(detectTerminal()); //=> "tmux" (if running inside tmux)

// With preferOuter: true, prefer the outermost terminal (GUI app)
console.log(detectTerminal({ preferOuter: true })); //=> "iterm" (the actual terminal app)

Option	Type	Default	Description
preferOuter	boolean	false	When true, prefer the outermost terminal (GUI app) over multiplexers like tmux/screen
resolveAmbiguousFromParent	boolean	false	When true, inspect parent processes if env-based detection is missing or ambiguous
unpipe	boolean	false	When true, continue env-based detection even when stdout is not currently a TTY

Additional options are available for tests and advanced integrations:

Option	Type	Description
env	NodeJS.ProcessEnv	Environment object to inspect instead of process.env
stdout	{ isTTY: boolean }	Stdout-like object used for TTY checks
platform	NodeJS.Platform	Platform value to use instead of process.platform
pid	number	Starting process id for parent-process detection
processTitle	string	Process title to inspect instead of process.title
execFileSync	typeof execFileSync	Command runner used by shell and parent-process detection

Details API

Use detectTerminalDetails() when you need more than the terminal identifier:

import { detectTerminalDetails } from 'detect-terminal';

const details = detectTerminalDetails({ resolveAmbiguousFromParent: true });

console.log(details.terminal); //=> "iterm"
console.log(details.source); //=> "parent"
console.log(details.supportsTrueColor); //=> true

The details object includes:

Property	Type	Description
terminal	string	Normalized terminal identifier
source	`'env' \	'parent' \
isTTY	boolean	Whether stdout is currently a TTY
isSSH	boolean	Whether SSH_CONNECTION is present
isAmbiguous	boolean	Whether env-based detection produced an ambiguous terminal
supportsColor	boolean	Whether any color support is available
colorLevel	`0 \	1 \
supports256Color	boolean	Whether TERM or COLORTERM indicates 256-color support
supportsTrueColor	boolean	Whether COLORTERM indicates truecolor support
term	`string \	undefined`
termProgram	`string \	undefined`
colorTerm	`string \	undefined`
generic	string	Normalized generic terminal value, usually derived from TERM
appName	`string \	undefined`
pid	`number \	undefined`

Helper APIs

The package also exports lower-level helpers for callers that want to inspect one detection layer at a time:

import {
  detectFromEnv,
  detectFromParentProcess,
  detectFromProcessTitle,
  detectFromShell,
  getColorLevel,
  getColorSupport
} from 'detect-terminal';

Helper	Description
detectFromEnv()	Detects from terminal-related environment variables
detectFromParentProcess()	Walks parent processes to identify the terminal app
detectFromProcessTitle()	Detects from process.title
detectFromShell()	Detects from shell-specific checks, including Windows COMSPEC and WT_SESSION
getColorSupport()	Reports 256-color and truecolor support from TERM and COLORTERM
getColorLevel()	Returns color level 0, 1, 2, or 3

Result-oriented variants are also exported for integrations that need source metadata:

import {
  detectFromEnvResult,
  detectFromParentProcessResult,
  detectFromProcessTitleResult,
  detectFromShellResult
} from 'detect-terminal';

Supported Terminals

The following terminals are supported. Detection is based on environment variables and process-level indicators to identify the terminal in use.

• alacritty
• aterm
• atomic_terminal
• bash
• cmd
• conhost
• csh
• dash
• dopamine
• dumb
• eterm
• fish
• foot
• ghostty
• gnome_terminal
• guake
• hyper
• iterm
• kitty
• konsole
• ksh
• kuake
• linux_console
• mate_terminal
• mrxvt
• node
• nu
• none
• powershell
• putty
• qterminal
• rio
• rxvt
• screen
• sh
• tcsh
• terminal
• terminal_app
• terminator
• terminology
• termux
• tilda
• tmux
• truecolor_terminal
• vscode
• vt100
• warp
• wezterm
• windows_cmd
• windows_terminal
• wterm
• xfce4_terminal
• xterm
• xterm_256color
• xterm_truecolor
• unknown
• zsh

Note:

• Some items are shell names (like cmd, sh (Bourne Shell), bash, zsh, fish, etc.) because the code's process-title detection maps those as possible values, and the code wasn't able to find a better terminal identifier.
• The names are as returned by the detection methods (i.e., terminal_app, gnome_terminal, etc.) and not the terminal program's real executable names. This approach was taken to avoid confusion with the actual executable names, which can vary across platforms and installations.
• Fallback/auto-generated names (using sanitized env values) are also possible in the code but are not explicitly named in the code.

Terminal Detection

Terminal	Detection (ENV / Process)	Description
Alacritty	ALACRITTY_SOCKET, ALACRITTY_LOG, TERM=alacritty, or TERM_PROGRAM=alacritty	Cross-platform, GPU-accelerated terminal emulator
Apple Terminal	TERM_PROGRAM=Apple_Terminal	macOS default terminal emulator
aterm	TERM=aterm or parent process name	AfterStep terminal emulator
Atomic Terminal	TERM=atomic-terminal or parent process name	Atomic terminal emulator
Cmd.exe	process.title=cmd or COMSPEC=cmd.exe	Windows Command Prompt
Eterm	TERM_PROGRAM=Eterm	Enlightened Terminal Emulator
Foot	TERM=foot* or process.title=foot	Fast, lightweight Wayland terminal emulator
Ghostty	GHOSTTY_RESOURCES_DIR or TERM=ghostty	GPU-accelerated terminal emulator
Gnome Terminal	TERM_PROGRAM=gnome-terminal, TERM_PROGRAM=gnome-terminal-server, VTE_VERSION >= 3803, TERM=gnome*, TERM=guake, or TERM=terminator	GNOME terminal emulator
Hyper	TERM_PROGRAM=Hyper	JS/HTML/CSS terminal emulator
iTerm2	TERM_PROGRAM=iTerm.app or iTerm or iTerm2	Advanced terminal for macOS
Kitty	KITTY_PID, TERM_PROGRAM=kitty, or TERM=kitty	GPU-accelerated terminal emulator
Konsole	TERM_PROGRAM=konsole or environment variables containing "konsole"	KDE terminal emulator
MATE Terminal	TERM_PROGRAM=mate-terminal	MATE terminal emulator
mrxvt	TERM=mrxvt or parent process name	Multi-tabbed rxvt-based terminal emulator
PowerShell	TERM_PROGRAM=powershell, process.title=powershell, process.title=pwsh, or COMSPEC=powershell.exe	Powerful Windows/macOS/Linux shell
PuTTY	TERM_PROGRAM=putty	Popular SSH/Telnet client for Windows
QTerminal	TERM_PROGRAM=qterminal	Lightweight terminal for LXQt
Rio	TERM_PROGRAM=rio or TERM=rio*	GPU-accelerated terminal built in Rust
rxvt/rxvt-unicode	TERM=rxvt* or TERM_PROGRAM=rxvt	Lightweight terminal emulator and its Unicode variant
screen	TERM=screen*	Terminal multiplexer
Terminator	TERM_PROGRAM=terminator	Multiple terminals per window
Terminology	TERM=terminology or parent process name	Enlightenment terminal emulator
Termux	TERM_PROGRAM=termux or TERMUX_VERSION on Android	Android terminal emulator
Tilda	TERM=tilda or parent process name	Drop-down terminal emulator
tmux	TERM=tmux*	Terminal multiplexer
VS Code	TERM_PROGRAM=vscode, VSCODE_PID, or TERM_PROGRAM_VERSION contains vscode	Visual Studio Code integrated terminal
Warp	TERM_PROGRAM=warp	Modern Rust-based terminal
WezTerm	TERM_PROGRAM=wezterm	GPU-accelerated terminal emulator
Windows Terminal	WT_SESSION present or COMSPEC=wt.exe	Modern tabbed terminal for Windows 10+
wterm	TERM=wterm or parent process name	Wterm terminal emulator
Xfce4 Terminal	TERM_PROGRAM=xfce4-terminal	Xfce terminal emulator
Xterm	TERM=xterm, TERM=xterm-256color, or truecolor xterm env values	X Window System terminal emulator
VT100/VT220	TERM=vt100 or TERM=vt220	DEC VT100 and VT220 (and compatible emulators)
Linux Console	TERM=linux	Native Linux virtual console
Dopamine	TERM=dopamine	Modern terminal emulator

Notes:

• Detection uses the TERM and TERM_PROGRAM environment variables, as well as process-level indicators such as process.title on some platforms, to identify the running terminal.
• Terminal-specific environment variables (like KITTY_PID, GHOSTTY_RESOURCES_DIR, ALACRITTY_SOCKET) are checked first as they provide the most reliable detection.
• Variable values are normalized to provide a consistent terminal identifier, regardless of differences in capitalization or formatting.
• detectTerminalDetails() returns metadata about the detection source, TTY/SSH status, color support, raw terminal env values, and parent process info when available.
• When stdout is not a TTY, detection returns none unless unpipe: true is used.
• Some Windows terminals are detected using Windows-specific variables such as COMSPEC or WT_SESSION.
• Terminal multiplexers such as tmux and GNU Screen are identified through the TERM variable when active. Use preferOuter: true to skip multiplexer detection and continue toward the outer terminal.
• When resolveAmbiguousFromParent: true is used, ambiguous env results such as xterm, vt100, truecolor terminals, linux console, or skipped multiplexers can be resolved by walking parent processes.
• When running inside Visual Studio Code's integrated terminal, detection relies on specific environment variables set by VS Code.
• Distinctions are maintained between terminal emulators (e.g., iTerm2, Konsole) and shells (e.g., bash, zsh), with shells excluded from the main detection table.
• In the absence of a recognized terminal, a fallback sanitizer produces a normalized identifier or unknown as a last resort.
• The detection logic is designed to cover terminals across UNIX-like systems (Linux, macOS) and Windows, providing broad compatibility for diverse development environments.

History

v3.0.0

• Added detectTerminalDetails() to return terminal metadata, detection source, TTY/SSH status, color support, raw env values, and parent process info
• Added resolveAmbiguousFromParent option to resolve ambiguous env results by walking parent processes
• Added unpipe option to continue detection when stdout is not currently a TTY
• Added parent-process detection for outer terminal apps, with multiplexer handling that respects preferOuter
• Added color capability reporting with supportsColor, colorLevel, supports256Color, and supportsTrueColor
• Added none terminal result for non-TTY output when unpipe is not enabled
• Added documentation for lower-level env, shell, parent-process, process-title, and color helper APIs
• Added support for additional terminal identifiers including aterm, atomic_terminal, mrxvt, terminology, tilda, and wterm
• Added test and integration options for custom env, stdout, platform, pid, process title, and command execution

v2.0.0

• Added preferOuter option to prefer outermost terminal (GUI app) over multiplexers like tmux/screen
• Added Ghostty terminal detection via GHOSTTY_RESOURCES_DIR environment variable
• Added Foot terminal detection (Wayland terminal emulator)
• Added Rio terminal detection (Rust-based GPU-accelerated terminal)
• Improved Alacritty detection with ALACRITTY_SOCKET and ALACRITTY_LOG environment variables
• Improved Kitty detection with KITTY_PID environment variable (most reliable method)
• Added Linux Console detection via TERM=linux
• Added Dopamine terminal detection
• Reordered detection priority: terminal-specific env vars are now checked before TERM_PROGRAM

v1.1.0

• Improved terminal detection accuracy with more advanced detection methods
• Added VTE_VERSION detection to properly identify GNOME Terminal when it masquerades as xterm
• Implemented environment variable scanning to detect Konsole terminals that advertise as xterm
• Enhanced COLORTERM precedence handling for better terminal identification
• Added macOS path parsing to extract application names from full paths
• Improved Android/Termux detection with TERMUX_VERSION checks
• Enhanced Windows Terminal detection with WT_SESSION prioritization and pwsh support
• Added better error handling with timeouts for shell execution
• Refined process title matching with more precise regex patterns

Related

You might also be interested in:

• cross-capture: Capture screenshots programmatically. Cross-platform, with support for MacOS (Darwin), Windows, and Linux. | homepage
• emit-keypress: Drop-dead simple keypress event emitter for Node.js. Create powerful CLI applications and experiences with ease. | homepage
• enquirer: Stylish, intuitive and user-friendly prompt system. Fast and lightweight enough for small projects, powerful and… more | homepage
• open-file-manager-dialog: Cross-platform library for opening a file manager dialog window programmatically on MacOS, Windows, or Linux. | homepage
• open-file-manager: Cross-platform utility to open a file or directory in the system's default file manager (Finder… more | homepage
• open-finder-dialog: Open a finder dialog window (finder prompt) programmatically. Only works on MacOS. | homepage
• open-linux-file-dialog: Open a file dialog window programmatically to allow the user to select one or more… more | homepage
• open-windows-file-dialog: Programmatically open a file dialog window (explorer) for picking files. Only works on Windows. Also… more | homepage

About

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright 2026, Jon Schlinkert. MIT

---

This file was generated by verb-generate-readme, v0.1.31, on May 12, 2026.