@nemus-cli/nemus 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-01
+
+### Added
+
+- **`--no-color` and `-q, --quiet` global flags.** `--no-color` disables ANSI
+  color; Nemus also honors the standard [`NO_COLOR`](https://no-color.org) env
+  var, auto-disables color when stdout isn't a TTY, and respects `FORCE_COLOR=1`.
+  `--quiet` suppresses routine progress logs (info/success/step) while still
+  showing warnings and errors; data output (including `--json`) is unaffected.
+
 ## [0.4.0] - 2026-09-01
 
 ### Changed

package/README.md

@@ -243,6 +243,14 @@ The workspace-scoped ones (`status`/`doctor`/`analyze-deps`) need an explicit
 workspace name with `--json` (they never prompt). On failure, `--json` prints a
 parseable `{ "ok": false, "error": … }` to stdout and exits non-zero.
 
+### Global flags
+
+- `--no-color` — disable ANSI color. Nemus also honors the standard
+  [`NO_COLOR`](https://no-color.org) env var and auto-disables color when stdout
+  isn't a TTY (piped/redirected); `FORCE_COLOR=1` forces it on.
+- `-q, --quiet` — suppress routine progress logs (info/success/step) while still
+  showing warnings and errors. Data (including `--json`) is unaffected.
+
 ### Shell completions
 
 Tab-complete subcommands and workspace names. `nemus completion <shell>` prints
@@ -319,6 +327,20 @@ repos, create/update workspaces, check status, and more directly from a prompt.
 
 Run `nemus --help` for the full command reference.
 
+## Cloud (optional, self-hosted)
+
+Nemus is **local-first** — everything above runs entirely on your machine. If you
+want to hand a task to an agent that runs **headlessly on infrastructure you own**
+(local Docker, AWS Fargate, or any Kubernetes cluster) and opens a PR for you,
+there's an **optional, opt-in** package: [`@nemus-cli/cloud`](./packages/cloud).
+
+It's a separate, vendor-neutral package built from swappable seams — runners
+(`docker`, `aws-fargate`, `kubernetes`), IaC provisioners (OpenTofu/Terraform
+modules), git forges (GitHub/GitLab), a bounded CI-fix loop, and notifiers — with
+no cloud SDK in the core CLI. It is **not published to npm**; it lives in this
+repo for you to build and run yourself. See
+[`packages/cloud/README.md`](./packages/cloud/README.md) to get started.
+
 ## Configuration
 
 `nemus configure` writes `~/.nemus/config.json`. Environment

package/dist/program.js

@@ -38,24 +38,18 @@ const commander_1 = require("commander");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const colors_1 = require("./utils/colors");
+const banner_1 = require("./utils/banner");
+const global_flags_1 = require("./utils/global-flags");
 // Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
-const g = colors_1.colors.green;
-const d = colors_1.colors.dim;
-const b = colors_1.colors.bright;
-const r = colors_1.colors.reset;
-const INNER = 38;
-const titleLine = `>_  Nemus`;
-const titlePad = ' '.repeat(Math.max(0, INNER - 2 - titleLine.length));
-const versionLine = `v${pkg.version} · multi-repo workspaces`;
-const versionPad = ' '.repeat(Math.max(0, INNER - 7 - versionLine.length));
-const bar = '─'.repeat(INNER);
-const bannerText = `
-${d}    ╭${bar}╮${r}
-${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}${titlePad}${d}│${r}
-${d}    │${r}       ${d}${versionLine}${r}${versionPad}${d}│${r}
-${d}    ╰${bar}╯${r}
-`;
+// --no-color must be applied BEFORE commander parses so it reaches the help
+// banner (a preAction hook is too late for help output, and ES imports run
+// before hooks). It's a long flag, so it can't be bundled — an argv scan is
+// sufficient here. colors.ts already applied NO_COLOR / non-TTY at import.
+// --quiet is handled in the preAction hook below (it only affects command
+// logs, never help), which also catches bundled short forms like `-yq`.
+if (process.argv.includes('--no-color'))
+    (0, colors_1.setColorEnabled)(false);
 exports.program = new commander_1.Command();
 exports.program
     .name('workspace')
@@ -63,7 +57,14 @@ exports.program
     .version(pkg.version, '-V, --version')
     .option('-f, --force-refresh', 'Force refresh GitHub repos (skip cache)')
     .option('-y, --yes', 'Skip confirmations')
-    .addHelpText('before', bannerText);
+    .option('--no-color', 'Disable colored output (also honors NO_COLOR)')
+    .option('-q, --quiet', 'Suppress progress logs (keep warnings + errors)')
+    .addHelpText('before', () => (0, banner_1.renderHelpBanner)(pkg.version));
+// Apply global --quiet / --color from commander's PARSED options (robust to
+// bundled short flags like `-yq` that a raw argv scan misses). Runs before every
+// command action; help output doesn't reach here, which is why --no-color is
+// also pre-scanned above.
+exports.program.hook('preAction', () => (0, global_flags_1.applyGlobalFlags)(exports.program.opts()));
 // Register top-level commands
 const create_1 = require("./commands/create");
 const list_1 = require("./commands/list");

package/dist/utils/banner.js

@@ -1,24 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.printBanner = exports.BANNER_PLAIN = exports.BANNER = void 0;
+exports.renderHelpBanner = exports.printBanner = exports.renderBanner = exports.BANNER_PLAIN = void 0;
 const colors_1 = require("./colors");
-const g = colors_1.colors.green;
-const d = colors_1.colors.dim;
-const b = colors_1.colors.bright;
-const r = colors_1.colors.reset;
-exports.BANNER = `
-${d}    ╭──────────────────────────────────────╮${r}
-${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}                           ${d}│${r}
-${d}    │${r}       ${d}multi-repo workspaces${r}          ${d}│${r}
-${d}    ╰──────────────────────────────────────╯${r}
-`;
 exports.BANNER_PLAIN = `
     ╭──────────────────────────────────────╮
     │  >_  Nemus                           │
     │       multi-repo workspaces          │
     ╰──────────────────────────────────────╯
 `;
+// Rendered live (not captured at import) so --no-color / NO_COLOR applied before
+// this is called produce a plain banner. With color off, every colors.* is ''.
+const renderBanner = () => {
+    const { green: g, dim: d, bright: b, reset: r } = colors_1.colors;
+    return `
+${d}    ╭──────────────────────────────────────╮${r}
+${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}                           ${d}│${r}
+${d}    │${r}       ${d}multi-repo workspaces${r}          ${d}│${r}
+${d}    ╰──────────────────────────────────────╯${r}
+`;
+};
+exports.renderBanner = renderBanner;
 const printBanner = () => {
-    console.log(exports.BANNER);
+    console.log((0, exports.renderBanner)());
 };
 exports.printBanner = printBanner;
+// The `--help` banner: a boxed splash with the version + tagline, width-fitted.
+// Lives here alongside renderBanner() so the two renderers don't drift; also
+// rendered live so --no-color / NO_COLOR yields a plain box.
+const renderHelpBanner = (version) => {
+    const { green: g, dim: d, bright: b, reset: r } = colors_1.colors;
+    const INNER = 38;
+    const titleLine = `>_  Nemus`;
+    const titlePad = ' '.repeat(Math.max(0, INNER - 2 - titleLine.length));
+    const versionLine = `v${version} · multi-repo workspaces`;
+    const versionPad = ' '.repeat(Math.max(0, INNER - 7 - versionLine.length));
+    const bar = '─'.repeat(INNER);
+    return `
+${d}    ╭${bar}╮${r}
+${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}${titlePad}${d}│${r}
+${d}    │${r}       ${d}${versionLine}${r}${versionPad}${d}│${r}
+${d}    ╰${bar}╯${r}
+`;
+};
+exports.renderHelpBanner = renderHelpBanner;

package/dist/utils/colors.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.colorize = exports.colors = void 0;
-exports.colors = {
+exports.colorize = exports.isColorEnabled = exports.colors = void 0;
+exports.setColorEnabled = setColorEnabled;
+exports.detectColorEnabled = detectColorEnabled;
+// ANSI escape codes. `colors` starts as a copy of these but is emptied in place
+// when color is disabled (--no-color / NO_COLOR / non-TTY), so BOTH `colorize()`
+// and inline `colors.x` template usage go plain without touching call sites.
+const ANSI = {
     reset: '\x1b[0m',
     bright: '\x1b[1m',
     dim: '\x1b[2m',
@@ -20,7 +25,43 @@ exports.colors = {
     bgYellow: '\x1b[43m',
     bgBlue: '\x1b[44m',
 };
+// Live map read at every use. Mutated in place by setColorEnabled so previously
+// imported references (e.g. `colors.gray` inside a template) see the change.
+exports.colors = { ...ANSI };
+let enabled = true;
+/** Whether colored output is currently on. */
+const isColorEnabled = () => enabled;
+exports.isColorEnabled = isColorEnabled;
+/** Turn color on/off. When off, every `colors.*` code becomes '' so output is
+ *  plain; when on, the ANSI codes are restored. */
+function setColorEnabled(on) {
+    enabled = on;
+    for (const key of Object.keys(ANSI)) {
+        exports.colors[key] = on ? ANSI[key] : '';
+    }
+}
+/**
+ * Decide whether to use color by default, following the common conventions:
+ * - `NO_COLOR` (any value, even empty) disables — see https://no-color.org
+ * - `FORCE_COLOR` (and not "0"/"false") forces it on, even when not a TTY
+ * - otherwise on only when the stdout stream is a TTY and `TERM` isn't `dumb`
+ */
+function detectColorEnabled(env = process.env, isTTY = !!process.stdout.isTTY) {
+    if ('NO_COLOR' in env)
+        return false;
+    const force = env.FORCE_COLOR;
+    if (force !== undefined && force !== '' && force !== '0' && force.toLowerCase() !== 'false') {
+        return true;
+    }
+    if (env.TERM === 'dumb')
+        return false;
+    return isTTY;
+}
 const colorize = (text, color) => {
     return `${exports.colors[color]}${text}${exports.colors.reset}`;
 };
 exports.colorize = colorize;
+// Apply the environment default at import time so NO_COLOR / a non-TTY pipe is
+// respected even before any CLI flag is parsed (an explicit --no-color / --color
+// flag overrides this later).
+setColorEnabled(detectColorEnabled());

package/dist/utils/global-flags.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyGlobalFlags = applyGlobalFlags;
+const colors_1 = require("./colors");
+const logger_1 = require("./logger");
+/**
+ * Apply parsed global flags to process-wide state. Kept pure over injected
+ * setters so it's testable without commander — the `preAction` hook in
+ * program.ts is a one-line call into this. Only ever turns features OFF here:
+ * color defaults on (and env/TTY detection already ran at import), so we act
+ * solely on an explicit `--no-color` (`color === false`).
+ */
+function applyGlobalFlags(opts, deps = {
+    setColorEnabled: colors_1.setColorEnabled,
+    setQuiet: logger_1.setQuiet,
+}) {
+    if (opts.color === false)
+        deps.setColorEnabled(false);
+    if (opts.quiet)
+        deps.setQuiet(true);
+}

package/dist/utils/logger.js

@@ -1,11 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logStep = exports.logWarning = exports.logError = exports.logSuccess = exports.logInfo = void 0;
+exports.logStep = exports.logWarning = exports.logError = exports.logSuccess = exports.logInfo = exports.isQuiet = exports.setQuiet = void 0;
 const colors_1 = require("./colors");
 // Diagnostics (info/success/error/warn/step) go to STDERR so stdout carries only
 // a command's actual data — required for clean `--json` piping (nemus list
 // --json | jq …) and for non-TTY consumers. Use `outputJson`/stdout for data.
 const logStream = (line) => console.error(line);
+// `--quiet` silences routine progress (info/success/step) while KEEPING warnings
+// and errors, which a script or human still needs to see.
+let quiet = false;
+const setQuiet = (on) => {
+    quiet = on;
+};
+exports.setQuiet = setQuiet;
+const isQuiet = () => quiet;
+exports.isQuiet = isQuiet;
 const getTimestamp = () => {
     const now = new Date();
     return now.toLocaleTimeString('en-US', {
@@ -16,10 +25,14 @@ const getTimestamp = () => {
     });
 };
 const logInfo = (message) => {
+    if (quiet)
+        return;
     logStream(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${message}`);
 };
 exports.logInfo = logInfo;
 const logSuccess = (message) => {
+    if (quiet)
+        return;
     logStream(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('✓', 'green')} ${message}`);
 };
 exports.logSuccess = logSuccess;
@@ -32,6 +45,8 @@ const logWarning = (message) => {
 };
 exports.logWarning = logWarning;
 const logStep = (stepOrMessage, total, message) => {
+    if (quiet)
+        return;
     if (typeof stepOrMessage === 'string') {
         // Single parameter version: just a message
         logStream(`${colors_1.colors.gray}[${getTimestamp()}]${colors_1.colors.reset} ${(0, colors_1.colorize)('▸', 'cyan')} ${stepOrMessage}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "workspaces": [
     "packages/*"
   ],

package/src/program.ts

@@ -1,28 +1,20 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
-import { colors } from './utils/colors';
+import { setColorEnabled } from './utils/colors';
+import { renderHelpBanner } from './utils/banner';
+import { applyGlobalFlags } from './utils/global-flags';
 
 // Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 
-const g = colors.green;
-const d = colors.dim;
-const b = colors.bright;
-const r = colors.reset;
-
-const INNER = 38;
-const titleLine = `>_  Nemus`;
-const titlePad = ' '.repeat(Math.max(0, INNER - 2 - titleLine.length));
-const versionLine = `v${pkg.version} · multi-repo workspaces`;
-const versionPad = ' '.repeat(Math.max(0, INNER - 7 - versionLine.length));
-const bar = '─'.repeat(INNER);
-const bannerText = `
-${d}    ╭${bar}╮${r}
-${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}${titlePad}${d}│${r}
-${d}    │${r}       ${d}${versionLine}${r}${versionPad}${d}│${r}
-${d}    ╰${bar}╯${r}
-`;
+// --no-color must be applied BEFORE commander parses so it reaches the help
+// banner (a preAction hook is too late for help output, and ES imports run
+// before hooks). It's a long flag, so it can't be bundled — an argv scan is
+// sufficient here. colors.ts already applied NO_COLOR / non-TTY at import.
+// --quiet is handled in the preAction hook below (it only affects command
+// logs, never help), which also catches bundled short forms like `-yq`.
+if (process.argv.includes('--no-color')) setColorEnabled(false);
 
 export const program = new Command();
 
@@ -32,7 +24,15 @@ program
   .version(pkg.version, '-V, --version')
   .option('-f, --force-refresh', 'Force refresh GitHub repos (skip cache)')
   .option('-y, --yes', 'Skip confirmations')
-  .addHelpText('before', bannerText);
+  .option('--no-color', 'Disable colored output (also honors NO_COLOR)')
+  .option('-q, --quiet', 'Suppress progress logs (keep warnings + errors)')
+  .addHelpText('before', () => renderHelpBanner(pkg.version));
+
+// Apply global --quiet / --color from commander's PARSED options (robust to
+// bundled short flags like `-yq` that a raw argv scan misses). Runs before every
+// command action; help output doesn't reach here, which is why --no-color is
+// also pre-scanned above.
+program.hook('preAction', () => applyGlobalFlags(program.opts()));
 
 // Register top-level commands
 import { registerCreateCommand } from './commands/create';

package/src/utils/banner.ts

@@ -1,17 +1,5 @@
 import { colors } from './colors';
 
-const g = colors.green;
-const d = colors.dim;
-const b = colors.bright;
-const r = colors.reset;
-
-export const BANNER = `
-${d}    ╭──────────────────────────────────────╮${r}
-${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}                           ${d}│${r}
-${d}    │${r}       ${d}multi-repo workspaces${r}          ${d}│${r}
-${d}    ╰──────────────────────────────────────╯${r}
-`;
-
 export const BANNER_PLAIN = `
     ╭──────────────────────────────────────╮
     │  >_  Nemus                           │
@@ -19,6 +7,37 @@ export const BANNER_PLAIN = `
     ╰──────────────────────────────────────╯
 `;
 
+// Rendered live (not captured at import) so --no-color / NO_COLOR applied before
+// this is called produce a plain banner. With color off, every colors.* is ''.
+export const renderBanner = (): string => {
+  const { green: g, dim: d, bright: b, reset: r } = colors;
+  return `
+${d}    ╭──────────────────────────────────────╮${r}
+${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}                           ${d}│${r}
+${d}    │${r}       ${d}multi-repo workspaces${r}          ${d}│${r}
+${d}    ╰──────────────────────────────────────╯${r}
+`;
+};
+
 export const printBanner = (): void => {
-  console.log(BANNER);
+  console.log(renderBanner());
+};
+
+// The `--help` banner: a boxed splash with the version + tagline, width-fitted.
+// Lives here alongside renderBanner() so the two renderers don't drift; also
+// rendered live so --no-color / NO_COLOR yields a plain box.
+export const renderHelpBanner = (version: string): string => {
+  const { green: g, dim: d, bright: b, reset: r } = colors;
+  const INNER = 38;
+  const titleLine = `>_  Nemus`;
+  const titlePad = ' '.repeat(Math.max(0, INNER - 2 - titleLine.length));
+  const versionLine = `v${version} · multi-repo workspaces`;
+  const versionPad = ' '.repeat(Math.max(0, INNER - 7 - versionLine.length));
+  const bar = '─'.repeat(INNER);
+  return `
+${d}    ╭${bar}╮${r}
+${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}${titlePad}${d}│${r}
+${d}    │${r}       ${d}${versionLine}${r}${versionPad}${d}│${r}
+${d}    ╰${bar}╯${r}
+`;
 };

package/src/utils/colors.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { colors, colorize, setColorEnabled, isColorEnabled, detectColorEnabled } from './colors';
+
+// Tests toggle global color state; restore a known state afterward.
+afterEach(() => setColorEnabled(true));
+
+describe('setColorEnabled / colorize', () => {
+  it('wraps with ANSI when on, and is plain when off (same call sites)', () => {
+    setColorEnabled(true);
+    expect(isColorEnabled()).toBe(true);
+    const on = colorize('hi', 'green');
+    expect(on).toContain('\x1b[32m');
+    expect(on).toContain('\x1b[0m');
+    expect(on).toContain('hi');
+
+    setColorEnabled(false);
+    expect(isColorEnabled()).toBe(false);
+    expect(colorize('hi', 'green')).toBe('hi'); // no codes at all
+  });
+
+  it('empties inline colors.* codes in place when disabled', () => {
+    setColorEnabled(false);
+    expect(colors.gray).toBe('');
+    expect(colors.reset).toBe('');
+    setColorEnabled(true);
+    expect(colors.gray).toBe('\x1b[90m');
+  });
+});
+
+describe('detectColorEnabled', () => {
+  it('NO_COLOR disables regardless of value (even empty)', () => {
+    expect(detectColorEnabled({ NO_COLOR: '1' }, true)).toBe(false);
+    expect(detectColorEnabled({ NO_COLOR: '' }, true)).toBe(false);
+  });
+
+  it('FORCE_COLOR forces on even without a TTY (but 0/false do not)', () => {
+    expect(detectColorEnabled({ FORCE_COLOR: '1' }, false)).toBe(true);
+    expect(detectColorEnabled({ FORCE_COLOR: '0' }, false)).toBe(false);
+    expect(detectColorEnabled({ FORCE_COLOR: 'false' }, false)).toBe(false);
+  });
+
+  it('NO_COLOR beats FORCE_COLOR', () => {
+    expect(detectColorEnabled({ NO_COLOR: '1', FORCE_COLOR: '1' }, true)).toBe(false);
+  });
+
+  it('otherwise follows the TTY, and TERM=dumb disables', () => {
+    expect(detectColorEnabled({}, true)).toBe(true);
+    expect(detectColorEnabled({}, false)).toBe(false);
+    expect(detectColorEnabled({ TERM: 'dumb' }, true)).toBe(false);
+  });
+});

package/src/utils/colors.ts

@@ -1,4 +1,7 @@
-export const colors = {
+// ANSI escape codes. `colors` starts as a copy of these but is emptied in place
+// when color is disabled (--no-color / NO_COLOR / non-TTY), so BOTH `colorize()`
+// and inline `colors.x` template usage go plain without touching call sites.
+const ANSI = {
   reset: '\x1b[0m',
   bright: '\x1b[1m',
   dim: '\x1b[2m',
@@ -18,8 +21,52 @@ export const colors = {
   bgGreen: '\x1b[42m',
   bgYellow: '\x1b[43m',
   bgBlue: '\x1b[44m',
-};
+} as const;
+
+export type ColorName = keyof typeof ANSI;
+
+// Live map read at every use. Mutated in place by setColorEnabled so previously
+// imported references (e.g. `colors.gray` inside a template) see the change.
+export const colors: Record<ColorName, string> = { ...ANSI };
+
+let enabled = true;
 
-export const colorize = (text: string, color: keyof typeof colors): string => {
+/** Whether colored output is currently on. */
+export const isColorEnabled = (): boolean => enabled;
+
+/** Turn color on/off. When off, every `colors.*` code becomes '' so output is
+ *  plain; when on, the ANSI codes are restored. */
+export function setColorEnabled(on: boolean): void {
+  enabled = on;
+  for (const key of Object.keys(ANSI) as ColorName[]) {
+    colors[key] = on ? ANSI[key] : '';
+  }
+}
+
+/**
+ * Decide whether to use color by default, following the common conventions:
+ * - `NO_COLOR` (any value, even empty) disables — see https://no-color.org
+ * - `FORCE_COLOR` (and not "0"/"false") forces it on, even when not a TTY
+ * - otherwise on only when the stdout stream is a TTY and `TERM` isn't `dumb`
+ */
+export function detectColorEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+  isTTY: boolean = !!process.stdout.isTTY,
+): boolean {
+  if ('NO_COLOR' in env) return false;
+  const force = env.FORCE_COLOR;
+  if (force !== undefined && force !== '' && force !== '0' && force.toLowerCase() !== 'false') {
+    return true;
+  }
+  if (env.TERM === 'dumb') return false;
+  return isTTY;
+}
+
+export const colorize = (text: string, color: ColorName): string => {
   return `${colors[color]}${text}${colors.reset}`;
 };
+
+// Apply the environment default at import time so NO_COLOR / a non-TTY pipe is
+// respected even before any CLI flag is parsed (an explicit --no-color / --color
+// flag overrides this later).
+setColorEnabled(detectColorEnabled());

package/src/utils/global-flags.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Command } from 'commander';
+import { applyGlobalFlags } from './global-flags';
+
+const spies = () => ({ setColorEnabled: vi.fn(), setQuiet: vi.fn() });
+
+// Mirror the real root-program global options so we test what commander actually
+// parses (esp. bundled short flags), not a hand-built opts object.
+const rootOpts = (argv: string[]) => {
+  const p = new Command();
+  p.option('-y, --yes', '').option('-q, --quiet', '').option('--no-color', '');
+  p.command('list').action(() => {});
+  p.parse(['node', 'nemus', 'list', ...argv]);
+  return p.opts();
+};
+
+describe('applyGlobalFlags', () => {
+  it('does nothing by default (color on, not quiet)', () => {
+    const d = spies();
+    applyGlobalFlags(rootOpts([]), d);
+    expect(d.setColorEnabled).not.toHaveBeenCalled();
+    expect(d.setQuiet).not.toHaveBeenCalled();
+  });
+
+  it('--no-color disables color', () => {
+    const d = spies();
+    applyGlobalFlags(rootOpts(['--no-color']), d);
+    expect(d.setColorEnabled).toHaveBeenCalledWith(false);
+  });
+
+  it('--quiet enables quiet', () => {
+    const d = spies();
+    applyGlobalFlags(rootOpts(['--quiet']), d);
+    expect(d.setQuiet).toHaveBeenCalledWith(true);
+  });
+
+  it('bundled short flags (-yq) still enable quiet', () => {
+    const d = spies();
+    const opts = rootOpts(['-yq']);
+    expect(opts.quiet).toBe(true); // commander expands the bundle
+    applyGlobalFlags(opts, d);
+    expect(d.setQuiet).toHaveBeenCalledWith(true);
+  });
+});

package/src/utils/global-flags.ts

@@ -0,0 +1,28 @@
+import { setColorEnabled } from './colors';
+import { setQuiet } from './logger';
+
+/** Global options commander parses off the root program. */
+export interface GlobalFlagOpts {
+  /** commander's negatable `--no-color` yields `color: false` when passed. */
+  color?: boolean;
+  /** `-q`/`--quiet`, including bundled short forms like `-yq`. */
+  quiet?: boolean;
+}
+
+/**
+ * Apply parsed global flags to process-wide state. Kept pure over injected
+ * setters so it's testable without commander — the `preAction` hook in
+ * program.ts is a one-line call into this. Only ever turns features OFF here:
+ * color defaults on (and env/TTY detection already ran at import), so we act
+ * solely on an explicit `--no-color` (`color === false`).
+ */
+export function applyGlobalFlags(
+  opts: GlobalFlagOpts,
+  deps: { setColorEnabled: (on: boolean) => void; setQuiet: (on: boolean) => void } = {
+    setColorEnabled,
+    setQuiet,
+  },
+): void {
+  if (opts.color === false) deps.setColorEnabled(false);
+  if (opts.quiet) deps.setQuiet(true);
+}

package/src/utils/logger.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { logInfo, logSuccess, logStep, logWarning, logError, setQuiet, isQuiet } from './logger';
+
+afterEach(() => {
+  setQuiet(false);
+  vi.restoreAllMocks();
+});
+
+describe('--quiet (setQuiet)', () => {
+  it('suppresses info/success/step but keeps warnings + errors', () => {
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+    setQuiet(true);
+    expect(isQuiet()).toBe(true);
+
+    logInfo('i');
+    logSuccess('s');
+    logStep('st');
+    expect(err).not.toHaveBeenCalled(); // routine progress silenced
+
+    logWarning('w');
+    logError('e');
+    expect(err).toHaveBeenCalledTimes(2); // warnings + errors still shown
+    expect(err.mock.calls.map((c) => String(c[0])).join('\n')).toMatch(/w[\s\S]*e|e[\s\S]*w/);
+  });
+
+  it('emits everything when not quiet', () => {
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+    setQuiet(false);
+    logInfo('i');
+    logSuccess('s');
+    logStep('st');
+    logWarning('w');
+    logError('e');
+    expect(err).toHaveBeenCalledTimes(5);
+  });
+});

package/src/utils/logger.ts

@@ -5,6 +5,14 @@ import { colors, colorize } from './colors';
 // --json | jq …) and for non-TTY consumers. Use `outputJson`/stdout for data.
 const logStream = (line: string): void => console.error(line);
 
+// `--quiet` silences routine progress (info/success/step) while KEEPING warnings
+// and errors, which a script or human still needs to see.
+let quiet = false;
+export const setQuiet = (on: boolean): void => {
+  quiet = on;
+};
+export const isQuiet = (): boolean => quiet;
+
 const getTimestamp = (): string => {
   const now = new Date();
   return now.toLocaleTimeString('en-US', {
@@ -16,10 +24,12 @@ const getTimestamp = (): string => {
 };
 
 export const logInfo = (message: string): void => {
+  if (quiet) return;
   logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${message}`);
 };
 
 export const logSuccess = (message: string): void => {
+  if (quiet) return;
   logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('✓', 'green')} ${message}`);
 };
 
@@ -32,6 +42,7 @@ export const logWarning = (message: string): void => {
 };
 
 export const logStep = (stepOrMessage: number | string, total?: number, message?: string): void => {
+  if (quiet) return;
   if (typeof stepOrMessage === 'string') {
     // Single parameter version: just a message
     logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('▸', 'cyan')} ${stepOrMessage}`);