@mcpcloud/cli 0.9.1 → 0.10.0-next-20260715004701

package/dist/index.js

@@ -1972,6 +1972,9 @@ function configFile() {
   return join(configDir(), "config.json");
 }
 var DEFAULT_PROFILE_NAME = "default";
+var DEFAULT_BASE_URL = "https://majestic-lobster-858.convex.site";
+var PRODUCTION_BASE_URL = DEFAULT_BASE_URL;
+var DEFAULT_APP_URL = "https://mcpcloud.sh";
 
 class MissingApiKeyError extends Error {
   constructor() {
@@ -2100,6 +2103,14 @@ function getActiveProfileName() {
   const first = Object.keys(persisted.profiles ?? {})[0];
   return first ?? saved;
 }
+function resolveActiveProfile() {
+  if (profileOverride)
+    return { name: profileOverride, source: "flag" };
+  const fromEnv = process.env["MCPCLOUD_PROFILE"]?.trim();
+  if (fromEnv)
+    return { name: fromEnv, source: "env" };
+  return { name: getActiveProfileName(), source: "config" };
+}
 function getActiveProfile(persisted, name) {
   return persisted.profiles?.[name] ?? {};
 }
@@ -2121,11 +2132,26 @@ function writeConfig(config) {
 function getApiKey() {
   return process.env["MCPCLOUD_API_KEY"] ?? readConfig().apiKey;
 }
+function resolveBaseUrl() {
+  if (baseUrlOverride)
+    return { url: baseUrlOverride, source: "flag" };
+  const env = process.env["MCPCLOUD_BASE_URL"]?.trim();
+  if (env)
+    return { url: env, source: "env" };
+  const profile = readConfig().baseUrl;
+  if (profile)
+    return { url: profile, source: "profile" };
+  return { url: DEFAULT_BASE_URL, source: "default" };
+}
 function getBaseUrl() {
-  const url = baseUrlOverride ?? process.env["MCPCLOUD_BASE_URL"] ?? readConfig().baseUrl;
-  if (!url)
-    throw new MissingBaseUrlError;
-  return url;
+  return resolveBaseUrl().url;
+}
+function isProductionBaseUrl(url) {
+  try {
+    return new URL(url).host === new URL(PRODUCTION_BASE_URL).host;
+  } catch {
+    return false;
+  }
 }
 function requireApiKey() {
   const key = getApiKey();
@@ -2152,10 +2178,10 @@ function getAppUrl() {
       if (host === "localhost" || host === "127.0.0.1")
         return "http://localhost:4000";
       if (host.endsWith(".convex.site") || host.endsWith(".convex.cloud"))
-        return "https://mcpcloud.sh";
+        return DEFAULT_APP_URL;
     } catch {}
   }
-  return "https://mcpcloud.sh";
+  return DEFAULT_APP_URL;
 }
 function listProfiles() {
   const persisted = readPersistedConfig();
@@ -2386,12 +2412,20 @@ function getRetryDelayMs(err) {
   }
   return 250 + Math.floor(Math.random() * 250);
 }
+var GATEWAY_STATUS_MESSAGES = {
+  502: "The gateway returned no response (HTTP 502 Bad Gateway). A long-running request — such as a first deploy that is still generating and uploading the bundle — can exceed the gateway timeout even though the operation keeps running server-side. Retry in a few seconds; for a deploy, re-run with `--wait` or follow progress with `mcp deployments logs <id> --follow`.",
+  503: "The service is temporarily unavailable (HTTP 503 Service Unavailable). This is usually transient — retry in a few seconds.",
+  504: "The gateway timed out waiting for the server (HTTP 504 Gateway Timeout). A long-running request may still be processing server-side. Retry in a few seconds; for a deploy, re-run with `--wait` or follow progress with `mcp deployments logs <id> --follow`."
+};
+function synthesizeStatusMessage(status, statusText) {
+  return GATEWAY_STATUS_MESSAGES[status] ?? (statusText || `HTTP ${status}`);
+}
 async function parseErrorBody(res) {
   const headerRequestId = res.headers.get("x-request-id") ?? undefined;
   const retryAfter = parseRetryAfter(res.headers.get("retry-after"));
   const fallback = {
     code: `http_${res.status}`,
-    message: res.statusText || `HTTP ${res.status}`
+    message: synthesizeStatusMessage(res.status, res.statusText)
   };
   if (headerRequestId)
     fallback.requestId = headerRequestId;
@@ -2834,7 +2868,12 @@ var ERROR_REMEDIATION = {
   invalid_status: "Invalid --status. Check the command help for accepted values.",
   deployment_not_found: "No such deployment in this org. Verify with `mcp servers list`.",
   server_not_found: "No such server in this org. Verify with `mcp servers list`.",
+  artifact_not_found: "No such server/artifact in that project. If you switched servers, stale .mcpcloud/state.json can cause this — run `mcp dev init` to re-select.",
+  bundle_not_found: "The server has no generated bundle yet. Run `mcp servers generate <id>` or deploy once, then retry.",
   missing_deployment_id: "Pass --deployment <id> or look it up with `mcp servers list`.",
+  http_502: "The API gateway dropped the request. Retry once; if it persists, check https://mcpcloud.sh/status.",
+  http_503: "Service temporarily unavailable. Honor Retry-After if present, then retry.",
+  http_504: "The request timed out at the gateway. Retry; long operations may still be running — check with the matching `get` command.",
   rate_limited: "Rate limit hit. Honor the Retry-After header and retry.",
   rate_limit_exceeded: "Rate limit hit. Wait the Retry-After interval before retrying.",
   quota_exceeded: "Plan quota exceeded. Check usage in the dashboard or upgrade.",
@@ -2868,6 +2907,14 @@ function getRemediation(code) {
     return;
   return ERROR_REMEDIATION[code];
 }
+var DOCS_ORIGIN = "https://mcpcloud.sh";
+function absolutizeDocsUrl(url) {
+  if (!url)
+    return url;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url))
+    return url;
+  return `${DOCS_ORIGIN}${url.startsWith("/") ? "" : "/"}${url}`;
+}
 function describeError(err) {
   if (err instanceof McpCloudApiError) {
     const out = {
@@ -2877,8 +2924,11 @@ function describeError(err) {
     };
     if (err.error.requestId)
       out.requestId = err.error.requestId;
-    if (err.error.docsUrl)
-      out.docsUrl = err.error.docsUrl;
+    if (err.error.docsUrl) {
+      const docsUrl = absolutizeDocsUrl(err.error.docsUrl);
+      if (docsUrl)
+        out.docsUrl = docsUrl;
+    }
     if (err.error.details)
       out.details = err.error.details;
     return out;
@@ -3371,6 +3421,16 @@ function previewKey(key) {
     return `${key.slice(0, 4)}…`;
   return `${key.slice(0, 8)}…${key.slice(-4)}`;
 }
+function profileSourceLabel(source) {
+  switch (source) {
+    case "flag":
+      return "--profile flag";
+    case "env":
+      return "MCPCLOUD_PROFILE";
+    case "config":
+      return "config default";
+  }
+}
 function registerAuthCommands(program2) {
   program2.command("login").description("Sign in via browser (default) or paste an API key").option("--key <apiKey>", "Save this key directly (skips browser + prompt)").option("--paste", "Skip the browser flow and prompt for an API key instead").option("--no-browser", "Alias for --paste").option("--port <number>", "Loopback port to receive the callback (default: auto)").option("--app-url <url>", "Override the dashboard origin for this run (default: from MCPCLOUD_APP_URL or config)").option("--timeout <seconds>", "How long to wait for the browser flow (default 300)").addHelpText("after", [
     "",
@@ -3510,12 +3570,17 @@ function registerAuthCommands(program2) {
 `)).action(runAction(async () => {
     const me = await api.get("/api/v1/me");
     const orgs = await api.get("/api/v1/organizations");
+    const profile = resolveActiveProfile();
+    const baseUrl = getBaseUrl();
+    const isProd = isProductionBaseUrl(baseUrl);
     if (isJsonMode()) {
       printJson({
         user: me.user,
         authMethod: me.authMethod,
         apiKey: me.apiKey,
-        baseUrl: getBaseUrl(),
+        profile: { name: profile.name, source: profile.source },
+        baseUrl,
+        isProductionBaseUrl: isProd,
         defaultOrganizationId: me.defaultOrganizationId,
         organizations: orgs.organizations
       });
@@ -3526,7 +3591,8 @@ function registerAuthCommands(program2) {
       user: me.user.email ?? me.user.name ?? me.user.id,
       "auth method": me.authMethod ?? "—",
       "api key": apiKeyDisplay,
-      "base url": getBaseUrl(),
+      profile: `${profile.name} (${profileSourceLabel(profile.source)})`,
+      "base url": isProd ? `${baseUrl} (production)` : baseUrl,
       "default org": me.defaultOrganizationId ?? "—",
       "org count": orgs.organizations.length
     });
@@ -3875,13 +3941,24 @@ var TERMINAL_STAGES = new Set([
   "terminated"
 ]);
 var TERMINAL_LEVELS = new Set(["success", "failure", "error"]);
+var TERMINAL_DEPLOYMENT_STATUSES = new Set([
+  "active",
+  "failed",
+  "paused",
+  "undeployed"
+]);
+function isTerminalDeploymentStatus(status) {
+  return status !== undefined && TERMINAL_DEPLOYMENT_STATUSES.has(status);
+}
 function isTerminalEvent(event) {
   if (TERMINAL_STAGES.has(event.stage))
     return true;
   if (TERMINAL_LEVELS.has(event.level))
     return true;
   const m = event.message.toLowerCase();
-  if (m.includes("deployment active"))
+  if (m.includes("deployment is active") || m.includes("deployment active"))
+    return true;
+  if (m.includes("deployment failed"))
     return true;
   if (m.includes("deploy succeeded") || m.includes("deploy failed"))
     return true;
@@ -4513,24 +4590,28 @@ function registerServerLifecycleCommands(servers) {
     let terminalEvent = null;
     let waitDone = !opts.wait;
     if (opts.wait) {
-      const totalTimeoutMs = Math.max(10, Number.parseInt(opts.waitTimeout, 10) || 300) * 1000;
-      if (!isJsonMode()) {
-        printStep(`Following events for ${c.bold(dep.deploymentId)} (timeout ${Math.round(totalTimeoutMs / 1000)}s)…`);
-      }
-      const result = await followDeploymentEvents({
-        organizationId: orgId,
-        deploymentId: dep.deploymentId,
-        totalTimeoutMs,
-        onEvent: (event) => {
-          if (!isJsonMode()) {
-            printInfo(formatEventLine2(event));
+      if (isTerminalDeploymentStatus(dep.status)) {
+        waitDone = true;
+      } else {
+        const totalTimeoutMs = Math.max(10, Number.parseInt(opts.waitTimeout, 10) || 300) * 1000;
+        if (!isJsonMode()) {
+          printStep(`Following events for ${c.bold(dep.deploymentId)} (timeout ${Math.round(totalTimeoutMs / 1000)}s)…`);
+        }
+        const result = await followDeploymentEvents({
+          organizationId: orgId,
+          deploymentId: dep.deploymentId,
+          totalTimeoutMs,
+          onEvent: (event) => {
+            if (!isJsonMode()) {
+              printInfo(formatEventLine2(event));
+            }
           }
+        });
+        terminalEvent = result.terminalEvent;
+        waitDone = result.done;
+        if (!waitDone && !isJsonMode()) {
+          printError(`Deploy did not reach a terminal state within ${Math.round(totalTimeoutMs / 1000)}s. Check \`mcp deployments get ${dep.deploymentId}\` and \`mcp deployments health ${dep.deploymentId}\`, or tail \`mcp deployments logs ${dep.deploymentId} --follow\`.`);
         }
-      });
-      terminalEvent = result.terminalEvent;
-      waitDone = result.done;
-      if (!waitDone && !isJsonMode()) {
-        printError(`Deploy did not reach a terminal state within ${Math.round(totalTimeoutMs / 1000)}s. Run \`mcp --json servers test-runs get ${dep.deploymentId}\` (or the dashboard) to keep watching.`);
       }
     }
     if (isJsonMode()) {
@@ -4542,7 +4623,7 @@ function registerServerLifecycleCommands(servers) {
     printSuccess(`Deployment ${c.bold(dep.deploymentId)} created.`);
     printKeyValue({
       id: dep.deploymentId,
-      url: dep.deploymentUrl,
+      ...dep.deploymentUrl ? { url: dep.deploymentUrl } : {},
       target: dep.target,
       "access mode": dep.accessMode,
       status: dep.status,
@@ -4552,6 +4633,9 @@ function registerServerLifecycleCommands(servers) {
         "terminal at": formatDate(terminalEvent.timestamp)
       } : {}
     });
+    if (!opts.wait && dep.status === "queued") {
+      printInfo(`Deploy is running in the background — follow with \`mcp deployments get ${dep.deploymentId}\` or rerun with --wait.`);
+    }
     if (opts.wait && !waitDone)
       throw new CliExitError(1);
   }));
@@ -4643,23 +4727,27 @@ function registerServerLifecycleCommands(servers) {
     let terminalEvent = null;
     let waitDone = !opts.wait;
     if (opts.wait) {
-      const totalTimeoutMs = Math.max(10, Number.parseInt(opts.waitTimeout, 10) || 300) * 1000;
-      if (!isJsonMode()) {
-        printStep(`Following events for ${c.bold(dep.deploymentId)}…`);
-      }
-      const r = await followDeploymentEvents({
-        organizationId: orgId,
-        deploymentId: dep.deploymentId,
-        totalTimeoutMs,
-        onEvent: (event) => {
-          if (!isJsonMode())
-            printInfo(formatEventLine2(event));
+      if (isTerminalDeploymentStatus(dep.status)) {
+        waitDone = true;
+      } else {
+        const totalTimeoutMs = Math.max(10, Number.parseInt(opts.waitTimeout, 10) || 300) * 1000;
+        if (!isJsonMode()) {
+          printStep(`Following events for ${c.bold(dep.deploymentId)}…`);
+        }
+        const r = await followDeploymentEvents({
+          organizationId: orgId,
+          deploymentId: dep.deploymentId,
+          totalTimeoutMs,
+          onEvent: (event) => {
+            if (!isJsonMode())
+              printInfo(formatEventLine2(event));
+          }
+        });
+        terminalEvent = r.terminalEvent;
+        waitDone = r.done;
+        if (!waitDone && !isJsonMode()) {
+          printError(`Deploy did not reach a terminal state within ${Math.round(totalTimeoutMs / 1000)}s. Check \`mcp deployments get ${dep.deploymentId}\` and \`mcp deployments health ${dep.deploymentId}\`, or tail \`mcp deployments logs ${dep.deploymentId} --follow\`.`);
         }
-      });
-      terminalEvent = r.terminalEvent;
-      waitDone = r.done;
-      if (!waitDone && !isJsonMode()) {
-        printError(`Deploy did not reach a terminal state within ${Math.round(totalTimeoutMs / 1000)}s.`);
       }
     }
     if (isJsonMode()) {
@@ -4678,7 +4766,7 @@ function registerServerLifecycleCommands(servers) {
     printSuccess(`Deployment ${c.bold(dep.deploymentId)} created.`);
     printKeyValue({
       id: dep.deploymentId,
-      url: dep.deploymentUrl,
+      ...dep.deploymentUrl ? { url: dep.deploymentUrl } : {},
       target: dep.target,
       "access mode": dep.accessMode,
       status: dep.status,
@@ -4688,6 +4776,9 @@ function registerServerLifecycleCommands(servers) {
         "terminal at": formatDate(terminalEvent.timestamp)
       } : {}
     });
+    if (!opts.wait && dep.status === "queued") {
+      printInfo(`Deploy is running in the background — follow with \`mcp deployments get ${dep.deploymentId}\` or rerun with --wait.`);
+    }
     if (opts.wait && !waitDone)
       throw new CliExitError(1);
   }));
@@ -5533,6 +5624,9 @@ import { dirname as dirname5, join as join8 } from "node:path";
 // src/lib/dev/state.ts
 import { existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join6, resolve as resolve5 } from "node:path";
+function cachedStateMatchesTarget(cached2, target) {
+  return cached2 !== null && cached2.serverId === target.serverId && cached2.organizationId === target.organizationId;
+}
 function devRoot(cwd) {
   return join6(cwd, ".mcpcloud");
 }
@@ -7441,7 +7535,7 @@ function diffLine2(label, applied, suggested) {
 // src/commands/tools.ts
 function registerToolCommands(program2) {
   const tools = program2.command("tools").description("Inspect and edit tools on a project or server");
-  tools.command("list").description("List tools for a project (or pass --server to look up its project automatically)").option("--org <organizationId>", "Organization ID").option("--project <projectId>", "Project ID to list tools for").option("--server <serverId>", "Server ID — the CLI fetches the server's projectId before listing tools").action(runAction(async (opts) => {
+  tools.command("list").description("List tools for a project, or scope to a single server with --server").option("--org <organizationId>", "Organization ID").option("--project <projectId>", "List every tool in this project").option("--server <serverId>", "List only the tools that belong to this server (the CLI resolves its project, fetches the project tools, then filters to this server)").action(runAction(async (opts) => {
     const orgId = await resolveOrgId(opts.org);
     if (!opts.project && !opts.server) {
       throw new Error("Pass either --project <projectId> or --server <serverId>.");
@@ -7458,10 +7552,11 @@ function registerToolCommands(program2) {
       organizationId: orgId,
       projectId
     });
-    printList(data.tools.map((t) => ({
+    const rows = opts.server ? data.tools.filter((t) => t.serverId === opts.server) : data.tools;
+    printList(rows.map((t) => ({
       name: t.name,
-      method: t.method,
-      path: t.path,
+      method: t.endpoint?.method ?? t.method ?? "—",
+      path: t.endpoint?.path ?? t.path ?? "—",
       enrichment: t.enrichmentStatus ?? "—",
       description: t.description.slice(0, 60) + (t.description.length > 60 ? "…" : "")
     })), [
@@ -7470,7 +7565,7 @@ function registerToolCommands(program2) {
       { key: "path", label: "Path", width: 32 },
       { key: "enrichment", label: "Enrichment", width: 12 },
       { key: "description", label: "Description", width: 60 }
-    ], data);
+    ], opts.server ? { ...data, tools: rows } : data);
   }));
   registerToolsShowCommand(tools);
   registerToolsDiffCommand(tools);
@@ -9035,7 +9130,7 @@ function previewKey2(key) {
 }
 function registerConfigCommands(program2) {
   const config = program2.command("config").description("Manage CLI configuration in ~/.mcpcloud/config.json");
-  config.command("show").description("Print the active profile (API key is redacted)").action(runAction(() => {
+  const showActiveProfile = runAction(() => {
     const cfg = readConfig();
     const profile2 = getActiveProfileName();
     const safe = {
@@ -9052,14 +9147,16 @@ function registerConfigCommands(program2) {
     printKeyValue({
       path: safe.path,
       profile: safe.profile,
-      "base url": safe.baseUrl ?? "—",
+      "base url": safe.baseUrl ?? "— (built-in default)",
       "app url": cfg.appUrl ?? "— (auto-derived)",
       "default org": safe.defaultOrganizationId ?? "—",
       "api key": safe.apiKeyPreview ?? "—",
       editor: cfg.editorCommand ?? "code",
       "editor open": cfg.editorOpenPreference ?? "ask"
     });
-  }));
+  });
+  config.command("show").description("Print the active profile (API key is redacted)").action(showActiveProfile);
+  config.command("current").description("Alias for `config show` — print the active profile").action(showActiveProfile);
   config.command("set-url <url>").description("Save the API base URL to ~/.mcpcloud/config.json").action(runAction((url) => {
     try {
       new URL(url);
@@ -9629,7 +9726,7 @@ async function runDevReplay(opts) {
     printInfo("No matching records in .mcpcloud/inspector/. Use --from / --since / --filter, or run something first.");
     return;
   }
-  const baseUrl = opts.url ?? resolveBaseUrl(cwd);
+  const baseUrl = opts.url ?? resolveBaseUrl2(cwd);
   if (!opts.dryRun && !baseUrl) {
     printError("No running mcp dev session in this directory. Start `mcp dev`, or pass --url <baseUrl>.");
     throw new CliExitError(1);
@@ -9707,7 +9804,7 @@ function parseLimit(raw) {
   }
   return n;
 }
-function resolveBaseUrl(cwd) {
+function resolveBaseUrl2(cwd) {
   const sessions = listSessions().filter((s) => s.cwd === cwd);
   if (sessions.length === 0)
     return null;
@@ -11220,8 +11317,13 @@ async function fetchBundle(args) {
     } catch {
       body = null;
     }
-    const message = body?.error?.message ?? `Bundle download failed (${res.status}).`;
-    throw new Error(message);
+    const envelope = body?.error;
+    const requestId = envelope?.requestId ?? res.headers?.get?.("x-request-id") ?? null;
+    throw new McpCloudApiError(res.status, {
+      code: envelope?.code ?? `http_${res.status}`,
+      message: envelope?.message ?? `Bundle download failed (${res.status}).`,
+      ...requestId ? { requestId } : {}
+    });
   }
   const text = await res.text();
   const parsed = JSON.parse(text);
@@ -25781,7 +25883,7 @@ if (!root) throw new Error("Missing #root mount node");
 clientExports.createRoot(root).render(
   /* @__PURE__ */ jsxRuntimeExports.jsx(reactExports.StrictMode, { children: /* @__PURE__ */ jsxRuntimeExports.jsx(App, {}) })
 );</script>
-    <style rel="stylesheet" crossorigin>/*! tailwindcss v4.3.0 | MIT License | https://tailwindcss.com */
+    <style rel="stylesheet" crossorigin>/*! tailwindcss v4.3.2 | MIT License | https://tailwindcss.com */
 @layer properties {
   @supports (((-webkit-hyphens: none)) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color: rgb(from red r g b)))) {
     *, :before, :after, ::backdrop {
@@ -26116,7 +26218,7 @@ clientExports.createRoot(root).render(
   }
 
   .top-0 {
-    top: calc(var(--spacing) * 0);
+    top: 0;
   }
 
   .z-10 {
@@ -26124,7 +26226,7 @@ clientExports.createRoot(root).render(
   }
 
   .m-0 {
-    margin: calc(var(--spacing) * 0);
+    margin: 0;
   }
 
   .mx-auto {
@@ -26136,7 +26238,7 @@ clientExports.createRoot(root).render(
   }
 
   .mt-1 {
-    margin-top: calc(var(--spacing) * 1);
+    margin-top: var(--spacing);
   }
 
   .mt-3 {
@@ -26144,7 +26246,7 @@ clientExports.createRoot(root).render(
   }
 
   .mb-1 {
-    margin-bottom: calc(var(--spacing) * 1);
+    margin-bottom: var(--spacing);
   }
 
   .mb-2\\.5 {
@@ -26152,7 +26254,7 @@ clientExports.createRoot(root).render(
   }
 
   .ml-1 {
-    margin-left: calc(var(--spacing) * 1);
+    margin-left: var(--spacing);
   }
 
   .ml-2 {
@@ -26201,7 +26303,7 @@ clientExports.createRoot(root).render(
   }
 
   .min-w-0 {
-    min-width: calc(var(--spacing) * 0);
+    min-width: 0;
   }
 
   .min-w-\\[240px\\] {
@@ -26253,7 +26355,7 @@ clientExports.createRoot(root).render(
   }
 
   .gap-1 {
-    gap: calc(var(--spacing) * 1);
+    gap: var(--spacing);
   }
 
   .gap-1\\.5 {
@@ -26329,7 +26431,7 @@ clientExports.createRoot(root).render(
   }
 
   .p-0 {
-    padding: calc(var(--spacing) * 0);
+    padding: 0;
   }
 
   .p-2 {
@@ -26341,7 +26443,7 @@ clientExports.createRoot(root).render(
   }
 
   .px-1 {
-    padding-inline: calc(var(--spacing) * 1);
+    padding-inline: var(--spacing);
   }
 
   .px-1\\.5 {
@@ -26369,7 +26471,7 @@ clientExports.createRoot(root).render(
   }
 
   .py-1 {
-    padding-block: calc(var(--spacing) * 1);
+    padding-block: var(--spacing);
   }
 
   .py-2 {
@@ -27495,8 +27597,12 @@ async function prepareDev(opts) {
   const env = envFile(cwd);
   const backups = backupsDir(cwd);
   const cached2 = readState(cwd);
-  let projectId = cached2?.projectId;
-  let serverName = cached2?.serverName;
+  const cacheIsForTarget = cachedStateMatchesTarget(cached2, {
+    serverId: opts.serverId,
+    organizationId: opts.organizationId
+  });
+  let projectId = cacheIsForTarget ? cached2.projectId : undefined;
+  let serverName = cacheIsForTarget ? cached2.serverName : undefined;
   let gitNative = false;
   let repoDir;
   const gitLink = opts.offline ? null : await resolveServerGitLink({
@@ -28463,7 +28569,8 @@ async function runDev(opts) {
   const cwd = process.cwd();
   const cached2 = readState(cwd);
   let serverId = opts.server ?? cached2?.serverId;
-  let organizationId = opts.org ?? cached2?.organizationId ?? undefined;
+  const serverCameFromCache = !opts.server && Boolean(cached2?.serverId);
+  let organizationId = opts.org ?? (serverCameFromCache ? cached2?.organizationId ?? undefined : undefined);
   if (!opts.server && cached2?.serverId && canRunInteractive()) {
     const choice = await promptResumeOrSwitch({
       serverId: cached2.serverId,
@@ -29575,19 +29682,15 @@ function checkActiveProfile() {
     ms: Date.now() - t0
   };
 }
+var BASE_URL_SOURCE_LABEL = {
+  flag: "--base-url flag",
+  env: "env var",
+  profile: "profile",
+  default: "built-in default"
+};
 function checkBaseUrl() {
   const t0 = Date.now();
-  const fromOverride = process.env["MCPCLOUD_BASE_URL"];
-  const fromConfig = readConfig().baseUrl;
-  const url = fromOverride ?? fromConfig;
-  if (!url) {
-    return {
-      name: "Base URL",
-      status: "fail",
-      detail: "Not configured. Run `mcp config set-url <url>` or set MCPCLOUD_BASE_URL.",
-      ms: Date.now() - t0
-    };
-  }
+  const { url, source } = resolveBaseUrl();
   try {
     new URL(url);
   } catch {
@@ -29598,11 +29701,11 @@ function checkBaseUrl() {
       ms: Date.now() - t0
     };
   }
-  const source = fromOverride ? "env var" : "profile";
+  const prodMarker = isProductionBaseUrl(url) ? " (production)" : "";
   return {
     name: "Base URL",
     status: "pass",
-    detail: `${url} (from ${source})`,
+    detail: `${url}${prodMarker} (from ${BASE_URL_SOURCE_LABEL[source]})`,
     ms: Date.now() - t0
   };
 }
@@ -30006,7 +30109,7 @@ function registerHelpCommand(program2) {
   });
 }
 
-// src/commands/init.ts
+// src/commands/init-shared.ts
 import { createInterface as createInterface2 } from "node:readline";
 function prompt2(question) {
   if (isNonInteractive()) {
@@ -30022,7 +30125,10 @@ function prompt2(question) {
 }
 async function pickProject(orgId, override) {
   if (override) {
-    const data = await api.get("/api/v1/project", { organizationId: orgId, projectId: override });
+    const data = await api.get("/api/v1/project", {
+      organizationId: orgId,
+      projectId: override
+    });
     return { project: data.project, created: false };
   }
   const list = await api.get("/api/v1/projects", { organizationId: orgId, limit: "25" });
@@ -30075,67 +30181,15 @@ async function pickServerName(override) {
     throw new Error("Server name must not be empty.");
   return name;
 }
-function registerInitCommand(program2) {
-  program2.command("init").description("Guided onboarding: pick org → pick/create project → create a server (empty skeleton, or generated from an OpenAPI/GraphQL spec via --from-spec)").option("--org <organizationId>", "Organization ID").option("--project <projectId>", "Reuse an existing project instead of creating one").option("--name <serverName>", "Name for the new server (skeleton path only)").option("--from-spec <file|url>", "Build from an OpenAPI spec (local file, http(s) URL, or @- for stdin), or — with --source-type graphql — a GraphQL endpoint URL to introspect").option("--source-type <type>", `Override spec classification: ${SOURCE_TYPES.join(" | ")} (OpenAPI auto-detected; graphql requires an endpoint URL)`).option("--deploy", "After importing the spec, deploy the server").option("--wait", "With --deploy, follow events until the deploy is terminal").option("--wait-timeout <seconds>", "Max seconds to wait for a terminal deploy state (default 300)", "300").addHelpText("after", [
-    "",
-    "Two modes:",
-    "  Skeleton (default): resolve org → pick/create project → create an empty server.",
-    "  Spec (--from-spec):  resolve org → pick/create project → ingest the spec into a",
-    "                       generated server, then optionally --deploy [--wait].",
-    "",
-    "Examples:",
-    "  $ mcp init",
-    '  $ mcp init --org org_acme --project proj_123 --name "Stripe MCP"',
-    "  $ mcp init --from-spec ./openapi.yaml --project proj_123",
-    "  $ mcp init --from-spec https://api.example.com/openapi.json --project proj_123 --deploy --wait"
-  ].join(`
-`)).action(runAction(async (opts) => {
-    const orgId = await resolveOrgId(opts.org);
-    if (opts.fromSpec) {
-      await runSpecInit({ orgId, opts });
-      return;
-    }
-    if (!isJsonMode()) {
-      const orgs = await api.get("/api/v1/organizations");
-      const org = orgs.organizations.find((o) => o.id === orgId);
-      printStep(`Using organization ${c.bold(org?.name ?? orgId)} ${c.dim("(" + orgId + ")")}`);
-    }
-    const { project, created: projectCreated } = await pickProject(orgId, opts.project);
-    if (!isJsonMode()) {
-      if (projectCreated) {
-        printSuccess(`Project ${c.bold(project.name)} created (${project.id}).`);
-      } else {
-        printStep(`Using project ${c.bold(project.name)} ${c.dim("(" + project.id + ")")}`);
-      }
-    }
-    const serverName = await pickServerName(opts.name);
-    if (!isJsonMode()) {
-      printStep(`Creating server skeleton ${c.bold(serverName)}…`);
-    }
-    const serverData = await api.post("/api/v1/servers", {
-      organizationId: orgId,
-      projectId: project.id,
-      name: serverName
-    });
-    const server = serverData.server;
-    if (isJsonMode()) {
-      printJson({
-        organizationId: orgId,
-        project,
-        projectCreated,
-        server
-      });
-      return;
-    }
-    printSuccess(`Server ${c.bold(server.id)} ready.`);
-    printInfo("");
-    printInfo("Next steps:");
-    printInfo(`  1. Import an API spec: \`mcp servers ingest --project ${project.id} --spec ./openapi.yaml\``);
-    printInfo(`     ${c.dim("(or re-run `mcp init --from-spec ./openapi.yaml` for the guided flow)")}`);
-    printInfo(`  2. Run \`mcp dev --spec ./openapi.yaml\` to iterate locally.`);
-    printInfo(`  3. \`mcp servers deploy ${server.id} --wait\` to ship it.`);
-  }));
+function reportProject(project, created) {
+  if (isJsonMode())
+    return;
+  if (created) {
+    printSuccess(`Project ${c.bold(project.name)} created (${project.id}).`);
+  }
 }
+
+// src/commands/init-spec.ts
 function validateSourceType2(value) {
   if (value === undefined)
     return;
@@ -30145,6 +30199,52 @@ function validateSourceType2(value) {
   }
   return v2;
 }
+async function deployIngestedServer(args) {
+  return await api.post("/api/v1/server/deploy", {
+    organizationId: args.orgId,
+    projectId: args.projectId,
+    serverId: args.serverId,
+    target: "workersDev",
+    accessMode: "public",
+    runtimeConfig: {
+      upstreamBaseUrl: null,
+      upstreamApiKey: null,
+      upstreamApiKeyHeader: null,
+      upstreamApiKeyPrefix: null,
+      upstreamCustomHeaders: null,
+      additionalPlainTextBindings: null,
+      additionalSecretBindings: null
+    }
+  });
+}
+async function runDeployStep(args) {
+  const { orgId, projectId, serverId, opts } = args;
+  if (!isJsonMode())
+    printStep(`Deploying ${c.bold(serverId)}…`);
+  const deployData = await deployIngestedServer({ orgId, projectId, serverId });
+  const dep = deployData.deployment;
+  let waitDone = !opts.wait;
+  let terminalEvent = null;
+  if (opts.wait) {
+    if (isTerminalDeploymentStatus(dep.status)) {
+      waitDone = true;
+    } else {
+      const totalTimeoutMs = Math.max(10, Number.parseInt(opts.waitTimeout, 10) || 300) * 1000;
+      const followed = await followDeploymentEvents({
+        organizationId: orgId,
+        deploymentId: dep.deploymentId,
+        totalTimeoutMs,
+        onEvent: (event) => {
+          if (!isJsonMode())
+            printInfo(formatEventLine(event));
+        }
+      });
+      waitDone = followed.done;
+      terminalEvent = followed.terminalEvent;
+    }
+  }
+  return { deployment: dep, waitDone, terminalEvent };
+}
 async function runSpecInit(args) {
   const { orgId, opts } = args;
   if (opts.name && !isJsonMode()) {
@@ -30153,46 +30253,36 @@ async function runSpecInit(args) {
   const sourceType = validateSourceType2(opts.sourceType);
   const payload = await readSpecSource(opts.fromSpec, sourceType);
   const { project, created: projectCreated } = await pickProject(orgId, opts.project);
-  if (!isJsonMode() && projectCreated) {
-    printSuccess(`Project ${c.bold(project.name)} created (${project.id}).`);
-  }
+  reportProject(project, projectCreated);
   if (!isJsonMode()) {
     printStep(`Importing ${c.bold(payload.sourceType)} spec into ${c.bold(project.name)}…`);
   }
-  const ingest = await api.post("/api/v1/server/ingest", buildIngestBody({
-    organizationId: orgId,
-    projectId: project.id,
-    payload
-  }));
+  const ingest = await api.post("/api/v1/server/ingest", buildIngestBody({ organizationId: orgId, projectId: project.id, payload }));
   const server = ingest.server;
   if (!isJsonMode()) {
     printSuccess(`Server ${c.bold(server.id)} created from spec.`);
   }
   let deployResult = null;
   if (opts.deploy) {
-    if (!isJsonMode())
-      printStep(`Deploying ${c.bold(server.id)}…`);
-    const deployData = await api.post("/api/v1/server/deploy", {
-      organizationId: orgId,
-      serverId: server.id
-    });
-    let waitDone = !opts.wait;
-    let terminalEvent = null;
-    if (opts.wait) {
-      const totalTimeoutMs = Math.max(10, Number.parseInt(opts.waitTimeout, 10) || 300) * 1000;
-      const followed = await followDeploymentEvents({
-        organizationId: orgId,
-        deploymentId: deployData.deployment.deploymentId,
-        totalTimeoutMs,
-        onEvent: (event) => {
-          if (!isJsonMode())
-            printInfo(formatEventLine(event));
-        }
+    try {
+      deployResult = await runDeployStep({
+        orgId,
+        projectId: project.id,
+        serverId: server.id,
+        opts
       });
-      waitDone = followed.done;
-      terminalEvent = followed.terminalEvent;
+    } catch (err) {
+      reportDeployFailure({
+        serverId: server.id,
+        projectId: project.id,
+        project,
+        projectCreated,
+        apiSource: ingest.apiSource,
+        server,
+        err
+      });
+      throw err;
     }
-    deployResult = { deployment: deployData.deployment, waitDone, terminalEvent };
   }
   if (isJsonMode()) {
     printJson({
@@ -30208,21 +30298,7 @@ async function runSpecInit(args) {
     return;
   }
   if (deployResult) {
-    const dep = deployResult.deployment;
-    printSuccess(`Deployment ${c.bold(dep.deploymentId)} created.`);
-    printKeyValue({
-      "server id": server.id,
-      "deployment id": dep.deploymentId,
-      url: dep.deploymentUrl ?? "—",
-      target: dep.target,
-      "access mode": dep.accessMode,
-      status: dep.status
-    });
-    if (opts.wait && !deployResult.waitDone) {
-      printError(`Deploy did not reach a terminal state in time. Watch with \`mcp deployments logs ${dep.deploymentId} --follow\`.`);
-      throw new CliExitError(1);
-    }
-    printStep(`Try it: \`mcp invoke ${server.id} <tool>\`.`);
+    reportDeploySuccess({ serverId: server.id, result: deployResult, opts });
     return;
   }
   printInfo("");
@@ -30230,6 +30306,111 @@ async function runSpecInit(args) {
   printStep(`Generate the bundle: \`mcp servers generate ${server.id} --out ./build\``);
   printStep(`Deploy it: \`mcp servers deploy ${server.id} --wait\``);
 }
+function resumeDeployCommand(serverId, projectId) {
+  return `mcp servers deploy ${serverId} --project ${projectId} --wait`;
+}
+function reportDeployFailure(args) {
+  const resume = resumeDeployCommand(args.serverId, args.projectId);
+  if (isJsonMode()) {
+    const message = args.err instanceof Error ? args.err.message : String(args.err);
+    printJson({
+      project: args.project,
+      projectCreated: args.projectCreated,
+      apiSource: args.apiSource,
+      server: args.server,
+      deploy: null,
+      deployFailed: true,
+      deployError: { message },
+      resumeCommand: resume
+    });
+    return;
+  }
+  printError(`Server ${c.bold(args.serverId)} was created, but the deploy step failed.`);
+  printInfo("");
+  printInfo("Created so far:");
+  printKeyValue({ "server id": args.serverId, "project id": args.projectId });
+  printInfo("");
+  printInfo(`Resume the deploy once the cause is cleared:`);
+  printStep(resume);
+  printInfo("");
+}
+function reportDeploySuccess(args) {
+  const { serverId, result, opts } = args;
+  const dep = result.deployment;
+  printSuccess(`Deployment ${c.bold(dep.deploymentId)} created.`);
+  printKeyValue({
+    "server id": serverId,
+    "deployment id": dep.deploymentId,
+    url: dep.deploymentUrl ?? "—",
+    target: dep.target,
+    "access mode": dep.accessMode,
+    status: dep.status
+  });
+  if (opts.wait && !result.waitDone) {
+    printError(`Deploy did not reach a terminal state in time. Check \`mcp deployments get ${dep.deploymentId}\` and \`mcp deployments health ${dep.deploymentId}\`, or tail \`mcp deployments logs ${dep.deploymentId} --follow\`.`);
+    throw new CliExitError(1);
+  }
+  printStep(`Try it: \`mcp invoke ${serverId} <tool>\`.`);
+}
+
+// src/commands/init.ts
+function registerInitCommand(program2) {
+  program2.command("init").description("Guided onboarding: pick org → pick/create project → create a server (empty skeleton, or generated from an OpenAPI/GraphQL spec via --from-spec)").option("--org <organizationId>", "Organization ID").option("--project <projectId>", "Reuse an existing project instead of creating one").option("--name <serverName>", "Name for the new server (skeleton path only)").option("--from-spec <file|url>", "Build from an OpenAPI spec (local file, http(s) URL, or @- for stdin), or — with --source-type graphql — a GraphQL endpoint URL to introspect").option("--source-type <type>", `Override spec classification: ${SOURCE_TYPES.join(" | ")} (OpenAPI auto-detected; graphql requires an endpoint URL)`).option("--deploy", "After importing the spec, deploy the server").option("--wait", "With --deploy, follow events until the deploy is terminal").option("--wait-timeout <seconds>", "Max seconds to wait for a terminal deploy state (default 300)", "300").addHelpText("after", [
+    "",
+    "Two modes:",
+    "  Skeleton (default): resolve org → pick/create project → create an empty server.",
+    "  Spec (--from-spec):  resolve org → pick/create project → ingest the spec into a",
+    "                       generated server, then optionally --deploy [--wait].",
+    "",
+    "Examples:",
+    "  $ mcp init",
+    '  $ mcp init --org org_acme --project proj_123 --name "Stripe MCP"',
+    "  $ mcp init --from-spec ./openapi.yaml --project proj_123",
+    "  $ mcp init --from-spec https://api.example.com/openapi.json --project proj_123 --deploy --wait"
+  ].join(`
+`)).action(runAction(runInit));
+}
+async function runInit(opts) {
+  const orgId = await resolveOrgId(opts.org);
+  if (opts.fromSpec) {
+    await runSpecInit({ orgId, opts });
+    return;
+  }
+  await runSkeletonInit({ orgId, opts });
+}
+async function runSkeletonInit(args) {
+  const { orgId, opts } = args;
+  if (!isJsonMode()) {
+    const orgs = await api.get("/api/v1/organizations");
+    const org = orgs.organizations.find((o) => o.id === orgId);
+    printStep(`Using organization ${c.bold(org?.name ?? orgId)} ${c.dim("(" + orgId + ")")}`);
+  }
+  const { project, created: projectCreated } = await pickProject(orgId, opts.project);
+  if (!isJsonMode()) {
+    if (projectCreated) {
+      printSuccess(`Project ${c.bold(project.name)} created (${project.id}).`);
+    } else {
+      printStep(`Using project ${c.bold(project.name)} ${c.dim("(" + project.id + ")")}`);
+    }
+  }
+  const serverName = await pickServerName(opts.name);
+  if (!isJsonMode()) {
+    printStep(`Creating server skeleton ${c.bold(serverName)}…`);
+  }
+  const serverData = await api.post("/api/v1/servers", { organizationId: orgId, projectId: project.id, name: serverName });
+  const server = serverData.server;
+  if (isJsonMode()) {
+    printJson({ organizationId: orgId, project, projectCreated, server });
+    return;
+  }
+  printSuccess(`Server ${c.bold(server.id)} ready.`);
+  printInfo("");
+  printInfo("Next steps:");
+  printInfo(`  1. Import an API spec: \`mcp servers ingest --project ${project.id} --spec ./openapi.yaml\``);
+  printInfo(`     ${c.dim("(or re-run `mcp init --from-spec ./openapi.yaml` for the guided flow)")}`);
+  printInfo(`  2. Run \`mcp dev --spec ./openapi.yaml\` to iterate locally.`);
+  printInfo(`  3. \`mcp servers deploy ${server.id} --wait\` to ship it.`);
+}
 
 // src/commands/installation.ts
 function registerInstallationCommands(program2) {
@@ -30920,6 +31101,7 @@ function registerUsageCommands(program2) {
       allowed: t.allowedCount,
       "billable invocations": usageData.usage.invocations?.billableCount ?? t.allowedToolCallCount ?? 0,
       "invocation cost": formatMicros(usageData.usage.invocations?.billedMicros),
+      "projected monthly": formatMicros(usageData.usage.invocations?.projectedMonthlyMicros),
       "rate-limited": t.rateLimitedCount,
       unauthorized: t.unauthorizedCount,
       failed: t.failedCount,
@@ -31127,6 +31309,73 @@ function registerOrgCommands(program2) {
   }));
 }
 
+// src/commands/connections.ts
+async function readKeyFromStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+function registerConnectionsCommands(program2) {
+  const connections = program2.command("connections").description("Manage your per-server upstream API keys (BYOK) from the terminal").addHelpText("after", [
+    "",
+    "Examples:",
+    "  $ mcp connections list",
+    "  $ mcp connections add <serverId> --key sk_live_…",
+    '  $ echo "$UPSTREAM_KEY" | mcp connections add <serverId> --key-stdin',
+    "  $ mcp connections remove <serverId>"
+  ].join(`
+`));
+  connections.command("list").description("List your stored upstream keys across servers (hints only)").action(runAction(async () => {
+    const data = await api.get("/api/v1/upstream-key");
+    if (isJsonMode()) {
+      printJson(data);
+      return;
+    }
+    printList(data.keys.map((entry) => ({
+      server: entry.serverName ?? entry.serverId,
+      key: `••••${entry.keyHint}`,
+      status: entry.status,
+      "last used": entry.lastUsedAt ? formatDate(entry.lastUsedAt) : "—",
+      updated: formatDate(entry.updatedAt)
+    })), [
+      { key: "server", label: "Server", width: 32 },
+      { key: "key", label: "Key", width: 10 },
+      { key: "status", label: "Status", width: 10 },
+      { key: "last used", label: "Last used", width: 22 },
+      { key: "updated", label: "Updated", width: 22 }
+    ], data);
+  }));
+  connections.command("add <serverId>").description("Save (or replace) your upstream API key for a server — rotation is just adding again").option("--key <apiKey>", "The upstream API key (visible in shell history)").option("--key-stdin", "Read the key from stdin instead (recommended for CI)").action(runAction(async (serverId, opts) => {
+    const apiKey = opts.keyStdin ? await readKeyFromStdin() : opts.key ?? "";
+    if (!apiKey.trim()) {
+      throw new Error("Provide the key via --key <apiKey> or pipe it with --key-stdin.");
+    }
+    const data = await api.post("/api/v1/upstream-key", { serverId, apiKey });
+    if (isJsonMode()) {
+      printJson(data);
+      return;
+    }
+    printKeyValue({
+      saved: String(data.saved),
+      key: `••••${data.keyHint}`,
+      note: "Stored encrypted; your next tool call uses it immediately."
+    });
+  }));
+  connections.command("remove <serverId>").description("Revoke your stored upstream key for a server").action(runAction(async (serverId) => {
+    const data = await api.delete("/api/v1/upstream-key", { serverId });
+    if (isJsonMode()) {
+      printJson(data);
+      return;
+    }
+    printKeyValue({
+      revoked: String(data.revoked),
+      note: data.revoked ? "Tool calls will prompt for a fresh key on next use." : "No active key was stored for this server."
+    });
+  }));
+}
+
 // src/lib/plugins.ts
 import { spawn as spawn7 } from "node:child_process";
 import {
@@ -35733,7 +35982,7 @@ function registerUpdateCommand(program2) {
 // src/create-program.ts
 function createProgram() {
   const program2 = new Command;
-  program2.name("mcp").description("The official CLI for MCPCloud — manage projects, MCP servers, skills, and API keys from the terminal").version(getCliVersion(), "-v, --version", "Print the CLI version").option("--json", "Output raw JSON (useful for scripting)").option("--base-url <url>", "API base URL for this invocation. Falls back to MCPCLOUD_BASE_URL or `mcp config set-url`.").option("--profile <name>", "Run against a named config profile for this invocation (overrides MCPCLOUD_PROFILE and the saved current profile).").option("--ci", "Force CI mode for this invocation. Auto-detected when CI=true. Disables color, swaps Unicode glyphs for ASCII, refuses interactive prompts, and always surfaces request IDs.").option("--warnings-as-errors", "Exit non-zero if any warning is emitted during the command (CI ergonomics).").option("--non-interactive", "Refuse interactive prompts (fail fast on missing input) without the color/glyph changes of --ci.").option("--quiet", "Suppress success/step/info chrome; data and errors still print. Pairs with exit codes for health/existence gates.").option("--format <mode>", "Output format for list commands: table (default), tsv, jsonl, json.").option("--no-table", "Shorthand for --format tsv. Tab-separated rows for awk/cut/grep pipelines.").option("--field <names>", "Comma-separated list of fields to include in list output (repeatable).", (value, prev) => prev ? [...prev, value] : [value]).option("--filter <key=substring>", "Substring filter for list rows (repeatable). Case-insensitive.", (value, prev) => prev ? [...prev, value] : [value]).option("--idempotency-key <key>", "Stable Idempotency-Key for mutations (1–255 ASCII chars, no whitespace). When omitted, the CLI auto-generates a UUID per invocation so internal retries on transient failures stay safe.").option("--debug", "Print every HTTP request/response with secrets redacted. Equivalent to MCPCLOUD_LOG=debug.").hook("preAction", (thisCommand) => {
+  program2.name("mcp").description("The official CLI for MCPCloud — manage projects, MCP servers, skills, and API keys from the terminal").version(getCliVersion(), "-v, --version", "Print the CLI version").option("--json", "Output raw JSON (useful for scripting)").option("--base-url <url>", "API base URL for this invocation. Falls back to MCPCLOUD_BASE_URL, `mcp config set-url`, then the built-in MCPCloud production default.").option("--profile <name>", "Run against a named config profile for this invocation (overrides MCPCLOUD_PROFILE and the saved current profile).").option("--ci", "Force CI mode for this invocation. Auto-detected when CI=true. Disables color, swaps Unicode glyphs for ASCII, refuses interactive prompts, and always surfaces request IDs.").option("--warnings-as-errors", "Exit non-zero if any warning is emitted during the command (CI ergonomics).").option("--non-interactive", "Refuse interactive prompts (fail fast on missing input) without the color/glyph changes of --ci.").option("--quiet", "Suppress success/step/info chrome; data and errors still print. Pairs with exit codes for health/existence gates.").option("--format <mode>", "Output format for list commands: table (default), tsv, jsonl, json.").option("--no-table", "Shorthand for --format tsv. Tab-separated rows for awk/cut/grep pipelines.").option("--field <names>", "Comma-separated list of fields to include in list output (repeatable).", (value, prev) => prev ? [...prev, value] : [value]).option("--filter <key=substring>", "Substring filter for list rows (repeatable). Case-insensitive.", (value, prev) => prev ? [...prev, value] : [value]).option("--idempotency-key <key>", "Stable Idempotency-Key for mutations (1–255 ASCII chars, no whitespace). When omitted, the CLI auto-generates a UUID per invocation so internal retries on transient failures stay safe.").option("--debug", "Print every HTTP request/response with secrets redacted. Equivalent to MCPCLOUD_LOG=debug.").hook("preAction", (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
     setJsonMode(Boolean(opts.json));
     setBaseUrlOverride(opts.baseUrl);
@@ -35753,21 +36002,22 @@ function createProgram() {
   }).addHelpText("after", [
     "",
     "Environment variables:",
-    "  MCPCLOUD_API_KEY    API key used for authentication (required)",
-    "  MCPCLOUD_BASE_URL   API base URL (required — no default is shipped)",
+    "  MCPCLOUD_API_KEY    API key used for authentication (or run `mcp login`)",
+    "  MCPCLOUD_BASE_URL   Override the API base URL (defaults to MCPCloud production)",
     "  MCPCLOUD_ORG_ID     Default organization ID",
     '  MCPCLOUD_PROFILE    Active config profile name (default: "default")',
     "  CI                  When truthy, enables CI mode automatically (no color, ASCII glyphs, no prompts)",
     "",
     "Examples:",
-    "  $ export MCPCLOUD_BASE_URL=https://your-deployment.example.com",
-    "  $ mcp config set-url https://your-deployment.example.com   # persist it",
-    "  $ mcp login",
+    "  $ mcp login                                                # sign in (production, out of the box)",
     "  $ mcp whoami",
     "  $ mcp skills connect skill_123 --agent claude-code --apply",
     "  $ mcp --json servers list",
     "  $ mcp servers list --field id,name --format jsonl",
-    "  $ mcp servers list --filter status=active --no-table"
+    "  $ mcp servers list --filter status=active --no-table",
+    "",
+    "Self-host / staging: point the CLI elsewhere with MCPCLOUD_BASE_URL,",
+    "`mcp config set-url <url>`, or --base-url <url> (each overrides the default)."
   ].join(`
 `));
   registerAuthCommands(program2);
@@ -35781,6 +36031,7 @@ function createProgram() {
   registerDeploymentCommands(program2);
   registerOrgCommands(program2);
   registerUsageCommands(program2);
+  registerConnectionsCommands(program2);
   registerMetricsCommands(program2);
   registerDevCommand(program2);
   registerCompletionCommand(program2);
@@ -35798,8 +36049,59 @@ function createProgram() {
   return program2;
 }
 
+// src/lib/first-run.ts
+function shouldShowFirstRunGreeting(input) {
+  if (input.hasCommand)
+    return false;
+  if (!input.isTty)
+    return false;
+  if (input.ciMode)
+    return false;
+  if (input.jsonMode)
+    return false;
+  if (input.authenticated)
+    return false;
+  if (input.hasSavedConfig)
+    return false;
+  return true;
+}
+function argvHasCommand(argv) {
+  return argv.slice(2).some((token) => !token.startsWith("-"));
+}
+function firstRunGreeting() {
+  return [
+    "Welcome to MCPCloud — turn an API spec into a deployed MCP server.",
+    "",
+    "Get started:",
+    "  1. mcp login             Sign in (opens your browser)",
+    "  2. mcp init              Scaffold a server from an OpenAPI / GraphQL spec",
+    "  3. mcp servers deploy    Ship it to the edge",
+    "",
+    "Run `mcp --help` for the full command reference.",
+    ""
+  ].join(`
+`);
+}
+
 // src/index.ts
+function maybeGreetFirstRun(argv) {
+  const cfg = readConfig();
+  const show = shouldShowFirstRunGreeting({
+    hasCommand: argvHasCommand(argv),
+    isTty: Boolean(process.stdout.isTTY),
+    ciMode: isCiEnv() || argv.includes("--ci"),
+    jsonMode: argv.includes("--json"),
+    authenticated: Boolean(getApiKey()),
+    hasSavedConfig: Boolean(cfg.baseUrl || cfg.apiKey || cfg.defaultOrganizationId)
+  });
+  if (!show)
+    return false;
+  process.stdout.write(firstRunGreeting());
+  return true;
+}
 async function main() {
+  if (maybeGreetFirstRun(process.argv))
+    return;
   const program2 = createProgram();
   if (process.env["MCPSH_DISABLE_PLUGINS"] !== "1") {
     await loadPlugins(program2);