Fix versions in lock file.

README.md

@@ -11,7 +11,7 @@ This package hosts non-domain-specific utilities that can be reused by CLI and l
 Current exported areas:
 
 - Markdown table rendering (`toMarkdownTable`)
-- Output helpers for CLI tools (`renderOutput`, `normalizeOutputFormat`, `parseHeaderSpec`)
+- Output helpers for CLI tools (`renderOutput`, `normalizeOutputFormat`, `parseColumnSpec`)
 - Input readers for stdin (`readJsonFromStdin`, `readCsvFromStdin`)
 - JMESPath output filtering (`outputFiltered`)
 

docs/Commands.md

@@ -2,25 +2,41 @@
 
 The `sk-tools` package provides generic CLI utilities not tied to a specific cloud provider.
 
+## Global Options
+
+These options apply to all commands unless stated otherwise:
+
+- `--query`, `-q` <jmespath> - Apply JMESPath filter before output rendering.
+- `--output`, `-o` <format> - Output format: `table|t|alignedtable|at|prettytable|pt|tsv`.
+- `--columns`, `-C` <definition> - Column selection for table outputs:
+  - `col1` - Select column (case-insensitive match), keep raw header label.
+  - `col1:` - Select column (case-insensitive match), use auto-generated header label.
+  - `col1: Label 1` - Select column (case-insensitive match), use custom header label.
+  - Prefix token with `=` for exact column-name match: `=col1`, `=col1:`, `=col1:Label`.
+  - Tokens are comma-separated and rendered in the specified order.
+- `--help`, `-h` - Show help.
+
 ## Table
 
-**Command name:** `table`
+**Command name:** `table` (alias: `t`)
 
-**Usage:** `sk-tools table [--from|-F <json|csv|tsv>] [--header|-H <definition|auto|a|original|o>] [global options]`
+**Usage:** `sk-tools table [--from|-F <json|csv|tsv>] [--columns|-C <definition>] [global options]`
 
 **Options:**
 
 - `--from`, `-F` <json|csv|tsv> - Input format read from stdin. Default: `json`.
-- `--header`, `-H` <definition|auto|a|original|o> - Header definition. Possible values:
-  - `col1, col2, ...` - Column names separated by comma. The number of columns should match table columns.
-  - `key1: Col1, key2: Col2, ...` - Property-to-column mapping.
-  - `auto`, `a` - Header generated automatically from result keys.
-  - `original`, `o` - Header based on original table shape.
-
-**Global options:**
-
-- `--query`, `-q` <jmespath> - JMESPath filter applied before rendering.
-- `--output`, `-o` <format> - Output format: `table|t|alignedtable|at|prettytable|pt|tsv`.
-- `--help`, `-h` - Show help.
+- `--columns`, `-C` <definition> - Column definition (see global options).
 
 **Description:** The `table` command transforms stdin data into tabular output. It accepts JSON, CSV, or TSV input and renders either Markdown table variants or TSV output.
+
+## Table Info
+
+**Command name:** `table-info` (alias: `ti`)
+
+**Usage:** `sk-tools table-info [--from|-F <json|csv|tsv>]`
+
+**Options:**
+
+- `--from`, `-F` <json|csv|tsv> - Input format read from stdin. Default: `json`.
+
+**Description:** The `table-info` command reads stdin data and prints basic diagnostics: number of rows, number of columns, and inferred type for each column.

package-lock.json

