First-run setup wizard skipped on Windows when API key is already in env

[jonathanpopham]

Summary

On Windows, the first-time install setup wizard appears to be skipped (or rendered too fast to interact with) when the user already has a Supermodel API key in their environment. Reported by a customer: their terminal "blew through" the wizard and they never saw the prompts — including the prompt to exclude .graph.* sidecar files from VCS.

Reported behavior

Customer "Elm" did a fresh npm install -g @supermodeltools/cli on Windows. On first invocation, the expected setup wizard (which normally walks through API key entry, ignore-file setup, etc.) did not appear, or scrolled past so fast it was non-interactive. They had a Supermodel API key already set in their environment.

Expected behavior

Even when a valid API key is detected in env, the user should still be walked through (or at minimum shown) the remaining first-run setup steps — particularly the .graph.* ignore-file prompt, which is unrelated to auth.

Hypothesis

The wizard likely short-circuits the entire flow when SUPERMODEL_API_KEY (or equivalent) is already present, instead of skipping just the auth step and continuing with the remaining setup steps.

Repro (suspected)

1. On a fresh Windows machine, set SUPERMODEL_API_KEY in env before installing.
2. npm install -g @supermodeltools/cli
3. Run supermodel <something> for the first time.
4. Observe: setup wizard either doesn't appear or scrolls through non-interactively; .graph.* files are not added to .gitignore.

Needs confirmation on a clean Windows VM.

Suggested fix direction

• Decouple the auth step from the rest of the first-run wizard — env-detected key should skip auth-prompts only, not the whole flow.
• If the wizard is meant to be one-shot and silent when env is pre-configured, surface a one-line summary of what was auto-configured and what was skipped, with a supermodel setup command to re-run interactively.

[coderabbitai]

🔗 Related PRs

#48 - feat: interactive setup wizard with file mode onboarding [merged]
#49 - Add first-run detection and install-time setup wizard [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[jonathanpopham]

Trace results — corrected diagnosis

Traced the install/run path. The original hypothesis (wizard short-circuits when env key present) is wrong. The actual cause is more fundamental:

The setup wizard is never auto-invoked on first run. It's only available as an explicit supermodel setup command.

Code path

cmd/root.go:45-60 (PersistentPreRunE):

cfg, err := config.Load()
// ...
if cfg.APIKey == "" {
    fmt.Fprintln(os.Stderr, "Run 'supermodel setup' to get started.")
    os.Exit(1)
}
return nil

internal/config/config.go:112:

if key := os.Getenv("SUPERMODEL_API_KEY"); key != "" {
    c.APIKey = key
}

So when a user has SUPERMODEL_API_KEY already set in their environment:

1. config.Load() populates cfg.APIKey from env
2. The empty-key guard passes silently
3. RunE falls straight through to shards.Watch(...) — no wizard, no gitignore prompt, no hook prompt, no shard-mode prompt, no awareness any of those steps exist

What Elm actually saw

Not "wizard scrolled past too fast" — the wizard never ran at all. He went directly into watch mode on first invocation.

What the wizard does cover

Reviewed internal/setup/wizard.go — the wizard itself handles auth, repo detection, agent hook install, and shard mode toggle correctly. It does NOT have a separate .graph.* ignore prompt though — gitignore is added automatically inside the shard-mode flow (line 148-150). That's worth noting in case the customer expected a prompt that was never going to appear regardless.

Suggested fix direction (revised)

• Detect first-run-without-setup state and auto-prompt. E.g. check for a marker (config file existence, ~/.supermodel/.setup-complete, etc.) and run the wizard the first time supermodel is invoked, even when env key is present.
• OR print a one-liner on every run-without-config that says "run `supermodel setup` to enable agent hook + gitignore" — at least surfaces the option.
• Decide intentionally: should env-key-only users get a fully-silent install (current behavior, friendly to CI/automation) or a one-time interactive nudge (better for new humans like Elm)?

[drQedwards]

I would just be careful where the wizard isn’t constantly reintroducing the intro windows like what is happening over on the beta with the Remix IDE when introducing the windows for using MCP tools.

A one time interactive nudge is recommended over a silent install regardless, a window suggesting “start the setup wizard? Recommended for first time install.” With options Yes / Skip.

No need for the app or the server or anything to do so it is a great choice.