nish/cli

A command-line tool's help menu: whether a stream gets colour, the escapes that paint it, and the rows a --help is made of.

import {
  HelpMenu,
  SGR_BG_BLACK,
  SGR_BG_BLUE,
  SGR_BG_BRIGHT_BLACK,
  SGR_BG_BRIGHT_BLUE,
  SGR_BG_BRIGHT_CYAN,
  SGR_BG_BRIGHT_GREEN,
  SGR_BG_BRIGHT_MAGENTA,
  SGR_BG_BRIGHT_RED,
  SGR_BG_BRIGHT_WHITE,
  SGR_BG_BRIGHT_YELLOW,
  SGR_BG_CYAN,
  SGR_BG_GREEN,
  SGR_BG_MAGENTA,
  SGR_BG_RED,
  SGR_BG_WHITE,
  SGR_BG_YELLOW,
  SGR_BLACK,
  SGR_BLUE,
  SGR_BOLD,
  SGR_BRIGHT_BLACK,
  SGR_BRIGHT_BLUE,
  SGR_BRIGHT_CYAN,
  SGR_BRIGHT_GREEN,
  SGR_BRIGHT_MAGENTA,
  SGR_BRIGHT_RED,
  SGR_BRIGHT_WHITE,
  SGR_BRIGHT_YELLOW,
  SGR_CYAN,
  SGR_FAINT,
  SGR_GREEN,
  SGR_INVERSE,
  SGR_ITALIC,
  SGR_MAGENTA,
  SGR_RED,
  SGR_STRIKETHROUGH,
  SGR_UNDERLINE,
  SGR_WHITE,
  SGR_YELLOW,
  Style,
  agentDriven,
  styleFor,
} from "nish/cli";
import { HelpMenu, agentDriven, styleFor } from "nish/cli";

const menu = new HelpMenu(styleFor(1, agentDriven()), "greet", 30, 40);
menu.header("1.0.0", "say hello");
menu.usage("<name> [flags]", "greet someone");
menu.section("Flags");
menu.row("--shout", "", "in capitals");
menu.row("--times", "<n>", "say it n times");
console.log(menu.text());
The terminal's own colours

A Style paints with the sixteen SGR colours (the eight basic ones and their bright twins), their backgrounds and the attributes, never a fixed RGB or 256-palette tone unless the caller asks for one through sgr. Every theme redefines those sixteen, so the menu comes out in whatever palette the reader chose, and a terminal with no theme set paints them in its built-in defaults. A terminal with no colours at all (tput colors says fewer than eight) gets the failsafe: the same structure in bold and underline, which a monochrome terminal still shows, and no colour from a colour painter. Colour that is forced is the theme's.

Colour is for a person reading a terminal

Colour is for a person reading a terminal, and nothing else may see it: a script that captures --help, a test that compares it, a pipe into less without -R all want the plain bytes. So styleFor decides per stream, by asking whether that stream is a terminal, and the conventions people already set win over the guess: NO_COLOR (https://no-color.org) turns it off, and CLICOLOR_FORCE or FORCE_COLOR turns it on for a pager that understands escapes. The plain text is the same bytes either way, and a row's padding is counted on the plain text, so the columns line up with or without escapes.

An agent is a reader of its own kind

it may drive a pseudo-terminal, so the terminal check says yes, but every escape is tokens it pays for and reads past. agentDriven says when one is at the keyboard, and styleFor is then plain whatever forcing variable its shell inherited.

What it reaches

Style and HelpMenu reach no capability. styleFor reads the environment and, on the terminal check, forks a shell (env and process.spawn), and agentDriven reads the environment; a program that builds its Style by hand reaches neither.

The compiler's own help is built with it

The compiler's own help is built with it, through a relative import from src/cli-style.ts, so this file is compiled by the last release as part of the compiler: it may use only what that release compiles (the rolling freeze, .claude/selfhost.md), which is why it asks the shell whether a descriptor is a terminal rather than calling nish:term's isTerminal.

Functions

agentDriven

Whether an agent, rather than a person, is running the program. NISH_AGENT answers for any agent: a no (envSaysNo) for no, any other value for yes. Without it, the variables the agents that set one put in their commands' environment (Claude Code's CLAUDECODE, Gemini CLI's GEMINI_CLI) say yes.

const agentDriven: () => boolean
returnsboolean

true when an agent is judged to be at the keyboard, the answer styleFor's agent takes; it reads the environment afresh each call.

styleFor

The style for descriptor fd (1 or 2), for a reader agent says is an agent or not (agentDriven, asked once by the caller). NO_COLOR wins, then an agent, then FORCE_COLOR saying no (isNo; Node reads 0 and false so), then a forcing variable, then CLICOLOR saying no or TERM=dumb, and only then the terminal check, where the colours TERM declares choose between the theme and the failsafe (paletteOf). Forced colour is the theme's, asked of nothing: the reader is a pager or an editor that renders the escapes itself (Emacs's shell sets TERM=dumb and paints ANSI colour), so TERM does not describe it, and forcing forks nothing.

