api2cli 0.1.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "api2cli",
+  "version": "0.1.0",
+  "description": "Turn any REST API into a standardized, agent-ready CLI",
+  "type": "module",
+  "bin": {
+    "api2cli": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --target bun",
+    "dev": "bun run src/index.ts"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT",
+  "keywords": ["cli", "api", "rest", "agent", "skill", "mcp", "agentskills"]
+}

package/src/commands/bundle.ts

@@ -0,0 +1,68 @@
+import { Command } from "commander";
+import { existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import pc from "picocolors";
+import { getCliDir, getDistDir, CLI_ROOT } from "../lib/config.js";
+import { readdirSync } from "fs";
+
+export const bundleCommand = new Command("bundle")
+  .description("Build/rebuild a CLI from source")
+  .argument("[app]", "CLI to build (omit with --all)")
+  .option("--compile", "Create standalone binary (~50MB, no runtime needed)")
+  .option("--all", "Build all installed CLIs")
+  .addHelpText(
+    "after",
+    "\nExamples:\n  api2cli bundle typefully\n  api2cli bundle typefully --compile\n  api2cli bundle --all",
+  )
+  .action(async (app: string | undefined, opts) => {
+    if (opts.all) {
+      if (!existsSync(CLI_ROOT)) {
+        console.log("No CLIs installed.");
+        return;
+      }
+      const dirs = readdirSync(CLI_ROOT).filter((d) => d.endsWith("-cli"));
+      for (const d of dirs) {
+        await buildCli(d.replace(/-cli$/, ""), opts.compile);
+      }
+      return;
+    }
+
+    if (!app) {
+      console.error("Specify an app name or use --all");
+      process.exit(2);
+    }
+
+    await buildCli(app, opts.compile);
+  });
+
+async function buildCli(app: string, compile?: boolean): Promise<void> {
+  const cliDir = getCliDir(app);
+  if (!existsSync(cliDir)) {
+    console.error(`${pc.red("✗")} ${app}-cli not found. Run: ${pc.cyan(`api2cli create ${app}`)}`);
+    return;
+  }
+
+  const distDir = getDistDir(app);
+  mkdirSync(distDir, { recursive: true });
+
+  console.log(`Building ${pc.bold(`${app}-cli`)}...`);
+
+  const entry = join(cliDir, "src", "index.ts");
+  const outfile = join(distDir, compile ? `${app}-cli` : `${app}-cli.js`);
+  const args = ["bun", "build", entry, "--outfile", outfile, "--target", "bun"];
+  if (compile) args.push("--compile");
+
+  const proc = Bun.spawn(args, { cwd: cliDir, stdout: "pipe", stderr: "pipe" });
+  const code = await proc.exited;
+
+  if (code === 0) {
+    const size = Bun.file(outfile).size;
+    const sizeStr = size > 1024 * 1024
+      ? `${(size / 1024 / 1024).toFixed(1)}MB`
+      : `${(size / 1024).toFixed(1)}KB`;
+    console.log(`${pc.green("✓")} Built ${pc.bold(`${app}-cli`)} (${sizeStr})`);
+  } else {
+    const stderr = await new Response(proc.stderr).text();
+    console.error(`${pc.red("✗")} Build failed: ${stderr}`);
+  }
+}

package/src/commands/create.ts

@@ -0,0 +1,78 @@
+import { Command } from "commander";
+import { existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import pc from "picocolors";
+import { getCliDir } from "../lib/config.js";
+import { copyTemplate, replacePlaceholders } from "../lib/template.js";
+
+export const createCommand = new Command("create")
+  .description("Generate a new CLI from API documentation")
+  .argument("<app>", "API/app name (e.g. typefully, dub, mercury)")
+  .option("--docs <url>", "URL to API documentation")
+  .option("--openapi <url>", "URL to OpenAPI/Swagger spec")
+  .option("--base-url <url>", "API base URL", "https://api.example.com")
+  .option("--auth-type <type>", "Auth type: bearer, api-key, basic, custom", "bearer")
+  .option("--auth-header <name>", "Auth header name", "Authorization")
+  .option("--force", "Overwrite existing CLI", false)
+  .addHelpText(
+    "after",
+    `
+Examples:
+  api2cli create typefully --base-url https://api.typefully.com --auth-type bearer
+  api2cli create dub --openapi https://api.dub.co/openapi.json
+  api2cli create my-api --docs https://docs.example.com/api`,
+  )
+  .action(async (app: string, opts) => {
+    const cliDir = getCliDir(app);
+
+    if (existsSync(cliDir) && !opts.force) {
+      console.error(`${pc.red("✗")} ${app}-cli already exists at ${cliDir}`);
+      console.error(`  Use ${pc.cyan("--force")} to overwrite.`);
+      process.exit(1);
+    }
+
+    console.log(`\n${pc.bold("Creating")} ${pc.cyan(`${app}-cli`)}...\n`);
+
+    // 1. Create target directory
+    mkdirSync(cliDir, { recursive: true });
+    console.log(`  ${pc.green("+")} Created ${pc.dim(cliDir)}`);
+
+    // 2. Copy template
+    copyTemplate(cliDir);
+    console.log(`  ${pc.green("+")} Copied template scaffold`);
+
+    // 3. Replace placeholders
+    replacePlaceholders(cliDir, {
+      appName: app,
+      appCli: `${app}-cli`,
+      baseUrl: opts.baseUrl,
+      authType: opts.authType,
+      authHeader: opts.authHeader,
+    });
+    console.log(`  ${pc.green("+")} Configured for ${pc.bold(app)}`);
+
+    // 4. Install dependencies
+    console.log(`  ${pc.dim("Installing dependencies...")}`);
+    const install = Bun.spawn(["bun", "install"], {
+      cwd: cliDir,
+      stdout: "ignore",
+      stderr: "pipe",
+    });
+    await install.exited;
+    console.log(`  ${pc.green("+")} Dependencies installed`);
+
+    // 5. Rename SKILL.md.template
+    const skillTemplate = join(cliDir, "SKILL.md.template");
+    const skillTarget = join(cliDir, "SKILL.md");
+    if (existsSync(skillTemplate)) {
+      const { renameSync } = require("fs");
+      renameSync(skillTemplate, skillTarget);
+    }
+
+    console.log(`\n${pc.green("✓")} Created ${pc.bold(`${app}-cli`)} at ${pc.dim(cliDir)}`);
+    console.log(`\n${pc.bold("Next steps:")}`);
+    console.log(`  1. Edit resources in ${pc.dim(`${cliDir}/src/resources/`)}`);
+    console.log(`  2. Build: ${pc.cyan(`api2cli bundle ${app}`)}`);
+    console.log(`  3. Link: ${pc.cyan(`api2cli link ${app}`)}`);
+    console.log(`  4. Auth: ${pc.cyan(`${app}-cli auth set "your-token"`)}`);
+  });

package/src/commands/doctor.ts

@@ -0,0 +1,48 @@
+import { Command } from "commander";
+import { existsSync } from "fs";
+import pc from "picocolors";
+import { CLI_ROOT, TOKENS_DIR, TEMPLATE_DIR } from "../lib/config.js";
+
+export const doctorCommand = new Command("doctor")
+  .description("Check system requirements and configuration")
+  .addHelpText("after", "\nExample:\n  api2cli doctor")
+  .action(async () => {
+    console.log(`\n${pc.bold("api2cli doctor")}\n`);
+    let issues = 0;
+
+    // Bun
+    try {
+      const proc = Bun.spawn(["bun", "--version"], { stdout: "pipe", stderr: "pipe" });
+      const version = (await new Response(proc.stdout).text()).trim();
+      console.log(`  ${pc.green("✓")} Bun ${version}`);
+    } catch {
+      console.log(`  ${pc.red("✗")} Bun not found. Install: ${pc.cyan("https://bun.sh")}`);
+      issues++;
+    }
+
+    // CLI root
+    if (existsSync(CLI_ROOT)) {
+      console.log(`  ${pc.green("✓")} CLI root: ${pc.dim(CLI_ROOT)}`);
+    } else {
+      console.log(`  ${pc.yellow("~")} CLI root not yet created: ${pc.dim(CLI_ROOT)}`);
+    }
+
+    // Tokens dir
+    if (existsSync(TOKENS_DIR)) {
+      console.log(`  ${pc.green("✓")} Tokens dir: ${pc.dim(TOKENS_DIR)}`);
+    } else {
+      console.log(`  ${pc.yellow("~")} Tokens dir not yet created: ${pc.dim(TOKENS_DIR)}`);
+    }
+
+    // Template
+    if (existsSync(TEMPLATE_DIR)) {
+      console.log(`  ${pc.green("✓")} Template: ${pc.dim(TEMPLATE_DIR)}`);
+    } else {
+      console.log(`  ${pc.red("✗")} Template not found: ${pc.dim(TEMPLATE_DIR)}`);
+      issues++;
+    }
+
+    console.log(
+      issues === 0 ? `\n${pc.green("All good!")} 🎉\n` : `\n${pc.red(`${issues} issue(s) found.`)}\n`,
+    );
+  });

package/src/commands/install.ts

@@ -0,0 +1,29 @@
+import { Command } from "commander";
+import { existsSync } from "fs";
+import pc from "picocolors";
+import { getCliDir } from "../lib/config.js";
+
+export const installCommand = new Command("install")
+  .description("Install a pre-built CLI from the registry")
+  .argument("<app>", "CLI to install (e.g. typefully, dub)")
+  .option("--force", "Overwrite existing CLI", false)
+  .addHelpText(
+    "after",
+    "\nExamples:\n  api2cli install typefully\n  api2cli install dub --force",
+  )
+  .action(async (app: string, opts) => {
+    const cliDir = getCliDir(app);
+
+    if (existsSync(cliDir) && !opts.force) {
+      console.error(`${pc.red("✗")} ${app}-cli already installed. Use ${pc.cyan("--force")} to reinstall.`);
+      process.exit(1);
+    }
+
+    console.log(`Installing ${pc.bold(`${app}-cli`)} from registry...`);
+
+    // TODO: Fetch from npm @api2cli/<app> or api2cli.dev API
+    // Download resources + config -> merge with template -> build -> link
+    console.log(`\n${pc.yellow("🚧")} Registry not yet available.`);
+    console.log(`\nCreate it manually instead:`);
+    console.log(`  ${pc.cyan(`api2cli create ${app} --docs <api-docs-url>`)}`);
+  });

package/src/commands/link.ts

@@ -0,0 +1,32 @@
+import { Command } from "commander";
+import { existsSync, readdirSync } from "fs";
+import pc from "picocolors";
+import { getCliDir, getDistDir, CLI_ROOT } from "../lib/config.js";
+import { addToPath } from "../lib/shell.js";
+
+export const linkCommand = new Command("link")
+  .description("Add a CLI to your PATH")
+  .argument("[app]", "CLI to link (omit with --all)")
+  .option("--all", "Link all installed CLIs")
+  .addHelpText("after", "\nExamples:\n  api2cli link typefully\n  api2cli link --all")
+  .action((app: string | undefined, opts) => {
+    if (opts.all || !app) {
+      if (!existsSync(CLI_ROOT)) {
+        console.log("No CLIs installed.");
+        return;
+      }
+      const dirs = readdirSync(CLI_ROOT).filter((d) => d.endsWith("-cli"));
+      for (const d of dirs) {
+        const name = d.replace(/-cli$/, "");
+        addToPath(name, getDistDir(name));
+      }
+      return;
+    }
+
+    if (!existsSync(getCliDir(app))) {
+      console.error(`${pc.red("✗")} ${app}-cli not found. Run: ${pc.cyan(`api2cli create ${app}`)}`);
+      process.exit(1);
+    }
+
+    addToPath(app, getDistDir(app));
+  });

package/src/commands/list.ts

@@ -0,0 +1,52 @@
+import { Command } from "commander";
+import { existsSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+import pc from "picocolors";
+import { CLI_ROOT, TOKENS_DIR } from "../lib/config.js";
+
+export const listCommand = new Command("list")
+  .description("List all installed CLIs")
+  .option("--json", "Output as JSON")
+  .addHelpText("after", "\nExamples:\n  api2cli list\n  api2cli list --json")
+  .action((opts) => {
+    if (!existsSync(CLI_ROOT)) {
+      console.log("No CLIs installed. Run: api2cli create <app>");
+      return;
+    }
+
+    const dirs = readdirSync(CLI_ROOT).filter((d) => {
+      return statSync(join(CLI_ROOT, d)).isDirectory() && d.endsWith("-cli");
+    });
+
+    if (dirs.length === 0) {
+      console.log("No CLIs installed.");
+      return;
+    }
+
+    if (opts.json) {
+      const data = dirs.map((d) => {
+        const name = d.replace(/-cli$/, "");
+        return {
+          name,
+          built: existsSync(join(CLI_ROOT, d, "dist")),
+          hasToken: existsSync(join(TOKENS_DIR, `${d}.txt`)),
+          path: join(CLI_ROOT, d),
+        };
+      });
+      console.log(JSON.stringify({ ok: true, data }, null, 2));
+      return;
+    }
+
+    console.log(`\n${pc.bold("Installed CLIs:")}\n`);
+    for (const d of dirs) {
+      const name = d.replace(/-cli$/, "");
+      const built = existsSync(join(CLI_ROOT, d, "dist"));
+      const hasToken = existsSync(join(TOKENS_DIR, `${d}.txt`));
+      const status = [
+        built ? pc.green("built") : pc.yellow("not built"),
+        hasToken ? pc.green("auth") : pc.dim("no auth"),
+      ].join(pc.dim(" | "));
+      console.log(`  ${pc.bold(name.padEnd(20))} ${status}`);
+    }
+    console.log();
+  });

package/src/commands/publish.ts

@@ -0,0 +1,22 @@
+import { Command } from "commander";
+import { existsSync } from "fs";
+import pc from "picocolors";
+import { getCliDir } from "../lib/config.js";
+
+export const publishCommand = new Command("publish")
+  .description("Publish a CLI to the api2cli registry")
+  .argument("<app>", "CLI to publish")
+  .option("--scope <scope>", "npm scope", "@api2cli")
+  .addHelpText("after", "\nExample:\n  api2cli publish typefully")
+  .action(async (app: string, opts) => {
+    const cliDir = getCliDir(app);
+
+    if (!existsSync(cliDir)) {
+      console.error(`${pc.red("✗")} ${app}-cli not found.`);
+      process.exit(1);
+    }
+
+    // TODO: Package resources + config, publish to npm + api2cli.dev
+    console.log(`Publishing ${pc.bold(`${app}-cli`)} as ${pc.cyan(`${opts.scope}/${app}`)}...`);
+    console.log(`\n${pc.yellow("🚧")} Publishing not yet implemented.`);
+  });

package/src/commands/remove.ts

@@ -0,0 +1,35 @@
+import { Command } from "commander";
+import { existsSync, rmSync } from "fs";
+import pc from "picocolors";
+import { getCliDir, getTokenFile, getDistDir } from "../lib/config.js";
+import { removeFromPath } from "../lib/shell.js";
+
+export const removeCommand = new Command("remove")
+  .description("Remove a CLI entirely")
+  .argument("<app>", "CLI to remove")
+  .option("--keep-token", "Keep the auth token")
+  .addHelpText("after", "\nExamples:\n  api2cli remove typefully\n  api2cli remove typefully --keep-token")
+  .action((app: string, opts) => {
+    const cliDir = getCliDir(app);
+
+    if (!existsSync(cliDir)) {
+      console.error(`${pc.red("✗")} ${app}-cli not found.`);
+      process.exit(1);
+    }
+
+    // Remove from PATH
+    removeFromPath(app, getDistDir(app));
+
+    // Remove directory
+    rmSync(cliDir, { recursive: true, force: true });
+    console.log(`${pc.green("✓")} Removed ${pc.bold(`${app}-cli`)}`);
+
+    // Remove token unless --keep-token
+    if (!opts.keepToken) {
+      const tokenFile = getTokenFile(app);
+      if (existsSync(tokenFile)) {
+        rmSync(tokenFile);
+        console.log(`${pc.green("✓")} Removed token`);
+      }
+    }
+  });

package/src/commands/tokens.ts

@@ -0,0 +1,35 @@
+import { Command } from "commander";
+import { existsSync, readdirSync, readFileSync } from "fs";
+import pc from "picocolors";
+import { TOKENS_DIR } from "../lib/config.js";
+import { join } from "path";
+
+export const tokensCommand = new Command("tokens")
+  .description("List all configured API tokens")
+  .option("--show", "Show full unmasked tokens")
+  .addHelpText("after", "\nExamples:\n  api2cli tokens\n  api2cli tokens --show")
+  .action((opts) => {
+    if (!existsSync(TOKENS_DIR)) {
+      console.log("No tokens configured yet.");
+      return;
+    }
+
+    const files = readdirSync(TOKENS_DIR).filter((f) => f.endsWith(".txt"));
+    if (files.length === 0) {
+      console.log("No tokens configured yet.");
+      return;
+    }
+
+    console.log(`\n${pc.bold("Configured tokens:")}\n`);
+    for (const f of files) {
+      const name = f.replace(".txt", "");
+      const token = readFileSync(join(TOKENS_DIR, f), "utf-8").trim();
+      const display = opts.show
+        ? token
+        : token.length > 8
+          ? `${token.slice(0, 4)}${pc.dim("...")}${token.slice(-4)}`
+          : pc.dim("****");
+      console.log(`  ${pc.bold(name.padEnd(25))} ${display}`);
+    }
+    console.log();
+  });

package/src/commands/unlink.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+import { getDistDir } from "../lib/config.js";
+import { removeFromPath } from "../lib/shell.js";
+
+export const unlinkCommand = new Command("unlink")
+  .description("Remove a CLI from your PATH")
+  .argument("<app>", "CLI to unlink")
+  .addHelpText("after", "\nExample:\n  api2cli unlink typefully")
+  .action((app: string) => {
+    removeFromPath(app, getDistDir(app));
+  });

package/src/commands/update.ts

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+import { existsSync } from "fs";
+import pc from "picocolors";
+import { getCliDir } from "../lib/config.js";
+
+export const updateCommand = new Command("update")
+  .description("Re-sync a CLI when the upstream API changes")
+  .argument("<app>", "CLI to update")
+  .option("--docs <url>", "Updated API documentation URL")
+  .option("--openapi <url>", "Updated OpenAPI spec URL")
+  .addHelpText("after", "\nExample:\n  api2cli update typefully --docs https://docs.typefully.com")
+  .action(async (app: string) => {
+    const cliDir = getCliDir(app);
+
+    if (!existsSync(cliDir)) {
+      console.error(`${pc.red("✗")} ${app}-cli not found. Run: ${pc.cyan(`api2cli create ${app}`)}`);
+      process.exit(1);
+    }
+
+    // TODO: Agent-driven update flow
+    // Re-read API docs -> diff endpoints -> add/update resources -> rebuild
+    console.log(`${pc.yellow("🚧")} Update is agent-driven.`);
+    console.log(`\nUse your AI agent to update resources in:`);
+    console.log(`  ${pc.dim(`${cliDir}/src/resources/`)}`);
+    console.log(`\nThen rebuild: ${pc.cyan(`api2cli bundle ${app}`)}`);
+  });

package/src/index.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { createCommand } from "./commands/create.js";
+import { installCommand } from "./commands/install.js";
+import { listCommand } from "./commands/list.js";
+import { bundleCommand } from "./commands/bundle.js";
+import { linkCommand } from "./commands/link.js";
+import { unlinkCommand } from "./commands/unlink.js";
+import { tokensCommand } from "./commands/tokens.js";
+import { removeCommand } from "./commands/remove.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { updateCommand } from "./commands/update.js";
+import { publishCommand } from "./commands/publish.js";
+
+const program = new Command();
+
+program
+  .name("api2cli")
+  .description("Turn any REST API into a standardized, agent-ready CLI")
+  .version("0.1.0");
+
+// Core
+program.addCommand(createCommand);
+program.addCommand(bundleCommand);
+program.addCommand(linkCommand);
+program.addCommand(unlinkCommand);
+program.addCommand(listCommand);
+
+// Auth
+program.addCommand(tokensCommand);
+
+// Lifecycle
+program.addCommand(removeCommand);
+program.addCommand(doctorCommand);
+program.addCommand(updateCommand);
+
+// Registry
+program.addCommand(installCommand);
+program.addCommand(publishCommand);
+
+program.parse();

package/src/lib/bashrc.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync, appendFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const MARKER_START = "# >>> api2cli >>>";
+const MARKER_END = "# <<< api2cli <<<";
+
+function getShellRc(): string {
+  const zshrc = join(homedir(), ".zshrc");
+  const bashrc = join(homedir(), ".bashrc");
+  if (existsSync(zshrc)) return zshrc;
+  return bashrc;
+}
+
+export function addToPath(appName: string, binDir: string): void {
+  const rcFile = getShellRc();
+  const content = existsSync(rcFile) ? readFileSync(rcFile, "utf-8") : "";
+
+  const exportLine = `export PATH="${binDir}:$PATH"`;
+
+  // Check if already linked
+  if (content.includes(exportLine)) {
+    console.log(`${appName} already in PATH`);
+    return;
+  }
+
+  // Find or create api2cli block
+  if (content.includes(MARKER_START)) {
+    // Insert before the end marker
+    const updated = content.replace(
+      MARKER_END,
+      `${exportLine}\n${MARKER_END}`
+    );
+    const { writeFileSync } = require("fs");
+    writeFileSync(rcFile, updated);
+  } else {
+    appendFileSync(rcFile, `\n${MARKER_START}\n${exportLine}\n${MARKER_END}\n`);
+  }
+
+  console.log(`Added ${appName} to PATH in ${rcFile}`);
+  console.log(`Run: source ${rcFile}`);
+}
+
+export function removeFromPath(appName: string, binDir: string): void {
+  const rcFile = getShellRc();
+  if (!existsSync(rcFile)) return;
+
+  const content = readFileSync(rcFile, "utf-8");
+  const exportLine = `export PATH="${binDir}:$PATH"`;
+  const updated = content.replace(`${exportLine}\n`, "");
+
+  const { writeFileSync } = require("fs");
+  writeFileSync(rcFile, updated);
+  console.log(`Removed ${appName} from PATH`);
+}

package/src/lib/config.ts

@@ -0,0 +1,35 @@
+import { homedir } from "os";
+import { join, resolve } from "path";
+
+/** Root directory for all generated CLIs */
+export const CLI_ROOT = join(homedir(), ".cli");
+
+/** Centralized token storage directory */
+export const TOKENS_DIR = join(homedir(), ".config", "tokens");
+
+/** Template directory (relative to this package in the monorepo) */
+export const TEMPLATE_DIR = resolve(import.meta.dir, "..", "..", "..", "template");
+
+/** Placeholders used in the template that get replaced during create */
+export const PLACEHOLDERS = [
+  "{{APP_NAME}}",
+  "{{APP_CLI}}",
+  "{{BASE_URL}}",
+  "{{AUTH_TYPE}}",
+  "{{AUTH_HEADER}}",
+] as const;
+
+/** Get the installation directory for a CLI */
+export function getCliDir(app: string): string {
+  return join(CLI_ROOT, `${app}-cli`);
+}
+
+/** Get the token file path for a CLI */
+export function getTokenFile(app: string): string {
+  return join(TOKENS_DIR, `${app}-cli.txt`);
+}
+
+/** Get the dist directory for a CLI */
+export function getDistDir(app: string): string {
+  return join(getCliDir(app), "dist");
+}

package/src/lib/shell.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import pc from "picocolors";
+
+const MARKER_START = "# >>> api2cli >>>";
+const MARKER_END = "# <<< api2cli <<<";
+
+/** Detect the user's shell rc file */
+function getShellRc(): string {
+  const shell = process.env.SHELL ?? "";
+  if (shell.includes("zsh")) return join(homedir(), ".zshrc");
+  if (shell.includes("fish")) return join(homedir(), ".config", "fish", "config.fish");
+  // Check if .zshrc exists even if SHELL isn't set
+  const zshrc = join(homedir(), ".zshrc");
+  if (existsSync(zshrc)) return zshrc;
+  return join(homedir(), ".bashrc");
+}
+
+/** Add a CLI's dist directory to PATH via the shell rc file. Idempotent. */
+export function addToPath(app: string, binDir: string): void {
+  const rcFile = getShellRc();
+  const content = existsSync(rcFile) ? readFileSync(rcFile, "utf-8") : "";
+  const exportLine = `export PATH="${binDir}:$PATH"`;
+
+  if (content.includes(exportLine)) {
+    console.log(`${pc.dim(app)} already in PATH`);
+    return;
+  }
+
+  if (content.includes(MARKER_START)) {
+    const updated = content.replace(MARKER_END, `${exportLine}\n${MARKER_END}`);
+    writeFileSync(rcFile, updated);
+  } else {
+    appendFileSync(rcFile, `\n${MARKER_START}\n${exportLine}\n${MARKER_END}\n`);
+  }
+
+  console.log(`${pc.green("+")} Added ${pc.bold(app)} to PATH in ${pc.dim(rcFile)}`);
+  console.log(`  Run: ${pc.cyan(`source ${rcFile}`)}`);
+}
+
+/** Remove a CLI from PATH in the shell rc file */
+export function removeFromPath(app: string, binDir: string): void {
+  const rcFile = getShellRc();
+  if (!existsSync(rcFile)) return;
+
+  const content = readFileSync(rcFile, "utf-8");
+  const exportLine = `export PATH="${binDir}:$PATH"\n`;
+
+  if (!content.includes(exportLine)) {
+    console.log(`${pc.dim(app)} not in PATH`);
+    return;
+  }
+
+  writeFileSync(rcFile, content.replace(exportLine, ""));
+  console.log(`${pc.red("-")} Removed ${pc.bold(app)} from PATH`);
+}