@higrowth/cli 0.1.1 → 0.3.0

package/README.md

@@ -1,8 +1,10 @@
 # @higrowth/cli
 
 Log in to a Higrowth workspace from your terminal and install the
-Claude Code skills that drive it. The replacement for `cp -r skills/
-higrowth ~/.claude/skills/` and copy-paste tokens.
+Higrowth playbook skills into your AI agent of choice. Supports
+**Claude Code**, **Claude Desktop**, **Cursor**, and **Codex**
+(CLI + Desktop + IDE extension share one config). Replaces the old
+`cp -r skills/higrowth ~/.claude/skills/` + copy-paste-token dance.
 
 ## Install
 
@@ -33,7 +35,7 @@ higrowth skills install
 | `higrowth login [--host URL] [--device]` | Browser-auth handshake (PKCE by default; `--device` for SSH/containers). Writes the MCP entry into `~/.claude/mcp.json`. |
 | `higrowth whoami` | Show the currently-configured workspace + token name. |
 | `higrowth logout` | Remove the higrowth entry from `~/.claude/mcp.json`. Local-only — does NOT revoke the token (do that in Settings). |
-| `higrowth skills install [--target TARGET]` | Copy the five skill files into your agent's skills dir. Auto-detects Claude Code, Cursor, Claude Desktop; pass `--target claude\|cursor\|claude-desktop\|all` to override. |
+| `higrowth skills install [--target TARGET]` | Copy the five skill files into your agent's skills dir. Auto-detects Claude Code / Cursor / Claude Desktop / Codex; pass `--target claude\|cursor\|claude-desktop\|codex\|all` to override. |
 | `higrowth skills list` | Show installed skills + which are out of date relative to the bundle. |
 | `higrowth skills update` | Re-install (overwrite) the latest skill versions. |
 
@@ -43,17 +45,28 @@ higrowth skills install
 |------|---------|--------------|
 | `--host URL` | `https://app.higrowth.ai` | Override the Higrowth host (for self-hosted or staging). |
 | `--device` | off | Use OAuth 2.0 device-code flow instead of PKCE. For SSH / containers. |
-| `--target TARGET` | auto-detect | `claude` / `cursor` / `claude-desktop` / `all`. |
+| `--target TARGET` | auto-detect | `claude` / `cursor` / `claude-desktop` / `codex` / `all`. `codex` covers Codex CLI + Desktop + IDE extension via one shared `~/.codex/config.toml`. |
 | `--config PATH` | platform default | Override the MCP config file path. |
 
