Add --silent flag to suppress non-error output

src/cli/index.ts

@@ -4,7 +4,7 @@ import pc from "picocolors";
 import { ExitCode } from "./exit-code";
 import { parseArgs } from "./parse-args";
 import type { CliOptions } from "./types";
-import { symbols, ui } from "./ui";
+import { setSilentMode, symbols, ui } from "./ui";
 
 export const CLI_NAME = "docs-cache";
 
@@ -33,6 +33,7 @@ Global options:
   --concurrency <n>
   --json
   --timeout-ms <n>
+  --silent
 `;
 
 const printHelp = () => {
@@ -324,6 +325,9 @@ export async function main(): Promise<void> {
 		const parsed = parseArgs();
 		const _rawArgs = parsed.rawArgs;
 
+		// Set silent mode if the flag is present
+		setSilentMode(parsed.options.silent);
+
 		if (parsed.help) {
 			printHelp();
 			process.exit(ExitCode.Success);

src/cli/parse-args.ts

@@ -41,6 +41,7 @@ export const parseArgs = (argv = process.argv): ParsedArgs => {
 			.option("--concurrency <n>", "Concurrency limit")
 			.option("--json", "Output JSON")
 			.option("--timeout-ms <n>", "Network timeout in milliseconds")
+			.option("--silent", "Suppress non-error output")
 			.help();
 
 		const result = cli.parse(argv, { run: false });
@@ -64,6 +65,7 @@ export const parseArgs = (argv = process.argv): ParsedArgs => {
 			timeoutMs: result.options.timeoutMs
 				? Number(result.options.timeoutMs)
 				: undefined,
+			silent: Boolean(result.options.silent),
 		};
 
 		if (options.concurrency !== undefined && options.concurrency < 1) {

src/cli/types.ts

@@ -9,4 +9,5 @@ export type CliOptions = {
 	concurrency?: number;
 	json: boolean;
 	timeoutMs?: number;
+	silent: boolean;
 };

src/cli/ui.ts

@@ -9,6 +9,12 @@ export const symbols = {
 	warn: pc.yellow("⚠"),
 };
 
+let _silentMode = false;
+
+export const setSilentMode = (silent: boolean) => {
+	_silentMode = silent;
+};
+
 export const ui = {
 	// Formatters
 	path: (value: string) => {
@@ -24,19 +30,25 @@ export const ui = {
 	pad: (value: string, length: number) => value.padEnd(length),
 
 	// Components
-	line: (text: string = "") => process.stdout.write(`${text}\n`),
+	line: (text: string = "") => {
+		if (_silentMode) return;
+		process.stdout.write(`${text}\n`);
+	},
 
 	header: (label: string, value: string) => {
+		if (_silentMode) return;
 		process.stdout.write(`${pc.blue("ℹ")} ${label.padEnd(10)} ${value}\n`);
 	},
 
 	item: (icon: string, label: string, details?: string) => {
+		if (_silentMode) return;
 		const partLabel = pc.bold(label);
 		const partDetails = details ? pc.gray(details) : "";
 		process.stdout.write(`  ${icon} ${partLabel} ${partDetails}\n`);
 	},
 
 	step: (action: string, subject: string, details?: string) => {
+		if (_silentMode) return;
 		const icon = pc.cyan("→");
 		process.stdout.write(
 			`  ${icon} ${action} ${pc.bold(subject)}${details ? ` ${pc.dim(details)}` : ""}\n`,

tests/cli-parse.test.js

@@ -104,3 +104,27 @@ test("parseArgs handles ssh repo only", async (t) => {
 		"git@github.com:fbosch/docs-cache.git",
 	]);
 });
+
+test("parseArgs handles --silent flag", async (t) => {
+	const module = await loadCliModule();
+	if (!module) {
+		t.skip("CLI not built yet");
+		return;
+	}
+	const result = module.parseArgs(["node", "docs-cache", "status", "--silent"]);
+
+	assert.equal(result.command, "status");
+	assert.equal(result.options.silent, true);
+});
+
+test("parseArgs silent flag defaults to false", async (t) => {
+	const module = await loadCliModule();
+	if (!module) {
+		t.skip("CLI not built yet");
+		return;
+	}
+	const result = module.parseArgs(["node", "docs-cache", "status"]);
+
+	assert.equal(result.command, "status");
+	assert.equal(result.options.silent, false);
+});