@simple-auth-kit/cli 1.0.1 → 1.2.0

package/README.md

@@ -21,7 +21,9 @@ npx @simple-auth-kit/cli init                       # fresh setup: guided "what
 npx @simple-auth-kit/cli add <combo> [--workspaces]  # install a specific combo
 npx @simple-auth-kit/cli add                         # guided picker, same flow as init (no config write)
 npx @simple-auth-kit/cli update [--check]             # re-installs whatever add last recorded — no args needed
-npx @simple-auth-kit/cli                              # full command/flag reference + available combos
+npx @simple-auth-kit/cli diff                         # shows the actual content diff for every file that differs from the registry (api combos only)
+npx @simple-auth-kit/cli                              # bare, in a real terminal: same guided picker as `add`
+npx @simple-auth-kit/cli --help                       # full command/flag reference + available combos
 ```
 
 `--into <path>` targets any directory (defaults to the current one). In a real terminal,
@@ -29,15 +31,37 @@ without `--force` or `--check`, a file that's changed locally since install prom
 per file — before it's overwritten; outside a TTY (CI/scripts) it's left alone by default and
 reported at the end, same as `--force` always applying and `--check` never writing anything.
 
+**Dependencies are installed for you**, shadcn-`add`-style — no separate `npm install` step.
+The package manager is auto-detected from a lockfile already in the target directory (npm if
+none found); override it with `--pm <npm|pnpm|yarn|bun>`, or skip the install entirely with
+`--skip-install` if you'd rather review `package.json` first.
+
 ## Available combos
 
-| Kind | Combo | Installs as |
-|---|---|---|
-| `api` | `nestjs-prisma`, `nestjs-drizzle`, `express-prisma`, `express-drizzle` | merged into `src/lib/auth` of an existing project (the Prisma/Drizzle config + schema land at the project root instead — see below) |
-| `admin` | `admin-nextjs`, `admin-react` | a whole new standalone app, scaffolded at the target (refuses a non-empty target unless `--force`) |
-| `mobile` | `mobile-expo`, `mobile-bare-rn` | a whole new standalone app, scaffolded at the target (same non-empty-target rule) |
+Add `--workspaces` to any of these for the workspaces variant.
+
+**`api`** — merged into `src/lib/auth` of an existing project (the Prisma/Drizzle config +
+schema land at the project root instead — see below):
+```bash
+npx @simple-auth-kit/cli add nestjs-prisma --into .
+npx @simple-auth-kit/cli add nestjs-drizzle --into .
+npx @simple-auth-kit/cli add express-prisma --into .
+npx @simple-auth-kit/cli add express-drizzle --into .
+```
+
+**`admin`** — a whole new standalone app, scaffolded at the target (refuses a non-empty target
+unless `--force`):
+```bash
+npx @simple-auth-kit/cli add admin-nextjs --into ./admin
+npx @simple-auth-kit/cli add admin-react --into ./admin
+```
 
-Add `--workspaces` to any `api`/`admin`/`mobile` combo for the workspaces variant.
+**`mobile`** — a whole new standalone app, scaffolded at the target (same non-empty-target
+rule):
+```bash
+npx @simple-auth-kit/cli add mobile-expo --into ./mobile
+npx @simple-auth-kit/cli add mobile-bare-rn --into ./mobile
+```
 
 ## Your own database models are safe
 

package/lib/copy.ts

@@ -48,6 +48,22 @@ export interface CopyOptions {
    * deleting anything on disk — for a "what would change" check before actually applying it.
    */
   dryRun?: boolean;
+  /**
+   * When set, every file whose on-disk content differs from what's about to be written gets a
+   * `{path, oldContent, newContent}` entry pushed onto this array — for rendering an actual
+   * diff (see `cmdDiff`), not just a filename list. Typically paired with `force: true` and
+   * `dryRun: true` so a locally-modified file's difference is captured too, not silently
+   * skipped the way a real install would.
+   */
+  collectDiffs?: DiffEntry[];
+}
+
+export interface DiffEntry {
+  /** Path relative to destRoot, POSIX separators — same form as CopyResult's arrays. */
+  path: string;
+  /** null when the file doesn't exist on disk yet (a brand-new file). */
+  oldContent: string | null;
+  newContent: string;
 }
 
 export interface CopyResult {
@@ -111,6 +127,7 @@ export async function copyOneFile(srcPath: string, destPath: string, destRoot: s
 
   result.updated.push(rel);
   result.manifest[rel] = newHash;
+  opts.collectDiffs?.push({ path: rel, oldContent: existing, newContent: content });
   if (opts.dryRun) return;
 
   await mkdir(dirname(destPath), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simple-auth-kit/cli",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "license": "MIT",
   "description": "simple-auth-kit add <combo> — copies registry source (backend combos, admin consoles, mobile apps) into a consumer repo, shadcn-CLI-style. Nothing is ever installed as a runtime dependency of the consumer.",
   "bin": {
@@ -20,6 +20,7 @@
     "prepack": "node scripts/bundle-registry.mjs"
   },
   "dependencies": {
+    "diff": "^9.0.0",
     "prompts": "^2.4.2",
     "tsx": "^4.23.11"
   },

package/simple-auth-kit.ts

@@ -16,11 +16,13 @@
 // workspaces support — or reads the same choices from --kind/--framework/--workspaces for
 // non-interactive/scripted use.
 import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { createTwoFilesPatch } from "diff";
 import prompts from "prompts";
-import { copyDir, copyOneFile, CopyResult, NEVER_COPY, pruneRemovedFiles, SCAFFOLD_NEVER_COPY, sha256, toPosix } from "./lib/copy.js";
+import { copyDir, copyOneFile, CopyOptions, CopyResult, DiffEntry, NEVER_COPY, pruneRemovedFiles, SCAFFOLD_NEVER_COPY, sha256, toPosix } from "./lib/copy.js";
 import { reconcileManifest, renameNative, type NativeIdentity } from "./lib/rename-native.js";
 
 const CLI_DIR = dirname(fileURLToPath(import.meta.url));
@@ -41,7 +43,7 @@ const KIND_LABELS: Record<Kind, string> = { api: "API (backend)", admin: "Admin
 const KIND_FRAMEWORK_NOUN: Record<Kind, string> = { api: "API stack", admin: "admin framework", mobile: "mobile framework" };
 
 /** Flags that take no value. Everything else consumes the next argv entry. */
-const BOOLEAN_FLAGS = new Set(["workspaces", "force", "check", "config-only"]);
+const BOOLEAN_FLAGS = new Set(["workspaces", "force", "check", "config-only", "skip-install", "help"]);
 
 interface SimpleAuthKitConfig {
   path: string;
@@ -178,6 +180,47 @@ async function resolveForcePaths(runDry: () => Promise<{ result: CopyResult }>,
   return new Set(picked ?? []);
 }
 
+const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
+type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+
+/** Detected from whichever lockfile is already sitting in targetRoot — npm if none match,
+ * matching what a fresh `npm install`-first project would have. Overridden by `--pm` when
+ * given, so e.g. a first-ever install (no lockfile yet to detect from) can still pick pnpm. */
+function detectPackageManager(targetRoot: string, flags: Record<string, string | true>): PackageManager {
+  const requested = flagString(flags.pm);
+  if (requested) {
+    if ((PACKAGE_MANAGERS as readonly string[]).includes(requested)) return requested as PackageManager;
+    console.error(`--pm "${requested}" isn't one of ${PACKAGE_MANAGERS.join(", ")} — falling back to auto-detection.`);
+  }
+  if (existsSync(join(targetRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(targetRoot, "yarn.lock"))) return "yarn";
+  if (existsSync(join(targetRoot, "bun.lockb")) || existsSync(join(targetRoot, "bun.lock"))) return "bun";
+  return "npm";
+}
+
+/**
+ * Actually runs the dependency install, shadcn-`add`-style, instead of just printing the
+ * command and leaving it to the consumer. `deps` empty means "just install whatever's in
+ * package.json" (the scaffold-mode case — dependencies are already declared, nothing to name).
+ * Skipped entirely under `--skip-install`, or when `deps` is non-empty but there's nothing new
+ * to add (an update that touched no files has nothing worth re-installing for). `--pm
+ * <npm|pnpm|yarn|bun>` picks the tool explicitly instead of auto-detecting it from a lockfile.
+ */
+function installDependencies(targetRoot: string, deps: string[], flags: Record<string, string | true>): void {
+  if (flags["skip-install"] === true) return;
+
+  const pm = detectPackageManager(targetRoot, flags);
+  // "install everything in package.json" (zero deps named) is the same bare verb across all
+  // four; naming specific packages is "install <pkgs>" for npm, "add <pkgs>" for the others.
+  const args = deps.length ? [pm === "npm" ? "install" : "add", ...deps] : ["install"];
+
+  console.log(`\nInstalling dependencies (${pm})...`);
+  const result = spawnSync(pm, args, { cwd: targetRoot, stdio: "inherit" });
+  if (result.status !== 0) {
+    console.error(`\n${pm} install exited with an error — run it yourself: cd ${targetRoot} && ${pm} ${args.join(" ")}`);
+  }
+}
+
 /**
  * The fresh-setup entry point: writes .simple-auth-kit.json (so merge-mode combos have an
  * install path/alias to anchor to), then launches the same guided "what do you need"
@@ -264,28 +307,28 @@ const ORM_LAYOUTS: { configFile: string; dataDir: string; generatedClientImport?
   { configFile: "drizzle.config.ts", dataDir: "drizzle" },
 ];
 
-/** "merge" install — core + shared + variant merged into an existing project at
- * <targetRoot>/<installPath>, with the core import alias rewritten. One exception: an ORM combo's
- * config file and data directory (see ORM_LAYOUTS) land at the *project root* instead — e.g. the
- * Prisma combos' `prisma.config.ts` + `prisma/`, or the Drizzle combos' `drizzle.config.ts` +
- * `drizzle/`.
- *
- * Both are still copied with `destRoot` (not targetRoot) as the manifest-key root, which makes
- * `copyOneFile` compute "../"-relative keys for them — deliberate, not an oversight: those keys
- * can never collide with a real destRoot-relative key, so `pruneRemovedFiles` below correctly
- * removes an ORM folder a pre-migration install left nested inside destRoot, without disturbing
- * anything else's keys. */
-async function installMerge(comboName: string, combo: ComboEntry, variant: string, registry: Registry, targetRoot: string, flags: Record<string, string | true>) {
+interface MergePlan {
+  destRoot: string;
+  installPath: string;
+  alias: string;
+  sharedDir: string;
+  variantDir: string;
+  orm: (typeof ORM_LAYOUTS)[number] | null;
+  skipFromShared: Set<string>;
+  skipFromVariant: Set<string>;
+  extraRewrites: { from: string; to: string }[] | undefined;
+  config: SimpleAuthKitConfig;
+  previous: Record<string, string>;
+}
+
+/** Everything about a merge-mode install that doesn't depend on force/dryRun/forcePaths —
+ * computed once, shared by installMerge's real run and cmdDiff's read-only one. */
+async function buildMergePlan(combo: ComboEntry, variant: string, targetRoot: string, flags: Record<string, string | true>, previous: Record<string, string>): Promise<MergePlan> {
   const config = await loadConfig(targetRoot);
   const installPath = flagString(flags.path) ?? config.path;
   const alias = flagString(flags.alias) ?? config.alias;
   const destRoot = resolve(targetRoot, installPath);
 
-  const lock = await loadLock(targetRoot);
-  const previous = lock.files ?? {};
-  const force = flags.force === true;
-  const checkOnly = flags.check === true;
-
   const comboDir = join(REGISTRY_ROOT, combo.dir);
   const sharedDir = join(comboDir, combo.sharedDir ?? "shared");
   const variantDir = join(comboDir, combo.variantsDir ?? "variants", variant);
@@ -308,37 +351,66 @@ async function installMerge(comboName: string, combo: ComboEntry, variant: strin
       ]
     : undefined;
 
-  const runCopy = async (opts: { force: boolean; forcePaths: Set<string>; dryRun: boolean }) => {
-    const result: CopyResult = { manifest: {}, skipped: [], ignored: [], updated: [] };
-    const copyOpts = {
-      aliasFrom: "@/lib/auth/core",
-      aliasTo: `${alias}/core`,
-      extraRewrites,
-      previous,
-      force: opts.force,
-      forcePaths: opts.forcePaths,
-      ignore: config.ignore,
-      neverCopy: NEVER_COPY,
-      dryRun: opts.dryRun,
-    };
-
-    await copyDir(join(REGISTRY_ROOT, registry.core.dir), join(destRoot, "core"), copyOpts, destRoot, result);
-    await copyDir(sharedDir, destRoot, { ...copyOpts, neverCopy: skipFromShared }, destRoot, result);
-    await copyDir(variantDir, destRoot, { ...copyOpts, neverCopy: skipFromVariant }, destRoot, result);
-
-    if (orm) {
-      await copyOneFile(join(sharedDir, orm.configFile), join(targetRoot, orm.configFile), destRoot, copyOpts, result);
-      await copyDir(join(variantDir, orm.dataDir), join(targetRoot, orm.dataDir), copyOpts, destRoot, result);
-    }
+  return { destRoot, installPath, alias, sharedDir, variantDir, orm, skipFromShared, skipFromVariant, extraRewrites, config, previous };
+}
 
-    // Switching variants has to remove the old variant's files, or the project ends up with both wired in.
-    const pruned = await pruneRemovedFiles(destRoot, previous, result, { force: opts.force, ignore: config.ignore, dryRun: opts.dryRun });
-    return { result, pruned };
+/** The actual copy pass for a merge-mode install — shared by installMerge (writes for real, or
+ * dry-runs for --check/the interactive-prompt pre-check) and cmdDiff (always a dry run, always
+ * force:true so a locally-modified file's difference is captured too instead of silently
+ * skipped). One exception to "everything merges into destRoot": an ORM combo's config file and
+ * data directory (see ORM_LAYOUTS) land at the *project root* instead — e.g. the Prisma combos'
+ * `prisma.config.ts` + `prisma/`, or the Drizzle combos' `drizzle.config.ts` + `drizzle/`.
+ *
+ * Both are still copied with destRoot (not targetRoot) as the manifest-key root, which makes
+ * copyOneFile compute "../"-relative keys for them — deliberate, not an oversight: those keys
+ * can never collide with a real destRoot-relative key, so pruneRemovedFiles below correctly
+ * removes an ORM folder a pre-migration install left nested inside destRoot, without disturbing
+ * anything else's keys. */
+async function runMergeCopy(
+  plan: MergePlan,
+  registry: Registry,
+  targetRoot: string,
+  opts: { force: boolean; forcePaths: Set<string>; dryRun: boolean; collectDiffs?: DiffEntry[] },
+): Promise<{ result: CopyResult; pruned: { removed: string[]; keptModified: string[] } }> {
+  const result: CopyResult = { manifest: {}, skipped: [], ignored: [], updated: [] };
+  const copyOpts: CopyOptions = {
+    aliasFrom: "@/lib/auth/core",
+    aliasTo: `${plan.alias}/core`,
+    extraRewrites: plan.extraRewrites,
+    previous: plan.previous,
+    force: opts.force,
+    forcePaths: opts.forcePaths,
+    ignore: plan.config.ignore,
+    neverCopy: NEVER_COPY,
+    dryRun: opts.dryRun,
+    collectDiffs: opts.collectDiffs,
   };
 
+  await copyDir(join(REGISTRY_ROOT, registry.core.dir), join(plan.destRoot, "core"), copyOpts, plan.destRoot, result);
+  await copyDir(plan.sharedDir, plan.destRoot, { ...copyOpts, neverCopy: plan.skipFromShared }, plan.destRoot, result);
+  await copyDir(plan.variantDir, plan.destRoot, { ...copyOpts, neverCopy: plan.skipFromVariant }, plan.destRoot, result);
+
+  if (plan.orm) {
+    await copyOneFile(join(plan.sharedDir, plan.orm.configFile), join(targetRoot, plan.orm.configFile), plan.destRoot, copyOpts, result);
+    await copyDir(join(plan.variantDir, plan.orm.dataDir), join(targetRoot, plan.orm.dataDir), copyOpts, plan.destRoot, result);
+  }
+
+  // Switching variants has to remove the old variant's files, or the project ends up with both wired in.
+  const pruned = await pruneRemovedFiles(plan.destRoot, plan.previous, result, { force: opts.force, ignore: plan.config.ignore, dryRun: opts.dryRun });
+  return { result, pruned };
+}
+
+async function installMerge(comboName: string, combo: ComboEntry, variant: string, registry: Registry, targetRoot: string, flags: Record<string, string | true>) {
+  const lock = await loadLock(targetRoot);
+  const previous = lock.files ?? {};
+  const force = flags.force === true;
+  const checkOnly = flags.check === true;
+
+  const plan = await buildMergePlan(combo, variant, targetRoot, flags, previous);
+
   if (checkOnly) {
-    const { result, pruned } = await runCopy({ force, forcePaths: new Set(), dryRun: true });
-    console.log(`\nCheck only — nothing written. "${comboName}" (${variant} variant) in ${installPath} (alias ${alias}):`);
+    const { result, pruned } = await runMergeCopy(plan, registry, targetRoot, { force, forcePaths: new Set(), dryRun: true });
+    console.log(`\nCheck only — nothing written. "${comboName}" (${variant} variant) in ${plan.installPath} (alias ${plan.alias}):`);
     printInstallSummary(result, pruned);
     const silent = !result.updated.length && !result.skipped.length && !pruned.removed.length && !pruned.keptModified.length;
     if (silent) console.log(`\nUp to date — nothing would change.`);
@@ -348,8 +420,8 @@ async function installMerge(comboName: string, combo: ComboEntry, variant: strin
   // Interactive + no --force: find locally-modified conflicts first (a dry run, nothing written),
   // and let the user pick which — if any — to overwrite anyway, shadcn-"this file already exists"
   // style, instead of the non-interactive default of silently leaving all of them alone.
-  const forcePaths = await resolveForcePaths(() => runCopy({ force: false, forcePaths: new Set(), dryRun: true }), flags);
-  const { result, pruned } = await runCopy({ force, forcePaths, dryRun: false });
+  const forcePaths = await resolveForcePaths(() => runMergeCopy(plan, registry, targetRoot, { force: false, forcePaths: new Set(), dryRun: true }), flags);
+  const { result, pruned } = await runMergeCopy(plan, registry, targetRoot, { force, forcePaths, dryRun: false });
 
   await writeFile(
     join(targetRoot, "auth.lock.json"),
@@ -357,11 +429,16 @@ async function installMerge(comboName: string, combo: ComboEntry, variant: strin
     "utf8",
   );
 
-  console.log(`\nInstalled "${comboName}" (${variant} variant) into ${installPath} (alias ${alias})`);
+  console.log(`\nInstalled "${comboName}" (${variant} variant) into ${plan.installPath} (alias ${plan.alias})`);
   printInstallSummary(result, pruned);
 
   const peerDeps = [...new Set([...registry.core.peerDependencies, ...combo.peerDependencies])];
-  console.log(`\nInstall peer dependencies:\n  npm install ${peerDeps.join(" ")}`);
+  console.log(`\nPeer dependencies: ${peerDeps.join(" ")}`);
+  if (result.updated.length) {
+    installDependencies(targetRoot, peerDeps, flags);
+  } else if (flags["skip-install"] !== true) {
+    console.log(`(nothing changed this run — skipping install)`);
+  }
   printPostInstallNotes(combo, variant);
 }
 
@@ -427,7 +504,13 @@ async function installScaffold(comboName: string, combo: ComboEntry, variant: st
 
   console.log(`\nGenerated "${appName}" (${comboName}, ${variant} variant) into ${targetRoot}`);
   printInstallSummary(result, pruned);
-  console.log(`\nDependencies are already declared in package.json — run \`npm install\` (or \`pnpm install\`) in ${targetRoot}.`);
+  if (result.updated.length) {
+    // Dependencies are already declared in package.json — no specific packages to name, just
+    // "install whatever's there" (installDependencies with an empty list does exactly that).
+    installDependencies(targetRoot, [], flags);
+  } else if (flags["skip-install"] !== true) {
+    console.log(`\n(nothing changed this run — skipping install)`);
+  }
   printPostInstallNotes(combo, variant);
 }
 
@@ -649,21 +732,100 @@ async function cmdUpdate(targetRoot: string, flags: Record<string, string | true
   await installCombo(lock.combo, combo, variant, registry, targetRoot, flags);
 }
 
+/**
+ * Shows the actual content diff between what's on disk and what the current registry would
+ * produce — for every tracked file that differs, whether that's because the registry changed
+ * upstream or because you hand-edited the file yourself (both are worth seeing before deciding
+ * what to do). Read-only: never writes anything, unlike `update`.
+ */
 async function cmdDiff(targetRoot: string) {
   const lock = await loadLock(targetRoot);
-  if (!lock.files) {
-    console.error(`No auth.lock.json found in ${targetRoot} — nothing installed yet.`);
+  if (!lock.combo || !lock.variant) {
+    console.error(`No auth.lock.json (or it's missing combo/variant) in ${targetRoot} — nothing installed to diff.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const registry = await loadRegistry();
+  const combo = registry.combos[lock.combo];
+  if (!combo) {
+    console.error(`auth.lock.json names combo "${lock.combo}", which no longer exists in this registry.`);
+    process.exitCode = 1;
     return;
   }
-  console.log(`diff is not implemented yet (deferred until there's more than one install to maintain) — installed files:`);
-  console.log(`  combo: ${lock.combo}, variant: ${lock.variant ?? DEFAULT_VARIANT}`);
-  for (const file of Object.keys(lock.files)) console.log(`  ${file}`);
+
+  if (comboInstallMode(combo) === "scaffold") {
+    console.error(`diff isn't supported yet for "${lock.combo}" (a scaffold-mode combo) — only merge-mode (api) combos support it.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const variant = resolveVariant(combo, lock.combo, lock.variant);
+  if (!variant) {
+    process.exitCode = 1;
+    return;
+  }
+
+  const plan = await buildMergePlan(combo, variant, targetRoot, {}, lock.files ?? {});
+  const diffs: DiffEntry[] = [];
+  // force:true so a locally-modified file's difference is captured too — diff wants to show
+  // everything that differs, not just what a real (non---force) install would apply; dryRun:true
+  // so nothing is written.
+  await runMergeCopy(plan, registry, targetRoot, { force: true, forcePaths: new Set(), dryRun: true, collectDiffs: diffs });
+
+  if (!diffs.length) {
+    console.log(`No differences — every tracked file in "${lock.combo}" (${variant} variant) matches the current registry.`);
+    return;
+  }
+
+  console.log(`${diffs.length} file(s) differ from the current registry:`);
+  for (const d of diffs) {
+    const patch = createTwoFilesPatch(d.path, d.path, d.oldContent ?? "", d.newContent, "installed", "registry");
+    process.stdout.write(`\n${patch}`);
+  }
+}
+
+async function printUsage(exitCode: number) {
+  const registry = await loadRegistry();
+  console.log("Usage: simple-auth-kit <init|add|update|diff> [...]");
+  console.log(`  init [--config-only] [--kind ...] [--into <path>]  (fresh setup: guided "what do you need" picker, like bare "add")`);
+  console.log(`      --config-only: just write .simple-auth-kit.json and stop, no install`);
+  console.log(`  add <combo> [--workspaces] [--force] [--skip-install] [--into <path>] [--path <dir>] [--alias <alias>]`);
+  console.log(`  add [--kind api,admin,mobile] [--framework <name>,...] [--workspaces] [--into <path>] [--name <appName>]`);
+  console.log(`      (bare "add", or "add" with --kind but no combo, launches a guided prompt for whatever's missing)`);
+  console.log(`  update [--check] [--force] [--skip-install] [--into <path>]  (re-installs whatever combo+variant auth.lock.json already records)`);
+  console.log(`      --check: report what would change, without writing anything (merge-mode combos only)`);
+  console.log(`  diff [--into <path>]  (shows the actual content diff for every tracked file that differs from the current registry — read-only; merge-mode combos only)`);
+  console.log(`  In a TTY, without --force or --check: a file changed locally since install prompts to overwrite, per file.`);
+  console.log(`  --skip-install: don't run the package manager after copying files — the default is to install for you, shadcn-\`add\`-style.`);
+  console.log(`  --pm <npm|pnpm|yarn|bun>: which package manager to install with — default: detected from a lockfile in the target directory, npm if none found.`);
+  console.log(`\nAvailable combos:`);
+  for (const kind of ["api", "admin", "mobile"] as Kind[]) {
+    const names = combosByKind(registry, kind).map(([name]) => name);
+    if (names.length) console.log(`  ${KIND_LABELS[kind]}: ${names.join(", ")}`);
+  }
+  console.log(`\nVariants (choose one at install time):`);
+  for (const [name, variant] of Object.entries(registry.variants)) {
+    console.log(`  ${name}${variant.flag ? ` (${variant.flag})` : " (default)"} — ${variant.description}`);
+  }
+  process.exitCode = exitCode;
 }
 
 async function main() {
   const { command, positional, flags } = parseArgs(process.argv.slice(2));
   const targetRoot = resolve(process.cwd(), flagString(flags.into) ?? ".");
 
+  if (command === "--help" || command === "-h" || command === "help" || flags.help === true) {
+    await printUsage(0);
+    return;
+  }
+  if (!command && isTTY()) {
+    // Bare `npx @simple-auth-kit/cli` in a real terminal — go straight to the guided picker
+    // (same flow as `add` with no combo) instead of just printing help text.
+    await cmdCreate(targetRoot, flags);
+    return;
+  }
+
   switch (command) {
     case "init":
       await cmdInit(targetRoot, flags);
@@ -684,28 +846,8 @@ async function main() {
     case "diff":
       await cmdDiff(targetRoot);
       break;
-    default: {
-      const registry = await loadRegistry();
-      console.log("Usage: simple-auth-kit <init|add|update|diff> [...]");
-      console.log(`  init [--config-only] [--kind ...] [--into <path>]  (fresh setup: guided "what do you need" picker, like bare "add")`);
-      console.log(`      --config-only: just write .simple-auth-kit.json and stop, no install`);
-      console.log(`  add <combo> [--workspaces] [--force] [--into <path>] [--path <dir>] [--alias <alias>]`);
-      console.log(`  add [--kind api,admin,mobile] [--framework <name>,...] [--workspaces] [--into <path>] [--name <appName>]`);
-      console.log(`      (bare "add", or "add" with --kind but no combo, launches a guided prompt for whatever's missing)`);
-      console.log(`  update [--check] [--force] [--into <path>]  (re-installs whatever combo+variant auth.lock.json already records)`);
-      console.log(`      --check: report what would change, without writing anything (merge-mode combos only)`);
-      console.log(`  In a TTY, without --force or --check: a file changed locally since install prompts to overwrite, per file.`);
-      console.log(`\nAvailable combos:`);
-      for (const kind of ["api", "admin", "mobile"] as Kind[]) {
-        const names = combosByKind(registry, kind).map(([name]) => name);
-        if (names.length) console.log(`  ${KIND_LABELS[kind]}: ${names.join(", ")}`);
-      }
-      console.log(`\nVariants (choose one at install time):`);
-      for (const [name, variant] of Object.entries(registry.variants)) {
-        console.log(`  ${name}${variant.flag ? ` (${variant.flag})` : " (default)"} — ${variant.description}`);
-      }
-      process.exitCode = command ? 1 : 0;
-    }
+    default:
+      await printUsage(command ? 1 : 0);
   }
 }