@floomhq/floom 3.0.0 → 3.0.2

package/dist/index.js

@@ -3040,6 +3040,21 @@ function emitJson(value) {
   writeStdout(JSON.stringify(value, null, 2) + "\n");
 }
 
+// src/lib/pipe-guard.ts
+var installed = false;
+function installPipeGuards() {
+  if (installed) return;
+  installed = true;
+  const swallow = (err) => {
+    if (err && err.code === "EPIPE") {
+      process.exit(0);
+    }
+    throw err;
+  };
+  process.stdout.on("error", swallow);
+  process.stderr.on("error", swallow);
+}
+
 // src/commands/login.ts
 init_src();
 import { spawn as spawn2 } from "node:child_process";
@@ -3238,7 +3253,7 @@ async function getMachineIdentity() {
 }
 
 // src/version.ts
-var VERSION = "3.0.0";
+var VERSION = "3.0.2";
 
 // src/api-client.ts
 var DEFAULT_TIMEOUT_MS = 2e4;
@@ -3289,12 +3304,12 @@ var HELP = "https://floom.dev/docs#troubleshooting";
 function friendlyApiErrorMessage(code, raw, status) {
   if (code === "AUTH_REQUIRED" || code === "TOKEN_INVALID" || status === 401) {
     return `Not signed in.
-  Run: npx -y @floomhq/floom login
+  Run: floom login
   More help: ${HELP}`;
   }
   if (code === "TOKEN_EXPIRED") {
     return `Your session has expired.
-  Run: npx -y @floomhq/floom login
+  Run: floom login
   More help: ${HELP}`;
   }
   if (code === "SKILL_ACCESS_DENIED" || status === 403) {
@@ -3303,7 +3318,7 @@ function friendlyApiErrorMessage(code, raw, status) {
   }
   if (code === "SKILL_NOT_FOUND" || status === 404) {
     return `Skill not found. It may have been deleted or the slug is wrong.
-  Run: npx -y @floomhq/floom list
+  Run: floom list
   More help: ${HELP}`;
   }
   if (code === "RATE_LIMITED" || status === 429) {
@@ -3312,7 +3327,7 @@ function friendlyApiErrorMessage(code, raw, status) {
   }
   if (code === "CLI_VERSION_TOO_OLD") {
     return `Your CLI is out of date.
-  Run: npx -y @floomhq/floom@latest <command>
+  Run: npm i -g @floomhq/floom@latest
   More help: ${HELP}`;
   }
   if (code === "FILE_TOO_LARGE" || code === "BUNDLE_TOO_LARGE") {
@@ -3331,7 +3346,7 @@ async function api(path, opts = {}) {
   if (opts.authRequired && !token) {
     throw new FloomError(
       "AUTH_REQUIRED",
-      "Not signed in.\n  Run: npx -y @floomhq/floom login\n  More help: https://floom.dev/docs#troubleshooting"
+      "Not signed in.\n  Run: floom login\n  More help: https://floom.dev/docs#troubleshooting"
     );
   }
   let lastError = null;
@@ -4013,13 +4028,13 @@ async function writeSkillAtomically(root, skill) {
   await rm(tempDir, { recursive: true, force: true });
   await rm(replacedDir, { recursive: true, force: true });
   await mkdir4(tempDir, { recursive: true });
-  const installed = [];
+  const installed2 = [];
   for (const file of skill.files) {
     const safePath = safeRemotePath(file.path);
     const dest = join7(tempDir, ...safePath.split("/"));
     await mkdir4(dirname(dest), { recursive: true });
     await writeFile3(dest, bytesForFile(file));
-    installed.push([slug, ...safePath.split("/")].join(sep4));
+    installed2.push([slug, ...safePath.split("/")].join(sep4));
   }
   let movedExisting = false;
   try {
@@ -4053,7 +4068,7 @@ async function writeSkillAtomically(root, skill) {
     await rm(tempDir, { recursive: true, force: true });
     if (!movedExisting) await rm(replacedDir, { recursive: true, force: true });
   }
-  return installed.sort();
+  return installed2.sort();
 }
 async function backupSkill(root, stamp, slug) {
   slug = safeSkillSlug(slug);
@@ -4686,14 +4701,19 @@ async function pushCommand(pathArg, options = {}, deps = {}) {
           wouldMutate: false,
           syncedCount: 0,
           plan: [],
+          error: { code: "AUTH_REQUIRED", message: "Not signed in \u2014 log in first to publish." },
           next: ["floom login"]
         });
+        process.exitCode = 1;
         return;
       }
       log.blank();
+      log.err("Not signed in \u2014 log in first to publish.");
+      log.blank();
       if (skills.length === 0) {
         log.info("No local skill folders found on this machine.");
         printNext([{ command: "floom login" }]);
+        process.exitCode = 1;
         return;
       }
       log.info(`  Found ${skills.length} skill${skills.length === 1 ? "" : "s"} on this machine:`);
@@ -4704,6 +4724,7 @@ async function pushCommand(pathArg, options = {}, deps = {}) {
       log.blank();
       log.info("After login, run:");
       log.command("floom push");
+      process.exitCode = 1;
       return;
     }
     const me = await fetchMe().catch(() => null);
@@ -4894,13 +4915,23 @@ async function pushExplicitPath(pathArg, options, pushApi, authed) {
   }
   if (!authed) {
     if (json) {
-      emitJson({ workspace: { name: "Library", signedIn: false }, mode: "plan", applied: false, wouldMutate: true, syncedCount: 0, plan: [], next: ["floom login"] });
+      emitJson({
+        workspace: { name: "Library", signedIn: false },
+        mode: "plan",
+        applied: false,
+        wouldMutate: false,
+        syncedCount: 0,
+        plan: [],
+        error: { code: "AUTH_REQUIRED", message: "Not signed in \u2014 log in first to publish." },
+        next: ["floom login"]
+      });
     } else {
       log.blank();
+      log.err("Not signed in \u2014 log in first to publish.");
       log.info(`Found local skill at ${tildePath(folder)}.`);
-      log.info("To publish it, sign in to Floom.");
       printNext([{ command: "floom login" }]);
     }
+    process.exitCode = 1;
     return;
   }
   const slug = basename(folder);
@@ -5177,10 +5208,42 @@ async function deleteCommand(slug, opts = {}, deps = { api }) {
 }
 
 // src/commands/list.ts
+init_src();
 var MAX_HUMAN_ROWS = 20;
 async function listCommand(opts = {}) {
   const json = Boolean(opts.json);
-  const result = await api("/skills", { authRequired: true });
+  if (!await readAuth()) {
+    if (json) {
+      emitJson({
+        workspace: { name: "Library", signedIn: false },
+        error: { code: "AUTH_REQUIRED", message: "Not signed in." },
+        skills: [],
+        next: ["floom login"]
+      });
+    } else {
+      log.err("Not signed in.");
+      printNext([{ command: "floom login" }]);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  let result;
+  try {
+    result = await api("/skills", { authRequired: true });
+  } catch (e) {
+    if (json) {
+      const fe = e instanceof FloomError ? e : null;
+      emitJson({
+        workspace: { name: "Library", signedIn: true },
+        error: { code: fe?.code ?? "INTERNAL_ERROR", message: e.message },
+        skills: [],
+        next: ["floom login"]
+      });
+      process.exitCode = 1;
+      return;
+    }
+    throw e;
+  }
   const localSkills = await discoverSkills();
   const installedBySlug = /* @__PURE__ */ new Map();
   for (const skill of localSkills) {
@@ -5814,9 +5877,9 @@ function buildApplyJson(workspaceName, applied, opts) {
     next: ["floom status"]
   };
 }
-async function planForAgent(agent, scope, skillsDir) {
+async function planForAgent(agent, scope, skillsDir, statusFn = statusLibrary) {
   try {
-    const status = await statusLibrary(agent, { installDir: skillsDir });
+    const status = await statusFn(agent, { installDir: skillsDir });
     return {
       agent,
       scope,
@@ -5829,7 +5892,12 @@ async function planForAgent(agent, scope, skillsDir) {
     return { agent, scope, skillsDir, pull: [], push: [], conflicts: [] };
   }
 }
-async function syncCommand(rawOpts = {}) {
+async function syncCommand(rawOpts = {}, deps = {}) {
+  const detectAgentsFn = deps.detectAgents ?? detectAgents;
+  const runSyncFn = deps.runSyncForTarget ?? runSyncForTarget;
+  const statusFn = deps.statusLibrary ?? statusLibrary;
+  const fetchMeFn = deps.fetchMe ?? fetchMe;
+  const readAuthFn = deps.readAuth ?? readAuth;
   const cleanup = installCancellationHandler();
   try {
     let flags;
@@ -5845,7 +5913,7 @@ async function syncCommand(rawOpts = {}) {
     }
     const json = flags.json;
     const planMode = isPlanMode(flags);
-    if (!await readAuth()) {
+    if (!await readAuthFn()) {
       if (json) {
         emitJson({ workspace: { name: "Library", signedIn: false }, mode: "plan", applied: false, wouldMutate: false, hasSkipped: false, agents: [], next: ["floom login"] });
       } else {
@@ -5855,30 +5923,30 @@ async function syncCommand(rawOpts = {}) {
       process.exitCode = 2;
       return;
     }
-    const detected = await detectAgents();
+    const detected = await detectAgentsFn();
     if (detected.length === 0) {
       if (json) {
-        emitJson({ workspace: { name: "Library", signedIn: true }, mode: "plan", applied: false, wouldMutate: false, hasSkipped: false, agents: [], next: ["floom sync --agent claude"] });
+        emitJson({ workspace: { name: "Library", signedIn: true }, mode: "plan", applied: false, wouldMutate: false, hasSkipped: false, agents: [], error: "no agents detected \u2014 install Claude, Codex, Cursor, Gemini, or OpenCode", next: ["floom sync --agent claude"] });
       } else {
-        log.info("No AI agents found on this machine.");
-        log.info("Floom looks for Claude, Codex, Cursor, Gemini, or OpenCode.");
+        log.err("No agents detected \u2014 install Claude, Codex, Cursor, Gemini, or OpenCode, then re-run.");
+        log.info("Floom syncs into one of: Claude, Codex, Cursor, Gemini, OpenCode.");
+        log.info("More: https://floom.dev/docs#agents");
       }
       process.exitCode = 1;
       return;
     }
+    const defaultedToAll = flags.agents.length === 0 && !flags.allAgents;
     const selectedAgents = flags.agents.length > 0 ? flags.agents : detected;
-    if (!planMode && flags.agents.length === 0 && !flags.allAgents && !isInteractive()) {
+    if (!planMode && !flags.yes && !isInteractive()) {
       if (json) {
-        emitJson({ workspace: { name: "Library", signedIn: true }, error: "floom sync needs to know which agents to update", next: ["floom sync --all-agents --yes"] });
+        emitJson({ workspace: { name: "Library", signedIn: true }, error: "floom sync needs --yes to apply changes in a non-interactive shell", next: ["floom sync --yes"] });
       } else {
-        log.err("floom sync needs to know which agents to update.");
-        log.blank();
-        log.info("Pass --agent <name>, repeat --agent, or use --all-agents.");
+        log.err("floom sync needs --yes to apply changes in a non-interactive shell.");
         log.blank();
         log.info("Examples:");
+        log.command("floom sync --yes                       # sync every detected agent");
         log.command("floom sync --agent claude --yes");
         log.command("floom sync --agent claude,codex --yes");
-        log.command("floom sync --all-agents --yes");
       }
       process.exitCode = 2;
       return;
@@ -5888,7 +5956,7 @@ async function syncCommand(rawOpts = {}) {
       process.exitCode = 2;
       return;
     }
-    const me = await fetchMe().catch(() => null);
+    const me = await fetchMeFn().catch(() => null);
     const workspaceName = me?.workspace?.name ?? "your Workspace";
     const hasProjectScope = await projectSkillsDirExists(process.cwd());
     const scopeChoice = flags.allScopes ? ["global", "project"] : flags.scope === "project" ? ["project"] : planMode && flags.scope === null && hasProjectScope ? ["global", "project"] : ["global"];
@@ -5897,7 +5965,7 @@ async function syncCommand(rawOpts = {}) {
       for (const scope of scopeChoice) {
         const dir = scope === "project" ? resolve6(projectSkillsDir(agent)) : resolve6(globalSkillsDir(agent));
         if (scope === "project" && !await projectSkillsDirExists(process.cwd())) continue;
-        plans.push(await planForAgent(agent, scope, dir));
+        plans.push(await planForAgent(agent, scope, dir, statusFn));
       }
     }
     const actionable = plans.filter((p) => p.pull.length > 0 || p.push.length > 0);
@@ -5950,12 +6018,24 @@ async function syncCommand(rawOpts = {}) {
       return;
     }
     if (!wouldMutate && !hasSkipped) {
+      if (json) {
+        const noopApplied = plans.map((p) => ({ plan: p, ok: true, message: "up to date" }));
+        emitJson(buildApplyJson(workspaceName, noopApplied, { failed: false, hasSkipped: false }));
+        return;
+      }
+      if (defaultedToAll && detected.length > 1) {
+        log.info(`Syncing every detected agent (${detected.map((a) => AGENT_LABELS[a]).join(", ")}).`);
+      }
       log.info("Everything is in sync.");
       log.blank();
       for (const p of plans) log.row([AGENT_LABELS[p.agent], "up to date"], [10]);
       printNext([{ command: "floom status" }]);
       return;
     }
+    if (defaultedToAll && detected.length > 1) {
+      log.info(`Syncing every detected agent (${detected.map((a) => AGENT_LABELS[a]).join(", ")}).`);
+      log.blank();
+    }
     log.heading("Sync plan for this machine");
     log.blank();
     for (const p of plans) {
@@ -5993,7 +6073,7 @@ async function syncCommand(rawOpts = {}) {
     const applied = [];
     for (const p of toSync) {
       try {
-        const result = await runSyncForTarget({ target: p.agent, yes: true, installDir: p.skillsDir });
+        const result = await runSyncFn({ target: p.agent, yes: true, installDir: p.skillsDir });
         const entry = appliedFromResult(p, result);
         if (!entry.ok) failed = true;
         applied.push(entry);
@@ -6642,19 +6722,19 @@ async function installCommand(input, rawOpts = {}) {
   }
   if (planMode) {
     const planAgents = await Promise.all(targets.map(async (t) => {
-      const installed = await existsAt(t.skillsDir, slug);
+      const installed2 = await existsAt(t.skillsDir, slug);
       return {
         name: t.agent,
         scope: t.scope,
         skillsDir: t.skillsDir,
         path: join12(t.skillsDir, slug),
-        action: installed ? "update" : "install",
+        action: installed2 ? "update" : "install",
         status: "ok",
         refusedReason: null,
         fromVersion: null,
         toVersion: shareData.skill.version.version_seq,
         backupPath: null,
-        message: installed ? `${shareData.skill.title} would be updated` : `${shareData.skill.title} would be installed`
+        message: installed2 ? `${shareData.skill.title} would be updated` : `${shareData.skill.title} would be installed`
       };
     }));
     if (json) {
@@ -7048,8 +7128,8 @@ function npmLatest() {
     }, 5e3);
   });
 }
-function significantlyOutdated(installed, latest) {
-  const a = installed.split(".").map((n) => Number.parseInt(n, 10));
+function significantlyOutdated(installed2, latest) {
+  const a = installed2.split(".").map((n) => Number.parseInt(n, 10));
   const b = latest.split(".").map((n) => Number.parseInt(n, 10));
   if ((b[0] ?? 0) > (a[0] ?? 0)) return true;
   if ((b[0] ?? 0) === (a[0] ?? 0) && (b[1] ?? 0) > (a[1] ?? 0)) return true;
@@ -7922,61 +8002,108 @@ function aliasNotice(oldName, newName) {
   log.notice(`"${oldName}" is now "${newName}" \u2014 both work for now.`);
 }
 var program = new Command();
-program.name("floom").description("Floom: one shared skill library, synced across every AI agent.").version(VERSION).addHelpCommand(false).helpOption(false).allowExcessArguments(true);
-program.option("-h, --help", "show grouped help");
-program.action(async (opts) => {
-  if (opts.help) {
-    printGroupedHelp();
+program.name("floom").description("Floom: one shared skill library, synced across every AI agent.").version(VERSION).addHelpCommand(false).helpOption("-h, --help", "show grouped help").allowExcessArguments(true).showSuggestionAfterError(true).showHelpAfterError(false);
+program.helpInformation = function helpInformation() {
+  printGroupedHelp();
+  return "";
+};
+function helpOpt(cmd) {
+  return cmd.helpOption("-h, --help", "show help for this command").allowExcessArguments(false);
+}
+program.action(async (_opts, cmd) => {
+  const stray = cmd.args.filter((a) => !a.startsWith("-"));
+  if (stray.length > 0) {
+    const unknown = stray[0];
+    log.err(`unknown command: ${unknown}`);
+    const knownNames = program.commands.map((c) => c.name());
+    const suggestion = closestCommand(unknown, knownNames);
+    if (suggestion) log.info(`Did you mean: floom ${suggestion}?`);
+    log.info("Run: floom --help");
+    process.exitCode = 2;
     return;
   }
   await dashboardCommand();
 });
-program.command("login").description("sign in to your Floom workspace").action(loginCommand);
-program.command("logout").description("sign out on this machine").action(logoutCommand);
-program.command("account").description("show account details").option("--json", "print account state as JSON").action((opts) => accountCommand(opts));
-program.command("whoami").description("show account details (alias)").option("--json", "print account state as JSON").action((opts) => {
+function closestCommand(input, candidates) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    const d = editDistance(input, c);
+    if (d < bestDist) {
+      bestDist = d;
+      best = c;
+    }
+  }
+  const threshold = Math.max(2, Math.floor(input.length * 0.4));
+  return best && bestDist <= threshold ? best : null;
+}
+function editDistance(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const prev = Array(b.length + 1).fill(0).map((_, i) => i);
+  const curr = Array(b.length + 1).fill(0);
+  for (let i = 1; i <= a.length; i += 1) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    for (let j = 0; j <= b.length; j += 1) prev[j] = curr[j];
+  }
+  return curr[b.length];
+}
+helpOpt(program.command("login").description("sign in to your Floom workspace")).action(loginCommand);
+helpOpt(program.command("logout").description("sign out on this machine")).action(logoutCommand);
+helpOpt(program.command("account").description("show account details").option("--json", "print account state as JSON")).action((opts) => accountCommand(opts));
+helpOpt(program.command("whoami").description("show account details (alias)").option("--json", "print account state as JSON")).action((opts) => {
   aliasNotice("whoami", "account");
   return accountCommand(opts);
 });
-program.command("push [path]").description("publish local skills to the Library").option("--yes", "proceed with all safe changes").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without changing anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty").option("--no-secret-check", "skip the pre-publish secret scan").option("--concurrency <n>", "bulk push concurrency, 1-16", "6").action((path, opts) => pushCommand(path, opts));
-program.command("pull [skill]").description("update local agents from the Library").option("--agent <name>", "limit to one or more agents (repeatable, comma-separated)", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--all-agents", "use every detected agent").option("--global", "use the user-level agent skills folder").option("--project", "use this project's agent skills folder").option("--all-scopes", "use both global and project-local copies").option("--yes", "skip confirmation for safe mutations").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without changing anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty").action((skill, opts) => {
+helpOpt(program.command("push [path]").description("publish local skills to the Library").option("--yes", "proceed with all safe changes").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without changing anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty").option("--no-secret-check", "skip the pre-publish secret scan").option("--concurrency <n>", "bulk push concurrency, 1-16", "6")).action((path, opts) => pushCommand(path, opts));
+helpOpt(program.command("pull [skill]").description("update local agents from the Library").option("--agent <name>", "limit to one or more agents (repeatable, comma-separated)", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--all-agents", "use every detected agent").option("--global", "use the user-level agent skills folder").option("--global-only", "(deprecated) alias for --global").option("--project", "use this project's agent skills folder").option("--all-scopes", "use both global and project-local copies").option("--yes", "skip confirmation for safe mutations").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without changing anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty")).action((skill, opts) => {
   if (Array.isArray(opts.target) && opts.target.length > 0) aliasNotice("--target", "--agent");
+  if (opts.globalOnly) {
+    aliasNotice("--global-only", "--global");
+    opts.global = true;
+  }
   return pullCommand(skill, opts);
 });
-program.command("sync").description("review both directions and resolve differences").option("--agent <name>", "limit to one or more agents (repeatable, comma-separated)", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--all-agents", "use every detected agent").option("--global", "use the user-level agent skills folder").option("--project", "use this project's agent skills folder").option("--all-scopes", "use both global and project-local copies").option("--yes", "skip confirmation for safe mutations").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without changing anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty").action((opts) => {
+helpOpt(program.command("sync").description("review both directions and resolve differences").option("--agent <name>", "limit to one or more agents (repeatable, comma-separated)", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--all-agents", "use every detected agent").option("--global", "use the user-level agent skills folder").option("--project", "use this project's agent skills folder").option("--all-scopes", "use both global and project-local copies").option("--yes", "skip confirmation for safe mutations").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without changing anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty")).action((opts) => {
   if (Array.isArray(opts.target) && opts.target.length > 0) aliasNotice("--target", "--agent");
   return syncCommand(opts);
 });
-program.command("new <name>").description("create a ready-to-edit skill").option("--agent <name>", "create in this agent's skills folder").option("--all-scopes", "(rejected \u2014 new creates one skill in one location)").option("--yes", "skip confirmation when non-interactive").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without creating anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty").action((name, opts) => newCommand(name, opts));
-program.command("restore [skill]").description("restore a local skill from a safety backup").option("--agent <name>", "the agent whose copy to restore").option("--backup <timestamp>", "restore a specific backup snapshot").option("--list", "list all available backups").option("--yes", "skip confirmation").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without restoring anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty").action((skill, opts) => restoreCommand(skill, opts));
-program.command("list").description("list team skills and local install status").option("--json", "print the Library as JSON").action((opts) => listCommand(opts));
-program.command("library").description("list team skills and local install status (alias)").option("--json", "print the Library as JSON").action((opts) => listCommand(opts));
-program.command("delete [skill]").description("delete a skill from the Library").option("--yes", "skip the type-the-name confirmation").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without deleting anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty").action((skill, opts) => deleteCommand(skill, opts));
-program.command("remove [skill]").description("delete a skill from the Library (alias)").option("--yes", "skip the type-the-name confirmation").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without deleting anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty").action((skill, opts) => {
+helpOpt(program.command("new <name>").description("create a ready-to-edit skill").option("--agent <name>", "create in this agent's skills folder").option("--all-scopes", "(rejected \u2014 new creates one skill in one location)").option("--yes", "skip confirmation when non-interactive").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without creating anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty")).action((name, opts) => newCommand(name, opts));
+helpOpt(program.command("restore [skill]").description("restore a local skill from a safety backup").option("--agent <name>", "the agent whose copy to restore").option("--backup <timestamp>", "restore a specific backup snapshot").option("--list", "list all available backups").option("--yes", "skip confirmation").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without restoring anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty")).action((skill, opts) => restoreCommand(skill, opts));
+helpOpt(program.command("list").description("list team skills and local install status").option("--json", "print the Library as JSON")).action((opts) => listCommand(opts));
+helpOpt(program.command("library").description("list team skills and local install status (alias)").option("--json", "print the Library as JSON")).action((opts) => listCommand(opts));
+helpOpt(program.command("delete [skill]").description("delete a skill from the Library").option("--yes", "skip the type-the-name confirmation").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without deleting anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty")).action((skill, opts) => deleteCommand(skill, opts));
+helpOpt(program.command("remove [skill]").description("delete a skill from the Library (alias)").option("--yes", "skip the type-the-name confirmation").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without deleting anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty")).action((skill, opts) => {
   aliasNotice("remove", "delete");
   return deleteCommand(skill, opts);
 });
-program.command("install <link>").description("install a skill from a share link").option("--agent <name>", "install into one or more agents (repeatable, comma-separated)", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--all-agents", "install into every detected agent").option("--global", "install into the user-level agent skills folder").option("--project", "install into this project's agent skills folder").option("--all-scopes", "install into both global and project-local copies").option("--yes", "skip confirmation for safe mutations").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without installing anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty").action((link, opts) => installCommand(link, opts));
-program.command("add <link>").description("install a skill from a share link (alias)").option("--agent <name>", "install into one or more agents", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--all-agents", "install into every detected agent").option("--global", "install into the user-level agent skills folder").option("--project", "install into this project's agent skills folder").option("--all-scopes", "install into both global and project-local copies").option("--yes", "skip confirmation for safe mutations").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without installing anything").action((link, opts) => {
+helpOpt(program.command("install <link>").description("install a skill from a share link").option("--agent <name>", "install into one or more agents (repeatable, comma-separated)", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--all-agents", "install into every detected agent").option("--global", "install into the user-level agent skills folder").option("--project", "install into this project's agent skills folder").option("--all-scopes", "install into both global and project-local copies").option("--yes", "skip confirmation for safe mutations").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without installing anything").option("--exit-zero", "with --dry-run, force exit 0 even if the plan is non-empty")).action((link, opts) => installCommand(link, opts));
+helpOpt(program.command("add <link>").description("install a skill from a share link (alias)").option("--agent <name>", "install into one or more agents", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--all-agents", "install into every detected agent").option("--global", "install into the user-level agent skills folder").option("--project", "install into this project's agent skills folder").option("--all-scopes", "install into both global and project-local copies").option("--yes", "skip confirmation for safe mutations").option("--json", "print the plan or result as JSON").option("--dry-run", "print the plan without installing anything")).action((link, opts) => {
   aliasNotice("add", "install");
   return installCommand(link, opts);
 });
-program.command("rename-device <label>").description("set a friendly name for this machine").action((label) => renameDeviceCommand(label));
-program.command("rename-machine <label>").description("set a friendly name for this machine (alias)").action((label) => {
+helpOpt(program.command("rename-device <label>").description("set a friendly name for this machine")).action((label) => renameDeviceCommand(label));
+helpOpt(program.command("rename-machine <label>").description("set a friendly name for this machine (alias)")).action((label) => {
   aliasNotice("rename-machine", "rename-device");
   return renameDeviceCommand(label);
 });
-program.command("status").description("inspect sync state across Library and agents").option("--agent <name>", "limit to one or more agents (repeatable, comma-separated)", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--verbose", "show every skill in every agent").option("--json", "print status as JSON").action((opts) => {
+helpOpt(program.command("status").description("inspect sync state across Library and agents").option("--agent <name>", "limit to one or more agents (repeatable, comma-separated)", collectAgent, []).option("--target <name>", "alias for --agent", collectAgent, []).option("--verbose", "show every skill in every agent").option("--json", "print status as JSON")).action((opts) => {
   if (Array.isArray(opts.target) && opts.target.length > 0) aliasNotice("--target", "--agent");
   return statusCommand(opts);
 });
-program.command("diff <skill>").description("compare local copies with the Library").option("--agent <name>", "limit to one agent").option("--json", "print the comparison as JSON").action((skill, opts) => diffCommand(skill, opts));
-program.command("doctor").description("diagnose auth, agents, manifests, and version").option("--json", "print diagnostics as JSON").action((opts) => doctorCommand(opts));
-program.command("mcp").description("run the local MCP server (for agent configuration)").action(mcpCommand);
+helpOpt(program.command("diff <skill>").description("compare local copies with the Library").option("--agent <name>", "limit to one agent").option("--json", "print the comparison as JSON")).action((skill, opts) => diffCommand(skill, opts));
+helpOpt(program.command("doctor").description("diagnose auth, agents, manifests, and version").option("--json", "print diagnostics as JSON")).action((opts) => doctorCommand(opts));
+helpOpt(program.command("mcp").description("run the local MCP server (for agent configuration)")).action(mcpCommand);
 function collectAgent(value, previous) {
   return [...previous, value];
 }
 async function main() {
+  installPipeGuards();
   detectJsonEarly();
   try {
     await program.parseAsync(process.argv);
@@ -7985,6 +8112,10 @@ async function main() {
       log.err(e.message);
       process.exit(1);
     }
+    const cerr = e;
+    if (cerr && typeof cerr.code === "string" && cerr.code.startsWith("commander.")) {
+      process.exit(typeof cerr.exitCode === "number" ? cerr.exitCode : 1);
+    }
     log.err(e.message ?? "Unknown error");
     if (process.env.FLOOM_DEBUG) {
       const raw = e?.stack ?? String(e);

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "3.0.0";
+export const VERSION = "3.0.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Floom CLI \u2014 one shared skill library, pulled into the AI agent you choose (Claude, Codex, Cursor, Gemini, OpenCode).",
   "license": "MIT",
   "homepage": "https://floom.dev",