@@ -1,6 +1,6 @@
 [project]
 name = "solisdash"
-version = "0.5.0"
+version = "0.6.0"
 description = "Self-hosted dashboard for the SolisCloud (Ginlong Solis) platform"
 readme = "README.md"
 requires-python = ">=3.10"
 
@@ -1 +1 @@
-__version__ = "0.5.0"
+__version__ = "0.6.0"
@@ -15,6 +15,8 @@
 import asyncio
 import getpass
 import logging
+import os
+import secrets
 import socket
 import sys
 import threading
@@ -32,6 +34,8 @@
 log = logging.getLogger("solisdash.cli")
 
 REPO_URL = "https://github.com/jdrumgoole/solisdash"
+DEFAULT_MONGO_URI = "mongodb://localhost:27017/"
+DEFAULT_API_URL = "https://www.soliscloud.com:13333"
 
 
 def find_free_port(host: str = "127.0.0.1") -> int:
@@ -186,6 +190,12 @@ def cmd_run(args: argparse.Namespace) -> int:
         level=logging.DEBUG if args.debug else logging.INFO,
         format="%(asctime)s %(levelname)s %(name)s: %(message)s",
     )
+    try:
+        if interactive_setup() == "aborted":
+            return 2
+    except KeyboardInterrupt:
+        print("\nSetup cancelled.", file=sys.stderr)
+        return 130
     port = args.port or find_free_port(args.host)
     server = UvicornServerThread(
         host=args.host,
@@ -215,6 +225,162 @@ def cmd_run(args: argparse.Namespace) -> int:
     return 0
 
 
+# --- first-run interactive onboarding --------------------------------------
+
+
+def _is_tty() -> bool:
+    """True when both stdin and stdout are connected to a real terminal.
+
+    The onboarding prompts only fire when both ends are interactive — under
+    systemd / ssh-no-tty / CI we bail with a friendly message instead.
+    """
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def _prompt(
+    label: str,
+    *,
+    default: str = "",
+    secret: bool = False,
+    input_fn: Callable[[str], str] = input,
+    getpass_fn: Callable[[str], str] = getpass.getpass,
+) -> str:
+    """One labelled prompt with optional default and secret-input handling.
+
+    `input_fn` / `getpass_fn` are injected so tests can stub them.
+    """
+    prompt = f"  {label}"
+    if default and not secret:
+        prompt += f" [{default}]"
+    prompt += ": "
+    raw = getpass_fn(prompt) if secret else input_fn(prompt).strip()
+    return raw or default
+
+
+def _read_kv(path: Path) -> dict[str, str]:
+    """Parse a simple `.env`-style file. Empty / comment lines are skipped."""
+    if not path.exists():
+        return {}
+    out: dict[str, str] = {}
+    for line in path.read_text().splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, _, value = stripped.partition("=")
+        out[key.strip()] = value.strip()
+    return out
+
+
+def _write_kv(path: Path, updates: dict[str, str]) -> None:
+    """Merge `updates` into `path` and write atomically.
+
+    Existing comments / formatting are not preserved — this is the first-run
+    writer; if the user later hand-edits the file we leave it alone.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    merged = _read_kv(path)
+    merged.update({k: v for k, v in updates.items() if v})
+    body = "\n".join(f"{k}={v}" for k, v in merged.items())
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(body + "\n", encoding="utf-8")
+    tmp.replace(path)
+    # Stash the secret away from group / other readers.
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass  # best-effort; Windows / unusual filesystems
+
+
+def _apply_env(updates: dict[str, str]) -> None:
+    """Update `os.environ` and clear the lru_cached settings."""
+    from solisdash.config import get_settings
+
+    for k, v in updates.items():
+        if v:
+            os.environ[k] = v
+    get_settings.cache_clear()
+
+
+def interactive_setup(
+    *,
+    is_tty_fn: Callable[[], bool] = _is_tty,
+    input_fn: Callable[[str], str] = input,
+    getpass_fn: Callable[[str], str] = getpass.getpass,
+    out: Callable[[str], None] = print,
+) -> str:
+    """Walk the user through first-run config when SOLIS_MONGODB_URI is missing.
+
+    Returns one of:
+    - `"skip"`      — nothing was missing, or non-TTY (server can still
+                      come up; the web `/setup` wizard will handle it).
+    - `"configured"`— prompts ran, values written to user config.
+    - `"aborted"`   — non-TTY *and* missing Mongo. Caller should exit non-zero.
+    """
+    from solisdash.config import get_settings, user_config_path
+
+    settings = get_settings()
+    if settings.SOLIS_MONGODB_URI:
+        # Already configured — silently fill in a SESSION_SECRET if missing.
+        if not settings.SESSION_SECRET:
+            secret_only = {"SESSION_SECRET": secrets.token_urlsafe(32)}
+            _write_kv(user_config_path(), secret_only)
+            _apply_env(secret_only)
+            log.info(
+                "Generated SESSION_SECRET and saved to %s", user_config_path()
+            )
+        return "skip"
+
+    if not is_tty_fn():
+        out(
+            "Solisdash isn't configured yet and stdin isn't a terminal — "
+            "can't prompt interactively. Set SOLIS_MONGODB_URI (and "
+            "ideally SOLIS_KEY_ID / SOLIS_KEYSECRET / SESSION_SECRET) in "
+            f"{user_config_path()} or via environment variables."
+        )
+        return "aborted"
+
+    config_path = user_config_path()
+    out("")
+    out("Solisdash first-run setup.")
+    out("Press Enter to accept the default in brackets. Values get saved")
+    out(f"to {config_path}. Re-run `solisdash` to start with the saved config.")
+    out("")
+
+    updates: dict[str, str] = {}
+    updates["SOLIS_MONGODB_URI"] = _prompt(
+        "MongoDB connection URI",
+        default=DEFAULT_MONGO_URI,
+        input_fn=input_fn,
+        getpass_fn=getpass_fn,
+    )
+    updates["SOLIS_API_URL"] = _prompt(
+        "SolisCloud API URL",
+        default=DEFAULT_API_URL,
+        input_fn=input_fn,
+        getpass_fn=getpass_fn,
+    )
+    updates["SOLIS_KEY_ID"] = _prompt(
+        "SolisCloud Key ID (Account → Basic Settings → API Management, "
+        "blank to skip and configure later)",
+        input_fn=input_fn,
+        getpass_fn=getpass_fn,
+    )
+    if updates["SOLIS_KEY_ID"]:
+        updates["SOLIS_KEYSECRET"] = _prompt(
+            "SolisCloud Key Secret",
+            secret=True,
+            input_fn=input_fn,
+            getpass_fn=getpass_fn,
+        )
+    updates["SESSION_SECRET"] = settings.SESSION_SECRET or secrets.token_urlsafe(32)
+
+    _write_kv(config_path, updates)
+    _apply_env(updates)
+    out("")
+    out(f"Saved to {config_path}")
+    return "configured"
+
+
 # --- subcommand: add-user --------------------------------------------------
 
 
 
@@ -1,17 +1,44 @@
-"""Typed settings loaded from environment / .env."""
+"""Typed settings loaded from environment / .env files."""
 
 from __future__ import annotations
 
+import os
 from functools import lru_cache
+from pathlib import Path
 
 from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
+def user_config_dir() -> Path:
+    """Per-user config directory.
+
+    Honours `XDG_CONFIG_HOME` on every platform — macOS often doesn't, but
+    one consistent path beats the platform-specific tangle.
+    """
+    base = os.environ.get("XDG_CONFIG_HOME")
+    return Path(base) / "solisdash" if base else Path.home() / ".config" / "solisdash"
+
+
+def user_config_path() -> Path:
+    """`.env` the `solisdash` CLI writes first-run configuration into."""
+    return user_config_dir() / ".env"
+
+
 class Settings(BaseSettings):
-    """Process-wide configuration. Read from environment or `.env`."""
+    """Process-wide configuration. Read from environment or `.env`.
+
+    Two `.env` files are honoured, with the second overriding the first:
+
+    1. `~/.config/solisdash/.env` — the CLI writes first-run config here,
+       so installs from PyPI have a home for it.
+    2. `./.env` in the current directory — dev-checkout convention.
+    """
 
-    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+    model_config = SettingsConfigDict(
+        env_file=(str(user_config_path()), ".env"),
+        extra="ignore",
+    )
 
     # SolisCloud
     SOLIS_KEY_ID: str = ""
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-__version__ = "0.5.0"`
	`1`	`+__version__ = "0.6.0"`