niahere 0.2.51 → 0.2.52

package/README.md

@@ -34,51 +34,63 @@ nia start               # starts daemon + registers OS service
 - **Slack** — Socket Mode bot with thread awareness, thinking emoji, watch channels for proactive monitoring
 - **Terminal chat** — REPL with session resume support
 - **Scheduled jobs** — recurring jobs and crons that run Claude and can message you back
-- **Persona system** — customizable identity, soul, owner profile, and on-demand memory
+- **Persona system** — customizable identity, soul, owner profile, rules, and memory (preloaded every session)
 - **Agents** — domain specialists (marketer, senior-dev) via Claude Agent SDK subagents
 - **Skills** — loads skills from multiple directories, invokable as slash commands
 - **Cross-platform service** — launchd (macOS), systemd (Linux), service-aware restart
-- **MCP tools** — 18 tools for job management, messaging, memory, and channel control
+- **MCP tools** — 20 tools for job management, messaging, memory, rules, and channel control
+- **Background memory consolidation** — extracts memories from conversations and job runs automatically
+- **Session summaries** — handoff notes between sessions for continuity
+- **Backups** — `nia backup` with auto-backup before updates
 - **Optional integrations** — add Gmail, Discord, and more via skills
 
 ## Commands
 
 ```
-nia init                       — interactive setup (db, channels, persona, images)
+nia init                       — interactive setup (db, channels, persona, agents, active hours)
 nia start / stop               — daemon + OS service (launchd/systemd)
 nia restart                    — restart daemon (service-aware)
 nia status                     — show daemon, jobs, channels, chat rooms
-nia chat [-r|--resume]         — interactive terminal chat
+nia health                     — check daemon, db, channels, config
+nia chat [-c|-r] [--channel ch] — terminal chat (new by default, -c continue, -r pick)
 nia run <prompt>               — one-shot prompt execution
 nia history [room]             — recent messages
-nia logs [-f]                  — daemon logs (follow with -f)
+nia logs [-f] [--channel ch]   — daemon logs (follow with -f, filter by channel)
 nia send [-c channel] <msg>    — send a message via channel
-nia skills                     — list available skills
 nia version                    — show version
+nia update                     — update to latest version (auto-backup + restart)
 
 nia job list                   — list all jobs
 nia job show [name]            — full details + recent runs
-nia job add <n> <s> <p>        — add a job (active hours only)
-nia job add <n> <s> <p> --agent <name> — add a job using an agent
-nia job add <n> <s> <p> --always — add a cron (runs 24/7)
+nia job status [name]          — quick status check
+nia job add <n> <s> <p>        — add a job (--type, --always, --agent, --prompt-file)
+nia job update <name>          — update a job (--schedule, --prompt, --prompt-file, --type, --always, --agent)
 nia job remove <name>          — delete a job
 nia job enable / disable <n>   — toggle a job
 nia job run <name>             — run a job once
 nia job log [name]             — show recent run history
 
+nia rules [show|reset]         — view or reset rules.md
+nia memory [show|reset]        — view or reset memory.md
 nia agent list                 — list available agents
 nia agent show <name>          — show agent details and prompt
+nia skills [source]            — list available skills
 
-nia db setup                   — install PostgreSQL + create database + migrate
-nia db migrate                 — run database migrations
-nia db status                  — check database connection
+nia channels                   — show channel status (on/off)
+nia channels on / off          — enable/disable channels (applied via SIGHUP, no restart)
+nia watch list                 — list Slack watch channels
+nia watch add/remove/enable/disable — manage watch channels
 
 nia config list                — show all config
 nia config get <key>           — get a config value (dot notation supported)
 nia config set <key> <value>   — set a config value
+nia validate                   — validate config.yaml
+nia backup [list]              — create or list backups
+nia test [-v]                  — run tests
 
-nia channels                   — show channel status (on/off)
-nia channels on / off          — enable/disable channels
+nia db setup                   — install PostgreSQL + create database + migrate
+nia db migrate                 — run database migrations
+nia db status                  — check database connection
 ```
 
 ## Architecture
