@evantahler/mcpx 0.21.6 → 0.21.8

package/.claude/skills/mcpx.md

@@ -199,6 +199,8 @@ mcpx deauth <server>           # remove stored auth
 | `-d, --with-descriptions`   | Include tool descriptions in list output                 |
 | `-c, --config <path>`       | Specify config file location                             |
 | `-N, --no-interactive`      | Decline server elicitation requests (for scripted usage) |
+| `--no-color`                | Disable ANSI colors (also honored via `NO_COLOR=1`)      |
+| `--force-color`             | Force ANSI colors even when piped (also `FORCE_COLOR=1`) |
 | `-S, --show-secrets`        | Show full auth tokens in verbose output (unmasked)       |
 | `-l, --log-level <level>`   | Minimum server log level to display (default: `warning`) |
 

package/.cursor/rules/mcpx.mdc

@@ -193,6 +193,8 @@ mcpx deauth <server>           # remove stored auth
 | `-d, --with-descriptions`   | Include tool descriptions in list output                 |
 | `-c, --config <path>`       | Specify config file location                             |
 | `-N, --no-interactive`      | Decline server elicitation requests (for scripted usage) |
+| `--no-color`                | Disable ANSI colors (also honored via `NO_COLOR=1`)      |
+| `--force-color`             | Force ANSI colors even when piped (also `FORCE_COLOR=1`) |
 | `-S, --show-secrets`        | Show full auth tokens in verbose output (unmasked)       |
 | `-l, --log-level <level>`   | Minimum server log level to display (default: `warning`) |
 

package/README.md

@@ -134,8 +134,24 @@ mcpx search -n 5 "manage pull requests"
 | `-j, --json`              | Force JSON output (default when piped)                   |
 | `-F, --format <format>`   | Output format: `json` or `markdown`                      |
 | `-N, --no-interactive`    | Decline server elicitation requests (for scripted usage) |
+| `--no-color`              | Disable ANSI colors in output                            |
+| `--force-color`           | Force ANSI colors even when piped                        |
 | `-l, --log-level <level>` | Minimum server log level to display (default: `warning`) |
 
+### Output & colors
+
+mcpx auto-detects whether stdout/stderr are interactive and adapts:
+
+- TTY → colored, formatted output (tables, headers, badges).
+- Non-TTY / piped → JSON.
+
+Color emission honors the standard env vars and matching flags:
+
+- `NO_COLOR=1` or `--no-color` — disable ANSI colors.
+- `FORCE_COLOR=1` or `--force-color` — enable ANSI colors even when piped.
+- `--json` / `-j` — JSON output, no colors.
+- `CI=true` — treated as non-interactive (spinners off).
+
 Server log messages (`notifications/message`) are displayed on stderr with level-appropriate coloring. Valid levels (in ascending severity): `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`. When a server declares logging capability, mcpx sends `logging/setLevel` to request messages at the configured threshold and above.
 
 ## Managing Servers

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@evantahler/mcpx",
-	"version": "0.21.6",
+	"version": "0.21.8",
 	"description": "A command-line interface for MCP servers. curl for MCP.",
 	"type": "module",
 	"exports": {
@@ -60,8 +60,5 @@
 		"@biomejs/biome": "^2.4.14",
 		"@types/bun": "latest",
 		"typescript": "^6"
-	},
-	"peerDependencies": {
-		"typescript": "^6"
 	}
 }

package/src/cli.ts

@@ -1,6 +1,10 @@
 #!/usr/bin/env bun
 
-import { bold, cyan, dim, green, yellow } from "ansis";
+// MUST be first: translates --no-color / --json / --force-color argv flags into
+// NO_COLOR / FORCE_COLOR env vars before any ansis-using module loads. ansis
+// decides its color level at module load and cannot be reconfigured afterwards.
+import "./output/early-env.ts";
+
 import { program } from "commander";
 import pkg from "../package.json";
 import { registerAddCommand } from "./commands/add.ts";
@@ -22,11 +26,27 @@ import { registerSkillCommand } from "./commands/skill.ts";
 import { registerTaskCommand } from "./commands/task.ts";
 import { registerUpgradeCommand } from "./commands/upgrade.ts";
 import { logger } from "./output/logger.ts";
+import { theme } from "./output/theme.ts";
+import { detectMode, setMode } from "./output/tty.ts";
 import { ExitError, installSignalHandlers } from "./shutdown.ts";
 import { maybeCheckForUpdate } from "./update/background.ts";
 
 installSignalHandlers();
 
+// Resolve output mode (TTY/color/json/verbose) from env + raw argv before
+// commander parses anything, so the help screen and any early prints honor
+// --no-color / --json / NO_COLOR / FORCE_COLOR. The mode is frozen via setMode
+// and propagated to ansis.level so direct ansis calls also respect it.
+const rawArgv = process.argv.slice(2);
+setMode(
+	detectMode({
+		json: rawArgv.includes("--json") || rawArgv.includes("-j"),
+		verbose: rawArgv.includes("--verbose") || rawArgv.includes("-v"),
+		noColor: rawArgv.includes("--no-color"),
+		forceColor: rawArgv.includes("--force-color"),
+	}),
+);
+
 program
 	.name("mcpx")
 	.description("A command-line interface for MCP servers. curl for MCP.")
@@ -38,6 +58,8 @@ program
 	.option("-v, --verbose", "show HTTP details and JSON-RPC protocol messages")
 	.option("-S, --show-secrets", "show full auth tokens in verbose output")
 	.option("-N, --no-interactive", "decline server elicitation requests")
+	.option("--no-color", "disable ANSI color output (also honored via NO_COLOR=1)")
+	.option("--force-color", "force ANSI color output even when piped (also honored via FORCE_COLOR=1)")
 	.option(
 		"-l, --log-level <level>",
 		"minimum server log level (debug|info|notice|warning|error|critical|alert|emergency)",
@@ -45,12 +67,12 @@ program
 	);
 
 program.configureHelp({
-	styleTitle: (str) => bold(str),
-	styleCommandText: (str) => cyan(str),
-	styleSubcommandText: (str) => cyan(str),
-	styleOptionText: (str) => yellow(str),
-	styleArgumentText: (str) => green(str),
-	styleDescriptionText: (str) => dim(str),
+	styleTitle: (str) => theme.tool(str),
+	styleCommandText: (str) => theme.path(str),
+	styleSubcommandText: (str) => theme.path(str),
+	styleOptionText: (str) => theme.warn(str),
+	styleArgumentText: (str) => theme.param(str),
+	styleDescriptionText: (str) => theme.muted(str),
 });
 
 registerListCommand(program);