+## Where things land
+
+| Target | MCP config | Skills dir |
+|--------|------------|------------|
+| `claude` (Claude Code) | `~/.claude/mcp.json` | `~/.claude/skills/<slug>/SKILL.md` |
+| `cursor` | `~/.cursor/mcp.json` | `~/.cursor/skills/<slug>/SKILL.md` |
+| `claude-desktop` | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) | `~/Library/Application Support/Claude/skills/<slug>/SKILL.md` |
+| `codex` | `~/.codex/config.toml` (TOML, not JSON) | `~/.agents/skills/<slug>/SKILL.md` |
+
+For Codex specifically: one write covers Codex CLI, Codex Desktop, and the Codex IDE extension because all three read the same `~/.codex/config.toml`. No per-app duplication.
+
 ## What it does NOT do
 
 - Doesn't manage tokens server-side. Token rotation / revocation
   happens in the Higrowth UI under Settings → API tokens.
 - Doesn't restart Claude Code for you. After `login` or `skills
   install`, restart manually so the new config takes effect.
-- Doesn't store secrets outside `~/.claude/mcp.json` (mode 600 where
-  possible).
+- Doesn't store secrets outside the per-target config file you're
+  installing into (mode 600 where the filesystem supports it).
 
 ## License
 

package/dist/index.js

@@ -74,12 +74,14 @@ function base64UrlEncode(buf) {
 import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "fs";
 import { dirname, join } from "path";
 import { homedir, platform } from "os";
+import TOML from "@iarna/toml";
 function configPaths() {
   const home = homedir();
   return [
-    { target: "claude", path: join(home, ".claude", "mcp.json") },
-    { target: "cursor", path: join(home, ".cursor", "mcp.json") },
-    { target: "claude-desktop", path: claudeDesktopPath(home) }
+    { target: "claude", path: join(home, ".claude", "mcp.json"), format: "json", label: "Claude Code" },
+    { target: "cursor", path: join(home, ".cursor", "mcp.json"), format: "json", label: "Cursor" },
+    { target: "claude-desktop", path: claudeDesktopPath(home), format: "json", label: "Claude Desktop" },
+    { target: "codex", path: join(home, ".codex", "config.toml"), format: "toml", label: "Codex (CLI + Desktop + IDE)" }
   ];
 }
 function claudeDesktopPath(home) {
@@ -118,55 +120,73 @@ function resolveConfigPath(target) {
   if (!found) throw new Error(`Unknown target: ${resolved}`);
   return found;
 }
-function readConfig(path) {
+function serversKey(format) {
+  return format === "toml" ? "mcp_servers" : "mcpServers";
+}
+function headersKey(format) {
+  return format === "toml" ? "http_headers" : "headers";
+}
+function readConfig(path, format) {
   if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf-8");
   try {
-    const raw = readFileSync(path, "utf-8");
-    return JSON.parse(raw);
+    return format === "toml" ? TOML.parse(raw) : JSON.parse(raw);
   } catch (err) {
     throw new Error(
       `Could not parse existing MCP config at ${path}: ${err instanceof Error ? err.message : String(err)}`
     );
   }
 }
+function serialize(cfg, format) {
+  if (format === "toml") {
+    return TOML.stringify(cfg);
+  }
+  return `${JSON.stringify(cfg, null, 2)}
+`;
+}
 function writeHigrowthEntry(input) {
-  const existing = readConfig(input.path);
+  const existing = readConfig(input.path, input.format);
+  const sk = serversKey(input.format);
+  const hk = headersKey(input.format);
+  const existingServers = existing[sk] ?? {};
   const next = {
     ...existing,
-    mcpServers: {
-      ...existing.mcpServers ?? {},
+    [sk]: {
+      ...existingServers,
       higrowth: {
         url: `${input.host}/api/mcp`,
-        headers: {
+        [hk]: {
           Authorization: `Bearer ${input.token}`
         }
       }
     }
   };
   mkdirSync(dirname(input.path), { recursive: true });
-  writeFileSync(input.path, `${JSON.stringify(next, null, 2)}
-`, "utf-8");
+  writeFileSync(input.path, serialize(next, input.format), "utf-8");
   tryChmod600(input.path);
 }
-function removeHigrowthEntry(path) {
+function removeHigrowthEntry(path, format) {
   if (!existsSync(path)) return false;
-  const existing = readConfig(path);
-  if (!existing.mcpServers || !existing.mcpServers.higrowth) return false;
-  const { higrowth: _, ...rest } = existing.mcpServers;
-  const next = { ...existing, mcpServers: rest };
+  const existing = readConfig(path, format);
+  const sk = serversKey(format);
+  const servers = existing[sk];
+  if (!servers || !servers.higrowth) return false;
+  const { higrowth: _drop, ...rest } = servers;
+  const next = { ...existing, [sk]: rest };
   if (Object.keys(rest).length === 0) {
-    delete next.mcpServers;
+    delete next[sk];
   }
-  writeFileSync(path, `${JSON.stringify(next, null, 2)}
-`, "utf-8");
+  writeFileSync(path, serialize(next, format), "utf-8");
   return true;
 }
-function readHigrowthEntry(path) {
+function readHigrowthEntry(path, format) {
   if (!existsSync(path)) return null;
-  const cfg = readConfig(path);
-  const entry = cfg.mcpServers?.higrowth;
+  const cfg = readConfig(path, format);
+  const servers = cfg[serversKey(format)];
+  const entry = servers?.higrowth;
   if (!entry?.url) return null;
-  const authHeader = entry.headers?.Authorization ?? "";
+  const headers = entry[headersKey(format)] ?? {};
+  const authHeader = headers.Authorization ?? "";
   const match = authHeader.match(/^Bearer\s+(\S+)$/);
   if (!match) return null;
   return { url: entry.url, token: match[1] };
@@ -196,8 +216,14 @@ async function loginCommand(opts) {
   } else {
     ({ token, organizationId } = await runPkceFlow(api, client));
   }
-  const cfg = opts.configOverride !== void 0 ? { target: opts.target === "auto" ? "claude" : opts.target, path: opts.configOverride } : resolveConfigPath(opts.target);
-  writeHigrowthEntry({ path: cfg.path, host, token });
+  const cfg = opts.configOverride !== void 0 ? {
+    target: opts.target === "auto" ? "claude" : opts.target,
+    path: opts.configOverride,
+    // Infer format from extension when the user supplied a custom path.
+    // `.toml` → codex-style; anything else (.json by convention) → JSON.
+    format: opts.configOverride.toLowerCase().endsWith(".toml") ? "toml" : "json"
+  } : resolveConfigPath(opts.target);
+  writeHigrowthEntry({ path: cfg.path, format: cfg.format, host, token });
   process.stdout.write(`
 \u2713 Logged in to ${host}
 `);
@@ -306,7 +332,7 @@ function tryHostname() {
 async function logoutCommand() {
   let removed = 0;
   for (const cfg of configPaths()) {
-    if (removeHigrowthEntry(cfg.path)) {
+    if (removeHigrowthEntry(cfg.path, cfg.format)) {
       process.stdout.write(`\u2713 Removed higrowth entry from ${cfg.path}
 `);
       removed += 1;
@@ -325,24 +351,25 @@ async function logoutCommand() {
 async function whoamiCommand() {
   let foundAny = false;
   for (const cfg of configPaths()) {
-    const entry = readHigrowthEntry(cfg.path);
+    const entry = readHigrowthEntry(cfg.path, cfg.format);
     if (!entry) continue;
     foundAny = true;
-    process.stdout.write(`${cfg.target.padEnd(15)}  ${entry.url}
+    const heading = cfg.label.padEnd(28);
+    process.stdout.write(`${heading}  ${entry.url}
 `);
