feat(setup): 'bun run sim' is the primary entry; bare invocation prints help

- Lead usage/wizard-outro/README with 'bun run sim <cmd>' (works with zero PATH setup); global bare 'sim' via bun link is an optional upgrade, with the ~/.bun/bin PATH caveat spelled out (Homebrew's bun omits it).
- Bare 'sim' now prints help instead of launching the wizard; the wizard is 'sim setup'. The 'setup' npm script passes the keyword so 'bun run setup' is unchanged.

Author: TheodoreSpeaks

README.md

@@ -91,19 +91,21 @@ bun run setup
 
 When it finishes, open [http://localhost:3000](http://localhost:3000).
 
-Manage your install with the `sim` CLI — run `bun link` once so `sim` works anywhere (or prefix `bun run`):
+Manage your install with `bun run sim`:
 
 ```bash
-sim start | stop | restart   # bring your install up / down / cycle
-sim status                    # what's installed and healthy
-sim logs                      # follow logs
-sim doctor                    # diagnose configuration problems
-sim down                      # remove containers (data kept)
-sim reset                     # archive .env and wipe managed data
+bun run sim start | stop | restart   # bring your install up / down / cycle
+bun run sim status                    # what's installed and healthy
+bun run sim logs                      # follow logs
+bun run sim doctor                    # diagnose configuration problems
+bun run sim down                      # remove containers (data kept)
+bun run sim reset                     # archive .env and wipe managed data
 ```
 
 `sim` detects how you're running (Docker Compose, local dev, or Kubernetes) and acts accordingly.
 
+Prefer a bare `sim`? Run `bun link` once — but note `sim` lands in `~/.bun/bin`, which Homebrew's bun doesn't add to your PATH, so you may need `export PATH="$HOME/.bun/bin:$PATH"` in your shell profile.
+
 Sim also supports local models via [Ollama](https://ollama.ai) and [vLLM](https://docs.vllm.ai/). See the [self-hosting docs](https://docs.sim.ai/self-hosting/docker) for details.
 
 ## Chat API Keys

package.json

@@ -59,7 +59,7 @@
     "mship:check": "bun run scripts/generate-mship-contracts.ts --check",
     "skills:sync": "bun run scripts/sync-skills.ts",
     "skills:check": "bun run scripts/sync-skills.ts --check",
-    "setup": "bun run scripts/setup/index.ts",
+    "setup": "bun run scripts/setup/index.ts setup",
     "sim": "bun run scripts/setup/index.ts",
     "doctor": "bun run scripts/setup/index.ts doctor",
     "agent-stream-docs:generate": "bun run scripts/sync-agent-stream-docs.ts",

scripts/setup/index.ts

@@ -8,17 +8,17 @@ import { theme } from './theme.ts'
 import { runWizard, type WizardMode } from './wizard.ts'
 
 const USAGE = `Usage:
-  sim                                    run the setup wizard
-  sim setup [--quick] [--mode compose|dev|k8s]
-  sim doctor [--fix] [--json]            check your setup
-  sim start | stop | restart             bring your install up / down / cycle
-  sim status                             what's installed and healthy
-  sim logs                               follow logs
-  sim down                               remove containers (data kept)
-  sim reset                              archive .env + wipe managed data
+  bun run setup                                run the setup wizard
+  bun run sim setup [--quick] [--mode compose|dev|k8s]
+  bun run sim doctor [--fix] [--json]          check your setup
+  bun run sim start | stop | restart           bring your install up / down / cycle
+  bun run sim status                           what's installed and healthy
+  bun run sim logs                             follow logs
+  bun run sim down                             remove containers (data kept)
+  bun run sim reset                            archive .env + wipe managed data
 
-Not linked yet? Prefix with "bun run" (e.g. bun run sim status), or run
-"bun link" once so "sim" works anywhere.`
+Prefer a bare "sim"? Run "bun link" once, then ensure ~/.bun/bin is on your
+PATH (Homebrew's bun doesn't add it): export PATH="$HOME/.bun/bin:$PATH".`
 
 function parseMode(value: string | undefined): WizardMode {
   if (value === 'compose' || value === 'dev' || value === 'k8s') return value
@@ -35,6 +35,12 @@ async function main(): Promise<void> {
 
   const command = args[0]
 
+  // Bare `sim` prints help; the wizard is `sim setup` (or `bun run setup`).
+  if (!command) {
+    console.log(USAGE)
+    return
+  }
+
   if (command === 'doctor') {
     process.exitCode = await runDoctor({
       fix: args.includes('--fix'),
@@ -43,26 +49,24 @@ async function main(): Promise<void> {
     return
   }
 
-  if (command && isLifecycleCommand(command)) {
+  if (isLifecycleCommand(command)) {
     await runLifecycle(command)
     return
   }
 
-  // Anything else that looks like a command (not a flag, not `setup`) is a typo.
-  if (command && !command.startsWith('-') && command !== 'setup') {
-    console.error(`Unknown command: ${command}\n`)
-    console.log(USAGE)
-    process.exitCode = 1
+  if (command === 'setup') {
+    const setupArgs = args.slice(1)
+    const modeIdx = setupArgs.indexOf('--mode')
+    await runWizard({
+      quick: setupArgs.includes('--quick'),
+      mode: modeIdx === -1 ? undefined : parseMode(setupArgs[modeIdx + 1]),
+    })
     return
   }
 
-  // Bare invocation and `setup` both run the wizard; strip the optional keyword.
-  const setupArgs = command === 'setup' ? args.slice(1) : args
-  const modeIdx = setupArgs.indexOf('--mode')
-  await runWizard({
-    quick: setupArgs.includes('--quick'),
-    mode: modeIdx === -1 ? undefined : parseMode(setupArgs[modeIdx + 1]),
-  })
+  console.error(`Unknown command: ${command}\n`)
+  console.log(USAGE)
+  process.exitCode = 1
 }
 
 function renderFailure(error: unknown): void {

scripts/setup/wizard.ts

@@ -162,10 +162,10 @@ export async function runWizard(flags: WizardFlags): Promise<void> {
   p.note(
     [
       mode === 'k8s' ? `port-forward, then open ${url}` : `open ${url}`,
-      'manage it:  sim start · sim stop · sim status · sim logs',
-      'check your setup:  sim doctor',
+      'manage it:  bun run sim start · stop · status · logs',
+      'check your setup:  bun run sim doctor',
       mode === 'dev' && !startDevNow ? `start Sim:  bun run ${devScript}` : null,
-      `run "sim" anywhere: ${theme.command('bun link')} once (otherwise ${theme.command('bun run sim <cmd>')})`,
+      `prefer a bare "sim"? ${theme.command('bun link')} once (needs ~/.bun/bin on PATH)`,
     ]
       .filter(Boolean)
       .join('\n'),