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());
agentDriven
Whether an agent, rather than a person, is running the program.
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).
HelpMenu
A help menu, built a line at a time and answered whole by text.
Style
How one output stream is painted.
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
fdi32requiredthe 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.