const styleFor: (fd: i32, agent: boolean) => Style
fdi32required

the descriptor the painted text is written to, 1 for standard output or 2 for standard error; only the terminal check reads it.

agentbooleanrequired

whether the reader is an agent, as agentDriven answered; true gives plain text, whatever forces colour.

returnsStyle

a new Style each call, the caller's to keep and recolour: one that paints the theme, one that paints the failsafe, or one that paints nothing.

Classes

HelpMenu

A help menu, built a line at a time and answered whole by text. Rows are indented two columns and their descriptions start at column; usage lines' descriptions start at usageColumn, past the longest command shape. Every width is counted on the plain text, one column a byte, so the columns line up whether or not style paints, as long as the text is ASCII.

class HelpMenu
Member
new HelpMenu(style: Style, program: string, column: i32, usageColumn: i32) An empty menu; nothing is written until text is asked for.
header(version: string, summary: string): void The opening line, the program's name, version and a one-line summary, and a blank after it.
line(text: string): void A line exactly as given, painted (or not) by the caller with the menu's style: a rule, a banner, a blank. Its width is the caller's to keep.
note(text: string): void An indented line of prose, faint.
row(flag: string, meta: string, description: string): void One row: the flag (or a command), its placeholder meta (may be empty), and what it does, the description starting at column.
section(title: string): void A section: a blank line, then title as a heading.
text(): string The menu so far, its lines joined by newlines, with no newline after the last.
title(version: string, summary: string): void The opening line alone, without header's blank after it, for a menu that puts something under its title (line) before the blank.
usage(shape: string, description: string): void A usage line: the command shape after the program's name, and what it is for (description may be empty). The first opens with usage: and the rest are indented under it.
value(text: string): void An indented line the reader fills in or opens, a path or a value, as a placeholder.

Style

How one output stream is painted. on says whether to mark the text up at all, and colour whether the terminal has colours to mark it up with; without them each mark falls back to bold, underline or nothing.

Each help role (heading, name, flag, meta, dim) keeps a pair of SGR lists, the theme's and the failsafe's, so a program recolours its menu by setting a pair (flagThemed, flagMono) and styleFor still decides whether, and which of the two, it paints. An empty list leaves the role plain.