@@ -88,7 +110,7 @@ for (let i = 0; i < cliArgs.length; i++) {
 	break;
 }
 if (firstCommand && !knownCommands.has(firstCommand)) {
-	console.error(`error: unknown command '${firstCommand}'. See 'mcpx --help'.`);
+	logger.error(`error: unknown command '${firstCommand}'. See 'mcpx --help'.`);
 	process.exit(1);
 }
 

package/src/client/trace.ts

@@ -1,7 +1,7 @@
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
-import { cyan, dim, green, red, yellow } from "ansis";
 import { logger } from "../output/logger.ts";
+import { glyph, theme } from "../output/theme.ts";
 
 export interface TraceOptions {
 	json: boolean;
@@ -70,14 +70,14 @@ function logOutgoing(
 
 	if ("id" in message && "method" in message) {
 		const m = message as { id: string | number; method: string; params?: unknown };
-		const arrow = isTTY ? cyan("→") : "→";
+		const arrow = isTTY ? glyph.arrowOut : "→";
 		const detail = summarizeParams(m.method, m.params);
 		const detailStr = detail ? ` ${detail}` : "";
-		logger.writeRaw(`${arrow} ${dim(`${m.method} (id: ${m.id})${detailStr}`)}\n`);
+		logger.writeRaw(`${arrow} ${theme.muted(`${m.method} (id: ${m.id})${detailStr}`)}\n`);
 	} else if ("method" in message) {
 		const m = message as { method: string };
-		const arrow = isTTY ? cyan("→") : "→";
-		logger.writeRaw(`${arrow} ${dim(m.method)}\n`);
+		const arrow = isTTY ? glyph.arrowOut : "→";
+		logger.writeRaw(`${arrow} ${theme.muted(m.method)}\n`);
 	}
 }
 
@@ -109,11 +109,11 @@ function logIncoming(
 		}
 
 		const isError = m.error !== undefined;
-		const arrow = isTTY ? (isError ? red("←") : green("←")) : "←";
+		const arrow = isTTY ? (isError ? glyph.arrowErr : glyph.arrowIn) : "←";
 		const timing = elapsed !== undefined ? ` [${elapsed}ms]` : "";
 		const summary = summarizeResult(method, m.result);
 		const summaryStr = summary ? ` — ${summary}` : "";
-		logger.writeRaw(`${arrow} ${dim(`${method} (id: ${m.id})${timing}${summaryStr}`)}\n`);
+		logger.writeRaw(`${arrow} ${theme.muted(`${method} (id: ${m.id})${timing}${summaryStr}`)}\n`);
 	} else if ("method" in message) {
 		// Notification (incoming)
 		const m = message as { method: string; params?: unknown };
@@ -123,9 +123,9 @@ function logIncoming(
 			return;
 		}
 
-		const arrow = isTTY ? yellow("←") : "←";
+		const arrow = isTTY ? glyph.arrowNote : "←";
 		const params = m.params ? ` ${JSON.stringify(m.params)}` : "";
-		logger.writeRaw(`${arrow} ${dim(`${m.method}${params}`)}\n`);
+		logger.writeRaw(`${arrow} ${theme.muted(`${m.method}${params}`)}\n`);
 	}
 }
 

package/src/context.ts

