isatty - test if a file descriptor is a terminal

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	shell-multiplexer-auto-attach
Document type	Source Dossier
Tier	1
Source title	isatty - test if a file descriptor is a terminal
Source URL	https://fishshell.com/docs/3.7/cmds/isatty.html
Source publisher / author	fish-shell project (fishshell.com)
Source type	vendor docs
Source date (published)	Unknown — not stated
Date researched	2026-10-10
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	web search synthesis
Confidence	High
Status	Active

Summary

fish ships isatty as its own standalone builtin command (distinct from a test -t primary), accepting either a numeric file descriptor or one of the names stdin/stdout/stderr, defaulting to fd 0 if no argument is given, and returning exit status 0 when the descriptor is a terminal. A dedicated search for whether fish's test builtin itself supports a -t file-descriptor primary (the POSIX test -t equivalent) came back empty across every doc mirror checked — isatty is the only confirmed mechanism for this check in fish.

Key findings

isatty takes a named stream (stdin, stdout, stderr) or a raw fd number; isatty stdin/isatty stdout is the idiomatic way to check both streams, directly mirroring what the bash/zsh plexer block does with [ -t 0 ] && [ -t 1 ].
Exit status 0 means "is a terminal", non-zero means "is not" — same polarity as POSIX test -t, so no inverted-logic trap when porting the bash/zsh condition.
The same behavior is documented identically across every fish doc version mirror checked from 3.2 through 4.5 (the 3.2, 3.3, 3.4, 3.5, 3.6 version pages and the w3cub 4.5 mirror all state the same thing), so this is a long-stable, safe builtin to depend on rather than a recent or version-fragile addition.
fish's test builtin was separately confirmed (via the companion search for a changelog/version-introduction date) to not document a -t primary at all in any version checked; isatty is therefore not an optional shortcut but the only available mechanism for this check in fish.

Pros / strengths

Officially documented, stable across at least five minor versions (3.2–3.6, plus 4.5 via mirror) with word-for-word identical behavior description — a safe primitive to build the plexer hook's tty check on.

Cons / limitations / caveats

Exact version of introduction could not be pinned down (see the separate, explicitly inconclusive isatty-version-changelog search, Tier 1 dossier fishshell-blog-release-3-4-0.md); documented as early as 3.2 in this search, which is more than sufficient for this project's purposes (any fish worth supporting today postdates 3.2 by years) but is a documented gap, not a guess.

Relevance to tai

Directly the basis for FISH_PLEXER_BLOCK in tai.py using isatty stdin and isatty stdout instead of attempting a test -t 0/test -t 1 primary that fish's test builtin does not support.

Changelog

Date	Change
2026-10-10	Initial dossier created.

3.2 KiB Raw Blame History Unescape Escape