@@ -92,7 +104,8 @@ All config and data lives in `~/.niahere/`:
     identity.md     — agent personality and voice
     owner.md        — who runs this agent
     soul.md         — how the agent works
-    memory.md       — persistent learnings (read/written on demand)
+    rules.md        — behavioral instructions (loaded every session)
+    memory.md       — persistent facts and context (loaded every session)
   images/
     reference.webp  — visual identity reference image
     profile.webp    — profile picture for Telegram/Slack
@@ -119,7 +132,7 @@ Users then run `/add-discord` on their fork and get clean code that does exactly
 ## Updating
 
 ```bash
-npm i -g niahere         # pulls the latest version from npm
+nia update               # auto-backup, install latest, restart daemon
 ```
 
 ## Author

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "niahere",
-  "version": "0.2.51",
-  "description": "A personal AI assistant daemon — scheduled jobs, chat across Telegram and Slack, persona system, and visual identity.",
+  "version": "0.2.52",
+  "description": "A personal AI assistant daemon — chat, scheduled jobs, persona system, extensible via skills.",
   "type": "module",
   "scripts": {
     "start": "bun run src/cli/index.ts start",

package/src/cli/agent.ts

@@ -1,8 +1,20 @@
 import { scanAgents } from "../core/agents";
+import { fail } from "../utils/cli";
+
+const HELP = `Usage: nia agent <command>
+
+Commands:
+  list          List all available agents
+  show <name>   Show agent details and prompt`;
 
 export async function agentCommand(): Promise<void> {
   const subcommand = process.argv[3];
 
+  if (subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
+    console.log(HELP);
+    return;
+  }
+
   switch (subcommand) {
     case "list": {
       const agents = scanAgents();
@@ -20,16 +32,10 @@ export async function agentCommand(): Promise<void> {
 
     case "show": {
       const name = process.argv[4];
-      if (!name) {
-        console.error("Usage: nia agent show <name>");
-        process.exit(1);
-      }
+      if (!name) fail("Usage: nia agent show <name>");
       const agents = scanAgents();
       const agent = agents.find((a) => a.name === name);
-      if (!agent) {
-        console.error(`Agent "${name}" not found.`);
-        process.exit(1);
-      }
+      if (!agent) fail(`Agent "${name}" not found.`);
       console.log(`Name:        ${agent.name}`);
       console.log(`Description: ${agent.description}`);
       if (agent.model) console.log(`Model:       ${agent.model}`);
@@ -40,8 +46,8 @@ export async function agentCommand(): Promise<void> {
     }
 
     default:
-      console.log("Usage: nia agent <list|show>");
-      console.log("  list          List all available agents");
-      console.log("  show <name>   Show agent details and prompt");
+      if (subcommand) console.error(`Unknown subcommand: ${subcommand}`);
+      console.log(HELP);
+      process.exit(subcommand ? 1 : 0);
   }
 }

package/src/cli/index.ts

@@ -29,7 +29,7 @@ try {
 const command = process.argv[2];
 
 // Ensure ~/.niahere/ exists for commands that need it
-if (command && !["init", "help", "version", "-v", "--version"].includes(command)) {
+if (command && !["init", "help", "version", "-v", "--version", "-h", "--help"].includes(command)) {
   mkdirSync(getNiaHome(), { recursive: true });
 }
 
@@ -494,30 +494,54 @@ switch (command) {
     break;
   }
 
-  default:
-    console.log("Usage: nia <command>\n");
-    console.log("  update              — update to latest version and restart");
-    console.log("  init                — setup nia");
-    console.log("  start / stop        — daemon + service control");
-    console.log("  restart             — restart daemon");
-    console.log("  status [--json --rooms N --all]  — show daemon, jobs, channels");
-    console.log("  health              — check daemon, db, channels, config");
-    console.log("  chat [--channel ch] — interactive chat (--channel simulates a channel)");
-    console.log("  run <prompt>        — one-shot execution");
-    console.log("  history [room]      — recent messages");
-    console.log("  logs [-f] [--channel ch]  — daemon logs (filter by channel)");
-    console.log("  job <sub>           — manage jobs");
-    console.log("  rules [show|reset]  — view or reset rules.md");
-    console.log("  memory [show|reset] — view or reset memory.md");
-    console.log("  db <sub>            — database setup/status/migrate");
-    console.log("  agent <sub>         — list/show agents");
-    console.log("  skills              — list available skills");
-    console.log("  watch <sub>         — manage Slack watch channels");
-    console.log("  validate            — validate config.yaml");
-    console.log("  config <sub>        — get/set/list config values");
-    console.log("  send [-c ch] <msg>  — send a message via channel");
-    console.log("  telegram <token>    — configure telegram");
-    console.log("  slack <bot> <app>   — configure slack");
-    console.log("  test                — run tests");
-    process.exit(command ? 1 : 0);
+  case "help":
+  case "--help":
+  case "-h":
+  default: {
+    const HELP = `Usage: nia <command>
+
+Daemon:
+  start                           Start daemon + register service
+  stop                            Stop daemon + unregister service
+  restart                         Restart daemon
+  status [--json --rooms N --all] Show daemon, jobs, channels
+  health                          Check daemon, db, channels, config
+  logs [-f] [--channel ch]        Daemon logs (filter by channel)
+
+Chat:
+  chat [-c] [-r] [--channel ch]   Interactive chat (new session by default)
+  run <prompt>                    One-shot execution
+  history [room]                  Recent messages
+  send [-c ch] <msg>              Send a message via channel
+
+Jobs:
+  job <sub>                       Manage jobs (list|add|update|remove|run|...)
+
+Persona:
+  rules [show|reset]              View or reset rules.md
+  memory [show|reset]             View or reset memory.md
+  agent <sub>                     List/show agents
+  skills [source]                 List available skills
+
+Channels:
+  channels [on|off]               Toggle channels
+  watch <sub>                     Manage Slack watch channels
+  telegram <token>                Configure telegram
+  slack <bot> <app>               Configure slack
+
+System:
+  config <set|get|list>           Manage config values
+  backup [list]                   Create or list backups
+  validate                        Validate config.yaml
+  db <sub>                        Database setup/status/migrate
+  update                          Update to latest version
+  init                            Initial setup
+  test [-v]                       Run tests`;
+
+    console.log(HELP);
+    // Unknown command → exit 1, help/no command → exit 0
+    const isHelp = !command || command === "help" || command === "--help" || command === "-h";
+    if (!isHelp) console.error(`\nUnknown command: ${command}`);
+    process.exit(isHelp ? 0 : 1);
+  }
 }

package/src/cli/job.ts

@@ -1,5 +1,4 @@
 import * as readline from "readline";
-import { CronExpressionParser } from "cron-parser";
 import { readState, readAudit } from "../utils/logger";
 import { getConfig } from "../utils/config";
 import { runJob } from "../core/runner";
@@ -9,9 +8,34 @@ import { Job } from "../db/models";
 import { withDb } from "../db/connection";
 import type { ScheduleType } from "../types";
 import { errMsg } from "../utils/errors";
-import { fail, pickFromList, ICON_PASS, ICON_FAIL } from "../utils/cli";
+import { fail, parseArgs, pickFromList, ICON_PASS, ICON_FAIL } from "../utils/cli";
 import { computeInitialNextRun } from "../core/scheduler";
 
+const HELP = `Usage: nia job <command>
+
+Commands:
+  list                          List all jobs
+  show [name]                   Full job details + recent runs
+  status [name]                 Quick status check
+  add <name> <schedule> <prompt>  Add a job
+      --prompt <text>             Prompt text (alternative to positional)
+      --prompt-file <path>        Read prompt from file (for long/multi-line)
+      --type cron|interval|once   Schedule type (default: cron)
+      --always                    Run 24/7 regardless of active hours
+      --agent <name>              Assign an agent to the job
+  update <name>                 Update a job
+      --schedule <schedule>       New schedule
+      --prompt <text>             New prompt
+      --prompt-file <path>        Read prompt from file (for long/multi-line)
+      --type cron|interval|once   Change schedule type
+      --always / --no-always      Toggle 24/7 mode
+      --agent <name>              Assign agent (--no-agent to remove)
+  remove <name>                 Delete a job
+  enable <name>                 Enable a job
+  disable <name>                Disable a job
+  run <name>                    Run a job once
+  log [name]                    Show recent run history`;
+
 async function pickJob(prompt = "Pick a job"): Promise<string> {
   let jobs: { name: string; schedule: string; enabled: boolean; prompt: string }[] = [];
   try {
@@ -39,6 +63,11 @@ async function pickJob(prompt = "Pick a job"): Promise<string> {
 export async function jobCommand(): Promise<void> {
   const subcommand = process.argv[3];
 
+  if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    console.log(HELP);
+    process.exit(subcommand ? 0 : 0);
+  }
+
   switch (subcommand) {
     case "list": {
       try {
@@ -62,42 +91,36 @@ export async function jobCommand(): Promise<void> {
     }
 
     case "add": {
-      const always = process.argv.includes("--always");
-      let cliArgs = process.argv.slice(4).filter((a) => a !== "--always");
-
-      // Parse --type flag
-      let scheduleType: ScheduleType = "cron";
-      const typeIdx = cliArgs.indexOf("--type");
-      if (typeIdx !== -1 && cliArgs[typeIdx + 1]) {
-        const val = cliArgs[typeIdx + 1];
-        if (val === "cron" || val === "interval" || val === "once") {
-          scheduleType = val;
-          cliArgs.splice(typeIdx, 2);
-        }
-      }
+      const args = parseArgs(process.argv.slice(4), ["always"]);
+      if (args.help) { console.log(HELP); return; }
 
-      // Parse --agent flag
-      let agent: string | undefined;
-      const agentIdx = cliArgs.indexOf("--agent");
-      if (agentIdx !== -1 && cliArgs[agentIdx + 1]) {
-        agent = cliArgs[agentIdx + 1];
-        cliArgs.splice(agentIdx, 2);
+      const scheduleType = (args.getString("type") || "cron") as ScheduleType;
+      if (!["cron", "interval", "once"].includes(scheduleType)) {
+        fail(`Invalid --type: "${scheduleType}". Must be cron, interval, or once.`);
       }
 
-      const name = cliArgs[0];
-      const schedule = cliArgs[1];
-      const prompt = cliArgs.slice(2).join(" ");
+      const always = args.getBool("always") ?? false;
+      const agent = args.getString("agent");
+
+      const [name, schedule, ...promptParts] = args.positional;
+      const promptFlag = args.getString("prompt");
+      const promptFile = args.getString("prompt-file");
+      let prompt: string;
+      if (promptFile) {
+        const { existsSync, readFileSync } = await import("fs");
+        if (!existsSync(promptFile)) fail(`File not found: ${promptFile}`);
+        prompt = readFileSync(promptFile, "utf8").trim();
+      } else if (promptFlag) {
+        prompt = promptFlag;
+      } else {
+        prompt = promptParts.join(" ");
+      }
 
       if (!name || !schedule || !prompt) {
-        console.log('Usage: nia job add <name> <schedule> <prompt> [--always] [--type cron|interval|once] [--agent <name>]');
+        console.error('Usage: nia job add <name> <schedule> <prompt> [--always] [--type cron|interval|once] [--agent <name>]');
         fail('Example: nia job add heartbeat "*/10 * * * *" Check system health --always');
       }
 
-      // Validate schedule based on type
-      if (scheduleType === "cron") {
-        try { CronExpressionParser.parse(schedule); } catch { fail(`Invalid cron schedule: ${schedule}`); }
-      }
-
       try {
         const config = getConfig();
         const nextRunAt = computeInitialNextRun(scheduleType, schedule, config.timezone);
@@ -144,29 +167,47 @@ export async function jobCommand(): Promise<void> {
     }
 
     case "update": {
-      const hasAlways = process.argv.includes("--always");
-      const hasNoAlways = process.argv.includes("--no-always");
-      let cliArgs = process.argv.slice(4).filter((a) => a !== "--always" && a !== "--no-always");
+      const args = parseArgs(process.argv.slice(4), ["always"]);
+      if (args.help) { console.log(HELP); return; }
 
-      const name = cliArgs[0];
+      const name = args.positional[0];
       if (!name) {
-        console.log('Usage: nia job update <name> [--schedule <schedule>] [--prompt <prompt>] [--always] [--no-always]');
+        console.error('Usage: nia job update <name> [--schedule <s>] [--prompt <p>] [--type <t>] [--always] [--no-always]');
         fail('Example: nia job update curator --schedule "4h" --prompt "New prompt"');
       }
 
-      const scheduleIdx = cliArgs.indexOf("--schedule");
-      const schedule = scheduleIdx !== -1 ? cliArgs[scheduleIdx + 1] : undefined;
-      const promptIdx = cliArgs.indexOf("--prompt");
-      const prompt = promptIdx !== -1 ? cliArgs.slice(promptIdx + 1).filter((a) => a !== "--schedule" && a !== schedule).join(" ") : undefined;
+      const fields: Partial<{ schedule: string; prompt: string; always: boolean; scheduleType: ScheduleType; agent: string | null }> = {};
+      const schedule = args.getString("schedule");
+      const promptFile = args.getString("prompt-file");
+      let prompt = args.getString("prompt");
+      if (promptFile) {
+        const { existsSync, readFileSync } = await import("fs");
+        if (!existsSync(promptFile)) fail(`File not found: ${promptFile}`);
+        prompt = readFileSync(promptFile, "utf8").trim();
+      }
+      const scheduleType = args.getString("type") as ScheduleType | undefined;
+      const always = args.getBool("always");
+      const agent = args.getString("agent");
+      const noAgent = args.getBool("agent");
+
+      if (schedule) fields.schedule = schedule;
+      if (prompt) fields.prompt = prompt;
+      if (scheduleType) {
+        if (!["cron", "interval", "once"].includes(scheduleType)) {
+          fail(`Invalid --type: "${scheduleType}". Must be cron, interval, or once.`);
+        }
+        fields.scheduleType = scheduleType;
+      }
+      if (always !== undefined) fields.always = always;
+      if (agent) fields.agent = agent;
+      if (noAgent === false) fields.agent = null;
+
+      if (Object.keys(fields).length === 0) {
+        fail("Nothing to update. Pass at least one flag (--schedule, --prompt, --type, --always, --agent).");
+      }
 
       try {
         await withDb(async () => {
-          const fields: Partial<{ schedule: string; prompt: string; always: boolean }> = {};
-          if (schedule) fields.schedule = schedule;
-          if (prompt) fields.prompt = prompt;
-          if (hasAlways) fields.always = true;
-          if (hasNoAlways) fields.always = false;
-
           const updated = await Job.update(name, fields);
           if (!updated) fail(`Job not found: "${name}". Use \`nia job list\` to see available jobs.`);
           console.log(`Job "${name}" updated.`);
@@ -186,9 +227,9 @@ export async function jobCommand(): Promise<void> {
           if (!job) fail(`Job not found: ${name}`);
 
           console.log(`  ${job.enabled ? "●" : "○"} ${job.name}`);
-          console.log(`  schedule: ${job.schedule}`);
+          console.log(`  schedule: ${job.schedule} (${job.scheduleType})`);
           console.log(`  enabled:  ${job.enabled}`);
-          console.log(`  type:     ${job.always ? "cron (runs 24/7)" : "job (active hours only)"}`);
+          console.log(`  always:   ${job.always}`);
           if (job.agent) console.log(`  agent:    ${job.agent}`);
           console.log(`  prompt:   ${job.prompt}`);
 
@@ -313,20 +354,8 @@ export async function jobCommand(): Promise<void> {
     }
 
     default:
-      console.log("Usage: nia job <list|show|status|add|update|remove|enable|disable|run|log|import>\n");
-      console.log("  list                          — list all jobs");
-      console.log("  show [name]                   — full job details + recent runs");
-      console.log("  status [name]                 — quick status check");
-      console.log("  add <name> <schedule> <prompt> — add a job (active hours only)")
-      console.log("      --always                  — run 24/7 regardless of active hours");
-      console.log("      --agent <name>            — assign an agent to the job");
-      console.log("  update <name> [--schedule s] [--prompt p] [--always] — update a job");
-      console.log("  remove <name>                 — delete a job");
-      console.log("  enable <name>                 — enable a job");
-      console.log("  disable <name>                — disable a job");
-      console.log("  run <name>                    — run a job once");
-      console.log("  log [name]                    — show recent run history");
-      console.log("  import                        — import YAML jobs to DB");
-      process.exit(subcommand ? 1 : 0);
+      console.error(`Unknown subcommand: ${subcommand}`);
+      console.log(HELP);
+      process.exit(1);
   }
 }

package/src/cli/watch.ts

@@ -2,9 +2,23 @@ import { readRawConfig } from "../utils/config";
 import { addWatchChannel, removeWatchChannel, enableWatchChannel, disableWatchChannel } from "../mcp/tools";
 import { fail, ICON_PASS, ICON_FAIL } from "../utils/cli";
 
+const HELP = `Usage: nia watch <command>
+
+Commands:
+  list                              List watch channels (default)
+  add <channel_id#name> <behavior>  Add a watch channel
+  remove <channel_id#name>          Remove a watch channel
+  enable <channel_id#name>          Enable a watch channel
+  disable <channel_id#name>         Disable a watch channel`;
+
 export function watchCommand(): void {
   const sub = process.argv[3];
 
+  if (sub === "--help" || sub === "-h" || sub === "help") {
+    console.log(HELP);
+    return;
+  }
+
   switch (sub) {
     case "list":
     case undefined: {
@@ -60,12 +74,8 @@ export function watchCommand(): void {
     }
 
     default:
-      console.log("Usage: nia watch <list|add|remove|enable|disable>\n");
-      console.log("  list                              — list watch channels (default)");
-      console.log("  add <channel_id#name> <behavior>  — add a watch channel");
-      console.log("  remove <channel_id#name>          — remove a watch channel");
-      console.log("  enable <channel_id#name>          — enable a watch channel");
-      console.log("  disable <channel_id#name>         — disable a watch channel");
-      process.exit(sub ? 1 : 0);
+      console.error(`Unknown subcommand: ${sub}`);
+      console.log(HELP);
+      process.exit(1);
   }
 }

package/src/core/scheduler.ts

@@ -65,6 +65,7 @@ function isWithinActiveHours(): boolean {
 }
 
 let timer: ReturnType<typeof setInterval> | null = null;
+const runningJobs = new Set<string>();
 
 async function tick(): Promise<void> {
   let dueJobs: Awaited<ReturnType<typeof Job.listDue>>;
@@ -87,12 +88,20 @@ async function tick(): Promise<void> {
       continue;
     }
 
+    if (runningJobs.has(job.name)) {
+      log.info({ job: job.name }, "scheduler: skipping — still running from previous invocation");
+      continue;
+    }
+
     log.info({ job: job.name, type: job.scheduleType }, "scheduler: running job");
+    runningJobs.add(job.name);
 
     runJob(job).then((result) => {
       log.info({ job: job.name, status: result.status, duration: result.duration_ms }, "scheduler: job completed");
     }).catch((err) => {
       log.error({ err, job: job.name }, "scheduler: job failed");
+    }).finally(() => {
+      runningJobs.delete(job.name);
     });
 
     let nextRun: Date | null = null;

package/src/utils/cli.ts

@@ -1,14 +1,17 @@
 import * as readline from "readline";
 
-// ANSI colors
-export const DIM = "\x1b[2m";
-export const BOLD = "\x1b[1m";
-export const RESET = "\x1b[0m";
-export const RED = "\x1b[31m";
-export const GREEN = "\x1b[32m";
-export const YELLOW = "\x1b[33m";
-export const CYAN = "\x1b[36m";
-export const CLEAR_LINE = "\x1b[2K\r";
+// TTY detection — disable colors/formatting when piped
+const isTTY = process.stdout.isTTY ?? false;
+
+// ANSI colors (empty strings when not a TTY)
+export const DIM = isTTY ? "\x1b[2m" : "";
+export const BOLD = isTTY ? "\x1b[1m" : "";
+export const RESET = isTTY ? "\x1b[0m" : "";
+export const RED = isTTY ? "\x1b[31m" : "";
+export const GREEN = isTTY ? "\x1b[32m" : "";
+export const YELLOW = isTTY ? "\x1b[33m" : "";
+export const CYAN = isTTY ? "\x1b[36m" : "";
+export const CLEAR_LINE = isTTY ? "\x1b[2K\r" : "";
 
 // Icons
 export const ICON_PASS = "\u2713";
@@ -19,11 +22,120 @@ export const ICON_RUNNING = "\u21bb";
 // Spinner frames
 export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
+/** Print error to stderr and exit with code 1. */
 export function fail(msg: string): never {
-  console.log(msg);
+  console.error(msg);
   process.exit(1);
 }
 
+// ---------------------------------------------------------------------------
+// Argument parser
+// ---------------------------------------------------------------------------
+
+export interface ParsedArgs {
+  /** Positional arguments (everything that isn't a flag or flag value). */
+  positional: string[];
+  /** Named flags: --foo bar → { foo: "bar" }, --flag → { flag: true }, --no-flag → { flag: false }. */
+  flags: Record<string, string | boolean>;
+  /** Returns a flag value as string, or undefined. */
+  getString(name: string): string | undefined;
+  /** Returns a flag as boolean (true if --name, false if --no-name, undefined if absent). */
+  getBool(name: string): boolean | undefined;
+  /** Returns true if --help or -h is present. */
+  help: boolean;
+}
+
+/**
+ * Parse CLI arguments into positional args and named flags.
+ *
+ * Supports:
+ * - `--flag value` → { flag: "value" }
+ * - `--flag` (no value or next arg is a flag) → { flag: true }
+ * - `--no-flag` → { flag: false }
+ * - `-h` / `--help` → help: true
+ * - Positional args (anything not a flag or flag value)
+ *
+ * @param argv - Arguments to parse (default: process.argv.slice(3) for subcommands)
+ * @param boolFlags - Flag names that are always boolean (never consume the next arg as value)
+ */
+export function parseArgs(argv?: string[], boolFlags: string[] = []): ParsedArgs {
+  const args = argv ?? process.argv.slice(3);
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+  const boolSet = new Set(boolFlags);
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === "--") {
+      // Everything after -- is positional
+      positional.push(...args.slice(i + 1));
+      break;
+    }
+
+    if (arg === "-h" || arg === "--help") {
+      flags.help = true;
+      i++;
+      continue;
+    }
+
+    if (arg.startsWith("--no-")) {
+      const name = arg.slice(5);
+      flags[name] = false;
+      i++;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      const name = arg.slice(2);
+      const next = args[i + 1];
+
+      if (boolSet.has(name) || !next || next.startsWith("-")) {
+        flags[name] = true;
+        i++;
+      } else {
+        flags[name] = next;
+        i += 2;
+      }
+      continue;
+    }
+
+    if (arg.startsWith("-") && arg.length === 2) {
+      // Short flag like -c value
+      const name = arg.slice(1);
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        flags[name] = true;
+        i++;
+      } else {
+        flags[name] = next;
+        i += 2;
+      }
+      continue;
+    }
+
+    positional.push(arg);
+    i++;
+  }
+
+  return {
+    positional,
+    flags,
+    getString(name: string): string | undefined {
+      const v = flags[name];
+      return typeof v === "string" ? v : undefined;
+    },
+    getBool(name: string): boolean | undefined {
+      const v = flags[name];
+      return typeof v === "boolean" ? v : undefined;
+    },
+    get help() {
+      return flags.help === true;
+    },
+  };
+}
+
 export function pickFromList(
   rl: readline.Interface,
   items: { name: string; label: string }[],