@@ -1,16 +1,22 @@
 {
     "name": "@slawek/sk-tools",
-    "version": "0.1.0",
+    "version": "0.4.1",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "@slawek/sk-tools",
-            "version": "0.1.0",
+            "version": "0.4.1",
             "license": "MIT",
             "dependencies": {
+                "commander": "^14.0.3",
                 "d3-dsv": "^3.0.1",
-                "jmespath": "^0.16.0"
+                "jmespath": "^0.16.0",
+                "semver": "^7.7.4",
+                "uuid": "^11.1.0"
+            },
+            "bin": {
+                "sk-tools": "dist/cli.js"
             },
             "devDependencies": {
                 "@types/d3-dsv": "^3.0.7",
@@ -47,12 +53,12 @@
             }
         },
         "node_modules/commander": {
-            "version": "7.2.0",
-            "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz",
-            "integrity": "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==",
+            "version": "14.0.3",
+            "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
+            "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==",
             "license": "MIT",
             "engines": {
-                "node": ">= 10"
+                "node": ">=20"
             }
         },
         "node_modules/d3-dsv": {
@@ -80,6 +86,15 @@
                 "node": ">=12"
             }
         },
+        "node_modules/d3-dsv/node_modules/commander": {
+            "version": "7.2.0",
+            "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz",
+            "integrity": "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==",
+            "license": "MIT",
+            "engines": {
+                "node": ">= 10"
+            }
+        },
         "node_modules/iconv-lite": {
             "version": "0.6.3",
             "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
@@ -113,6 +128,18 @@
             "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
             "license": "MIT"
         },
