@lofenta/cli 0.0.0-stage → 0.5.2

package/src/index.js

@@ -0,0 +1,2309 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs")
+const os = require("node:os")
+const path = require("node:path")
+const { spawnSync } = require("node:child_process")
+const readlineCore = require("node:readline")
+const readline = require("node:readline/promises")
+const { stdin, stdout, stderr, exit } = require("node:process")
+
+const PKG = (() => {
+  try { return require("../package.json") } catch { return {} }
+})()
+const VERSION = PKG.version || "0.0.0"
+
+const CONFIG_DIR = path.join(os.homedir(), ".config", "lofenta")
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json")
+const DEFAULT_BASE_URL = process.env.LOFENTA_BASE_URL || "https://lofenta.com"
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  blue: "\x1b[38;5;39m",
+  white: "\x1b[97m",
+  inverse: "\x1b[7m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+}
+const BRAND_MARK = [
+  "                      ==",
+  "                    ++++",
+  "                  ++++++",
+  "                ++++++++",
+  "               +++++++++",
+  "             +++++++++++",
+  "           ++++++++++++ ",
+  "         ++++++++++++   ",
+  "       ***+++++++++     ",
+  "     ********++++       ",
+  "    ***********       ++",
+  "  ************       +++",
+  "************       ***++",
+  "**********       *******",
+  "********       *********",
+  "******                  ",
+  "****       *************",
+  "#*       ************** ",
+  "       **************   ",
+  "     #*************     ",
+]
+function ensureConfigDir() {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true })
+}
+
+function loadConfig() {
+  try {
+    const config = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"))
+    // Recover from a stale local-dev base URL left in a config file: any
+    // localhost/loopback origin falls back to the public default.
+    if (typeof config.baseUrl === "string" &&
+        /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)(:\d+)?\/?$/i.test(config.baseUrl)) {
+      config.baseUrl = DEFAULT_BASE_URL
+    }
+    return config
+  } catch {
+    return {}
+  }
+}
+
+function saveConfig(config) {
+  ensureConfigDir()
+  fs.writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8")
+}
+
+function tokenize(input) {
+  return Array.from(input.matchAll(/"[^"]*"|'[^']*'|\S+/g), (match) => {
+    const token = match[0]
+    if ((token.startsWith("\"") && token.endsWith("\"")) || (token.startsWith("'") && token.endsWith("'"))) {
+      return token.slice(1, -1)
+    }
+    return token
+  })
+}
+
+function parseArgv(argv) {
+  const args = [...argv]
+  let command = null
+
+  if (!args.length) {
+    return { command, positionals: [], flags: {} }
+  }
+
+  const first = args[0]
+  if (first === "--deploy") {
+    command = "deploy"
+    args.shift()
+  } else if (first.startsWith("/")) {
+    command = first.slice(1)
+    args.shift()
+  } else if (!first.startsWith("-")) {
+    command = first
+    args.shift()
+  }
+
+  const flags = {}
+  const positionals = []
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i]
+
+    if (token.startsWith("--")) {
+      const normalized = token.slice(2)
+      const eq = normalized.indexOf("=")
+      if (eq !== -1) {
+        flags[normalized.slice(0, eq)] = normalized.slice(eq + 1)
+        continue
+      }
+
+      const next = args[i + 1]
+      if (next && !next.startsWith("-")) {
+        flags[normalized] = next
+        i += 1
+      } else {
+        flags[normalized] = true
+      }
+      continue
+    }
+
+    positionals.push(token)
+  }
+
+  return { command, positionals, flags }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function paint(text, color) {
+  return `${color}${text}${ANSI.reset}`
+}
+
+function clearScreen() {
+  stdout.write("\x1b[2J\x1b[H")
+}
+
+function renderBrand() {
+  return BRAND_MARK.map((line) => paint(line, ANSI.blue)).join("\n")
+}
+
+function buildBrandHeader(title, subtitle, config = loadConfig()) {
+  let out = `${renderBrand()}\n\n`
+  out += `${paint(title, `${ANSI.bold}${ANSI.white}`)}\n`
+  if (subtitle) out += `${paint(subtitle, ANSI.dim)}\n`
+  out += `${paint(`Base URL: ${config.baseUrl || DEFAULT_BASE_URL}   Auth: ${config.apiKey ? "configured" : "missing"}`, ANSI.dim)}\n\n`
+  return out
+}
+
+function printBrandHeader(title, subtitle, config = loadConfig()) {
+  clearScreen()
+  stdout.write(buildBrandHeader(title, subtitle, config))
+}
+
+async function askQuestion(prompt) {
+  const rl = readline.createInterface({ input: stdin, output: stdout })
+  const answer = await rl.question(prompt)
+  rl.close()
+  return answer.trim()
+}
+
+async function waitForEnter(message = "Press Enter to continue.") {
+  await askQuestion(`${message} `)
+}
+
+function inferBaseUrl(config, flags) {
+  return flags["base-url"] || config.baseUrl || DEFAULT_BASE_URL
+}
+
+function inferApiKey(config, flags) {
+  return flags["api-key"] || process.env.LOFENTA_API_KEY || config.apiKey || ""
+}
+
+function formatConnectionError(error, baseUrl) {
+  if (!error) return `Could not reach Lofenta at ${baseUrl}.`
+  const message = String(error.message || error)
+  if (message === "fetch failed") {
+    return `Could not reach Lofenta at ${baseUrl}. Change the base URL in Config or set LOFENTA_BASE_URL.`
+  }
+  return message
+}
+
+async function request(baseUrl, pathname, options = {}) {
+  const url = new URL(pathname, baseUrl)
+  const headers = { Accept: "application/json", ...(options.headers || {}) }
+
+  if (options.apiKey) {
+    headers.Authorization = `Bearer ${options.apiKey}`
+  }
+
+  if (options.body !== undefined) {
+    headers["Content-Type"] = "application/json"
+  }
+
+  const res = await fetch(url, {
+    method: options.method || "GET",
+    headers,
+    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+  })
+
+  const json = await res.json().catch(() => null)
+
+  if (!res.ok || !json?.ok) {
+    const message = json?.message || `Request failed with status ${res.status}`
+    const error = new Error(message)
+    error.status = res.status
+    throw error
+  }
+
+  return json.data
+}
+
+// Streaming SSE consumer for /api/cli/projects/:id/logs. Calls `onAppend(text)`,
+// `onReplace(text)`, `onStatus(status)`, `onEnd(reason)`. Resolves when the stream
+// closes naturally or the server sends `event: end`.
+async function streamSse(baseUrl, pathname, options = {}, handlers = {}) {
+  const url = new URL(pathname, baseUrl)
+  const headers = { Accept: "text/event-stream" }
+  if (options.apiKey) headers.Authorization = `Bearer ${options.apiKey}`
+  const res = await fetch(url, { method: "GET", headers })
+  if (!res.ok) {
+    const text = await res.text().catch(() => "")
+    throw new Error(`stream failed (${res.status}): ${text.slice(0, 120)}`)
+  }
+  const reader = res.body?.getReader()
+  if (!reader) throw new Error("stream had no body")
+  const decoder = new TextDecoder()
+  let buf = ""
+  while (true) {
+    const { value, done } = await reader.read()
+    if (done) break
+    buf += decoder.decode(value, { stream: true })
+    // SSE frames are separated by blank lines
+    let idx
+    while ((idx = buf.indexOf("\n\n")) !== -1) {
+      const frame = buf.slice(0, idx)
+      buf = buf.slice(idx + 2)
+      let event = "message"
+      const dataLines = []
+      for (const line of frame.split("\n")) {
+        if (line.startsWith(":")) continue
+        if (line.startsWith("event: ")) event = line.slice(7).trim()
+        else if (line.startsWith("data: ")) dataLines.push(line.slice(6))
+      }
+      const data = dataLines.join("\n")
+      if (event === "append") handlers.onAppend?.(data)
+      else if (event === "replace") handlers.onReplace?.(data)
+      else if (event === "status") handlers.onStatus?.(data)
+      else if (event === "end") { handlers.onEnd?.(data); return }
+      else if (event === "error") handlers.onError?.(data)
+      // Generic catch-all so callers can opt into custom event names (e.g. "line" from tail).
+      handlers.onEvent?.(event, data)
+    }
+  }
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"))
+  } catch {
+    return null
+  }
+}
+
+function hasFile(cwd, file) {
+  return fs.existsSync(path.join(cwd, file))
+}
+
+function detectFramework(cwd) {
+  const packageJson = readJson(path.join(cwd, "package.json"))
+  const composerJson = readJson(path.join(cwd, "composer.json"))
+  const deps = new Set([
+    ...Object.keys(packageJson?.dependencies || {}),
+    ...Object.keys(packageJson?.devDependencies || {}),
+  ])
+
+  if (deps.has("next")) return "nextjs"
+  if (deps.has("strapi")) return "strapi"
+  if (deps.has("@directus/sdk") || deps.has("directus")) return "directus"
+  if (deps.has("n8n")) return "n8n"
+  if (deps.has("ghost")) return "ghost"
+  if (hasFile(cwd, "Dockerfile")) return "docker"
+
+  const composerText = composerJson ? JSON.stringify(composerJson).toLowerCase() : ""
+  if (composerText.includes("laravel/framework")) return "laravel"
+  if (composerText.includes("wordpress")) return "wordpress"
+  if (composerJson) return "php"
+
+  if (hasFile(cwd, "pyproject.toml") || hasFile(cwd, "requirements.txt")) return "python"
+  if (packageJson) return "nodejs"
+  if (hasFile(cwd, "index.html")) return "static"
+  return "auto"
+}
+
+function runGit(cwd, args) {
+  const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" })
+  if (result.status !== 0) return ""
+  return result.stdout.trim()
+}
+
+function normalizeRepo(remote) {
+  if (!remote) return null
+
+  const trimmed = remote.trim()
+  const githubHttps = trimmed.match(/^https?:\/\/github\.com\/(.+?)(?:\.git)?$/i)
+  if (githubHttps) return githubHttps[1]
+
+  const githubSsh = trimmed.match(/^git@github\.com:(.+?)(?:\.git)?$/i)
+  if (githubSsh) return githubSsh[1]
+
+  return trimmed
+}
+
+function detectProject(cwd) {
+  const framework = detectFramework(cwd)
+  const repo = normalizeRepo(runGit(cwd, ["remote", "get-url", "origin"]))
+  const branch = runGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]) || "main"
+  const name = path.basename(cwd)
+
+  return { cwd, name, framework, repo, branch }
+}
+
+function printHelp() {
+  stdout.write(`
+Lofenta CLI v${VERSION}
+
+Interactive:
+  lofenta                                       Open the interactive menu
+  /login  /deploy  /whoami  /logout  /config    Slash commands inside the menu
+  /exit                                         Leave the menu
+
+Auth:
+  lofenta login [--api-key <key>] [--base-url <url>] [--link] [--code]
+  lofenta whoami [--base-url <url>] [--api-key <key>]
+  lofenta logout
+  lofenta doctor [--path <dir>] [--json]
+  lofenta config                                Print CLI config path + values
+
+Projects:
+  lofenta projects                              List your projects with last deploy status
+  lofenta project <id|name>                     Show one project + recent deployments + domains
+  lofenta status [project]                      One-line status (uses linked project if omitted)
+  lofenta link [id|name]                        Link the current directory to a project (.lofenta file)
+  lofenta unlink                                Remove the .lofenta link
+  lofenta open [project] [--url]                Open the dashboard in a browser (--url opens the live URL)
+  lofenta templates                             List available project templates
+  lofenta orgs                                  List teams you belong to
+  lofenta delete <project> [--yes]              Permanently delete a project (typed confirmation)
+
+Deploys:
+  lofenta init                                  Interactive wizard: pick template (paginated), name, deploy
+  lofenta deploy [template] [--name <n>] [--framework <f>] [--repo o/r] [--branch <b>] [--domain <d>] [--path <dir>] [--json]
+  lofenta redeploy [project]                    Trigger a fresh deploy from the last known commit
+  lofenta restart [project]                     Restart the running container (no rebuild)
+  lofenta rollback [project] [--deployment <id>]  Roll back to the previous live deployment
+  lofenta deployments [project] [--limit <N>]   List recent deployments
+  lofenta logs [project] [--deployment <id>]    Live tail deployment log (SSE)
+  lofenta tail [project] [--lines N]            Live container stdout/stderr (SSE)
+  lofenta exec [project] -- <cmd>               Run a one-shot command inside the running container
+  lofenta run [project] -- <cmd>                Run a LOCAL command with the project env injected
+  lofenta stop [project]                        Stop the running container (start it again later)
+  lofenta start [project]                       Start a previously stopped container
+  lofenta watch [project] [--interval 2]        Refresh project status every N seconds
+
+Env & secrets:
+  lofenta env ls <project> [--show]             List env vars (values masked by default)
+  lofenta env set <project> KEY=VAL [...]       Add or overwrite env vars
+  lofenta env rm <project> KEY [...]            Remove env vars
+  lofenta env pull <project> [.env]             Dump env vars to a local file
+  lofenta env import <project> [path/to/.env]   Bulk import a .env file (skips comments)
+  lofenta secrets <ls|set|rm|pull|import> ...   Alias for env
+
+Domains:
+  lofenta domains ls <project>                  List custom domains + DNS records needed
+  lofenta domains add <project> <domain>        Attach a new custom domain
+  lofenta domains rm <project> <domain>         Detach a custom domain
+
+Data & infra:
+  lofenta snapshots ls <project>                List database snapshots (Postgres/MariaDB only)
+  lofenta snapshots create <project> [label]    Take a new snapshot
+  lofenta snapshots restore <project> <id>      Restore from a snapshot
+  lofenta services <project>                    List linked internal services
+  lofenta volumes <project>                     List named Docker volumes
+  lofenta db connect [project]                  Interactive database shell (one statement per line)
+  lofenta db query <project> "<statement>"      Run one statement and print the result
+
+Account:
+  lofenta plan                                  Current plan summary
+  lofenta usage                                 Plan limits, what you've used, what's left
+  lofenta billing                               Open the billing page in a browser
+  lofenta completion <bash|zsh|fish>            Shell tab-completion script (source it from your rc)
+
+Deploy parameters:
+  --name        Project name in Lofenta. Defaults to the current directory name.
+  --framework   Force a detected stack such as nextjs, laravel, nodejs, python, docker, static.
+  --template    Alias for --framework.
+  --repo        Override the detected Git remote. GitHub remotes are normalized to owner/repo.
+  --branch      Override the detected branch.
+  --domain      Attach or update the project domain.
+  --org         Deploy into a team (slug or id) instead of your personal account.
+  --path        Deploy from a different directory.
+  --base-url    Lofenta app URL. Defaults to LOFENTA_BASE_URL or ${DEFAULT_BASE_URL}
+  --api-key     Use an API key without storing it.
+  --json        Print machine-readable output.
+
+Login modes:
+  lofenta login
+    Starts the browser/device login flow and shows both a URL and a short code.
+
+  lofenta login --code
+    Same flow, optimized for a second screen or another browser.
+
+  lofenta login --link
+    Same flow, but you can just open the generated approval link directly.
+
+  lofenta login --api-key <key>
+    Stores a long-lived API key for unattended scripts and VPS usage.
+`)
+}
+
+function printJson(value) {
+  stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+}
+
+async function ensureBaseUrl(config, flags, interactive) {
+  const explicit = inferBaseUrl(config, flags)
+  if (explicit) return explicit
+  if (!interactive) throw new Error("No base URL configured. Pass --base-url or set LOFENTA_BASE_URL.")
+  const input = await askQuestion("Lofenta base URL: ")
+  if (!input) throw new Error("Base URL is required.")
+  return input
+}
+
+async function handleApiKeyLogin(config, flags, interactive) {
+  let apiKey = flags["api-key"]
+
+  if (!apiKey && interactive) {
+    apiKey = await askQuestion("API key: ")
+  }
+
+  if (!apiKey) {
+    throw new Error("Missing API key. Pass --api-key or generate one in Dashboard > Settings > CLI access.")
+  }
+
+  const baseUrl = await ensureBaseUrl(config, flags, interactive)
+  let data
+  try {
+    data = await request(baseUrl, "/api/cli/me", { apiKey })
+  } catch (error) {
+    throw new Error(formatConnectionError(error, baseUrl))
+  }
+
+  saveConfig({ ...config, baseUrl, apiKey })
+
+  stdout.write(`Saved API key for ${data.user.email}\n`)
+}
+
+async function handleDeviceLogin(config, flags, interactive, displayMode = "link") {
+  const baseUrl = await ensureBaseUrl(config, flags, interactive)
+  let flow
+
+  try {
+    flow = await request(baseUrl, "/api/cli/device/start", { method: "POST", body: {} })
+  } catch (error) {
+    throw new Error(formatConnectionError(error, baseUrl))
+  }
+
+  printBrandHeader("Login", "Authorize this CLI session in your browser.", config)
+  stdout.write(`${paint("Authorize Lofenta CLI", `${ANSI.bold}${ANSI.white}`)}\n`)
+  stdout.write(`${paint("Open the browser page below and confirm the request for this exact device code.", ANSI.dim)}\n\n`)
+
+  if (displayMode === "code") {
+    stdout.write(`Open ${flow.verificationUri}\n`)
+    stdout.write(`Code: ${paint(flow.userCode, `${ANSI.bold}${ANSI.blue}`)}\n\n`)
+    stdout.write(`Direct link: ${flow.verificationUriComplete}\n\n`)
+  } else {
+    stdout.write(`Open this link:\n${flow.verificationUriComplete}\n\n`)
+    stdout.write(`Or open ${flow.verificationUri} and enter code ${paint(flow.userCode, `${ANSI.bold}${ANSI.blue}`)}\n\n`)
+  }
+
+  stdout.write("Waiting for authorization")
+
+  while (true) {
+    await sleep((flow.interval || 2) * 1000)
+
+    try {
+      const result = await request(baseUrl, "/api/cli/device/poll", {
+        method: "POST",
+        body: { deviceCode: flow.deviceCode },
+      })
+
+      if (result.status === "approved" && result.apiKey) {
+        stdout.write("\n")
+        saveConfig({ ...config, baseUrl, apiKey: result.apiKey })
+        stdout.write(`Authorized as ${result.user.email}\n`)
+        return
+      }
+
+      stdout.write(".")
+    } catch (error) {
+      stdout.write("\n")
+      throw error
+    }
+  }
+}
+
+async function handleWhoAmI(config, flags) {
+  const baseUrl = inferBaseUrl(config, flags)
+  const apiKey = inferApiKey(config, flags)
+
+  if (!apiKey) {
+    throw new Error("Not logged in. Run lofenta login or pass --api-key.")
+  }
+
+  let data
+  try {
+    data = await request(baseUrl, "/api/cli/me", { apiKey })
+  } catch (error) {
+    throw new Error(formatConnectionError(error, baseUrl))
+  }
+  stdout.write(`${data.user.email}\n`)
+}
+
+async function handleLogout(config) {
+  saveConfig({ ...config, apiKey: "" })
+  stdout.write("Logged out of Lofenta CLI\n")
+}
+
+async function handleDoctor(config, flags) {
+  const cwd = path.resolve(flags.path || process.cwd())
+  const detected = detectProject(cwd)
+  const payload = {
+    configPath: CONFIG_PATH,
+    baseUrl: inferBaseUrl(config, flags),
+    hasApiKey: Boolean(inferApiKey(config, flags)),
+    detected,
+  }
+
+  if (flags.json) {
+    printJson(payload)
+    return
+  }
+
+  stdout.write(`Config: ${payload.configPath}\n`)
+  stdout.write(`Base URL: ${payload.baseUrl}\n`)
+  stdout.write(`API key: ${payload.hasApiKey ? "configured" : "missing"}\n`)
+  stdout.write(`Directory: ${detected.cwd}\n`)
+  stdout.write(`Name: ${detected.name}\n`)
+  stdout.write(`Framework: ${detected.framework}\n`)
+  stdout.write(`Repo: ${detected.repo || "not detected"}\n`)
+  stdout.write(`Branch: ${detected.branch}\n`)
+}
+
+async function requireAuthed(config, flags) {
+  const baseUrl = inferBaseUrl(config, flags)
+  const apiKey = inferApiKey(config, flags)
+  if (!apiKey) throw new Error("Not logged in. Run `lofenta login` first or pass --api-key.")
+  return { baseUrl, apiKey }
+}
+
+function formatRel(iso) {
+  if (!iso) return "?"
+  const diff = Date.now() - new Date(iso).getTime()
+  const sec = Math.max(0, Math.floor(diff / 1000))
+  if (sec < 60) return `${sec}s ago`
+  if (sec < 3600) return `${Math.floor(sec / 60)}m ago`
+  if (sec < 86400) return `${Math.floor(sec / 3600)}h ago`
+  return `${Math.floor(sec / 86400)}d ago`
+}
+
+async function handleProjectsList(config, flags) {
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const orgFilter = flags.org ? `?org=${encodeURIComponent(String(flags.org))}` : ""
+  const data = await request(baseUrl, `/api/cli/projects${orgFilter}`, { apiKey })
+  if (flags.json) {
+    printJson(data)
+    return
+  }
+  if (data.length === 0) {
+    stdout.write("No projects yet. Run `lofenta deploy` in a project directory to create one.\n")
+    return
+  }
+  const hasOrg = data.some((p) => p.org)
+  const head = hasOrg
+    ? ["NAME", "TEAM", "STATUS", "LAST DEPLOY", "BRANCH", "UPDATED"]
+    : ["NAME", "STATUS", "LAST DEPLOY", "BRANCH", "UPDATED"]
+  const rows = data.map((p) => {
+    const base = [
+      p.status,
+      p.lastDeploy ? `${p.lastDeploy.status}` : "(none)",
+      p.gitBranch || "?",
+      formatRel(p.updatedAt),
+    ]
+    return hasOrg ? [p.name, p.org ? p.org.slug : "-", ...base] : [p.name, ...base]
+  })
+  printTable(head, rows)
+}
+
+async function handleOrgs(config, flags) {
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, "/api/cli/orgs", { apiKey })
+  if (flags.json) { printJson(data); return }
+  if (!data.length) { stdout.write("You are not a member of any team.\n"); return }
+  printTable(
+    ["SLUG", "NAME", "ROLE", "PROJECTS"],
+    data.map((o) => [o.slug, o.name, o.role, String(o.projects)]),
+  )
+}
+
+async function handleProjectInfo(config, flags, positionals) {
+  const idOrName = positionals[0]
+  if (!idOrName) throw new Error("Usage: lofenta project <id|name>")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(idOrName)}`, { apiKey })
+  if (flags.json) {
+    printJson(data)
+    return
+  }
+  stdout.write(`${paint(data.name, `${ANSI.bold}${ANSI.white}`)}  ${paint(data.id, ANSI.dim)}\n`)
+  stdout.write(`Status: ${data.status}\n`)
+  if (data.subdomain) stdout.write(`Subdomain: ${data.subdomain}.lofenta.com\n`)
+  if (data.previewUrl) stdout.write(`URL: ${data.previewUrl}\n`)
+  stdout.write(`Repo: ${data.gitRepo || "(local upload / template)"}\n`)
+  stdout.write(`Branch: ${data.gitBranch || "?"}\n`)
+  if (data.domains.length > 0) {
+    stdout.write(`\nDomains:\n`)
+    for (const d of data.domains) {
+      stdout.write(`  ${d.domain}  ssl=${d.sslStatus}  verified=${d.verified}\n`)
+    }
+  }
+  if (data.deployments.length > 0) {
+    stdout.write(`\nRecent deployments:\n`)
+    for (const d of data.deployments) {
+      stdout.write(`  ${d.status.padEnd(11)} ${formatRel(d.createdAt).padEnd(10)} ${d.commitMessage || ""}\n`)
+    }
+  }
+}
+
+async function handleEnv(config, flags, positionals) {
+  const sub = (positionals[0] || "ls").toLowerCase()
+  if (sub === "import" || sub === "load") {
+    return handleEnvImport(config, flags, positionals.slice(1))
+  }
+  const projectArg = positionals[1]
+  if (!projectArg) throw new Error("Usage: lofenta env <ls|set|rm|pull|import> <project> [args]")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const projectPath = `/api/cli/projects/${encodeURIComponent(projectArg)}/env`
+
+  if (sub === "ls" || sub === "list") {
+    const data = await request(baseUrl, projectPath, { apiKey })
+    if (flags.json) { printJson(data); return }
+    if (data.length === 0) { stdout.write("No env vars set.\n"); return }
+    const show = flags.show
+    for (const v of data) {
+      const value = show ? v.value : "********"
+      stdout.write(`${v.key}=${value}\n`)
+    }
+    if (!show) stdout.write(paint("\n(values masked; pass --show to reveal)\n", ANSI.dim))
+    return
+  }
+
+  if (sub === "set") {
+    const pairs = positionals.slice(2)
+    if (pairs.length === 0) throw new Error("Usage: lofenta env set <project> KEY=VAL [KEY2=VAL2 ...]")
+    const set = []
+    for (const p of pairs) {
+      const eq = p.indexOf("=")
+      if (eq < 1) throw new Error(`expected KEY=VAL, got "${p}"`)
+      set.push({ key: p.slice(0, eq), value: p.slice(eq + 1) })
+    }
+    const data = await request(baseUrl, projectPath, { method: "PATCH", apiKey, body: { set } })
+    stdout.write(`Set ${data.added + data.updated} keys (added ${data.added}, updated ${data.updated}). Total now: ${data.total}\n`)
+    return
+  }
+
+  if (sub === "rm" || sub === "del" || sub === "delete") {
+    const keys = positionals.slice(2)
+    if (keys.length === 0) throw new Error("Usage: lofenta env rm <project> KEY [KEY2 ...]")
+    const data = await request(baseUrl, projectPath, { method: "PATCH", apiKey, body: { remove: keys } })
+    stdout.write(`Removed ${data.removed} keys. Total now: ${data.total}\n`)
+    return
+  }
+
+  if (sub === "pull") {
+    const dest = positionals[2] || ".env"
+    const data = await request(baseUrl, projectPath, { apiKey })
+    const lines = data.map((v) => `${v.key}=${v.value}`)
+    fs.writeFileSync(dest, lines.join("\n") + "\n", "utf8")
+    stdout.write(`Wrote ${data.length} keys to ${dest}\n`)
+    return
+  }
+
+  throw new Error(`Unknown env subcommand: ${sub}`)
+}
+
+async function handleDomains(config, flags, positionals) {
+  const sub = (positionals[0] || "ls").toLowerCase()
+  if (sub === "rm" || sub === "remove" || sub === "delete") {
+    return handleDomainRm(config, flags, positionals.slice(1))
+  }
+  const projectArg = positionals[1]
+  if (!projectArg) throw new Error("Usage: lofenta domains <ls|add|rm> <project> [domain]")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const projectPath = `/api/cli/projects/${encodeURIComponent(projectArg)}/domains`
+
+  if (sub === "ls" || sub === "list") {
+    const data = await request(baseUrl, projectPath, { apiKey })
+    if (flags.json) { printJson(data); return }
+    if (data.length === 0) { stdout.write("No custom domains.\n"); return }
+    for (const d of data) {
+      stdout.write(`${d.domain}  ssl=${d.sslStatus}  verified=${d.verified}\n`)
+      if (d.cfOwnershipName && !d.verified) {
+        stdout.write(`  TXT ${d.cfOwnershipName} -> ${d.cfOwnershipValue}\n`)
+      }
+      if (d.cfCnameTarget && !d.verified) {
+        stdout.write(`  CNAME -> ${d.cfCnameTarget}\n`)
+      }
+    }
+    return
+  }
+
+  if (sub === "add") {
+    const domain = positionals[2]
+    if (!domain) throw new Error("Usage: lofenta domains add <project> <domain>")
+    const data = await request(baseUrl, projectPath, { method: "POST", apiKey, body: { domain } })
+    if (data.alreadyAttached) {
+      stdout.write(`Domain ${data.domain} was already attached.\n`)
+    } else {
+      stdout.write(`Added ${data.domain}. Check \`lofenta domains ls ${projectArg}\` for the DNS values to set.\n`)
+    }
+    return
+  }
+
+  throw new Error(`Unknown domains subcommand: ${sub}`)
+}
+
+async function handleLogs(config, flags, positionals) {
+  const projectArg = positionals[0]
+  if (!projectArg) throw new Error("Usage: lofenta logs <project> [--deployment <id>]")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  let path = `/api/cli/projects/${encodeURIComponent(projectArg)}/logs`
+  if (flags.deployment) path += `?deploymentId=${encodeURIComponent(flags.deployment)}`
+  stdout.write(paint(`Streaming logs from ${baseUrl}${path}\n\n`, ANSI.dim))
+  await streamSse(baseUrl, path, { apiKey }, {
+    onAppend: (txt) => stdout.write(txt),
+    onReplace: (txt) => { clearScreen(); stdout.write(txt) },
+    onStatus: (s) => stdout.write(paint(`\n[status: ${s}]\n`, ANSI.dim)),
+    onEnd: (reason) => stdout.write(paint(`\n[stream ended: ${reason}]\n`, ANSI.dim)),
+    onError: (msg) => stderr.write(paint(`\n[error: ${msg}]\n`, ANSI.dim)),
+  })
+}
+
+function printTable(head, rows) {
+  const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i] ?? "").length)))
+  const fmt = (cells) => cells.map((c, i) => String(c ?? "").padEnd(widths[i])).join("  ")
+  stdout.write(paint(fmt(head), `${ANSI.bold}${ANSI.white}`) + "\n")
+  for (const r of rows) stdout.write(fmt(r) + "\n")
+}
+
+function renderUsageBar(used, limit, width = 22) {
+  // ASCII bar, colored by pressure: green < 70%, yellow 70-89%, red 90%+.
+  if (limit === null || limit === undefined || limit <= 0) return paint("(unlimited)", ANSI.dim)
+  const ratio = Math.min(1, used / limit)
+  const pct = Math.round(ratio * 100)
+  const filled = Math.round(ratio * width)
+  const color = pct >= 90 ? ANSI.red : pct >= 70 ? ANSI.yellow : ANSI.green
+  const bar = `${color}${"#".repeat(filled)}${ANSI.reset}${ANSI.dim}${"-".repeat(width - filled)}${ANSI.reset}`
+  return `[${bar}] ${String(pct).padStart(3)}%`
+}
+
+// ---------- v0.4: exec / tail / env import / domains rm / usage / watch / snapshots / services / volumes / completion / init ----------
+
+const FETCH_DEFAULT_TIMEOUT_MS = 60_000
+
+async function rawRequest(baseUrl, pathname, options = {}) {
+  // Variant of request() that returns the full body (not json.data). Some new endpoints
+  // surface metadata alongside data; this lets the handler decide what to print.
+  const url = new URL(pathname, baseUrl)
+  const headers = { Accept: "application/json", ...(options.headers || {}) }
+  if (options.apiKey) headers.Authorization = `Bearer ${options.apiKey}`
+  if (options.body !== undefined) headers["Content-Type"] = "application/json"
+  const res = await fetch(url, {
+    method: options.method || "GET",
+    headers,
+    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+  })
+  const json = await res.json().catch(() => null)
+  if (!res.ok || !json?.ok) {
+    const message = json?.message || `Request failed with status ${res.status}`
+    const error = new Error(message)
+    error.status = res.status
+    throw error
+  }
+  return json
+}
+
+function parseDotEnv(content) {
+  // Minimal .env parser: strips quotes, skips blank/# comment lines, supports inline #
+  // comments only when preceded by whitespace (KEY=foo # comment), and handles
+  // `export FOO=bar` for compatibility with shell-style files.
+  const out = []
+  for (const raw of String(content).split(/\r?\n/)) {
+    let line = raw.trim()
+    if (!line || line.startsWith("#")) continue
+    if (line.startsWith("export ")) line = line.slice(7)
+    const eq = line.indexOf("=")
+    if (eq === -1) continue
+    const key = line.slice(0, eq).trim()
+    let value = line.slice(eq + 1).trim()
+    if (!key) continue
+    if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1)
+    } else {
+      const hashIdx = value.search(/\s#/)
+      if (hashIdx >= 0) value = value.slice(0, hashIdx).trim()
+    }
+    out.push({ key, value })
+  }
+  return out
+}
+
+async function handleExec(config, flags, positionals, passthrough = []) {
+  // Positionals: [project] cmd...  (project optional if linked)
+  // Or: -- cmd...  with project from --project or .lofenta link
+  let projectArg, commandTokens
+  const linked = readLinkedProject()
+  if (passthrough.length > 0) {
+    // `lofenta exec [project] -- cmd...`: the -- tail is the exact command.
+    projectArg = positionals[0] || linked
+    commandTokens = passthrough
+  } else if (linked && positionals.length > 0) {
+    projectArg = positionals[0]
+    // If positionals[0] doesn't look like a project name (contains slash, equals etc),
+    // assume it's the start of the command and use the linked project.
+    const looksLikeCommand = /[\s\/=]/.test(projectArg) || /^-/.test(projectArg)
+    if (looksLikeCommand) {
+      commandTokens = positionals
+      projectArg = linked
+    } else {
+      commandTokens = positionals.slice(1)
+    }
+  } else if (linked && positionals.length === 0) {
+    projectArg = linked
+    commandTokens = []
+  } else {
+    projectArg = positionals[0]
+    commandTokens = positionals.slice(1)
+  }
+  if (!projectArg) throw new Error("Usage: lofenta exec <project> -- <cmd>  (or omit project in a linked directory)")
+  const command = commandTokens.join(" ").trim()
+  if (!command) throw new Error("Provide a command after --. Example: lofenta exec my-app -- ls /app")
+
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const result = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/exec`, {
+    method: "POST",
+    apiKey,
+    body: { command, ...(flags.user ? { user: String(flags.user) } : {}) },
+  })
+  if (result.stdout) stdout.write(result.stdout)
+  if (result.stderr) stderr.write(result.stderr)
+  if (result.truncated) stderr.write(paint("\n[output truncated at 256 KiB]\n", ANSI.dim))
+  if (typeof result.exitCode === "number" && result.exitCode !== 0) {
+    stderr.write(paint(`\n[exit ${result.exitCode}]\n`, ANSI.dim))
+    process.exitCode = result.exitCode
+  }
+}
+
+async function handleRun(config, flags, positionals, passthrough = []) {
+  // lofenta run [project] -- <cmd...>: run a LOCAL command with the project's env
+  // vars injected. Project env wins over the local shell env on key conflicts.
+  const projectArg = positionals[0] || flags.project || readLinkedProject()
+  if (!projectArg) throw new Error("Usage: lofenta run [project] -- <cmd>  (or link a project first)")
+  if (passthrough.length === 0) throw new Error("Provide a command after --. Example: lofenta run -- npm run dev")
+
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const vars = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/env`, { apiKey })
+  const injected = {}
+  for (const v of vars) injected[v.key] = v.value
+  stdout.write(paint(`Running with ${vars.length} env vars from ${projectArg}\n`, ANSI.dim))
+
+  const { spawn } = require("node:child_process")
+  const child = spawn(passthrough[0], passthrough.slice(1), {
+    stdio: "inherit",
+    env: { ...process.env, ...injected },
+  })
+  child.on("error", (err) => {
+    stderr.write(`${err.message || String(err)}\n`)
+    process.exit(1)
+  })
+  child.on("exit", (code, signal) => {
+    process.exit(signal ? 1 : (code ?? 0))
+  })
+  // Keep the CLI alive until the child exits (process.exit above ends it).
+  await new Promise(() => {})
+}
+
+async function handleDb(config, flags, positionals) {
+  // db query [project] <statement...> | db connect [project]
+  const sub = (positionals[0] || "connect").toLowerCase()
+  const rest = positionals.slice(1)
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+
+  const runStatement = (projectArg, statement) =>
+    request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/db`, {
+      method: "POST",
+      apiKey,
+      body: { statement },
+    })
+
+  if (sub === "query" || sub === "q") {
+    // Project = first arg if more follow, else linked; statement = the rest joined.
+    let projectArg, statement
+    if (rest.length >= 2) { projectArg = rest[0]; statement = rest.slice(1).join(" ") }
+    else { projectArg = readLinkedProject(); statement = rest.join(" ") }
+    if (!projectArg || !statement.trim()) throw new Error('Usage: lofenta db query <project> "<statement>"')
+    const data = await runStatement(projectArg, statement)
+    if (flags.json) { printJson(data); return }
+    if (data.stdout) stdout.write(data.stdout)
+    if (data.stderr) stderr.write(data.stderr)
+    if (data.truncated) stderr.write(paint("\n[output truncated at 256 KiB]\n", ANSI.dim))
+    if (typeof data.exitCode === "number" && data.exitCode !== 0) process.exitCode = data.exitCode
+    return
+  }
+
+  if (sub === "connect" || sub === "shell") {
+    const projectArg = rest[0] || readLinkedProject()
+    if (!projectArg) throw new Error("Usage: lofenta db connect <project>")
+    // Probe to resolve the engine and fail fast on missing DB / access problems.
+    // Redis and Mongo reject the SQL but still return ok payloads with the engine.
+    let engine = "db"
+    try {
+      const probe = await runStatement(projectArg, "select 1")
+      engine = probe.engine || "db"
+    } catch (err) {
+      throw new Error(err.message || String(err))
+    }
+    stdout.write(paint(`Connected to ${projectArg} (${engine}). One statement per line. \\q or Ctrl+D to quit.\n`, ANSI.dim))
+    const rl = readline.createInterface({ input: stdin, output: stdout })
+    try {
+      while (true) {
+        let line
+        try { line = await rl.question(`${engine}> `) } catch { break }
+        line = line.trim()
+        if (!line) continue
+        if (line === "\\q" || line === "exit" || line === "quit") break
+        try {
+          const data = await runStatement(projectArg, line)
+          if (data.stdout) stdout.write(data.stdout)
+          if (data.stderr) stderr.write(data.stderr)
+          if (data.truncated) stderr.write(paint("[output truncated at 256 KiB]\n", ANSI.dim))
+        } catch (err) {
+          stderr.write(`${err.message || String(err)}\n`)
+        }
+      }
+    } finally {
+      rl.close()
+    }
+    return
+  }
+
+  throw new Error(`Unknown db subcommand: ${sub}. Use connect or query.`)
+}
+
+async function handleStopStart(config, flags, positionals, action) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error(`Usage: lofenta ${action} <project>`)
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/${action}`, {
+    method: "POST",
+    apiKey,
+    body: {},
+  })
+  stdout.write(`${paint(data.name, `${ANSI.bold}${ANSI.white}`)} is now ${data.status}.\n`)
+}
+
+async function handleDelete(config, flags, positionals) {
+  const projectArg = positionals[0]
+  if (!projectArg) throw new Error("Usage: lofenta delete <project> [--yes]")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const project = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}`, { apiKey })
+
+  stdout.write(`${paint("This permanently deletes:", `${ANSI.bold}${ANSI.white}`)} ${project.name} (${project.id})\n`)
+  stdout.write("Containers, volumes, domains, env vars, deploy history. No undo.\n")
+  if (!flags.yes) {
+    const answer = await askQuestion(`Type the project name (${project.name}) to confirm: `)
+    if (answer !== project.name) throw new Error("Name did not match. Nothing was deleted.")
+  }
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(project.id)}`, {
+    method: "DELETE",
+    apiKey,
+  })
+  stdout.write(`Deleted ${paint(data.name, `${ANSI.bold}${ANSI.white}`)}.\n`)
+}
+
+async function handleTail(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta tail <project> [--lines N]")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const lines = flags.lines ? Number(flags.lines) : 200
+  const path = `/api/cli/projects/${encodeURIComponent(projectArg)}/tail?lines=${encodeURIComponent(String(lines))}`
+  stdout.write(paint(`Tailing container for ${projectArg}. Ctrl+C to stop.\n\n`, ANSI.dim))
+  // Reuse the SSE consumer but parse `line` events instead of append/replace.
+  await streamSse(baseUrl, path, { apiKey }, {
+    onAppend: () => {},
+    onReplace: () => {},
+    onStatus: () => {},
+    onEnd: (reason) => stdout.write(paint(`\n[stream ended: ${reason}]\n`, ANSI.dim)),
+    onError: (msg) => stderr.write(paint(`\n[error: ${msg}]\n`, ANSI.dim)),
+    onEvent: (eventName, data) => {
+      if (eventName === "line") stdout.write(`${data}\n`)
+    },
+  })
+}
+
+async function handleEnvImport(config, flags, positionals) {
+  // positionals[0] = project, positionals[1] = file (default .env)
+  const projectArg = positionals[0] || resolveProjectArg([], flags)
+  if (!projectArg) throw new Error("Usage: lofenta env import <project> [path/to/.env]")
+  const filePath = positionals[1] || ".env"
+  const abs = path.resolve(filePath)
+  if (!fs.existsSync(abs)) throw new Error(`File not found: ${abs}`)
+  const content = fs.readFileSync(abs, "utf8")
+  const parsed = parseDotEnv(content)
+  if (parsed.length === 0) throw new Error("No env vars parsed from file.")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  stdout.write(`Importing ${parsed.length} env vars from ${paint(abs, ANSI.dim)}\n`)
+  const result = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/env`, {
+    method: "PATCH",
+    apiKey,
+    body: { set: parsed },
+  })
+  stdout.write(`${paint(String(result.added), `${ANSI.bold}${ANSI.white}`)} added, ${paint(String(result.updated), `${ANSI.bold}${ANSI.white}`)} updated. Total now ${result.total}.\n`)
+}
+
+async function handleDomainRm(config, flags, positionals) {
+  // positionals[0] = project, positionals[1] = domain (or only positionals[0] = domain if linked)
+  const linked = readLinkedProject()
+  let projectArg, domain
+  if (positionals.length >= 2) {
+    projectArg = positionals[0]
+    domain = positionals[1]
+  } else if (linked && positionals.length === 1) {
+    projectArg = linked
+    domain = positionals[0]
+  } else {
+    throw new Error("Usage: lofenta domains rm <project> <domain>")
+  }
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/domains?domain=${encodeURIComponent(domain)}`, {
+    method: "DELETE",
+    apiKey,
+  })
+  stdout.write(`Detached ${paint(domain, `${ANSI.bold}${ANSI.white}`)} from ${projectArg}\n`)
+}
+
+async function handleUsage(config, flags) {
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, "/api/cli/usage", { apiKey })
+  if (flags.json) { printJson(data); return }
+  const { plan, usage } = data
+  const mib = (b) => `${(b / 1024 / 1024).toFixed(1)} MiB`
+  const gib = (g) => `${g} GiB`
+  stdout.write(`${paint(plan.name + " plan", `${ANSI.bold}${ANSI.white}`)}  ${paint("$" + plan.monthlyPrice + "/mo", ANSI.dim)}\n\n`)
+  // Bars are rendered by hand instead of printTable: the ANSI color codes inside
+  // the bar would break printTable's column width math.
+  const line = (label, used, limit) => {
+    const counts = limit === null || limit === undefined ? `${used} / unlimited` : `${used} / ${limit}`
+    stdout.write(`${label.padEnd(28)} ${counts.padEnd(16)} ${renderUsageBar(used, limit)}\n`)
+  }
+  line("Services", usage.services, plan.limits.services)
+  line("Custom domains", usage.customDomains, plan.limits.customDomains)
+  line("Build minutes (month)", usage.buildMinutesThisMonth, plan.limits.buildMinutes)
+  stdout.write(`${"Projects".padEnd(28)} ${String(usage.projectCount)}\n`)
+  stdout.write(`${"Total storage".padEnd(28)} ${mib(usage.totalStorageBytes)}  ${paint(`(per-project cap ${gib(plan.storageQuotaGiB)})`, ANSI.dim)}\n`)
+}
+
+async function handleWatch(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta watch <project> [--interval 2]")
+  const interval = Math.max(1, Number(flags.interval ?? 2)) * 1000
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  stdout.write(paint(`Watching ${projectArg} every ${interval / 1000}s. Ctrl+C to stop.\n`, ANSI.dim))
+  let stopped = false
+  process.on("SIGINT", () => { stopped = true })
+  while (!stopped) {
+    try {
+      const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}`, { apiKey })
+      clearScreen()
+      const last = data.deployments[0]
+      const head = data.previewUrl || (data.subdomain ? `https://${data.subdomain}.lofenta.app` : "(no URL)")
+      stdout.write(`${paint(data.name, `${ANSI.bold}${ANSI.white}`)}  ${paint(data.id, ANSI.dim)}\n`)
+      stdout.write(`Status: ${data.status}\n`)
+      stdout.write(`URL:    ${head}\n`)
+      if (last) stdout.write(`Last:   ${last.status} ${formatRel(last.createdAt)} ${last.commitMessage ? `· ${last.commitMessage}` : ""}\n`)
+      stdout.write(paint(`\nrefreshed ${new Date().toLocaleTimeString()}  ·  Ctrl+C to stop\n`, ANSI.dim))
+    } catch (err) {
+      stderr.write(`watch: ${err.message || String(err)}\n`)
+    }
+    await sleep(interval)
+  }
+}
+
+async function handleSnapshots(config, flags, positionals) {
+  const sub = (positionals[0] || "ls").toLowerCase()
+  // Allow `snapshots ls/create/restore [project]` with project as 2nd arg or linked.
+  let projectArg = positionals[1]
+  if (!projectArg) projectArg = readLinkedProject()
+  if (!projectArg) throw new Error("Usage: lofenta snapshots <ls|create|restore> <project> [snapshotId]")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const base = `/api/cli/projects/${encodeURIComponent(projectArg)}/snapshots`
+  if (sub === "ls" || sub === "list") {
+    const data = await request(baseUrl, base, { apiKey })
+    if (flags.json) { printJson(data); return }
+    if (data.length === 0) { stdout.write("No snapshots yet.\n"); return }
+    const rows = data.map((s) => [
+      s.id.slice(0, 8),
+      s.engine,
+      s.label,
+      `${(s.sizeBytes / 1024 / 1024).toFixed(1)} MiB`,
+      formatRel(s.createdAt),
+    ])
+    printTable(["ID", "ENGINE", "LABEL", "SIZE", "WHEN"], rows)
+    return
+  }
+  if (sub === "create" || sub === "new") {
+    const label = flags.label || positionals[2] || ""
+    const data = await request(baseUrl, base, { method: "POST", apiKey, body: { label } })
+    stdout.write(`Created snapshot ${paint(data.id.slice(0, 8), `${ANSI.bold}${ANSI.white}`)} (${data.label}) · ${(data.sizeBytes / 1024 / 1024).toFixed(1)} MiB\n`)
+    return
+  }
+  if (sub === "restore") {
+    const snapshotId = positionals[2] || flags.snapshot
+    if (!snapshotId) throw new Error("Usage: lofenta snapshots restore <project> <snapshotId>")
+    const data = await request(baseUrl, `${base}/${encodeURIComponent(snapshotId)}/restore`, {
+      method: "POST",
+      apiKey,
+      body: {},
+    })
+    stdout.write(`Restored snapshot ${paint(snapshotId.slice(0, 8), `${ANSI.bold}${ANSI.white}`)} (${data.label})\n`)
+    return
+  }
+  throw new Error(`Unknown snapshots subcommand: ${sub}`)
+}
+
+async function handleServices(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta services <project>")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/services`, { apiKey })
+  if (flags.json) { printJson(data); return }
+  if (!data.links.length) {
+    stdout.write("No linked services.\n")
+  } else {
+    const rows = data.links.map((l) => [l.serviceProject?.name ?? l.serviceProjectId, l.serviceProject?.templateId ?? "?", l.alias ?? "-"])
+    printTable(["SERVICE", "ENGINE", "ALIAS"], rows)
+  }
+  if (data.available?.length) {
+    stdout.write(paint(`\nAvailable to link: ${data.available.map((s) => s.name).join(", ")}\n`, ANSI.dim))
+  }
+}
+
+async function handleVolumes(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta volumes <project>")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/volumes`, { apiKey })
+  if (flags.json) { printJson(data); return }
+  if (!data.volumes.length) { stdout.write("No volumes.\n"); return }
+  const rows = data.volumes.map((v) => [v.name, v.mountPath, `${((v.sizeBytes ?? 0) / 1024 / 1024).toFixed(1)} MiB`])
+  printTable(["NAME", "MOUNT", "SIZE"], rows)
+}
+
+async function handlePlan(config, flags) {
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, "/api/cli/usage", { apiKey })
+  if (flags.json) { printJson(data); return }
+  stdout.write(`${paint(data.plan.name, `${ANSI.bold}${ANSI.white}`)} plan  ${paint("$" + data.plan.monthlyPrice + "/mo", ANSI.dim)}\n`)
+  stdout.write(`Storage per project: ${data.plan.storageQuotaGiB} GiB\n`)
+  stdout.write(`Deploy history kept: ${data.plan.deployHistory ?? "unlimited"}\n`)
+  stdout.write(`Log retention:       ${data.plan.logRetentionDays ?? "ephemeral"} days\n`)
+  stdout.write(paint(`\nRun lofenta usage to see consumption details.\n`, ANSI.dim))
+}
+
+async function handleBilling(config, flags) {
+  const baseUrl = inferBaseUrl(config, flags)
+  if (!baseUrl) throw new Error("No base URL configured.")
+  const url = `${baseUrl.replace(/\/$/, "")}/dashboard/settings`
+  stdout.write(`Opening ${paint(url, ANSI.dim)}\n`)
+  if (!openInBrowser(url)) {
+    stdout.write(paint("(could not launch a browser; copy the URL above)\n", ANSI.dim))
+  }
+}
+
+async function handleCompletion(config, flags, positionals) {
+  // Print a shell completion script for the requested shell. Source it (e.g.
+  // `source <(lofenta completion bash)`) to get tab completion on subcommands.
+  const sh = (positionals[0] || flags.shell || "bash").toLowerCase()
+  const COMMANDS = [
+    "login", "logout", "whoami", "doctor", "config",
+    "projects", "project", "status", "deploy", "redeploy", "restart", "rollback", "deployments",
+    "logs", "tail", "exec", "run", "open", "link", "unlink",
+    "env", "secrets", "domains", "templates", "orgs",
+    "usage", "plan", "billing", "watch",
+    "snapshots", "services", "volumes", "db",
+    "stop", "start", "delete",
+    "completion", "help", "version", "exit",
+  ]
+  if (sh === "bash") {
+    stdout.write(`# bash completion for lofenta
+_lofenta_complete() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "\$COMP_CWORD" = "1" ]; then
+    COMPREPLY=( \$(compgen -W "${COMMANDS.join(" ")}" -- "\$cur") )
+  fi
+}
+complete -F _lofenta_complete lofenta
+`)
+    return
+  }
+  if (sh === "zsh") {
+    stdout.write(`#compdef lofenta
+_lofenta() { _arguments -C "1: :(${COMMANDS.join(" ")})" "*::arg:->args" }
+compdef _lofenta lofenta
+`)
+    return
+  }
+  if (sh === "fish") {
+    for (const cmd of COMMANDS) {
+      stdout.write(`complete -c lofenta -n "__fish_use_subcommand" -a "${cmd}"\n`)
+    }
+    return
+  }
+  throw new Error(`Unsupported shell: ${sh}. Pick one of bash, zsh, fish.`)
+}
+
+async function handleInit(config, flags) {
+  // Interactive: pick template (paginated) → pick name → optional domain → optional .env
+  // → deploy. Falls back to non-interactive when stdin is not a TTY by demanding
+  // --template + --name.
+  const interactive = stdin.isTTY && stdout.isTTY
+  if (!interactive) {
+    if (!flags.template || !flags.name) throw new Error("Non-interactive init requires --template and --name.")
+    await handleDeploy(config, { template: flags.template, name: flags.name, domain: flags.domain }, [])
+    return
+  }
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const templates = await request(baseUrl, "/api/cli/templates", { apiKey })
+  if (!templates.length) throw new Error("No templates available.")
+  const PLAN_ORDER = { hobby: 0, developer: 1, team: 2 }
+  templates.sort((a, b) => {
+    if ((b.featured ? 1 : 0) !== (a.featured ? 1 : 0)) return (b.featured ? 1 : 0) - (a.featured ? 1 : 0)
+    const pa = PLAN_ORDER[a.requiredPlan] ?? 0
+    const pb = PLAN_ORDER[b.requiredPlan] ?? 0
+    if (pa !== pb) return pa - pb
+    return a.name.localeCompare(b.name)
+  })
+  const items = templates.map((t) => ({
+    label: `${t.name.padEnd(22)} ${paint(t.id, ANSI.dim)}`,
+    hint: t.description,
+    value: t.id,
+  }))
+  const choice = await selectMenu({
+    title: "lofenta init",
+    subtitle: "Pick a template. ↑/↓ select · ←/→ page · Enter pick · q cancel.",
+    items,
+    config,
+    pageSize: 6,
+  })
+  if (!choice || choice === "exit") return
+  const defaultName = path.basename(process.cwd()).replace(/[^a-z0-9-]/gi, "-").toLowerCase() || "my-app"
+  const name = (await askQuestion(`Project name (default: ${defaultName}): `)) || defaultName
+  const domain = await askQuestion("Custom domain (optional, blank to skip): ")
+  await handleDeploy(config, { template: choice, name, ...(domain ? { domain } : {}) }, [])
+}
+
+const LINK_FILE = ".lofenta"
+
+function findLinkFile(startDir) {
+  let dir = path.resolve(startDir || process.cwd())
+  while (true) {
+    const candidate = path.join(dir, LINK_FILE)
+    if (fs.existsSync(candidate)) return candidate
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function readLinkedProject() {
+  const file = findLinkFile()
+  if (!file) return null
+  try {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"))
+    return typeof data?.project === "string" ? data.project : null
+  } catch {
+    return null
+  }
+}
+
+function writeLinkFile(projectIdOrName) {
+  const dir = process.cwd()
+  const file = path.join(dir, LINK_FILE)
+  fs.writeFileSync(
+    file,
+    `${JSON.stringify({ project: projectIdOrName, linkedAt: new Date().toISOString() }, null, 2)}\n`,
+    "utf8",
+  )
+  return file
+}
+
+function resolveProjectArg(positionals, flags) {
+  const explicit = positionals[0] || flags.project
+  if (explicit) return explicit
+  const linked = readLinkedProject()
+  if (linked) return linked
+  return null
+}
+
+function openInBrowser(url) {
+  const platform = process.platform
+  let cmd
+  let args
+  if (platform === "darwin") { cmd = "open"; args = [url] }
+  else if (platform === "win32") { cmd = "cmd"; args = ["/c", "start", "", url] }
+  else { cmd = "xdg-open"; args = [url] }
+  const r = spawnSync(cmd, args, { stdio: "ignore", detached: true })
+  return r.status === 0 || r.status === null
+}
+
+async function handleLink(config, flags, positionals) {
+  const idOrName = positionals[0] || flags.project
+  if (!idOrName) throw new Error("Usage: lofenta link <id|name>")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  // Verify the project exists & belongs to us before writing the link file.
+  const project = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(idOrName)}`, { apiKey })
+  const file = writeLinkFile(project.name || idOrName)
+  stdout.write(`Linked ${paint(process.cwd(), ANSI.dim)} to ${paint(project.name, `${ANSI.bold}${ANSI.white}`)}\n`)
+  stdout.write(`${paint(file, ANSI.dim)}\n`)
+}
+
+async function handleUnlink() {
+  const file = findLinkFile()
+  if (!file) {
+    stdout.write("No .lofenta link found in this directory tree.\n")
+    return
+  }
+  fs.unlinkSync(file)
+  stdout.write(`Removed ${paint(file, ANSI.dim)}\n`)
+}
+
+async function handleStatus(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta status <id|name>  (or run inside a `lofenta link`ed directory)")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}`, { apiKey })
+  if (flags.json) { printJson(data); return }
+  const head = data.previewUrl || (data.subdomain ? `https://${data.subdomain}.lofenta.app` : "(no URL yet)")
+  const last = data.deployments[0]
+  stdout.write(`${paint(data.name, `${ANSI.bold}${ANSI.white}`)}  ${paint(data.id, ANSI.dim)}\n`)
+  stdout.write(`Status: ${data.status}\n`)
+  stdout.write(`URL:    ${head}\n`)
+  if (last) stdout.write(`Last:   ${last.status} ${formatRel(last.createdAt)} ${last.commitMessage ? `· ${last.commitMessage}` : ""}\n`)
+  if (data.domains.length) {
+    stdout.write(`Domains:\n`)
+    for (const d of data.domains) stdout.write(`  ${d.domain}  ssl=${d.sslStatus}\n`)
+  }
+}
+
+async function handleOpen(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta open <id|name>  (or run inside a `lofenta link`ed directory)")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}`, { apiKey })
+  const targetUrl = flags.url
+    ? (data.previewUrl || (data.subdomain ? `https://${data.subdomain}.lofenta.app` : null))
+    : `${baseUrl.replace(/\/$/, "")}/dashboard/projects/${data.id}`
+  if (!targetUrl) throw new Error("No live URL for this project yet. Try without --url to open the dashboard.")
+  stdout.write(`Opening ${paint(targetUrl, ANSI.dim)}\n`)
+  if (!openInBrowser(targetUrl)) {
+    stdout.write(paint("(could not launch a browser; copy the URL above)\n", ANSI.dim))
+  }
+}
+
+async function handleRestart(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta restart <id|name>")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/restart`, {
+    method: "POST",
+    apiKey,
+    body: {},
+  })
+  stdout.write(`Restarted ${paint(data.project.name, `${ANSI.bold}${ANSI.white}`)}`)
+  if (data.portChanged) stdout.write(paint("  (host port rebound)", ANSI.dim))
+  stdout.write("\n")
+}
+
+async function handleRedeploy(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta redeploy <id|name>")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/redeploy`, {
+    method: "POST",
+    apiKey,
+    body: {},
+  })
+  const mode = data.mode === "in_flight" ? "already in flight" : "queued"
+  stdout.write(`Deployment ${paint(data.deployment.id, ANSI.dim)} ${mode}\n`)
+  stdout.write(paint(`Tail with: lofenta logs ${projectArg}\n`, ANSI.dim))
+}
+
+async function handleRollback(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta rollback <id|name> [--deployment <id>]")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const body = flags.deployment ? { deploymentId: flags.deployment } : {}
+  const data = await request(baseUrl, `/api/cli/projects/${encodeURIComponent(projectArg)}/rollback`, {
+    method: "POST",
+    apiKey,
+    body,
+  })
+  stdout.write(`Rolling back to ${paint(data.target.commitSha.slice(0, 7), `${ANSI.bold}${ANSI.white}`)}`)
+  if (data.target.commitMessage) stdout.write(paint(`  ${data.target.commitMessage}`, ANSI.dim))
+  stdout.write(`\nDeployment: ${paint(data.deployment.id, ANSI.dim)}\n`)
+  stdout.write(paint(`Tail with: lofenta logs ${projectArg}\n`, ANSI.dim))
+}
+
+async function handleDeploymentsList(config, flags, positionals) {
+  const projectArg = resolveProjectArg(positionals, flags)
+  if (!projectArg) throw new Error("Usage: lofenta deployments <id|name>")
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  let url = `/api/cli/projects/${encodeURIComponent(projectArg)}/deployments`
+  if (flags.limit) url += `?limit=${encodeURIComponent(flags.limit)}`
+  const data = await request(baseUrl, url, { apiKey })
+  if (flags.json) { printJson(data); return }
+  if (data.deployments.length === 0) {
+    stdout.write("No deployments yet.\n")
+    return
+  }
+  const limit = flags.limit ? Math.min(Number(flags.limit) || 20, data.deployments.length) : data.deployments.length
+  const rows = data.deployments.slice(0, limit).map((d) => [
+    d.id.slice(0, 8),
+    d.status,
+    d.commitSha ? d.commitSha.slice(0, 7) : "-",
+    formatRel(d.createdAt),
+    (d.commitMessage || "").slice(0, 50),
+  ])
+  printTable(["ID", "STATUS", "COMMIT", "WHEN", "MESSAGE"], rows)
+}
+
+async function handleTemplates(config, flags) {
+  const { baseUrl, apiKey } = await requireAuthed(config, flags)
+  const data = await request(baseUrl, `/api/cli/templates`, { apiKey })
+  if (flags.json) { printJson(data); return }
+  if (data.length === 0) { stdout.write("No templates available.\n"); return }
+  const rows = data.map((t) => [
+    t.id,
+    t.name,
+    t.kind,
+    t.requiredPlan,
+    t.featured ? "yes" : "",
+  ])
+  printTable(["ID", "NAME", "KIND", "MIN PLAN", "FEATURED"], rows)
+}
+
+async function handleDeploy(config, flags, positionals) {
+  const cwd = path.resolve(flags.path || process.cwd())
+  const detected = detectProject(cwd)
+  const baseUrl = inferBaseUrl(config, flags)
+  const apiKey = inferApiKey(config, flags)
+
+  if (!apiKey) {
+    throw new Error("Not logged in. Run lofenta login first or pass --api-key.")
+  }
+
+  const explicitFramework = positionals[0] || flags.framework || flags.template
+  const payload = {
+    name: flags.name || detected.name,
+    framework: explicitFramework || detected.framework,
+    repo: flags.repo || detected.repo,
+    branch: flags.branch || detected.branch,
+    domain: flags.domain || null,
+    org: flags.org ? String(flags.org) : null,
+  }
+
+  let data
+  try {
+    data = await request(baseUrl, "/api/cli/deploy", {
+      method: "POST",
+      apiKey,
+      body: payload,
+    })
+  } catch (error) {
+    throw new Error(formatConnectionError(error, baseUrl))
+  }
+
+  if (flags.json) {
+    printJson({
+      request: payload,
+      response: data,
+    })
+    return
+  }
+
+  stdout.write(`${data.mode === "created" ? "Created" : "Redeployed"} project ${data.project.name}\n`)
+  stdout.write(`Framework: ${payload.framework}\n`)
+  stdout.write(`Repo: ${payload.repo || "template/manual"}\n`)
+  stdout.write(`Branch: ${payload.branch}\n`)
+  stdout.write(`Deployment: ${data.deployment.id}\n`)
+  stdout.write(`Dashboard: ${data.dashboardUrl}\n`)
+}
+
+async function selectMenu({ title, subtitle, items, config = loadConfig(), pageSize = 0 }) {
+  // Pagination auto-sizes to the terminal height so long lists never scroll off the
+  // top (e.g. an account with many projects). An explicit pageSize (the template
+  // browser) still wins. Left/Right walk pages, Up/Down walks the current page; the
+  // selected index is global, so changing page lands on the first item of the new page.
+  const termRows = stdout.rows && stdout.rows > 0 ? stdout.rows : 24
+  const headerRows = BRAND_MARK.length + 6 // brand art + title/subtitle/base-url + footer
+  const effectivePageSize = pageSize > 0 ? pageSize : Math.max(4, termRows - headerRows)
+  const usingPages = items.length > effectivePageSize
+  const pages = usingPages ? Math.ceil(items.length / effectivePageSize) : 1
+  let selected = 0
+  let page = 0
+  const visibleRange = () => {
+    if (!usingPages) return [0, items.length]
+    const start = page * effectivePageSize
+    return [start, Math.min(start + effectivePageSize, items.length)]
+  }
+
+  return new Promise((resolve) => {
+    readlineCore.emitKeypressEvents(stdin)
+    stdin.resume()
+    if (stdin.isTTY) stdin.setRawMode(true)
+    // Hide the cursor while the menu owns the screen; a cursor hopping around
+    // during repaints is half of the perceived flicker.
+    stdout.write("\x1b[?25l")
+
+    // Flicker-free repaint: clear the screen only on the FIRST frame. Every
+    // following frame jumps the cursor home (ESC[H) and overwrites in place,
+    // erasing each line's leftovers (ESC[K) and anything below the frame
+    // (ESC[J), all in ONE stdout.write. The old full-clear-per-keypress
+    // (ESC[2J + ~30 separate writes) blanked the terminal between clear and
+    // repaint, which read as glitching while navigating.
+    let firstFrame = true
+    const render = () => {
+      let body = buildBrandHeader(title, subtitle, config)
+      const [start, end] = visibleRange()
+      for (let i = start; i < end; i += 1) {
+        const item = items[i]
+        const prefix = i === selected ? paint("> ", `${ANSI.bold}${ANSI.blue}`) : "  "
+        const label = i === selected
+          ? paint(item.label, `${ANSI.inverse}${ANSI.bold}`)
+          : paint(item.label, ANSI.white)
+        const hint = item.hint ? paint(`  ${item.hint}`, ANSI.dim) : ""
+        body += `${prefix}${label}${hint}\n`
+      }
+      const footer = usingPages
+        ? `Page ${page + 1}/${pages}  ·  ↑/↓ select  ·  ←/→ page  ·  Enter pick  ·  / command mode  ·  q cancel`
+        : "Use arrow keys and Enter. Press / for command mode."
+      body += `\n${paint(footer, ANSI.dim)}\n`
+      const frame = body.split("\n").join("\x1b[K\n") + "\x1b[J"
+      stdout.write((firstFrame ? "\x1b[2J\x1b[H" : "\x1b[H") + frame)
+      firstFrame = false
+    }
+
+    const cleanup = () => {
+      stdin.off("keypress", onKeypress)
+      if (stdin.isTTY) stdin.setRawMode(false)
+      stdin.pause()
+      stdout.write("\x1b[?25h")
+    }
+
+    const finish = (value) => {
+      cleanup()
+      resolve(value)
+    }
+
+    const onKeypress = (str, key = {}) => {
+      if (key.ctrl && key.name === "c") {
+        finish("exit")
+        return
+      }
+
+      if (key.name === "up") {
+        if (!usingPages) {
+          selected = (selected - 1 + items.length) % items.length
+        } else {
+          const [start, end] = visibleRange()
+          // Wrap inside the current page so the user doesn't accidentally jump pages.
+          selected = selected - 1 < start ? end - 1 : selected - 1
+        }
+        render()
+        return
+      }
+
+      if (key.name === "down") {
+        if (!usingPages) {
+          selected = (selected + 1) % items.length
+        } else {
+          const [start, end] = visibleRange()
+          selected = selected + 1 >= end ? start : selected + 1
+        }
+        render()
+        return
+      }
+
+      if (usingPages && key.name === "right") {
+        page = (page + 1) % pages
+        selected = page * effectivePageSize
+        render()
+        return
+      }
+      if (usingPages && key.name === "left") {
+        page = (page - 1 + pages) % pages
+        selected = page * effectivePageSize
+        render()
+        return
+      }
+
+      if (key.name === "return") {
+        finish(items[selected].value)
+        return
+      }
+
+      if (str === "/") {
+        finish("__command__")
+        return
+      }
+
+      if (key.name === "escape" || str === "q") {
+        finish("exit")
+      }
+    }
+
+    stdin.on("keypress", onKeypress)
+    render()
+  })
+}
+
+async function interactiveLoginMenu(config) {
+  if (config.apiKey) {
+    throw new Error("Already logged in. Run /logout first if you want to replace this CLI session.")
+  }
+
+  const choice = await selectMenu({
+    title: "Login",
+    subtitle: "Choose how this terminal should connect to your Lofenta account.",
+    items: [
+      { label: "Continue in browser", hint: "Open the full approval link in a browser", value: "link" },
+      { label: "Use device code", hint: "Open the short URL and confirm with a code", value: "code" },
+      { label: "Use API key", hint: "Paste a long-lived API key from dashboard settings", value: "api-key" },
+      { label: "Back", hint: "Return to the main menu", value: "back" },
+    ],
+    config,
+  })
+
+  if (choice === "exit" || choice === "back") return choice
+
+  if (choice === "api-key") {
+    printBrandHeader("Login", "Paste a long-lived API key from Dashboard > Settings > CLI access.", config)
+    await handleApiKeyLogin(config, {}, true)
+    return null
+  }
+
+  await handleDeviceLogin(config, {}, true, choice)
+  return null
+}
+
+async function dispatch(parsed, config, context = {}) {
+  const command = (parsed.command || "").toLowerCase()
+  const interactive = Boolean(context.interactive)
+
+  if (!command || command === "help") {
+    printHelp()
+    return
+  }
+
+  if (command === "version") {
+    stdout.write(`${VERSION}\n`)
+    return
+  }
+
+  if (command === "login") {
+    if (config.apiKey) {
+      throw new Error("Already logged in. Run lofenta logout first if you want to authenticate again.")
+    }
+
+    if (parsed.flags["api-key"]) {
+      await handleApiKeyLogin(config, parsed.flags, interactive)
+      return
+    }
+
+    if (interactive && !parsed.flags.code && !parsed.flags.link) {
+      return interactiveLoginMenu(config)
+    }
+
+    await handleDeviceLogin(config, parsed.flags, interactive, parsed.flags.code ? "code" : "link")
+    return
+  }
+
+  if (command === "whoami") {
+    await handleWhoAmI(config, parsed.flags)
+    return
+  }
+
+  if (command === "logout") {
+    await handleLogout(config)
+    return
+  }
+
+  if (command === "doctor") {
+    await handleDoctor(config, parsed.flags)
+    return
+  }
+
+  if (command === "config") {
+    printJson({ configPath: CONFIG_PATH, config })
+    return
+  }
+
+  if (command === "deploy") {
+    await handleDeploy(config, parsed.flags, parsed.positionals)
+    return
+  }
+
+  if (command === "projects") {
+    await handleProjectsList(config, parsed.flags)
+    return
+  }
+  if (command === "project") {
+    await handleProjectInfo(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "env") {
+    await handleEnv(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "domains" || command === "domain") {
+    await handleDomains(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "logs" || command === "log") {
+    await handleLogs(config, parsed.flags, parsed.positionals)
+    return
+  }
+
+  if (command === "secrets" || command === "secret") {
+    await handleEnv(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "templates" || command === "template") {
+    await handleTemplates(config, parsed.flags)
+    return
+  }
+  if (command === "link") {
+    await handleLink(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "unlink") {
+    await handleUnlink()
+    return
+  }
+  if (command === "status") {
+    await handleStatus(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "open") {
+    await handleOpen(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "restart") {
+    await handleRestart(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "redeploy") {
+    await handleRedeploy(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "rollback") {
+    await handleRollback(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "deployments" || command === "deployment") {
+    await handleDeploymentsList(config, parsed.flags, parsed.positionals)
+    return
+  }
+
+  if (command === "exec") {
+    await handleExec(config, parsed.flags, parsed.positionals, parsed.passthrough || [])
+    return
+  }
+  if (command === "run") {
+    await handleRun(config, parsed.flags, parsed.positionals, parsed.passthrough || [])
+    return
+  }
+  if (command === "tail") {
+    await handleTail(config, parsed.flags, parsed.positionals)
+    return
+  }
+
+  if (command === "usage") {
+    await handleUsage(config, parsed.flags)
+    return
+  }
+  if (command === "plan") {
+    await handlePlan(config, parsed.flags)
+    return
+  }
+  if (command === "billing") {
+    await handleBilling(config, parsed.flags)
+    return
+  }
+  if (command === "watch") {
+    await handleWatch(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "snapshots" || command === "snapshot") {
+    await handleSnapshots(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "orgs" || command === "org" || command === "teams") {
+    await handleOrgs(config, parsed.flags)
+    return
+  }
+  if (command === "db" || command === "database") {
+    await handleDb(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "stop") {
+    await handleStopStart(config, parsed.flags, parsed.positionals, "stop")
+    return
+  }
+  if (command === "start") {
+    await handleStopStart(config, parsed.flags, parsed.positionals, "start")
+    return
+  }
+  if (command === "delete" || command === "remove") {
+    await handleDelete(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "services" || command === "service") {
+    await handleServices(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "volumes" || command === "volume") {
+    await handleVolumes(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "completion") {
+    await handleCompletion(config, parsed.flags, parsed.positionals)
+    return
+  }
+  if (command === "init") {
+    await handleInit(config, parsed.flags)
+    return
+  }
+
+  if (command === "exit" || command === "quit") {
+    return "exit"
+  }
+
+  throw new Error(`Unknown command: ${command}`)
+}
+
+async function runCommandMode() {
+  printBrandHeader("Command mode", "Type a slash command like /login, /deploy, or /whoami.")
+  const line = await askQuestion("lofenta> ")
+  if (!line) return null
+  const tokens = tokenize(line)
+  const dd = tokens.indexOf("--")
+  const parsed = parseArgv(dd === -1 ? tokens : tokens.slice(0, dd))
+  parsed.passthrough = dd === -1 ? [] : tokens.slice(dd + 1)
+  return dispatch(parsed, loadConfig(), { interactive: true })
+}
+
+async function runInteractiveAction(title, subtitle, action) {
+  printBrandHeader(title, subtitle)
+  try {
+    const result = await action()
+    if (result === "exit") return "exit"
+  } catch (error) {
+    stderr.write(`${error.message || String(error)}\n`)
+  }
+  await waitForEnter()
+  return null
+}
+
+// Paginated template browser launched from the interactive menu. Fetches the catalog
+// once, renders 6 per page in a paginated selectMenu, and on pick prompts for a project
+// name then dispatches to handleDeploy(template, name). Used by the Templates menu item.
+async function runTemplateBrowser(config) {
+  let templates
+  try {
+    const { baseUrl, apiKey } = await requireAuthed(config, {})
+    templates = await request(baseUrl, "/api/cli/templates", { apiKey })
+  } catch (err) {
+    return runInteractiveAction("Templates", "Could not fetch templates.", async () => {
+      stderr.write(`${err.message || String(err)}\n`)
+    })
+  }
+  if (!templates.length) {
+    return runInteractiveAction("Templates", "No templates available.", async () => {})
+  }
+
+  // Sort: featured first, then required-plan ascending, then alpha. Keeps the most
+  // useful options on page 1.
+  const PLAN_ORDER = { hobby: 0, developer: 1, team: 2 }
+  templates.sort((a, b) => {
+    if ((b.featured ? 1 : 0) !== (a.featured ? 1 : 0)) return (b.featured ? 1 : 0) - (a.featured ? 1 : 0)
+    const pa = PLAN_ORDER[a.requiredPlan] ?? 0
+    const pb = PLAN_ORDER[b.requiredPlan] ?? 0
+    if (pa !== pb) return pa - pb
+    return a.name.localeCompare(b.name)
+  })
+
+  const items = templates.map((t) => {
+    const tags = []
+    if (t.featured) tags.push("featured")
+    if (t.requiredPlan && t.requiredPlan !== "hobby") tags.push(t.requiredPlan)
+    if (t.requires?.length) tags.push(`needs: ${t.requires.join(",")}`)
+    const tagSuffix = tags.length ? `  [${tags.join(" · ")}]` : ""
+    return {
+      label: `${t.name.padEnd(22)} ${paint(t.id, ANSI.dim)}`,
+      hint: `${t.description}${tagSuffix}`,
+      value: t.id,
+    }
+  })
+
+  const choice = await selectMenu({
+    title: "Templates",
+    subtitle: "Pick one to deploy as a new project. ↑/↓ select · ←/→ page · Enter pick · q cancel.",
+    items,
+    config,
+    pageSize: 6,
+  })
+  if (!choice || choice === "exit") return null
+  if (choice === "__command__") {
+    return runInteractiveAction("Command mode", "Type a slash command or regular CLI command.", runCommandMode)
+  }
+
+  const picked = templates.find((t) => t.id === choice)
+  return runInteractiveAction(
+    `Deploy ${picked?.name ?? choice}`,
+    `Creating a new project from the ${picked?.name ?? choice} template.`,
+    async () => {
+      const defaultName = path.basename(process.cwd()).replace(/[^a-z0-9-]/gi, "-").toLowerCase() || "my-app"
+      const name = (await askQuestion(`Project name (default: ${defaultName}): `)) || defaultName
+      await handleDeploy(config, { template: choice, name }, [])
+    },
+  )
+}
+
+// Pick a project for interactive actions: linked .lofenta wins, otherwise fetch the list
+// and let the user choose. Returns the project name string or null when the user backs out.
+async function promptProject(config, { actionLabel = "Pick a project" } = {}) {
+  const linked = readLinkedProject()
+  if (linked) return linked
+  const { baseUrl, apiKey } = await requireAuthed(config, {})
+  let projects
+  try {
+    projects = await request(baseUrl, "/api/cli/projects", { apiKey })
+  } catch (err) {
+    stderr.write(`${err.message || String(err)}\n`)
+    return null
+  }
+  if (!projects.length) {
+    stdout.write("No projects yet. Run a deploy from your repo first.\n")
+    return null
+  }
+  const choice = await selectMenu({
+    title: actionLabel,
+    subtitle: "Use up/down + Enter. Press / for command mode, q to cancel.",
+    items: projects.map((p) => ({
+      label: p.name,
+      hint: `${p.status}  ${p.lastDeploy?.status ?? "no deploys"}`,
+      value: p.name,
+    })),
+    config,
+  })
+  if (!choice || choice === "exit" || choice === "__command__") return null
+  return choice
+}
+
+async function startShell() {
+  while (true) {
+    const config = loadConfig()
+    const isAuthenticated = Boolean(config.apiKey)
+    const menuItems = isAuthenticated
+      ? [
+          { label: "New project (init)", hint: "Pick a template, name it, deploy it", value: "init" },
+          { label: "Status", hint: "One-line snapshot of a project", value: "status" },
+          { label: "Deploy current directory", hint: "Auto-detect the app here and create / redeploy", value: "deploy" },
+          { label: "Redeploy", hint: "Trigger a fresh build for an existing project", value: "redeploy" },
+          { label: "Restart container", hint: "Bounce the running container without rebuilding", value: "restart" },
+          { label: "Rollback", hint: "Revert to the previous successful deployment", value: "rollback" },
+          { label: "Tail container", hint: "Live stdout/stderr from the running container", value: "tail" },
+          { label: "Deploy log", hint: "Live deploy log via SSE", value: "logs" },
+          { label: "Run command (exec)", hint: "One-shot command in the running container", value: "exec" },
+          { label: "Open in browser", hint: "Dashboard page (add --url for the live site)", value: "open" },
+          { label: "Watch", hint: "Refresh project status every 2s", value: "watch" },
+          { label: "Snapshots", hint: "List / create / restore database snapshots", value: "snapshots" },
+          { label: "Services", hint: "Linked internal Postgres/Redis/MariaDB", value: "services" },
+          { label: "Volumes", hint: "Named Docker volumes attached", value: "volumes" },
+          { label: "Projects", hint: "List all your projects", value: "projects" },
+          { label: "Deployments", hint: "Recent deployments for a project", value: "deployments" },
+          { label: "Templates", hint: "Browse + deploy from catalog (paginated)", value: "templates" },
+          { label: "Usage", hint: "Plan limits, what you've used, what's left", value: "usage" },
+          { label: "Plan", hint: "Current plan summary", value: "plan" },
+          { label: "Billing", hint: "Open the billing page in a browser", value: "billing" },
+          { label: "Link this directory", hint: `Save a ${LINK_FILE} so commands omit the project arg`, value: "link" },
+          { label: "Unlink this directory", hint: `Remove the ${LINK_FILE} file`, value: "unlink" },
+          { label: "Who am I", hint: "Show the currently connected account", value: "whoami" },
+          { label: "Logout", hint: "Remove the saved API key from this machine", value: "logout" },
+          { label: "Config", hint: "View saved base URL and auth state", value: "config" },
+          { label: "Help", hint: "Show command reference and flags", value: "help" },
+          { label: "Exit", hint: "Close the CLI", value: "exit" },
+        ]
+      : [
+          { label: "Login", hint: "Connect with browser approval, device code, or API key", value: "login" },
+          { label: "Deploy current project", hint: "Auto-detect the app in the current directory", value: "deploy" },
+          { label: "Config", hint: "View saved base URL and auth state", value: "config" },
+          { label: "Help", hint: "Show command reference and flags", value: "help" },
+          { label: "Exit", hint: "Close the CLI", value: "exit" },
+        ]
+
+    const choice = await selectMenu({
+      title: "LOFENTA CLI",
+      subtitle: "Manage your projects without leaving the terminal.",
+      items: menuItems,
+      config,
+    })
+
+    if (choice === "exit") break
+
+    if (choice === "__command__") {
+      const result = await runInteractiveAction("Command mode", "Type a slash command or regular CLI command.", runCommandMode)
+      if (result === "exit") break
+      continue
+    }
+
+    if (choice === "login") {
+      const result = await runInteractiveAction("Login", "Choose how this terminal should connect to Lofenta.", async () => interactiveLoginMenu(config))
+      if (result === "exit") break
+      continue
+    }
+
+    if (choice === "deploy") {
+      await runInteractiveAction("Deploy", "Lofenta will inspect this directory and deploy the detected app.", async () => {
+        await handleDeploy(config, {}, [])
+      })
+      continue
+    }
+
+    if (choice === "status") {
+      const project = await promptProject(config, { actionLabel: "Status of which project?" })
+      if (!project) continue
+      await runInteractiveAction("Status", `Snapshot for ${project}.`, async () => {
+        await handleStatus(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "redeploy") {
+      const project = await promptProject(config, { actionLabel: "Redeploy which project?" })
+      if (!project) continue
+      await runInteractiveAction("Redeploy", `Triggering a fresh deploy for ${project}.`, async () => {
+        await handleRedeploy(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "restart") {
+      const project = await promptProject(config, { actionLabel: "Restart which project's container?" })
+      if (!project) continue
+      await runInteractiveAction("Restart", `Bouncing the running container for ${project}.`, async () => {
+        await handleRestart(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "rollback") {
+      const project = await promptProject(config, { actionLabel: "Rollback which project?" })
+      if (!project) continue
+      await runInteractiveAction("Rollback", `Reverting ${project} to its previous live deployment.`, async () => {
+        await handleRollback(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "logs") {
+      const project = await promptProject(config, { actionLabel: "Tail logs for which project?" })
+      if (!project) continue
+      await runInteractiveAction("Logs", `Streaming logs for ${project}. Ctrl+C to stop.`, async () => {
+        await handleLogs(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "open") {
+      const project = await promptProject(config, { actionLabel: "Open which project?" })
+      if (!project) continue
+      await runInteractiveAction("Open", `Launching dashboard for ${project}.`, async () => {
+        await handleOpen(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "projects") {
+      await runInteractiveAction("Projects", "All projects on your account.", async () => {
+        await handleProjectsList(config, {})
+      })
+      continue
+    }
+
+    if (choice === "deployments") {
+      const project = await promptProject(config, { actionLabel: "Deployments for which project?" })
+      if (!project) continue
+      await runInteractiveAction("Deployments", `Recent deployments for ${project}.`, async () => {
+        await handleDeploymentsList(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "templates") {
+      const result = await runTemplateBrowser(config)
+      if (result === "exit") break
+      continue
+    }
+
+    if (choice === "link") {
+      const project = await promptProject(config, { actionLabel: "Link this directory to which project?" })
+      if (!project) continue
+      await runInteractiveAction("Link", `Saving ${LINK_FILE} pointing at ${project}.`, async () => {
+        await handleLink(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "unlink") {
+      await runInteractiveAction("Unlink", "Removing the .lofenta link file.", async () => {
+        await handleUnlink()
+      })
+      continue
+    }
+
+    if (choice === "init") {
+      await runInteractiveAction("New project", "Pick a template and deploy.", async () => {
+        await handleInit(config, {})
+      })
+      continue
+    }
+
+    if (choice === "tail") {
+      const project = await promptProject(config, { actionLabel: "Tail container for which project?" })
+      if (!project) continue
+      await runInteractiveAction("Tail", `Streaming container output for ${project}. Ctrl+C to stop.`, async () => {
+        await handleTail(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "exec") {
+      const project = await promptProject(config, { actionLabel: "Run a command in which project?" })
+      if (!project) continue
+      await runInteractiveAction("Exec", `One-shot command inside ${project}.`, async () => {
+        const cmd = await askQuestion("Command to run: ")
+        if (!cmd) return
+        await handleExec(config, {}, [project, ...tokenize(cmd)])
+      })
+      continue
+    }
+
+    if (choice === "watch") {
+      const project = await promptProject(config, { actionLabel: "Watch which project?" })
+      if (!project) continue
+      await runInteractiveAction("Watch", `Refreshing ${project}. Ctrl+C to stop.`, async () => {
+        await handleWatch(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "snapshots") {
+      const project = await promptProject(config, { actionLabel: "Snapshots of which project?" })
+      if (!project) continue
+      await runInteractiveAction("Snapshots", `Database snapshots for ${project}.`, async () => {
+        await handleSnapshots(config, {}, ["ls", project])
+      })
+      continue
+    }
+
+    if (choice === "services") {
+      const project = await promptProject(config, { actionLabel: "Services for which project?" })
+      if (!project) continue
+      await runInteractiveAction("Services", `Linked services for ${project}.`, async () => {
+        await handleServices(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "volumes") {
+      const project = await promptProject(config, { actionLabel: "Volumes for which project?" })
+      if (!project) continue
+      await runInteractiveAction("Volumes", `Docker volumes attached to ${project}.`, async () => {
+        await handleVolumes(config, {}, [project])
+      })
+      continue
+    }
+
+    if (choice === "usage") {
+      await runInteractiveAction("Usage", "Plan limits, what you've used, what's left.", async () => {
+        await handleUsage(config, {})
+      })
+      continue
+    }
+
+    if (choice === "plan") {
+      await runInteractiveAction("Plan", "Current plan summary.", async () => {
+        await handlePlan(config, {})
+      })
+      continue
+    }
+
+    if (choice === "billing") {
+      await runInteractiveAction("Billing", "Opening the billing page in a browser.", async () => {
+        await handleBilling(config, {})
+      })
+      continue
+    }
+
+    if (choice === "whoami") {
+      await runInteractiveAction("Who am I", "Current authenticated account.", async () => {
+        await handleWhoAmI(config, {})
+      })
+      continue
+    }
+
+    if (choice === "logout") {
+      await runInteractiveAction("Logout", "Remove the saved local login for this machine.", async () => {
+        await handleLogout(config)
+      })
+      continue
+    }
+
+    if (choice === "config") {
+      await runInteractiveAction("Config", "Saved local CLI configuration.", async () => {
+        printJson({ configPath: CONFIG_PATH, config })
+      })
+      continue
+    }
+
+    if (choice === "help") {
+      await runInteractiveAction("Help", "Command reference and supported flags.", async () => {
+        printHelp()
+      })
+    }
+  }
+}
+
+async function main() {
+  // Everything after a bare -- is an untouched passthrough command (run/exec).
+  // Splitting BEFORE parseArgv also fixes the old bug where parseArgv treated
+  // "--" as an empty flag and swallowed the next token of the command.
+  const raw = process.argv.slice(2)
+
+  // Global flags handled before command parsing so `lofenta --version` / `-v` and
+  // `lofenta --help` / `-h` work even in a TTY (where a bare invocation opens the menu).
+  if (raw[0] === "--version" || raw[0] === "-v" || raw[0] === "version") {
+    stdout.write(`${VERSION}\n`)
+    return
+  }
+  if (raw[0] === "--help" || raw[0] === "-h") {
+    printHelp()
+    return
+  }
+
+  const dd = raw.indexOf("--")
+  const parsed = parseArgv(dd === -1 ? raw : raw.slice(0, dd))
+  parsed.passthrough = dd === -1 ? [] : raw.slice(dd + 1)
+
+  if (!parsed.command) {
+    if (stdin.isTTY && stdout.isTTY) {
+      await startShell()
+      exit(0)
+    }
+
+    printHelp()
+    return
+  }
+
+  try {
+    await dispatch(parsed, loadConfig(), { interactive: false })
+  } catch (error) {
+    stderr.write(`${error.message || String(error)}\n`)
+    exit(1)
+  }
+}
+
+main()