class Style
Member
new Style(on: boolean, colour: boolean) A style with every role at its default pair. styleFor builds the right one for a stream; a program calls this to decide for itself.
dimMono: string The SGR list dim paints descriptions and notes with on the failsafe, where the terminal has no colours: empty, so plain, unless set.
dimThemed: string The SGR list dim paints descriptions and notes with when the terminal has colours: faint (SGR_FAINT) unless the program sets another.
flagMono: string The SGR list flag paints a flag or command with on the failsafe, where the terminal has no colours: bold (SGR_BOLD) unless set.
flagThemed: string The SGR list flag paints a flag or command with when the terminal has colours: cyan (SGR_CYAN) unless the program sets another.
headingMono: string The SGR list heading paints a section heading with on the failsafe, where the terminal has no colours: bold (SGR_BOLD) unless set.
headingThemed: string The SGR list heading paints a section heading with when the terminal has colours: bold magenta ("1;35") unless the program sets another.
metaMono: string The SGR list meta paints a placeholder with on the failsafe, where the terminal has no colours: underline (SGR_UNDERLINE) unless set.
metaThemed: string The SGR list meta paints a placeholder with when the terminal has colours: yellow (SGR_YELLOW) unless the program sets another.
nameMono: string The SGR list name paints the tool's own name with on the failsafe, where the terminal has no colours: bold (SGR_BOLD) unless set.
nameThemed: string The SGR list name paints the tool's own name with when the terminal has colours: bold magenta ("1;35") unless the program sets another.
bgBlack(text: string): string text on the theme's black (SGR_BG_BLACK).
bgBlue(text: string): string text on the theme's blue (SGR_BG_BLUE).
bgBrightBlack(text: string): string text on the theme's bright black (SGR_BG_BRIGHT_BLACK).
bgBrightBlue(text: string): string text on the theme's bright blue (SGR_BG_BRIGHT_BLUE).
bgBrightCyan(text: string): string text on the theme's bright cyan (SGR_BG_BRIGHT_CYAN).
bgBrightGreen(text: string): string text on the theme's bright green (SGR_BG_BRIGHT_GREEN).
bgBrightMagenta(text: string): string text on the theme's bright magenta (SGR_BG_BRIGHT_MAGENTA).
bgBrightRed(text: string): string text on the theme's bright red (SGR_BG_BRIGHT_RED).
bgBrightWhite(text: string): string text on the theme's bright white (SGR_BG_BRIGHT_WHITE).
bgBrightYellow(text: string): string text on the theme's bright yellow (SGR_BG_BRIGHT_YELLOW).
bgCyan(text: string): string text on the theme's cyan (SGR_BG_CYAN).
bgGreen(text: string): string text on the theme's green (SGR_BG_GREEN).
bgMagenta(text: string): string text on the theme's magenta (SGR_BG_MAGENTA).
bgRed(text: string): string text on the theme's red (SGR_BG_RED).
bgWhite(text: string): string text on the theme's white (SGR_BG_WHITE).
bgYellow(text: string): string text on the theme's yellow (SGR_BG_YELLOW).
black(text: string): string text in the theme's black (SGR_BLACK).
blue(text: string): string text in the theme's blue (SGR_BLUE).
bold(text: string): string text bold (SGR_BOLD), under the failsafe too.
brightBlack(text: string): string text in the theme's bright black, a gray (SGR_BRIGHT_BLACK).
brightBlue(text: string): string text in the theme's bright blue (SGR_BRIGHT_BLUE).
brightCyan(text: string): string text in the theme's bright cyan (SGR_BRIGHT_CYAN).
brightGreen(text: string): string text in the theme's bright green (SGR_BRIGHT_GREEN).
brightMagenta(text: string): string text in the theme's bright magenta (SGR_BRIGHT_MAGENTA).
brightRed(text: string): string text in the theme's bright red (SGR_BRIGHT_RED).
brightWhite(text: string): string text in the theme's bright white (SGR_BRIGHT_WHITE).
brightYellow(text: string): string text in the theme's bright yellow (SGR_BRIGHT_YELLOW).
cyan(text: string): string text in the theme's cyan (SGR_CYAN).
dim(text: string): string Text that explains rather than names, such as descriptions and notes, in dimThemed or dimMono.
faint(text: string): string text faint (SGR_FAINT), under the failsafe too.
flag(text: string): string A flag, or a command a person would type, in flagThemed or flagMono.
green(text: string): string text in the theme's green (SGR_GREEN).
heading(text: string): string A section heading, in headingThemed or headingMono.
inverse(text: string): string text with foreground and background swapped (SGR_INVERSE), under the failsafe too.
italic(text: string): string text italic (SGR_ITALIC), where the terminal has it, under the failsafe too.
magenta(text: string): string text in the theme's magenta (SGR_MAGENTA).
meta(text: string): string A placeholder the person fills in, such as <file.ts> or speed|size, in metaThemed or metaMono.
name(text: string): string The tool's own name where it opens a line, in nameThemed or nameMono.
red(text: string): string text in the theme's red (SGR_RED).
sgr(text: string, codes: string): string text painted with any SGR parameter list ("1;31", "38;5;208", "38;2;255;128;0") when colour is on, and unchanged otherwise: the way to 256-colour and truecolor, which ignore the reader's theme, so they stay the caller's explicit choice. The failsafe paints nothing, since the list may name a colour a monochrome terminal cannot show.
strikethrough(text: string): string text struck through (SGR_STRIKETHROUGH), under the failsafe too.
underline(text: string): string text underlined (SGR_UNDERLINE), under the failsafe too.
white(text: string): string text in the theme's white (SGR_WHITE).
yellow(text: string): string text in the theme's yellow (SGR_YELLOW).