+        "node_modules/semver": {
+            "version": "7.7.4",
+            "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
+            "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+            "license": "ISC",
+            "bin": {
+                "semver": "bin/semver.js"
+            },
+            "engines": {
+                "node": ">=10"
+            }
+        },
         "node_modules/typescript": {
             "version": "5.9.3",
             "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
@@ -133,6 +160,19 @@
             "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==",
             "dev": true,
             "license": "MIT"
+        },
+        "node_modules/uuid": {
+            "version": "11.1.0",
+            "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz",
+            "integrity": "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==",
+            "funding": [
+                "https://github.com/sponsors/broofa",
+                "https://github.com/sponsors/ctavan"
+            ],
+            "license": "MIT",
+            "bin": {
+                "uuid": "dist/esm/bin/uuid"
+            }
         }
     }
 }

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@slawek/sk-tools",
-    "version": "0.1.1",
+    "version": "0.4.1",
     "type": "module",
     "files": [
         "dist",
@@ -10,16 +10,18 @@
     "scripts": {
         "clean": "rm -rf dist",
         "build": "npm run clean && tsc && chmod +x dist/cli.js",
-        "build:watch": "tsc --watch",
-        "prepublishOnly": "npm run build"
+        "build:watch": "tsc --watch"
     },
     "engines": {
         "node": ">=24.0.0"
     },
     "description": "A set of generic NodeJS utilities shared by Slawek tools.",
     "dependencies": {
+        "commander": "^14.0.3",
         "d3-dsv": "^3.0.1",
-        "jmespath": "^0.16.0"
+        "jmespath": "^0.16.0",
+        "semver": "^7.7.4",
+        "uuid": "^11.1.0"
     },
     "devDependencies": {
         "@types/d3-dsv": "^3.0.7",

scripts/bump-patch.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import semver from 'semver';
+import { Command, Option } from 'commander';
+
+function bump(fileName, version, releaseType = 'patch') {
+    const filePath = path.resolve(process.cwd(), fileName);
+
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+
+    const json = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const currentVersion = json.version;
+
+    if (typeof currentVersion !== 'string') {
+        throw new Error(`${fileName} does not contain a string "version" field.`);
+    }
+
+    const nextVersion = version ?? semver.inc(currentVersion, releaseType);
+
+    if (!nextVersion) {
+        throw new Error(`Unsupported semver format: "${currentVersion}"`);
+    }
+
+    json.version = nextVersion;
+
+    fs.writeFileSync(filePath, `${JSON.stringify(json, null, 4)}\n`, 'utf8');
+    console.log(`Bumped version in ${fileName} to ${nextVersion}`);
+    return nextVersion;
+}
+
+const program = new Command();
+program
+    .name('bump-patch')
+    .description('Bump the version in package.json')
+    .addOption(new Option('-r, --release-type <type>', 'Release type (major, minor, patch)')
+        .choices(['major', 'minor', 'patch'])
+        .default('patch')
+    )
+    .parse(process.argv);
+
+bump('package.json', undefined, program.opts().releaseType);

src/cli.ts

@@ -1,124 +1,53 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: MIT
 
-import { parseArgs } from "node:util";
+import { Command, Option } from "commander";
 
-import {
-    normalizeOutputFormat,
-    outputFiltered,
-    parseHeaderSpec,
-    readCsvFromStdin,
-    readJsonFromStdin,
-    renderOutput,
-} from "./cli/utils.ts";
-
-type CliValues = {
-    help?: boolean;
-    from?: string;
-    query?: string;
-    header?: string;
-    output?: string;
-    [key: string]: string | boolean | undefined;
-};
-
-function usage(): string {
-    return `Usage: sk-tools <command> [options]
-
-Commands:
-  table                    Render stdin data as Markdown table
-
-Global options (all commands):
-  --query, -q <jmespath>
-  --output, -o <format>     table|t|alignedtable|at|prettytable|pt|tsv
-  --help, -h
-
-Use: sk-tools --help <command>
-or:  sk-tools <command> --help`;
-}
-
-function usageTable(): string {
-    return `Usage: sk-tools table [--from|-F <json|csv|tsv>] [--header|-H <definition|auto|a|original|o>] [global options]
-
-Options:
-  --from, -F <json|csv|tsv>  Input format on stdin (default: json)
-  --header, -H <value>       Header mode: auto|a (default), original|o, or "col1, col2" or "key1: Label 1, key2: Label 2"`;
-}
-
-function usageCommand(command: string): string {
-    switch (command) {
-        case "table":
-            return usageTable();
-        default:
-            return `Unknown command: ${command}\n\n${usage()}`;
-    }
-}
-
-async function runTableCommand(values: CliValues): Promise<unknown> {
-    const from = (values.from ?? "json").toString().trim().toLowerCase();
-
-    if (from === "json") {
-        return readJsonFromStdin();
-    }
-    if (from === "csv") {
-        return readCsvFromStdin(",");
-    }
-    if (from === "tsv") {
-        return readCsvFromStdin("\t");
-    }
-
-    throw new Error(`Invalid --from '${values.from}'. Allowed: json, csv, tsv`);
-}
+import { runTableInfoCommand } from "./cli/commands/table-info.ts";
+import { runTableCommand } from "./cli/commands/table.ts";
+import { renderCliOutput } from "./cli/utils.ts";
 
 async function main(): Promise<void> {
-    const argv = process.argv.slice(2);
-    const command = argv[0];
+    const skTools = new Command();
 
-    if (!command) {
-        console.log(usage());
-        process.exit(0);
-    }
+    skTools
+        .name("sk-tools")
+        .description("A set of generic NodeJS utilities shared by Slawek tools.")
+        .option("-q, --query <jmespath>", "JMESPath query to filter output")
+        .option("-C, --columns <definition>", "Column tokens: col (raw), col: (auto), col:Label (custom), exact via = prefix")
+        .addOption(new Option("-o, --output <format>", "Output format: table|t|alignedtable|at|prettytable|pt|tsv")
+            .choices(["table", "t", "alignedtable", "at", "prettytable", "pt", "tsv"]));
 
-    if (command === "-h" || command === "--help") {
-        const helpCommand = argv[1];
-        console.log(helpCommand ? usageCommand(helpCommand) : usage());
-        process.exit(0);
-    }
-
-    const { values } = parseArgs({
-        args: argv.slice(1),
-        options: {
-            help: { type: "boolean", short: "h" },
-            from: { type: "string", short: "F" },
-            query: { type: "string", short: "q" },
-            header: { type: "string", short: "H" },
-            output: { type: "string", short: "o" },
-        },
-        strict: true,
-        allowPositionals: false,
+    skTools
+        .command("table")
+        .alias("t")
+        .description("Render stdin data as Markdown table")
+        .addOption(new Option("-F, --from <json|csv|tsv>", "Input format on stdin")
+            .choices(["json", "csv", "tsv"])
+            .default("json"))
+        .action(async (options, command) => {
+            const allOptions = command.optsWithGlobals();
+            const output = await runTableCommand(options);
+            renderCliOutput(output, allOptions.output ?? "alignedtable", allOptions.query, allOptions.columns);
         });
 
-    const typedValues = values as CliValues;
+    skTools
+        .command("table-info")
+        .alias("ti")
+        .description("Print row/column stats and inferred column types")
+        .addOption(new Option("-F, --from <json|csv|tsv>", "Input format on stdin")
+            .choices(["json", "csv", "tsv"])
+            .default("json"))
+        .action(async (options) => {
+            const output = await runTableInfoCommand(options);
+            console.log(output);
+        });
 
-    if (typedValues.help) {
-        console.log(usageCommand(command));
-        process.exit(0);
-    }
-
-    if (command !== "table") {
-        throw new Error(`Unknown command: ${command}`);
-    }
-
-    const outputFormat = normalizeOutputFormat(typedValues.output);
-    const result = await runTableCommand(typedValues);
-    const filtered = outputFiltered(result, typedValues.query);
-    const headerSpec = parseHeaderSpec(typedValues.header);
-
-    renderOutput(outputFormat, headerSpec, filtered);
+    await skTools.parseAsync(process.argv);
 }
 
 main().catch((err: unknown) => {
     const error = err as Error;
     console.error(`Error: ${error.message}`);
-    console.error(usage());
     process.exit(1);
 });

src/cli/commands/table-info.ts

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: MIT
+
+import {
+  readCsvFromStdin,
+  readJsonFromStdin,
+} from "../utils.ts";
+
+type TableInfoCommandValues = {
+  from?: string;
+};
+
+type RowObject = Record<string, unknown>;
+
+type ValueType = "string" | "number" | "boolean" | "object" | "array" | "null" | "unknown";
+
+function getType(value: unknown): ValueType {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (value === undefined) return "unknown";
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "object") return "object";
+  return "unknown";
+}
+
+function normalizeRows(input: unknown): { rowCount: number; rows: RowObject[] } {
+  if (Array.isArray(input)) {
+    return {
+      rowCount: input.length,
+      rows: input.map((item) =>
+        item && typeof item === "object" && !Array.isArray(item)
+          ? item as RowObject
+          : { value: item }
+      ),
+    };
+  }
+
+  if (input && typeof input === "object") {
+    return {
+      rowCount: 1,
+      rows: [input as RowObject],
+    };
+  }
+
+  return {
+    rowCount: 1,
+    rows: [{ value: input }],
+  };
+}
+
+function inferColumnType(rows: RowObject[], column: string): string {
+  const kinds = new Set<ValueType>();
+
+  for (const row of rows) {
+    if (!(column in row)) {
+      continue;
+    }
+
+    const kind = getType(row[column]);
+    if (kind !== "unknown") {
+      kinds.add(kind);
+    }
+  }
+
+  if (kinds.size === 0) {
+    return "unknown";
+  }
+
+  if (kinds.size === 1) {
+    return [...kinds][0];
+  }
+
+  if (kinds.size === 2 && kinds.has("null")) {
+    return [...kinds].find((kind) => kind !== "null") ?? "unknown";
+  }
+
+  return `mixed(${[...kinds].join("|")})`;
+}
+
+function buildInfo(input: unknown): string {
+  const { rowCount, rows } = normalizeRows(input);
+  const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+
+  const lines = [
+    `Number of columns: ${columns.length}`,
+    `Number of rows: ${rowCount}`,
+    "",
+    "Columns:",
+  ];
+
+  if (columns.length === 0) {
+    lines.push("- (none)");
+    return lines.join("\n");
+  }
+
+  for (const column of columns) {
+    lines.push(`- ${column}: ${inferColumnType(rows, column)}`);
+  }
+
+  return lines.join("\n");
+}
+
+export async function runTableInfoCommand(values: TableInfoCommandValues): Promise<string> {
+  const from = (values.from ?? "json").toString().trim().toLowerCase();
+
+  if (from === "json") {
+    return buildInfo(await readJsonFromStdin());
+  }
+  if (from === "csv") {
+    return buildInfo(await readCsvFromStdin(","));
+  }
+  if (from === "tsv") {
+    return buildInfo(await readCsvFromStdin("\t"));
+  }
+
+  throw new Error(`Invalid --from '${values.from}'. Allowed: json, csv, tsv`);
+}

src/cli/commands/table.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT
+
+import {
+  readCsvFromStdin,
+  readJsonFromStdin,
+} from "../utils.ts";
+
+type TableCommandValues = {
+  from?: string;
+};
+
+export async function runTableCommand(values: TableCommandValues): Promise<unknown> {
+  const from = (values.from ?? "json").toString().trim().toLowerCase();
+
+  if (from === "json") {
+    return readJsonFromStdin();
+  }
+  if (from === "csv") {
+    return readCsvFromStdin(",");
+  }
+  if (from === "tsv") {
+    return readCsvFromStdin("\t");
+  }
+
+  throw new Error(`Invalid --from '${values.from}'. Allowed: json, csv, tsv`);
+}

src/cli/utils.ts

@@ -5,11 +5,16 @@ import { dsvFormat } from "d3-dsv";
 
 import { toMarkdownTable } from "../markdown.ts";
 
-type HeaderSpec =
-  | { mode: "auto" }
-  | { mode: "original" }
-  | { mode: "list"; labels: string[] }
-  | { mode: "map"; map: Record<string, string> };
+type ColumnToken = {
+  sourceKey: string;
+  exactMatch: boolean;
+  labelMode: "raw" | "auto" | "custom";
+  customLabel?: string;
+};
+
+type ColumnSpec =
+  | { mode: "default" }
+  | { mode: "tokens"; tokens: ColumnToken[] };
 
 type OutputFormat = "json" | "table" | "alignedtable" | "prettytable" | "tsv";
 
@@ -22,41 +27,69 @@ export function outputFiltered(object: unknown, query?: string): unknown {
     : object;
 }
 
-export function parseHeaderSpec(headerValue?: string): HeaderSpec {
-  if (!headerValue) {
-    return { mode: "auto" };
+function parseColumnToken(rawToken: string): ColumnToken {
+  const token = rawToken.trim();
+  if (!token) {
+    throw new Error("Invalid --columns token: empty token");
   }
 
-  const raw = headerValue.trim();
-  if (raw === "" || raw.toLowerCase() === "auto" || raw.toLowerCase() === "a") {
-    return { mode: "auto" };
+  const exactMatch = token.startsWith("=");
+  const core = exactMatch ? token.slice(1).trim() : token;
+  if (!core) {
+    throw new Error(`Invalid --columns token: '${rawToken}'`);
   }
-  if (raw.toLowerCase() === "original" || raw.toLowerCase() === "o") {
-    return { mode: "original" };
+
+  const separatorIndex = core.indexOf(":");
+  if (separatorIndex < 0) {
+    return {
+      sourceKey: core,
+      exactMatch,
+      labelMode: "raw",
+    };
+  }
+
+  const sourceKey = core.slice(0, separatorIndex).trim();
+  if (!sourceKey) {
+    throw new Error(`Invalid --columns token: '${rawToken}'`);
+  }
+
+  const rawLabel = core.slice(separatorIndex + 1);
+  const label = rawLabel.trim();
+  if (!label) {
+    return {
+      sourceKey,
+      exactMatch,
+      labelMode: "auto",
+    };
+  }
+
+  return {
+    sourceKey,
+    exactMatch,
+    labelMode: "custom",
+    customLabel: label,
+  };
+}
+
+export function parseColumnSpec(columnsValue?: string): ColumnSpec {
+  if (!columnsValue) {
+    return { mode: "default" };
+  }
+
+  const raw = columnsValue.trim();
+  if (raw === "") {
+    return { mode: "default" };
   }
 
   const parts = raw.split(",").map((p) => p.trim()).filter(Boolean);
-  const isMap = parts.some((p) => p.includes(":"));
-
-  if (!isMap) {
-    return { mode: "list", labels: parts };
+  if (parts.length === 0) {
+    return { mode: "default" };
   }
 
-  const map: Record<string, string> = {};
-  for (const part of parts) {
-    const idx = part.indexOf(":");
-    if (idx < 0) {
-      throw new Error(`Invalid --header mapping segment: '${part}'`);
-    }
-    const key = part.slice(0, idx).trim();
-    const label = part.slice(idx + 1).trim();
-    if (!key || !label) {
-      throw new Error(`Invalid --header mapping segment: '${part}'`);
-    }
-    map[key] = label;
-  }
-
-  return { mode: "map", map };
+  return {
+    mode: "tokens",
+    tokens: parts.map((part) => parseColumnToken(part)),
+  };
 }
 
 export function normalizeOutputFormat(outputValue?: string): OutputFormat {
@@ -82,7 +115,7 @@ function isScalar(value: unknown): value is Scalar {
   return value == null || typeof value !== "object";
 }
 
-function getScalarRowsAndHeaders(value: unknown): { headers: string[]; rows: ScalarRow[] } {
+export function getScalarRowsAndHeaders(value: unknown): { headers: string[]; rows: ScalarRow[] } {
   let rows: Array<Record<string, unknown>>;
   if (Array.isArray(value)) {
     rows = value.map((item) =>
@@ -202,7 +235,7 @@ export async function readCsvFromStdin(separator: string): Promise<unknown> {
 
 export function renderOutput(
   outputFormat: OutputFormat,
-  headerSpec: HeaderSpec,
+  columnSpec: ColumnSpec,
   output: unknown,
 ): void {
   if (outputFormat === "tsv") {
@@ -215,12 +248,24 @@ export function renderOutput(
   // - alignedtable: aligned columns, no quoting
   // - prettytable: aligned columns + quoting selected values
   if (outputFormat === "prettytable") {
-    console.log(toMarkdownTable(output, "prettytable", headerSpec));
+    console.log(toMarkdownTable(output, "prettytable", columnSpec));
   } else if (outputFormat === "alignedtable") {
-    console.log(toMarkdownTable(output, "alignedtable", headerSpec));
+    console.log(toMarkdownTable(output, "alignedtable", columnSpec));
   } else if (outputFormat === "table") {
-    console.log(toMarkdownTable(output, "table", headerSpec));
+    console.log(toMarkdownTable(output, "table", columnSpec));
   } else {
     console.log(JSON.stringify(output, null, 2));
   }
 }
+
+export function renderCliOutput(
+  output: unknown,
+  outputValue?: string,
+  query?: string,
+  columnsValue?: string,
+): void {
+  const outputFormat = normalizeOutputFormat(outputValue);
+  const filtered = outputFiltered(output, query);
+  const columnSpec = parseColumnSpec(columnsValue);
+  renderOutput(outputFormat, columnSpec, filtered);
+}

src/config/index.ts

@@ -4,7 +4,7 @@ import { readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
-function getConfigDir(moduleName: string): string {
+export function getConfigDir(moduleName: string): string {
   if (process.platform === "win32") {
     return path.join(process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local"), moduleName);
   }

src/index.ts

@@ -3,9 +3,11 @@
 export { toMarkdownTable } from "./markdown.ts";
 export {
   outputFiltered,
-  parseHeaderSpec,
+  parseColumnSpec,
   normalizeOutputFormat,
   readJsonFromStdin,
   readCsvFromStdin,
   renderOutput,
+  renderCliOutput,
 } from "./cli/utils.ts";
+export { getConfigDir, getConfig } from "./config/index.ts";

src/markdown.ts

@@ -1,14 +1,20 @@
 // SPDX-License-Identifier: MIT
 
+import { validate as validateUuid } from "uuid";
+
 type Scalar = string | number | boolean | null | undefined;
 type ScalarRow = Record<string, Scalar>;
 
-type HeaderSpec =
+type ColumnToken = {
+  sourceKey: string;
+  exactMatch: boolean;
+  labelMode: "raw" | "auto" | "custom";
+  customLabel?: string;
+};
+
+type ColumnSpec =
   | { mode: "default" }
-  | { mode: "auto" }
-  | { mode: "original" }
-  | { mode: "list"; labels: string[] }
-  | { mode: "map"; map: Record<string, string> };
+  | { mode: "tokens"; tokens: ColumnToken[] };
 
 type TableMode = "table" | "alignedtable" | "prettytable";
 
@@ -20,7 +26,15 @@ function formatCell(value: unknown): string {
 }
 
 const inlineCodePredicates = [
-  (value: Scalar): boolean => isGuid(value),
+  (value: Scalar): boolean => typeof value === "string" && validateUuid(value),
+  (value: Scalar): boolean => {
+    if (typeof value !== "string" || !value.toLowerCase().startsWith("/subscriptions/")) {
+      return false;
+    }
+    const rest = value.slice("/subscriptions/".length);
+    const subscriptionId = rest.split("/", 1)[0];
+    return validateUuid(subscriptionId);
+  },
   (value: Scalar): boolean =>
     typeof value === "string"
     && /^(?:\d{1,3}\.){3}\d{1,3}(?:\/(?:\d{1,2}|(?:\d{1,3}\.){3}\d{1,3}))?$/.test(value),
@@ -38,11 +52,6 @@ function renderCell(raw: Scalar, shouldQuote: boolean): string {
   return text;
 }
 
-function isGuid(value: unknown): value is string {
-  return typeof value === "string"
-    && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
-}
-
 function toAutoHeaderLabel(key: string): string {
   const withSpaces = String(key)
     .replace(/[_-]+/g, " ")
@@ -106,21 +115,43 @@ function getScalarRowsAndHeaders(value: unknown): { headers: string[]; rows: Sca
   return { headers, rows: scalarRows };
 }
 
+function resolveColumnKey(headers: string[], token: ColumnToken): string {
+  if (token.exactMatch) {
+    return headers.find((header) => header === token.sourceKey) ?? token.sourceKey;
+  }
+
+  const matches = headers.filter(
+    (header) => header.toLowerCase() === token.sourceKey.toLowerCase(),
+  );
+
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous --columns token '${token.sourceKey}' matches multiple columns: ${matches.join(", ")}. Use exact match with '=...'.`,
+    );
+  }
+
+  return matches[0] ?? token.sourceKey;
+}
+
 export function toMarkdownTable(
   value: unknown,
   mode: TableMode = "table",
-  headerSpec: HeaderSpec = { mode: "default" },
+  columnSpec: ColumnSpec = { mode: "default" },
 ): string {
   const prettyMode = mode === "prettytable";
   const { headers, rows } = getScalarRowsAndHeaders(value);
-  const headerDefinitions = headers.map((key, idx) => {
+  const headerDefinitions = columnSpec.mode === "default"
+    ? headers.map((key) => ({
+      key,
+      label: toAutoHeaderLabel(key),
+    }))
+    : columnSpec.tokens.map((token) => {
+      const key = resolveColumnKey(headers, token);
       let label = key;
-    if (headerSpec.mode === "auto") {
+      if (token.labelMode === "auto") {
         label = toAutoHeaderLabel(key);
-    } else if (headerSpec.mode === "list" && headerSpec.labels[idx]) {
-      label = headerSpec.labels[idx];
-    } else if (headerSpec.mode === "map" && headerSpec.map[key]) {
-      label = headerSpec.map[key];
+      } else if (token.labelMode === "custom") {
+        label = token.customLabel ?? "";
       }
       return { key, label };
     });