-    process.stdout.write(`${"".padEnd(15)}  ${maskToken(entry.token)}
+    process.stdout.write(`${"".padEnd(28)}  ${maskToken(entry.token)}
 `);
-    process.stdout.write(`${"".padEnd(15)}  ${cfg.path}
+    process.stdout.write(`${"".padEnd(28)}  ${cfg.path}
 
 `);
     const summary = await probeToken(entry.url, entry.token);
     if (summary) {
-      process.stdout.write(`${"".padEnd(15)}  \u2713 ${summary}
+      process.stdout.write(`${"".padEnd(28)}  \u2713 ${summary}
 
 `);
     } else {
       process.stdout.write(
-        `${"".padEnd(15)}  \u2717 token did not authenticate (revoked or stale?)
+        `${"".padEnd(28)}  \u2717 token did not authenticate (revoked or stale?)
 
 `
       );
@@ -1027,7 +1054,7 @@ async function skillsInstallCommand(opts) {
   const targets = resolveTargets(opts.target);
   if (targets.length === 0) {
     process.stdout.write(
-      "No supported skills directory detected. Pass --target claude|cursor|claude-desktop|all.\n"
+      "No supported skills directory detected. Pass --target claude|cursor|claude-desktop|codex|all.\n"
     );
     process.exitCode = 1;
     return;
@@ -1089,7 +1116,8 @@ function resolveTargets(t) {
   const all = [
     "claude",
     "cursor",
-    "claude-desktop"
+    "claude-desktop",
+    "codex"
   ];
   if (t === "all") return all;
   if (t === "auto") {
@@ -1102,6 +1130,7 @@ function skillsDir(t) {
   const home = homedir2();
   if (t === "claude") return join2(home, ".claude", "skills");
   if (t === "cursor") return join2(home, ".cursor", "skills");
+  if (t === "codex") return join2(home, ".agents", "skills");
   if (platform3() === "darwin") {
     return join2(home, "Library", "Application Support", "Claude", "skills");
   }
@@ -1128,8 +1157,174 @@ function compareSkill(path, skill) {
   }
 }
 
+// src/commands/upgrade.ts
+var PKG_NAME = "@higrowth/cli";
+async function upgradeCommand() {
+  process.stdout.write(
+    `
+Upgrade ${PKG_NAME} to the latest version with whichever package
+manager you used to install it:
+
+  npm install -g ${PKG_NAME}@latest
+  pnpm add -g ${PKG_NAME}@latest
+  bun add -g ${PKG_NAME}@latest
+  yarn global add ${PKG_NAME}@latest
+
+Or, if you installed via the curl-piped flow:
+
+  curl -fsSL https://app.higrowth.ai/install.sh | sh
+
+After upgrade, run \`higrowth -v\` to confirm.
+`
+  );
+}
+
+// src/lib/update-check.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join3 } from "path";
+import { homedir as homedir3 } from "os";
+var PKG_NAME2 = "@higrowth/cli";
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var REQUEST_TIMEOUT_MS = 2e3;
+function cachePath() {
+  return join3(homedir3(), ".config", "higrowth", "update-check.json");
+}
+function readCache() {
+  const path = cachePath();
+  if (!existsSync3(path)) return null;
+  try {
+    const raw = readFileSync3(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.latestVersion !== "string") return null;
+    if (typeof parsed.fetchedAt !== "number") return null;
+    return { latestVersion: parsed.latestVersion, fetchedAt: parsed.fetchedAt };
+  } catch {
+    return null;
+  }
+}
+function writeCache(latestVersion) {
+  const path = cachePath();
+  try {
+    mkdirSync3(dirname3(path), { recursive: true });
+    writeFileSync3(
+      path,
+      JSON.stringify({ latestVersion, fetchedAt: Date.now() }, null, 2),
+      "utf-8"
+    );
+  } catch {
+  }
+}
+async function fetchLatestFromNpm() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PKG_NAME2}/latest`, {
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body.version ?? null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function compareVersions(a, b) {
+  const parse = (v) => v.split("-")[0].split(".").map((s) => Number.parseInt(s, 10)).map((n2) => Number.isFinite(n2) ? n2 : 0);
+  const aa = parse(a);
+  const bb = parse(b);
+  const n = Math.max(aa.length, bb.length);
+  for (let i = 0; i < n; i++) {
+    const ai = aa[i] ?? 0;
+    const bi = bb[i] ?? 0;
+    if (ai !== bi) return ai - bi;
+  }
+  return 0;
+}
+function shouldSkip() {
+  if (process.env.HIGROWTH_NO_UPDATE_CHECK === "1") return true;
+  if (process.env.CI) return true;
+  if (!process.stdout.isTTY) return true;
+  return false;
+}
+function beginUpdateCheck(currentVersion) {
+  if (shouldSkip()) {
+    return async () => {
+    };
+  }
+  const cached = readCache();
+  const fresh = cached && Date.now() - cached.fetchedAt < CHECK_INTERVAL_MS;
+  const fetchPromise = fresh ? Promise.resolve(cached.latestVersion) : fetchLatestFromNpm().then((v) => {
+    if (v) writeCache(v);
+    return v;
+  });
+  return async () => {
+    let latest;
+    try {
+      latest = await fetchPromise;
+    } catch {
+      return;
+    }
+    if (!latest) return;
+    if (compareVersions(latest, currentVersion) <= 0) return;
+    process.stderr.write(
+      `
+\u2191 ${PKG_NAME2} ${latest} is available (you have ${currentVersion}).
+  Upgrade:  npm i -g ${PKG_NAME2}@latest
+  (or bun add -g / pnpm add -g / yarn global add depending on how you installed.)
+  Silence:  set HIGROWTH_NO_UPDATE_CHECK=1
+`
+    );
+  };
+}
+
+// package.json
+var package_default = {
+  name: "@higrowth/cli",
+  version: "0.3.0",
+  description: "Higrowth CLI \u2014 log in via browser, install Claude Code / Codex skills, manage the MCP connection.",
+  type: "module",
+  license: "Apache-2.0",
+  bin: {
+    higrowth: "dist/index.js"
+  },
+  files: [
+    "dist/",
+    "README.md"
+  ],
+  scripts: {
+    build: "tsup",
+    dev: "tsup --watch",
+    check: "tsc --noEmit"
+  },
+  engines: {
+    node: ">=20"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  devDependencies: {
+    "@types/iarna__toml": "^2.0.5",
+    "@types/node": "^22.10.5",
+    tsup: "^8.5.0",
+    typescript: "^5.6.3"
+  },
+  keywords: ["higrowth", "seo", "aeo", "mcp", "claude-code", "agent"],
+  homepage: "https://github.com/higrowth-ai/hg-engine",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/higrowth-ai/hg-engine.git",
+    directory: "cli"
+  },
+  dependencies: {
+    "@iarna/toml": "^2.2.5"
+  }
+};
+
 // src/index.ts
-var VERSION = "0.1.1";
+var VERSION = package_default.version;
 var DEFAULT_HOST = "https://app.higrowth.ai";
 var USAGE = `higrowth \u2014 Connect your agent to a Higrowth workspace
 
@@ -1160,14 +1355,23 @@ COMMANDS
   skills update [--target TARGET]
       Re-install the bundled skill versions.
 
-  version
+  upgrade
+      Show the right command to upgrade @higrowth/cli to the latest
+      published version, matched to your package manager (npm / pnpm /
+      bun / yarn / curl-pipe). The CLI auto-checks for new versions on
+      every invocation (cached 24h); set HIGROWTH_NO_UPDATE_CHECK=1 to
+      silence the nudge.
+
+  version | --version | -v
       Print version + exit.
 
 FLAGS
   --host URL          Override Higrowth host (default: ${DEFAULT_HOST}).
   --device            Use OAuth device-code flow instead of PKCE.
   --target TARGET     One of: auto (default) | claude | cursor |
-                      claude-desktop | all.
+                      claude-desktop | codex | all.
+                      codex covers Codex CLI, Codex Desktop, and the
+                      Codex IDE extension \u2014 they share one config.
   --config PATH       Override the MCP config file path.
 
 EXAMPLES
@@ -1207,15 +1411,32 @@ function resolveTarget(raw) {
   if (raw === void 0) return "auto";
   if (raw === true) return "auto";
   const s = String(raw).toLowerCase();
-  if (s === "auto" || s === "claude" || s === "cursor" || s === "claude-desktop" || s === "all") {
+  if (s === "auto" || s === "claude" || s === "cursor" || s === "claude-desktop" || s === "codex" || s === "all") {
     return s;
   }
   throw new Error(
-    `Unknown target "${s}". Use auto | claude | cursor | claude-desktop | all.`
+    `Unknown target "${s}". Use auto | claude | cursor | claude-desktop | codex | all.`
   );
 }
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  if (args.flags.version === true || args.flags.v === true) {
+    process.stdout.write(`higrowth ${VERSION}
+`);
+    return;
+  }
+  if (args.command === "" && (args.flags.help === true || args.flags.h === true)) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  const showUpdateNotice = beginUpdateCheck(VERSION);
+  try {
+    await runCommand(args);
+  } finally {
+    await showUpdateNotice();
+  }
+}
+async function runCommand(args) {
   const host = typeof args.flags.host === "string" ? args.flags.host : DEFAULT_HOST;
   const target = resolveTarget(args.flags.target);
   const device = args.flags.device === true;
@@ -1223,20 +1444,16 @@ async function main() {
   switch (args.command) {
     case "":
     case "help":
-    case "--help":
-    case "-h":
       process.stdout.write(USAGE);
       return;
     case "version":
-    case "--version":
-    case "-v":
       process.stdout.write(`higrowth ${VERSION}
 `);
       return;
     case "login":
       if (target === "all") {
         process.stderr.write(
-          "login writes to a single config file. Use --target claude | cursor | claude-desktop (or omit for auto-detect). To install skills across all agents, use `higrowth skills install --target all` after login.\n"
+          "login writes to a single config file. Use --target claude | cursor | claude-desktop | codex (or omit for auto-detect). To install skills across all agents, use `higrowth skills install --target all` after login.\n"
         );
         process.exitCode = 2;
         return;
@@ -1249,6 +1466,9 @@ async function main() {
     case "logout":
       await logoutCommand();
       return;
+    case "upgrade":
+      await upgradeCommand();
+      return;
     case "skills":
       if (args.subcommand === "install" || args.subcommand === void 0) {
         await skillsInstallCommand({ target });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@higrowth/cli",
-  "version": "0.1.1",
-  "description": "Higrowth CLI — log in via browser, install Claude Code skills, manage the MCP connection.",
+  "version": "0.3.0",
+  "description": "Higrowth CLI — log in via browser, install Claude Code / Codex skills, manage the MCP connection.",
   "type": "module",
   "license": "Apache-2.0",
   "bin": {
@@ -23,6 +23,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/iarna__toml": "^2.0.5",
     "@types/node": "^22.10.5",
     "tsup": "^8.5.0",
     "typescript": "^5.6.3"
@@ -33,5 +34,8 @@
     "type": "git",
     "url": "git+https://github.com/higrowth-ai/hg-engine.git",
     "directory": "cli"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5"
   }
 }