Add man page generator for tagoio CLI

.gitignore

@@ -61,3 +61,6 @@ exportBackup
 .tago-lock.dev-ue.lock
 .tago-lock.dev-ue-2.lock
 .tago-lock.dev-1.lock
+
+# generated by `npm run man` and shipped via the `files` field at publish time
+man/

README.md

@@ -51,6 +51,8 @@ Installing the TagoIO Command Line Tools is a straightforward process. Follow th
    tagoio login
    ```
 
+6. **Reference (Optional)**: A man page is installed alongside the CLI. Run `man tagoio` for the full command reference. Fish users can additionally run `fish_update_completions` to enable tab-completion (fish auto-extracts flag metadata from the installed man page).
+
 ## Command List
 List of commands of the CLI
 **Usage**:

package.json

@@ -20,10 +20,13 @@
     "npm": ">=10.0.0"
   },
   "files": [
-    "build"
+    "build",
+    "man"
   ],
   "scripts": {
-    "build": "rm -rf ./build; tsc --build; chmod +x ./build/index.js",
+    "man": "mkdir -p man && tsx src/lib/generate-man.ts > man/tagoio.1 && chmod 644 man/tagoio.1",
+    "build": "npm run man && rm -rf ./build; tsc --build; chmod +x ./build/index.js",
+    "prepublishOnly": "npm run man",
     "test": "vitest run",
     "test:single": "vitest --",
     "test:coverage": "vitest run --coverage",
@@ -35,6 +38,7 @@
   "bin": {
     "tagoio": "./build/index.js"
   },
+  "man": "./man/tagoio.1",
   "author": "TagoIO LLC",
   "license": "ISC",
   "dependencies": {
@@ -59,8 +63,8 @@
     "@types/prompts": "^2.4.9",
     "@types/unzipper": "^0.10.11",
     "@vitest/coverage-v8": "^4.1.5",
-    "oxfmt": "^0.46.0",
-    "oxlint": "1.61.0",
+    "oxfmt": "^0.47.0",
+    "oxlint": "1.62.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   }

src/index.ts

@@ -25,18 +25,6 @@ dotenv.config({ path: ENV_FILE_PATH, quiet: true });
 const indexConfigFile = getConfigFile();
 const defaultEnvironment = process.env.TAGOIO_DEFAULT || "";
 
-/**
- * Calls functions to add all available commands to the CLI program.
- * @param program - The CLI program to add commands to.
- * @returns A Promise that resolves when all commands have been added.
- */
-async function getAllCommands(program: Command) {
-  analysisCommands(program);
-  deviceCommands(program);
-  dashboardCommands(program);
-  profileCommands(program, defaultEnvironment);
-}
-
 /**
  * Returns a string with ANSI escape codes to display text in red.
  *
@@ -49,21 +37,29 @@ function errorColor(str: string) {
 }
 
 /**
- * Initializes the TagoIO Command Line Tools program and sets up the available commands.
- * @returns {Promise<void>} A Promise that resolves when the program has finished parsing the command line arguments.
+ * @description Builds the commander program with every top-level command
+ * (init / login / set-env / list-env) and every namespace (analysis,
+ * devices, dashboard, profile) registered. Returns the configured program
+ * without calling `program.parse()`.
+ *
+ * This is the single source of truth for the CLI's command surface. Both the
+ * runtime entry point (`initiateCMD`) and the man-page generator
+ * (`src/lib/generate-man.ts`) call it — adding a new command in this file
+ * automatically appears in `tagoio --help` and in `man tagoio` on the next
+ * `npm run man`.
+ *
+ * @param defaultEnv - Default value for the optional `[environment]`
+ *   argument on `init` and `login`. Pass `""` for a user-agnostic build
+ *   (e.g. man-page generation); pass the runtime selection otherwise.
  */
-async function initiateCMD() {
-  const updateLog = await updater({ name: packageJSON.name, version: packageJSON.version });
+function buildProgram(defaultEnv: string): Command {
   const program = new Command();
-  program.exitOverride(async () => {
-    updateLog();
-  });
 
   program.version(packageJSON.version).description(`${kleur.bold(`TagoIO Command Line Tools - v${packageJSON.version}`)}
-  \tDefault Environment: ${highlightMSG(defaultEnvironment)}
-  \tProfile ID: ${highlightMSG(indexConfigFile?.[defaultEnvironment]?.id || "N/A")}
-  \tName: ${highlightMSG(indexConfigFile?.[defaultEnvironment]?.profileName || "N/A")}
-  \tEmail: ${highlightMSG(indexConfigFile?.[defaultEnvironment]?.email || "N/A")}`);
+  \tDefault Environment: ${highlightMSG(defaultEnv)}
+  \tProfile ID: ${highlightMSG(indexConfigFile?.[defaultEnv]?.id || "N/A")}
+  \tName: ${highlightMSG(indexConfigFile?.[defaultEnv]?.profileName || "N/A")}
+  \tEmail: ${highlightMSG(indexConfigFile?.[defaultEnv]?.email || "N/A")}`);
 
   program.configureOutput({
     writeErr: (str) => process.stderr.write(`[${errorColor("ERROR")}] ${str}`),
@@ -74,7 +70,7 @@ async function initiateCMD() {
   program
     .command("init")
     .description("create/update the config file for analysis in your current folder")
-    .argument("[environment]", "name of the environment.", defaultEnvironment)
+    .argument("[environment]", "name of the environment.", defaultEnv)
     .option("-t, --token <profile-token>", "profile token of the environment and skip login step")
     .action(startConfig)
     .addHelpText(
@@ -91,7 +87,7 @@ Example:
   program
     .command("login")
     .description("login to your account and store profile_token in the tago-lock.")
-    .argument("[environment]", "name of the environment", defaultEnvironment)
+    .argument("[environment]", "name of the environment", defaultEnv)
     .option("-u, --email <email>", "your TagoIO email")
     .option("-p, --password <password>", "your TagoIO password")
     .option("-t, --token <profile-token>", "set a profile-token for the environment and skip login step")
@@ -131,9 +127,31 @@ Example:
    $ tagoio list-env`,
     );
 
-  await getAllCommands(program);
+  analysisCommands(program);
+  deviceCommands(program);
+  dashboardCommands(program);
+  profileCommands(program, defaultEnv);
 
+  return program;
+}
+
+/**
+ * Initializes the TagoIO Command Line Tools program and parses argv.
+ */
+async function initiateCMD() {
+  const updateLog = await updater({ name: packageJSON.name, version: packageJSON.version });
+  const program = buildProgram(defaultEnvironment);
+  program.exitOverride(async () => {
+    updateLog();
+  });
   program.parse();
 }
 
-initiateCMD().catch(console.error);
+// Auto-run only when invoked as the CLI binary; importing this module from a
+// build-time tool (e.g. the man-page generator) must NOT trigger argv parsing.
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  initiateCMD().catch(console.error);
+}
+
+export { buildProgram };