Constants

"40"

SGR_BG_BLACK: string

The SGR parameter for the theme's black as the background.

"44"

SGR_BG_BLUE: string

The SGR parameter for the theme's blue as the background.

"100"

SGR_BG_BRIGHT_BLACK: string

The SGR parameter for the theme's bright black as the background.

"104"

SGR_BG_BRIGHT_BLUE: string

The SGR parameter for the theme's bright blue as the background.

"106"

SGR_BG_BRIGHT_CYAN: string

The SGR parameter for the theme's bright cyan as the background.

"102"

SGR_BG_BRIGHT_GREEN: string

The SGR parameter for the theme's bright green as the background.

"105"

SGR_BG_BRIGHT_MAGENTA: string

The SGR parameter for the theme's bright magenta as the background.

"101"

SGR_BG_BRIGHT_RED: string

The SGR parameter for the theme's bright red as the background.

"107"

SGR_BG_BRIGHT_WHITE: string

The SGR parameter for the theme's bright white as the background.

"103"

SGR_BG_BRIGHT_YELLOW: string

The SGR parameter for the theme's bright yellow as the background.

"46"

SGR_BG_CYAN: string

The SGR parameter for the theme's cyan as the background.

"42"

SGR_BG_GREEN: string

The SGR parameter for the theme's green as the background.

"45"

SGR_BG_MAGENTA: string

The SGR parameter for the theme's magenta as the background.

"41"

SGR_BG_RED: string

The SGR parameter for the theme's red as the background.

"47"

SGR_BG_WHITE: string

The SGR parameter for the theme's white as the background.

"43"

SGR_BG_YELLOW: string

The SGR parameter for the theme's yellow as the background.

"30"

SGR_BLACK: string

The SGR parameter for the theme's black as the text colour.

"34"

SGR_BLUE: string

The SGR parameter for the theme's blue as the text colour.

"1"

SGR_BOLD: string

The SGR parameter for bold, or increased intensity.

"90"

SGR_BRIGHT_BLACK: string

The SGR parameter for the theme's bright black (gray) as the text colour.

"94"

SGR_BRIGHT_BLUE: string

The SGR parameter for the theme's bright blue as the text colour.

"96"

SGR_BRIGHT_CYAN: string

The SGR parameter for the theme's bright cyan as the text colour.

"92"

SGR_BRIGHT_GREEN: string

The SGR parameter for the theme's bright green as the text colour.

"95"

SGR_BRIGHT_MAGENTA: string

The SGR parameter for the theme's bright magenta as the text colour.

"91"

SGR_BRIGHT_RED: string

The SGR parameter for the theme's bright red as the text colour.

"97"

SGR_BRIGHT_WHITE: string

The SGR parameter for the theme's bright white as the text colour.

"93"

SGR_BRIGHT_YELLOW: string

The SGR parameter for the theme's bright yellow as the text colour.

"36"

SGR_CYAN: string

The SGR parameter for the theme's cyan as the text colour.

"2"

SGR_FAINT: string

The SGR parameter for faint, or decreased intensity.

"32"

SGR_GREEN: string

The SGR parameter for the theme's green as the text colour.

"7"

SGR_INVERSE: string

The SGR parameter for inverse: foreground and background swapped.

"3"

SGR_ITALIC: string

The SGR parameter for italic, which some terminals do not show.

"35"

SGR_MAGENTA: string

The SGR parameter for the theme's magenta as the text colour.

"31"

SGR_RED: string

The SGR parameter for the theme's red as the text colour.

"9"

SGR_STRIKETHROUGH: string

The SGR parameter for struck through.

"4"

SGR_UNDERLINE: string

The SGR parameter for underline.

"37"

SGR_WHITE: string

The SGR parameter for the theme's white as the text colour.

"33"

SGR_YELLOW: string

The SGR parameter for the theme's yellow as the text colour.