@@ -38,7 +38,7 @@ export async function getContext(program: Command): Promise<AppContext> {
 
 	const formatFlag = opts.format as string | undefined;
 	if (formatFlag && !VALID_FORMATS.includes(formatFlag as OutputFormat)) {
-		console.error(`error: Invalid format "${formatFlag}". Use: ${VALID_FORMATS.join(", ")}`);
+		logger.error(`error: Invalid format "${formatFlag}". Use: ${VALID_FORMATS.join(", ")}`);
 		process.exit(1);
 	}
 	const format = formatFlag as OutputFormat | undefined;

package/src/output/early-env.ts

@@ -0,0 +1,26 @@
+/**
+ * Early env munging — MUST be imported FIRST in src/cli.ts, before any other
+ * module that pulls in ansis (transitively or directly). ansis decides its
+ * color level at module load by inspecting NO_COLOR / FORCE_COLOR / TTY, and
+ * the decision cannot be changed afterwards. So we translate --no-color /
+ * --json / --force-color command-line flags into env vars here, before ansis
+ * loads.
+ */
+
+const argv = process.argv.slice(2);
+const hasFlag = (flag: string): boolean => argv.includes(flag);
+const hasFlagOr = (flags: readonly string[]): boolean => flags.some((f) => argv.includes(f));
+
+if (hasFlag("--no-color") || hasFlagOr(["--json", "-j"])) {
+	// Setting NO_COLOR to any non-empty string disables ansis colors.
+	// (We do not touch NO_COLOR if it was already set externally.)
+	if (!process.env.NO_COLOR || process.env.NO_COLOR === "") {
+		process.env.NO_COLOR = "1";
+	}
+}
+
+if (hasFlag("--force-color")) {
+	if (!process.env.FORCE_COLOR || process.env.FORCE_COLOR === "") {
+		process.env.FORCE_COLOR = "1";
+	}
+}

package/src/output/format-output.ts

@@ -1,5 +1,11 @@
 import type { FormatOptions } from "./formatter.ts";
-import { isInteractive } from "./formatter.ts";
+import { isInteractive as ttyIsInteractive } from "./tty.ts";
+
+/** TTY-aware interactivity check, with an explicit JSON override. */
+function isInteractive(options: FormatOptions): boolean {
+	if (options.json) return false;
+	return ttyIsInteractive();
+}
 
 /**
  * Format output with automatic JSON/interactive branching.

package/src/output/format-table.ts

@@ -1,5 +1,6 @@
-import ansis, { dim } from "ansis";
+import ansis from "ansis";
 import { wrapDescription } from "./formatter.ts";
+import { theme } from "./theme.ts";
 
 export interface Column<T> {
 	value: (item: T) => string;
@@ -29,28 +30,30 @@ function getTerminalWidth(): number | undefined {
  */
 export function formatTable<T>(items: T[], options: TableOptions<T>): string {
 	if (items.length === 0) {
-		return dim(options.emptyMessage ?? "No items found");
+		return theme.muted(options.emptyMessage ?? "No items found");
 	}
 
 	const sep = options.separator ?? "  ";
 	const termWidth = getTerminalWidth();
 
-	// Calculate max width for each column
-	const maxWidths = options.columns.map((col) => Math.max(...items.map((item) => col.value(item).length)));
+	// Calculate max width for each column (account for any ANSI from the value
+	// fn — though most value fns return plain strings, theme.pill* return ANSI).
+	const maxWidths = options.columns.map((col) => Math.max(...items.map((item) => visibleLength(col.value(item)))));
 
 	return items
 		.map((item) => {
 			const parts = options.columns.map((col, i) => {
 				const raw = col.value(item);
-				const pad = maxWidths[i]! - raw.length;
-				return col.style(raw) + " ".repeat(Math.max(0, pad));
+				const styled = col.style(raw);
+				const pad = (maxWidths[i] ?? 0) - visibleLength(raw);
+				return styled + " ".repeat(Math.max(0, pad));
 			});
 			const prefix = parts.join(sep);
 
 			const desc = options.description?.(item);
 			if (desc) {
 				const pw = visibleLength(prefix) + sep.length;
-				const formatted = termWidth != null ? wrapDescription(desc, pw, termWidth) : dim(desc);
+				const formatted = termWidth != null ? wrapDescription(desc, pw, termWidth) : theme.muted(desc);
 				return `${prefix}${sep}${formatted}`;
 			}
 

package/src/output/formatter.ts

@@ -1,10 +1,12 @@
-import ansis, { bold, cyan, dim, green, red, yellow } from "ansis";
+import ansis from "ansis";
 import type { PromptWithServer, ResourceWithServer, ToolWithServer } from "../client/manager.ts";
 import type { Prompt, Resource, Tool } from "../config/schemas.ts";
 import type { SearchResult } from "../search/index.ts";
 import type { ValidationError } from "../validation/schema.ts";
 import { formatOutput } from "./format-output.ts";
 import { formatTable } from "./format-table.ts";
+import { glyph, theme, underline } from "./theme.ts";
+import { isInteractive as ttyIsInteractive } from "./tty.ts";
 
 export const VALID_FORMATS = ["json", "markdown"] as const;
 
@@ -29,7 +31,7 @@ export interface UnifiedItem {
 /** Check if stdout is a TTY (interactive terminal) */
 export function isInteractive(options: FormatOptions): boolean {
 	if (options.json) return false;
-	return process.stdout.isTTY ?? false;
+	return ttyIsInteractive();
 }
 
 /** Get terminal width, or undefined if not a TTY. Subtracts 1 for safety margin. */
@@ -77,8 +79,8 @@ function wrapLines(text: string, maxWidth: number): string[] {
 
 /**
  * Word-wrap a description string to fit within the available terminal width.
- * Returns dim()-wrapped text with continuation lines indented to prefixWidth.
- * @param text - raw description text (before dim())
+ * Returns theme.muted()-wrapped text with continuation lines indented to prefixWidth.
+ * @param text - raw description text (before theme.muted())
  * @param prefixWidth - visible character width of everything before the description
  * @param termWidth - terminal width in columns
  */
@@ -90,16 +92,16 @@ export function wrapDescription(text: string, prefixWidth: number, termWidth: nu
 		const fallbackIndent = Math.min(prefixWidth, 4);
 		const fallbackAvail = termWidth - fallbackIndent;
 		if (fallbackAvail < 20) {
-			return dim(text.length > termWidth ? `${text.slice(0, termWidth - 3)}...` : text);
+			return theme.muted(text.length > termWidth ? `${text.slice(0, termWidth - 3)}...` : text);
 		}
 		const wrapped = wrapLines(text, fallbackAvail);
 		const indent = " ".repeat(fallbackIndent);
-		return wrapped.map((l) => `\n${indent}${dim(l)}`).join("");
+		return wrapped.map((l) => `\n${indent}${theme.muted(l)}`).join("");
 	}
 
 	const wrapped = wrapLines(text, available);
 	const indent = " ".repeat(prefixWidth);
-	return wrapped.map((l, i) => (i === 0 ? dim(l) : `\n${indent}${dim(l)}`)).join("");
+	return wrapped.map((l, i) => (i === 0 ? theme.muted(l) : `\n${indent}${theme.muted(l)}`)).join("");
 }
 
 export interface ServerOverview {
@@ -129,47 +131,55 @@ export function formatServerOverview(overview: ServerOverview, options: FormatOp
 		() => {
 			const lines: string[] = [];
 
-			// Header: server name + version
-			const header = cyan.bold(overview.serverName);
+			// Header: server name + version, with a dim underline
+			const header = theme.server(overview.serverName);
+			let headerLine: string;
+			let headerVisible: number;
 			if (overview.version) {
-				lines.push(`${header}  ${dim(`v${overview.version.version}`)}  ${dim(`(${overview.version.name})`)}`);
+				const versionStr = `v${overview.version.version}`;
+				const nameStr = `(${overview.version.name})`;
+				headerLine = `${header}  ${theme.muted(versionStr)}  ${theme.muted(nameStr)}`;
+				headerVisible = overview.serverName.length + 2 + versionStr.length + 2 + nameStr.length;
 			} else {
-				lines.push(header);
+				headerLine = header;
+				headerVisible = overview.serverName.length;
 			}
+			lines.push(headerLine);
+			lines.push(underline(headerVisible));
 
 			// Capabilities
 			if (overview.capabilities) {
 				lines.push("");
-				lines.push(bold("Capabilities:"));
+				lines.push(theme.tool("Capabilities:"));
 				const caps = overview.capabilities;
 				const present = KNOWN_CAPABILITIES.filter((k) => k in caps);
 				const absent = KNOWN_CAPABILITIES.filter((k) => !(k in caps));
-				for (const k of present) lines.push(`  ${green("✓")} ${k}`);
-				for (const k of absent) lines.push(`  ${dim("✗")} ${dim(k)}`);
+				for (const k of present) lines.push(`  ${glyph.ok} ${k}`);
+				for (const k of absent) lines.push(`  ${theme.muted("✗")} ${theme.muted(k)}`);
 			}
 
 			// Instructions
 			if (overview.instructions) {
 				lines.push("");
-				lines.push(bold("Instructions:"));
-				lines.push(`  ${dim(overview.instructions)}`);
+				lines.push(theme.tool("Instructions:"));
+				lines.push(`  ${theme.muted(overview.instructions)}`);
 			}
 
 			// Tools
 			lines.push("");
 			if (overview.tools.length === 0) {
-				lines.push(`${bold("Tools:")} ${dim("none")}`);
+				lines.push(`${theme.tool("Tools:")} ${theme.muted("none")}`);
 			} else {
-				lines.push(bold(`Tools (${overview.tools.length}):`));
+				lines.push(theme.tool(`Tools (${overview.tools.length}):`));
 				const maxName = Math.max(...overview.tools.map((t) => t.name.length));
 				const termWidth = getTerminalWidth();
 				for (let i = 0; i < overview.tools.length; i++) {
 					const t = overview.tools[i]!;
 					if (i > 0) lines.push("");
-					const name = `  ${bold(t.name.padEnd(maxName))}`;
+					const name = `  ${theme.tool(t.name.padEnd(maxName))}`;
 					if (t.description) {
 						const pw = visibleLength(name) + 2;
-						const desc = termWidth != null ? wrapDescription(t.description, pw, termWidth) : dim(t.description);
+						const desc = termWidth != null ? wrapDescription(t.description, pw, termWidth) : theme.muted(t.description);
 						lines.push(`${name}  ${desc}`);
 					} else {
 						lines.push(name);
@@ -182,7 +192,7 @@ export function formatServerOverview(overview: ServerOverview, options: FormatOp
 			counts.push(`Resources: ${overview.resourceCount}`);
 			counts.push(`Prompts: ${overview.promptCount}`);
 			lines.push("");
-			lines.push(dim(counts.join(" | ")));
+			lines.push(theme.muted(counts.join(" | ")));
 
 			return lines.join("\n");
 		},
@@ -201,8 +211,8 @@ export function formatToolList(tools: ToolWithServer[], options: FormatOptions):
 		() =>
 			formatTable(tools, {
 				columns: [
-					{ value: (t) => t.server, style: cyan },
-					{ value: (t) => t.tool.name, style: bold },
+					{ value: (t) => t.server, style: theme.path },
+					{ value: (t) => t.tool.name, style: theme.tool },
 				],
 				description: options.withDescriptions ? (t) => t.tool.description : undefined,
 				emptyMessage: "No tools found",
@@ -220,11 +230,11 @@ export function formatServerTools(serverName: string, tools: Tool[], options: Fo
 		},
 		() => {
 			if (tools.length === 0) {
-				return dim(`No tools found for ${serverName}`);
+				return theme.muted(`No tools found for ${serverName}`);
 			}
-			const header = cyan.bold(serverName);
+			const header = theme.server(serverName);
 			const body = formatTable(tools, {
-				columns: [{ value: (t) => `  ${t.name}`, style: bold }],
+				columns: [{ value: (t) => `  ${t.name}`, style: theme.tool }],
 				description: (t) => t.description,
 			});
 			return `${header}\n${body}`;
@@ -244,10 +254,12 @@ export function formatToolSchema(serverName: string, tool: Tool, options: Format
 		},
 		() => {
 			const lines: string[] = [];
-			lines.push(`${cyan(serverName)}/${bold(tool.name)}`);
-			if (tool.description) lines.push(dim(tool.description));
+			const headerText = `${serverName}/${tool.name}`;
+			lines.push(`${theme.path(serverName)}/${theme.tool(tool.name)}`);
+			lines.push(underline(headerText.length));
+			if (tool.description) lines.push(theme.muted(tool.description));
 			lines.push("");
-			lines.push(bold("Input Schema:"));
+			lines.push(theme.tool("Input Schema:"));
 			lines.push(formatSchema(tool.inputSchema, 2));
 			return lines.join("\n");
 		},
@@ -262,16 +274,16 @@ function formatSchema(schema: Tool["inputSchema"], indent: number): string {
 	const required = new Set(schema.required ?? []);
 
 	if (Object.keys(properties).length === 0) {
-		return `${pad}${dim("(no parameters)")}`;
+		return `${pad}${theme.muted("(no parameters)")}`;
 	}
 
 	return Object.entries(properties)
 		.map(([name, prop]) => {
 			const p = prop as Record<string, unknown>;
 			const type = (p.type as string) ?? "any";
-			const req = required.has(name) ? red("*") : "";
-			const desc = p.description ? `  ${dim(String(p.description))}` : "";
-			return `${pad}${green(name)}${req} ${dim(`(${type})`)}${desc}`;
+			const req = required.has(name) ? theme.error("*") : "";
+			const desc = p.description ? `  ${theme.muted(String(p.description))}` : "";
+			return `${pad}${theme.success(name)}${req} ${theme.muted(`(${type})`)}${desc}`;
 		})
 		.join("\n");
 }
@@ -288,15 +300,17 @@ export function formatToolHelp(serverName: string, tool: Tool, options: FormatOp
 		},
 		() => {
 			const lines: string[] = [];
-			lines.push(`${cyan(serverName)}/${bold(tool.name)}`);
-			if (tool.description) lines.push(dim(tool.description));
+			const headerText = `${serverName}/${tool.name}`;
+			lines.push(`${theme.path(serverName)}/${theme.tool(tool.name)}`);
+			lines.push(underline(headerText.length));
+			if (tool.description) lines.push(theme.muted(tool.description));
 			lines.push("");
-			lines.push(bold("Parameters:"));
+			lines.push(theme.tool("Parameters:"));
 			lines.push(formatSchema(tool.inputSchema, 2));
 			const example = generateExample(tool.inputSchema);
 			lines.push("");
-			lines.push(bold("Example:"));
-			lines.push(dim(`  mcpx call ${serverName} ${tool.name} '${JSON.stringify(example)}'`));
+			lines.push(theme.tool("Example:"));
+			lines.push(theme.muted(`  mcpx call ${serverName} ${tool.name} '${JSON.stringify(example)}'`));
 			return lines.join("\n");
 		},
 		options,
@@ -458,7 +472,7 @@ function resetUrlPlaceholders(): void {
 
 function restoreUrlPlaceholders(ansiOutput: string): string {
 	for (const [token, url] of urlMap) {
-		ansiOutput = ansiOutput.replace(token, `\x1b[34m\x1b[4m${url}\x1b[24m\x1b[39m`);
+		ansiOutput = ansiOutput.replace(token, theme.url(url));
 	}
 	return ansiOutput;
 }
@@ -675,8 +689,8 @@ export function formatValidationErrors(
 	return formatOutput(
 		{ error: "validation", server: serverName, tool: toolName, details: errors },
 		() => {
-			const header = `${red("error:")} invalid arguments for ${cyan(serverName)}/${bold(toolName)}`;
-			const details = errors.map((e) => `  ${yellow(e.path)}: ${e.message}`).join("\n");
+			const header = `${glyph.fail} ${theme.error("error:")} invalid arguments for ${theme.path(serverName)}/${theme.tool(toolName)}`;
+			const details = errors.map((e) => `  ${theme.warn(e.path)}: ${e.message}`).join("\n");
 			return `${header}\n${details}`;
 		},
 		options,
@@ -689,7 +703,7 @@ export function formatSearchResults(results: SearchResult[], options: FormatOpti
 		results,
 		() => {
 			if (results.length === 0) {
-				return dim("No matching tools found");
+				return theme.muted("No matching tools found");
 			}
 
 			const termWidth = getTerminalWidth();
@@ -697,14 +711,14 @@ export function formatSearchResults(results: SearchResult[], options: FormatOpti
 
 			return results
 				.map((r) => {
-					const header = `${cyan(r.server)}  ${bold(r.tool)}  ${yellow(r.score.toFixed(2))}`;
+					const header = `${theme.path(r.server)}  ${theme.tool(r.tool)}  ${theme.warn(r.score.toFixed(2))}`;
 					const fullDesc = r.description
 						.split("\n")
 						.map((l) => l.trim())
 						.filter((l) => l.length > 0)
 						.join(" ");
 					const indent = " ".repeat(descIndent);
-					const desc = termWidth != null ? wrapDescription(fullDesc, descIndent, termWidth) : dim(fullDesc);
+					const desc = termWidth != null ? wrapDescription(fullDesc, descIndent, termWidth) : theme.muted(fullDesc);
 					return `${header}\n${indent}${desc}`;
 				})
 				.join("\n\n");
@@ -725,8 +739,8 @@ export function formatResourceList(resources: ResourceWithServer[], options: For
 		() =>
 			formatTable(resources, {
 				columns: [
-					{ value: (r) => r.server, style: cyan },
-					{ value: (r) => r.resource.uri, style: bold },
+					{ value: (r) => r.server, style: theme.path },
+					{ value: (r) => r.resource.uri, style: theme.tool },
 				],
 				description: options.withDescriptions ? (r) => r.resource.description : undefined,
 				emptyMessage: "No resources found",
@@ -749,11 +763,11 @@ export function formatServerResources(serverName: string, resources: Resource[],
 		},
 		() => {
 			if (resources.length === 0) {
-				return dim(`No resources found for ${serverName}`);
+				return theme.muted(`No resources found for ${serverName}`);
 			}
-			const header = cyan.bold(serverName);
+			const header = theme.server(serverName);
 			const body = formatTable(resources, {
-				columns: [{ value: (r) => `  ${r.uri}`, style: bold }],
+				columns: [{ value: (r) => `  ${r.uri}`, style: theme.tool }],
 				description: (r) => r.description,
 			});
 			return `${header}\n${body}`;
@@ -775,17 +789,19 @@ export function formatResourceContents(
 			const contents =
 				(result as { contents?: Array<{ text?: string; blob?: string; mimeType?: string }> })?.contents ?? [];
 			const lines: string[] = [];
-			lines.push(`${cyan(serverName)}/${bold(uri)}`);
+			const headerText = `${serverName}/${uri}`;
+			lines.push(`${theme.path(serverName)}/${theme.resource(uri)}`);
+			lines.push(underline(headerText.length));
 			lines.push("");
 
 			if (contents.length === 0) {
-				lines.push(dim("(empty)"));
+				lines.push(theme.muted("(empty)"));
 			} else {
 				for (const item of contents) {
 					if (item.text !== undefined) {
 						lines.push(item.text);
 					} else if (item.blob !== undefined) {
-						lines.push(dim(`<binary blob, ${item.blob.length} bytes base64>`));
+						lines.push(theme.muted(`<binary blob, ${item.blob.length} bytes base64>`));
 					}
 				}
 			}
@@ -807,8 +823,8 @@ export function formatPromptList(prompts: PromptWithServer[], options: FormatOpt
 		() =>
 			formatTable(prompts, {
 				columns: [
-					{ value: (p) => p.server, style: cyan },
-					{ value: (p) => p.prompt.name, style: bold },
+					{ value: (p) => p.server, style: theme.path },
+					{ value: (p) => p.prompt.name, style: theme.prompt },
 				],
 				description: options.withDescriptions ? (p) => p.prompt.description : undefined,
 				emptyMessage: "No prompts found",
@@ -830,23 +846,23 @@ export function formatServerPrompts(serverName: string, prompts: Prompt[], optio
 		},
 		() => {
 			if (prompts.length === 0) {
-				return dim(`No prompts found for ${serverName}`);
+				return theme.muted(`No prompts found for ${serverName}`);
 			}
 
-			const header = cyan.bold(serverName);
+			const header = theme.server(serverName);
 			const maxName = Math.max(...prompts.map((p) => p.name.length));
 			const termWidth = getTerminalWidth();
 
 			const lines = prompts.map((p) => {
-				const name = `  ${bold(p.name.padEnd(maxName))}`;
+				const name = `  ${theme.prompt(p.name.padEnd(maxName))}`;
 				const args =
 					p.arguments && p.arguments.length > 0
-						? `  ${dim(`(${p.arguments.map((a) => (a.required ? a.name : `[${a.name}]`)).join(", ")})`)}`
+						? `  ${theme.muted(`(${p.arguments.map((a) => (a.required ? a.name : `[${a.name}]`)).join(", ")})`)}`
 						: "";
 				if (p.description) {
 					const prefix = `${name}${args}`;
 					const pw = visibleLength(prefix) + 2;
-					const desc = termWidth != null ? wrapDescription(p.description, pw, termWidth) : dim(p.description);
+					const desc = termWidth != null ? wrapDescription(p.description, pw, termWidth) : theme.muted(p.description);
 					return `${prefix}  ${desc}`;
 				}
 				return `${name}${args}`;
@@ -873,11 +889,13 @@ export function formatPromptMessages(
 				messages?: Array<{ role: string; content: { type: string; text?: string } }>;
 			};
 			const lines: string[] = [];
-			lines.push(`${cyan(serverName)}/${bold(name)}`);
-			if (r.description) lines.push(dim(r.description));
+			const headerText = `${serverName}/${name}`;
+			lines.push(`${theme.path(serverName)}/${theme.prompt(name)}`);
+			lines.push(underline(headerText.length));
+			if (r.description) lines.push(theme.muted(r.description));
 			lines.push("");
 			for (const msg of r.messages ?? []) {
-				lines.push(`${bold(msg.role)}:`);
+				lines.push(`${theme.tool(msg.role)}:`);
 				if (msg.content.text !== undefined) {
 					lines.push(`  ${msg.content.text}`);
 				}
@@ -890,11 +908,12 @@ export function formatPromptMessages(
 
 /** Format a unified list of tools, resources, and prompts across servers */
 export function formatUnifiedList(items: UnifiedItem[], options: FormatOptions): string {
-	const typeLabel = (t: string) => {
-		if (t === "tool") return green(t);
-		if (t === "resource") return cyan(t);
-		return yellow(t);
+	const typePill = (i: UnifiedItem): string => {
+		if (i.type === "tool") return theme.pillTool(i.type);
+		if (i.type === "resource") return theme.pillResource(i.type);
+		return theme.pillPrompt(i.type);
 	};
+	const nameStyle = (i: UnifiedItem) => (i.type === "prompt" ? theme.prompt(i.name) : theme.tool(i.name));
 
 	return formatOutput(
 		items.map((i) => ({
@@ -906,9 +925,9 @@ export function formatUnifiedList(items: UnifiedItem[], options: FormatOptions):
 		() =>
 			formatTable(items, {
 				columns: [
-					{ value: (i) => i.server, style: cyan },
-					{ value: (i) => i.type, style: typeLabel },
-					{ value: (i) => i.name, style: bold },
+					{ value: (i) => typePill(i), style: (s) => s },
+					{ value: (i) => i.server, style: theme.path },
+					{ value: (i) => nameStyle(i), style: (s) => s },
 				],
 				description: options.withDescriptions ? (i) => i.description : undefined,
 				emptyMessage: "No tools, resources, or prompts found",
@@ -928,27 +947,28 @@ export function formatTaskStatus(
 			const statusColor = (s: string) => {
 				switch (s) {
 					case "completed":
-						return green(s);
+						return theme.success(s);
 					case "working":
-						return yellow(s);
+						return theme.warn(s);
 					case "failed":
 					case "cancelled":
-						return red(s);
+						return theme.error(s);
 					case "input_required":
-						return yellow(s);
+						return theme.warn(s);
 					default:
 						return s;
 				}
 			};
 
 			const lines: string[] = [];
-			lines.push(`${bold("Task:")} ${cyan(task.taskId)}`);
-			lines.push(`${bold("Status:")} ${statusColor(task.status)}`);
-			if (task.statusMessage) lines.push(`${bold("Message:")} ${dim(String(task.statusMessage))}`);
-			if (task.createdAt) lines.push(`${bold("Created:")} ${dim(String(task.createdAt))}`);
-			if (task.lastUpdatedAt) lines.push(`${bold("Updated:")} ${dim(String(task.lastUpdatedAt))}`);
-			if (task.ttl != null) lines.push(`${bold("TTL:")} ${dim(`${String(task.ttl)}ms`)}`);
-			if (task.pollInterval != null) lines.push(`${bold("Poll interval:")} ${dim(`${String(task.pollInterval)}ms`)}`);
+			lines.push(`${theme.tool("Task:")} ${theme.path(task.taskId)}`);
+			lines.push(`${theme.tool("Status:")} ${statusColor(task.status)}`);
+			if (task.statusMessage) lines.push(`${theme.tool("Message:")} ${theme.muted(String(task.statusMessage))}`);
+			if (task.createdAt) lines.push(`${theme.tool("Created:")} ${theme.muted(String(task.createdAt))}`);
+			if (task.lastUpdatedAt) lines.push(`${theme.tool("Updated:")} ${theme.muted(String(task.lastUpdatedAt))}`);
+			if (task.ttl != null) lines.push(`${theme.tool("TTL:")} ${theme.muted(`${String(task.ttl)}ms`)}`);
+			if (task.pollInterval != null)
+				lines.push(`${theme.tool("Poll interval:")} ${theme.muted(`${String(task.pollInterval)}ms`)}`);
 			return lines.join("\n");
 		},
 		options,
@@ -965,18 +985,18 @@ export function formatTasksList(
 		{ tasks, ...(nextCursor ? { nextCursor } : {}) },
 		() => {
 			if (tasks.length === 0) {
-				return dim("No tasks found");
+				return theme.muted("No tasks found");
 			}
 
 			const statusColor = (s: string) => {
 				switch (s) {
 					case "completed":
-						return green(s.padEnd(14));
+						return theme.success(s.padEnd(14));
 					case "working":
-						return yellow(s.padEnd(14));
+						return theme.warn(s.padEnd(14));
 					case "failed":
 					case "cancelled":
-						return red(s.padEnd(14));
+						return theme.error(s.padEnd(14));
 					default:
 						return s.padEnd(14);
 				}
@@ -985,15 +1005,15 @@ export function formatTasksList(
 			const maxId = Math.max(...tasks.map((t) => t.taskId.length));
 
 			const lines = tasks.map((t) => {
-				const id = cyan(t.taskId.padEnd(maxId));
+				const id = theme.path(t.taskId.padEnd(maxId));
 				const status = statusColor(t.status);
-				const updated = t.lastUpdatedAt ? dim(String(t.lastUpdatedAt)) : "";
+				const updated = t.lastUpdatedAt ? theme.muted(String(t.lastUpdatedAt)) : "";
 				return `${id}  ${status}  ${updated}`;
 			});
 
 			if (nextCursor) {
 				lines.push("");
-				lines.push(dim(`Next cursor: ${nextCursor}`));
+				lines.push(theme.muted(`Next cursor: ${nextCursor}`));
 			}
 
 			return lines.join("\n");
@@ -1009,12 +1029,13 @@ export function formatTaskCreated(
 ): string {
 	return formatOutput(
 		{ task },
-		() => `${green("Task created:")} ${cyan(task.taskId)} ${dim(`(status: ${task.status})`)}`,
+		() =>
+			`${glyph.ok} ${theme.success("Task created:")} ${theme.taskId(task.taskId)} ${theme.muted(`(status: ${task.status})`)}`,
 		options,
 	);
 }
 
 /** Format an error message */
 export function formatError(message: string, options: FormatOptions): string {
-	return formatOutput({ error: message }, () => `${red("error:")} ${message}`, options);
+	return formatOutput({ error: message }, () => `${glyph.fail} ${theme.error("error:")} ${message}`, options);
 }

package/src/output/logger.ts

@@ -1,6 +1,7 @@
-import { dim, red, yellow } from "ansis";
 import { createSpinner } from "nanospinner";
 import type { FormatOptions } from "./formatter.ts";
+import { glyph, styleStackLine, theme } from "./theme.ts";
+import { detectMode, isJson, isVerbose, setMode, useSpinner } from "./tty.ts";
 
 /** MCP log levels ordered by severity (RFC 5424) */
 const LOG_LEVELS = ["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"] as const;
@@ -15,14 +16,14 @@ function logLevelIndex(level: string): number {
 function colorForLevel(level: string): (s: string) => string {
 	switch (level) {
 		case "debug":
-			return dim;
+			return theme.muted;
 		case "warning":
-			return yellow;
+			return theme.warn;
 		case "error":
 		case "critical":
 		case "alert":
 		case "emergency":
-			return red;
+			return theme.error;
 		default:
 			return (s: string) => s;
 	}
@@ -49,14 +50,21 @@ class Logger {
 		return Logger.instance;
 	}
 
-	/** Set format options (called once during context setup) */
+	/** Set format options (called once during context setup). Also re-resolves the
+	 * output mode so verbose/json flags parsed by commander update the global mode. */
 	configure(options: FormatOptions): void {
 		this.formatOptions = options;
+		setMode(
+			detectMode({
+				json: !!options.json,
+				verbose: !!options.verbose,
+			}),
+		);
 	}
 
 	/** Whether interactive output is suppressed (JSON mode or non-TTY stderr) */
 	private isSilent(): boolean {
-		return !!this.formatOptions.json || !(process.stderr.isTTY ?? false);
+		return isJson() || !(process.stderr.isTTY ?? false);
 	}
 
 	/** Write a line to stderr, pausing any active spinner around the write */
@@ -73,24 +81,37 @@ class Logger {
 	/** Info-level message (dim text on stderr). Suppressed in JSON/non-TTY mode. */
 	info(msg: string): void {
 		if (this.isSilent()) return;
-		this.writeStderr(dim(msg));
+		this.writeStderr(theme.muted(msg));
+	}
+
+	/** Success message (green ✓ on stderr). Suppressed in JSON/non-TTY mode. */
+	success(msg: string): void {
+		if (this.isSilent()) return;
+		this.writeStderr(`${glyph.ok} ${msg}`);
 	}
 
 	/** Warning message (yellow text on stderr). Suppressed in JSON/non-TTY mode. */
 	warn(msg: string): void {
 		if (this.isSilent()) return;
-		this.writeStderr(yellow(msg));
+		this.writeStderr(`${glyph.warn} ${theme.warn(msg)}`);
 	}
 
 	/** Error message (red text on stderr). Always writes. */
 	error(msg: string): void {
-		this.writeStderr(red(msg));
+		// If the message looks like a stack trace, style each frame line.
+		if (msg.includes("\n") && /\n\s*at\s/.test(msg)) {
+			const [first, ...rest] = msg.split("\n");
+			const styled = [theme.error(first ?? ""), ...rest.map(styleStackLine)].join("\n");
+			this.writeStderr(styled);
+			return;
+		}
+		this.writeStderr(theme.error(msg));
 	}
 
 	/** Debug/verbose message (dim text on stderr). Only when verbose is enabled. */
 	debug(msg: string): void {
-		if (!this.formatOptions.verbose || this.isSilent()) return;
-		this.writeStderr(dim(msg));
+		if (!isVerbose() || this.isSilent()) return;
+		this.writeStderr(theme.muted(msg));
 	}
 
 	/** Write a raw string to stderr. Spinner-aware but no formatting or newline added. */
@@ -109,7 +130,7 @@ class Logger {
 		const minLevel = this.formatOptions.logLevel ?? "warning";
 		if (logLevelIndex(params.level) < logLevelIndex(minLevel)) return;
 
-		if (this.formatOptions.json) {
+		if (isJson()) {
 			// JSON mode: structured object to stderr
 			const obj = { server: serverName, ...params };
 			process.stderr.write(`${JSON.stringify(obj)}\n`);
@@ -126,11 +147,9 @@ class Logger {
 	}
 
 	/** Start a spinner. Returns the Spinner interface. */
-	startSpinner(text: string, options?: FormatOptions): Spinner {
-		const opts = options ?? this.formatOptions;
-
+	startSpinner(text: string, _options?: FormatOptions): Spinner {
 		// No spinner in JSON/piped/verbose mode — verbose writeRaw output conflicts with spinner rendering
-		if (opts.json || opts.verbose || !(process.stderr.isTTY ?? false)) {
+		if (!useSpinner() || !(process.stderr.isTTY ?? false)) {
 			return { update() {}, success() {}, error() {}, stop() {} };
 		}
 

package/src/output/theme.ts

@@ -0,0 +1,123 @@
+import ansis, { bold, cyan, dim, green, magenta, red, yellow } from "ansis";
+import { useColor } from "./tty.ts";
+
+/**
+ * Semantic color tokens for the mcpx CLI. Output modules consume these names
+ * (theme.server, theme.success) rather than raw ansis colors so the palette
+ * can shift in one place.
+ *
+ * Each token also gates on useColor() at call time, so flags parsed after
+ * module load (e.g. --no-color via context.ts) still suppress output. Direct
+ * ansis usage elsewhere is governed by the env vars early-env.ts sets before
+ * ansis loads.
+ */
+
+const ESC_URL_OPEN = "\x1b[34m\x1b[4m";
+const ESC_URL_CLOSE = "\x1b[24m\x1b[39m";
+
+const wrap = (fn: (s: string) => string) => (s: string) => (useColor() ? fn(s) : s);
+
+// Entity tokens — used for nouns the user references
+export const server = wrap(cyan.bold);
+export const tool = wrap(bold);
+export const resource = wrap(cyan);
+export const prompt = wrap(magenta);
+export const taskId = wrap(cyan);
+
+// Semantic tokens — used for status / severity
+export const success = wrap(green);
+export const warn = wrap(yellow);
+export const error = wrap(red);
+export const muted = wrap(dim);
+
+// Detail tokens — finer-grained styling
+export const path = wrap(cyan);
+export const param = wrap(green);
+export const scalar = wrap(yellow);
+export const required = wrap(red);
+export const url = (s: string): string => (useColor() ? `${ESC_URL_OPEN}${s}${ESC_URL_CLOSE}` : s);
+export const label = (s: string): string => (useColor() ? bold(`${s}:`) : `${s}:`);
+
+// Pills — high-contrast inverted badges for type labels (drop into tables)
+const pillize = (bgFn: (s: string) => string) => (s: string) =>
+	useColor() ? bgFn(` ${s.toUpperCase()} `) : ` ${s.toUpperCase()} `;
+export const pillTool = pillize((s) => ansis.bgGreen.black(s));
+export const pillResource = pillize((s) => ansis.bgCyan.black(s));
+export const pillPrompt = pillize((s) => ansis.bgMagenta.black(s));
+
+// Glyph tokens — single-character status indicators. Defined as getters so
+// they re-evaluate the color decision on access.
+export const glyph = {
+	get ok() {
+		return useColor() ? green("✓") : "✓";
+	},
+	get fail() {
+		return useColor() ? red("✗") : "✗";
+	},
+	get warn() {
+		return useColor() ? yellow("⚠") : "⚠";
+	},
+	get info() {
+		return useColor() ? dim("ℹ") : "ℹ";
+	},
+	get bullet() {
+		return useColor() ? dim("•") : "•";
+	},
+	get arrowOut() {
+		return useColor() ? cyan("→") : "→";
+	},
+	get arrowIn() {
+		return useColor() ? green("←") : "←";
+	},
+	get arrowErr() {
+		return useColor() ? red("←") : "←";
+	},
+	get arrowNote() {
+		return useColor() ? yellow("←") : "←";
+	},
+};
+
+// Render a dim underline `─` of matching visible width (used under headers).
+export function underline(visibleWidth: number): string {
+	return muted("─".repeat(Math.max(0, visibleWidth)));
+}
+
+/** Stack-trace styling: dim "at", bold function name, cyan path, scalar line:col. */
+export function styleStackLine(line: string): string {
+	if (!useColor()) return line;
+	const m = line.match(/^(\s*at\s+)(.+?)\s+\((.+?):(\d+):(\d+)\)\s*$/);
+	if (m) {
+		const [, atPart, fn, file, ln, col] = m;
+		return `${dim(atPart ?? "")}${bold(fn ?? "")} (${cyan(file ?? "")}:${yellow(ln ?? "")}:${yellow(col ?? "")})`;
+	}
+	const m2 = line.match(/^(\s*at\s+)(.+?):(\d+):(\d+)\s*$/);
+	if (m2) {
+		const [, atPart, file, ln, col] = m2;
+		return `${dim(atPart ?? "")}${cyan(file ?? "")}:${yellow(ln ?? "")}:${yellow(col ?? "")}`;
+	}
+	return line;
+}
+
+export const theme = {
+	server,
+	tool,
+	resource,
+	prompt,
+	taskId,
+	success,
+	warn,
+	error,
+	muted,
+	path,
+	param,
+	scalar,
+	required,
+	url,
+	label,
+	pillTool,
+	pillResource,
+	pillPrompt,
+	glyph,
+	underline,
+	styleStackLine,
+};

package/src/output/tty.ts

@@ -0,0 +1,101 @@
+/**
+ * Single source of truth for whether the CLI is running interactively and
+ * whether ANSI colors should be emitted. All output modules consult these
+ * helpers — no module inspects process.stdout / env vars directly.
+ *
+ * Resolution (read once at startup via detectMode, then frozen via setMode):
+ *   stdout.isTTY && stderr.isTTY && !json   → interactive
+ *   anything else                            → non-interactive
+ *   CI=true                                  → forces non-interactive
+ *   --no-color or NO_COLOR=1                 → disables ANSI even if interactive
+ *   FORCE_COLOR                              → forces ANSI on regardless
+ *
+ * Direct ansis usage outside theme.ts is governed by env vars set by
+ * early-env.ts (which runs before ansis loads). Theme tokens additionally
+ * gate on useColor() at call time, so post-load flag updates also apply.
+ */
+
+export interface OutputMode {
+	interactive: boolean;
+	color: boolean;
+	json: boolean;
+	verbose: boolean;
+}
+
+export interface DetectModeOptions {
+	json?: boolean;
+	noColor?: boolean;
+	forceColor?: boolean;
+	verbose?: boolean;
+}
+
+let mode: OutputMode | null = null;
+let lockedColorChoice: { noColor?: boolean; forceColor?: boolean } = {};
+
+function isTruthyEnv(v: string | undefined): boolean {
+	if (!v) return false;
+	const lower = v.toLowerCase();
+	return lower !== "0" && lower !== "false" && lower !== "";
+}
+
+export function detectMode(opts: DetectModeOptions = {}): OutputMode {
+	const json = !!opts.json;
+	const verbose = !!opts.verbose;
+	const stdoutTty = !!(process.stdout.isTTY ?? false);
+	const stderrTty = !!(process.stderr.isTTY ?? false);
+	const ci = isTruthyEnv(process.env.CI);
+
+	const interactive = !json && !ci && stdoutTty && stderrTty;
+
+	// Color choices passed once (typically by cli.ts at startup) are remembered,
+	// so subsequent re-detections (e.g. logger.configure after commander parses)
+	// don't forget about --no-color / --force-color flags from argv.
+	if (opts.noColor !== undefined) lockedColorChoice.noColor = opts.noColor;
+	if (opts.forceColor !== undefined) lockedColorChoice.forceColor = opts.forceColor;
+
+	const noColorEnv = process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "";
+	const forceColor = !!lockedColorChoice.forceColor || isTruthyEnv(process.env.FORCE_COLOR);
+	const noColorFlag = !!lockedColorChoice.noColor;
+
+	let color: boolean;
+	if (forceColor) color = true;
+	else if (noColorFlag || noColorEnv || json) color = false;
+	else color = stderrTty || stdoutTty;
+
+	return { interactive, color, json, verbose };
+}
+
+export function setMode(m: OutputMode): void {
+	mode = m;
+}
+
+export function getMode(): OutputMode {
+	if (!mode) mode = detectMode();
+	return mode;
+}
+
+export function useColor(): boolean {
+	return getMode().color;
+}
+
+export function isInteractive(): boolean {
+	return getMode().interactive;
+}
+
+export function useSpinner(): boolean {
+	return getMode().interactive && !getMode().verbose;
+}
+
+export function isJson(): boolean {
+	return getMode().json;
+}
+
+export function isVerbose(): boolean {
+	return getMode().verbose;
+}
+
+/** Test helper: clear cached mode so the next getMode() re-detects. */
+export function resetMode(): void {
+	mode = null;
+	lockedColorChoice = {};
+}