@mks2508/coolify-mks-cli-mcp 0.6.2 → 0.8.0

package/src/cli/coolify-state.ts

@@ -8,21 +8,32 @@
  * @module
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 /**
- * State stored in .coolify.json (generated by create-bunspace deployer).
+ * State stored in .coolify.json (generated by create-bunspace deployer or init command).
+ *
+ * This file links a local directory to a Coolify deployment, storing all necessary
+ * UUIDs and metadata for CLI commands to work without manual UUID entry.
  */
 export interface ICoolifyDeployState {
   /** Application UUID in Coolify */
   appUuid: string;
+  /** Application name (for display purposes) */
+  appName?: string;
   /** Server UUID */
   serverUuid: string;
+  /** Server name (for display purposes) */
+  serverName?: string;
   /** Project UUID */
   projectUuid: string;
+  /** Project name (for display purposes) */
+  projectName?: string;
   /** Environment UUID */
   environmentUuid: string;
+  /** Environment name (for display purposes) */
+  environmentName?: string;
   /** Domain if configured */
   domain?: string;
   /** Docker compose or Dockerfile path */
@@ -31,18 +42,72 @@ export interface ICoolifyDeployState {
   baseDirectory?: string;
   /** Git branch */
   branch?: string;
-  /** Application type */
+  /** Git repository URL */
+  gitRepository?: string;
+  /** Application source type (github-app, deploy-key, docker-image, etc.) */
+  sourceType?: string;
+  /** Application type (legacy, may be undefined) */
   type?: string;
-  /** Build pack */
+  /** Build pack (dockerfile, nixpacks, static, dockercompose) */
   buildPack?: string;
   /** Auto-deploy enabled */
   autoDeployEnabled?: boolean;
+  /** When this state was last updated */
+  updatedAt?: string;
+  /** Coolify instance URL */
+  coolifyUrl?: string;
+}
+
+/**
+ * Multi-app state for monorepos deploying multiple services from one repo.
+ *
+ * Stored alongside or instead of the single-app state in .coolify.json.
+ */
+export interface ICoolifyMultiAppState {
+  /** All apps deployed from this repo */
+  apps: Array<{
+    /** Application UUID in Coolify */
+    uuid: string;
+    /** Application name */
+    name: string;
+    /** Service role (e.g. "backend", "admin", "docs", "proxy") */
+    service: string;
+    /** Domain if configured */
+    domain?: string;
+    /** Dockerfile path relative to repo root */
+    dockerfile?: string;
+    /** Exposed port */
+    port?: number;
+  }>;
+  /** Server UUID */
+  serverUuid: string;
+  /** Server name (for display purposes) */
+  serverName?: string;
+  /** Project UUID */
+  projectUuid: string;
+  /** Project name (for display purposes) */
+  projectName?: string;
+  /** Environment UUID */
+  environmentUuid: string;
+  /** Environment name (for display purposes) */
+  environmentName?: string;
+  /** Git branch */
+  branch?: string;
+  /** Git repository URL */
+  gitRepository?: string;
+  /** Coolify instance URL */
+  coolifyUrl?: string;
+  /** When this state was last updated */
+  updatedAt?: string;
 }
 
 const STATE_FILE = ".coolify.json";
 
 /**
- * Loads .coolify.json from the current working directory.
+ * Loads .coolify.json from the current working directory (single-app format).
+ *
+ * Handles both single-app and multi-app formats. For multi-app state with
+ * exactly one app, returns a synthesized single-app state for backward compat.
  *
  * @returns The deploy state if found, null otherwise
  */
@@ -55,21 +120,98 @@ export function loadCoolifyState(): ICoolifyDeployState | null {
 
   try {
     const content = readFileSync(statePath, "utf-8");
-    const state = JSON.parse(content) as ICoolifyDeployState;
+    const state = JSON.parse(content);
+
+    // Multi-app format — synthesize single-app state if exactly 1 app
+    if (Array.isArray(state.apps)) {
+      if (state.apps.length === 1) {
+        const app = state.apps[0];
+        return {
+          appUuid: app.uuid,
+          appName: app.name,
+          serverUuid: state.serverUuid,
+          serverName: state.serverName,
+          projectUuid: state.projectUuid,
+          projectName: state.projectName,
+          environmentUuid: state.environmentUuid,
+          environmentName: state.environmentName,
+          domain: app.domain,
+          branch: state.branch,
+          gitRepository: state.gitRepository,
+          coolifyUrl: state.coolifyUrl,
+          updatedAt: state.updatedAt,
+        };
+      }
+      // Multi-app with multiple apps — cannot auto-select
+      return null;
+    }
 
+    // Single-app format
     if (!state.appUuid) {
       return null;
     }
 
-    return state;
+    return state as ICoolifyDeployState;
   } catch {
     return null;
   }
 }
 
+/**
+ * Loads .coolify.json in multi-app format.
+ *
+ * If the file is in single-app format, returns null (use loadCoolifyState instead).
+ *
+ * @returns The multi-app state if found, null otherwise
+ */
+export function loadMultiAppState(): ICoolifyMultiAppState | null {
+  const statePath = join(process.cwd(), STATE_FILE);
+
+  if (!existsSync(statePath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(statePath, "utf-8");
+    const state = JSON.parse(content);
+
+    if (!Array.isArray(state.apps)) {
+      return null;
+    }
+
+    return state as ICoolifyMultiAppState;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes .coolify.json in multi-app format to the current working directory.
+ *
+ * @param state - The multi-app state to write
+ */
+export function writeMultiAppState(state: ICoolifyMultiAppState): void {
+  const statePath = join(process.cwd(), STATE_FILE);
+  writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Writes .coolify.json to the current working directory.
+ *
+ * @param state - The state to write
+ */
+export function writeCoolifyState(state: ICoolifyDeployState): void {
+  const statePath = join(process.cwd(), STATE_FILE);
+  writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
 /**
  * Resolves a UUID argument — if not provided, tries to read from .coolify.json.
  *
+ * Supports both single-app and multi-app state formats. For multi-app state
+ * with exactly one app, auto-selects that app. For multiple apps, returns null
+ * (user must specify explicitly).
+ *
  * @param uuid - UUID from CLI argument (may be undefined)
  * @param field - Which field to read from .coolify.json (default: appUuid)
  * @returns The resolved UUID or null if not found
@@ -78,11 +220,22 @@ export function resolveUuid(
   uuid: string | undefined,
   field: keyof ICoolifyDeployState = "appUuid",
 ): string | null {
-  if (uuid) return uuid;
+  // Only return directly if it looks like a UUID (lowercase alphanumeric, 16-40 chars)
+  // Names like "mks-backend" should fall through to .coolify.json or name resolver
+  if (uuid && /^[a-z0-9]{16,40}$/.test(uuid)) return uuid;
 
+  // Try single-app state first (also handles multi-app with 1 app)
   const state = loadCoolifyState();
-  if (!state) return null;
+  if (state) {
+    const value = state[field];
+    return typeof value === "string" ? value : null;
+  }
+
+  // Try multi-app state — only auto-resolve if exactly 1 app
+  const multiState = loadMultiAppState();
+  if (multiState && multiState.apps.length === 1 && field === "appUuid") {
+    return multiState.apps[0].uuid;
+  }
 
-  const value = state[field];
-  return typeof value === "string" ? value : null;
+  return null;
 }

package/src/cli/index.ts

@@ -9,12 +9,17 @@
 
 import { Command } from "commander";
 import chalk from "chalk";
+import { setVerbosity } from "@mks2508/better-logger";
+
+// Silence SDK logger in CLI mode — all progress goes through spinners/prompts
+setVerbosity("silent");
 import { createCommand } from "./commands/create.js";
 import { deployCommand } from "./commands/deploy.js";
 import { listCommand } from "./commands/list.js";
 import { logsCommand } from "./commands/logs.js";
 import { serversCommand } from "./commands/servers.js";
 import { projectsCommand } from "./commands/projects.js";
+import { statusCommand } from "./commands/status.js";
 import { environmentsCommand } from "./commands/environments.js";
 import { configCommand } from "./commands/config.js";
 import { envCommand } from "./commands/env.js";
@@ -28,6 +33,7 @@ import { stopCommand } from "./commands/stop.js";
 import { restartCommand } from "./commands/restart.js";
 import { buildLogsCommand } from "./commands/build-logs.js";
 import { serviceLogsCommand } from "./commands/service-logs.js";
+import { initCommand } from "./commands/init.js";
 import { versionCommand } from "./commands/version.js";
 import { databasesCommand } from "./commands/databases.js";
 import { servicesCommand as servicesListCommand } from "./commands/services.js";
@@ -37,6 +43,7 @@ import {
   dbListCommand,
   dbGetCommand,
   dbCreateCommand,
+  dbUpdateCommand,
   dbStartCommand,
   dbStopCommand,
   dbRestartCommand,
@@ -78,10 +85,22 @@ import {
 
 const program = new Command();
 
+// Detect binary name to show correct help
+const binaryName = process.argv[1]?.includes("coolify-cli") ? "coolify-cli" : "coolify-mcp";
+
 program
-  .name("coolify-mcp")
-  .description("CLI for Coolify deployment management")
-  .version("0.1.0");
+  .name(binaryName)
+  .description(
+    `${chalk.bold.hex("#8c52ff")("Coolify CLI")} — Manage deployments, env vars, and resources\n` +
+    `  Global: ${chalk.gray("bun install -g @mks2508/coolify-mks-cli-mcp")}`,
+  )
+  .version("0.8.0")
+  .addHelpText("beforeAll", () => {
+    // Show banner before help output
+    const { showAutoBanner } = require("./ui/banner.js");
+    showAutoBanner("0.8.0");
+    return "";
+  });
 
 // Create application
 program
@@ -126,6 +145,14 @@ program
     'Base directory for build context (default: "/")',
     "/",
   )
+  .option(
+    "--github-app-uuid <uuid>",
+    "GitHub App UUID (auto-detected if not provided)",
+  )
+  .option(
+    "--domain <domain>",
+    "Domain to set after creation (e.g., app.example.com or https://app.example.com)",
+  )
   .action(createCommand);
 
 // Config command
@@ -137,6 +164,16 @@ program
   .option("--value <value>", 'Configuration value (for "set" action)')
   .action(configCommand);
 
+// Init application (link existing or create new)
+program
+  .command("init")
+  .description("Initialize Coolify deployment (link existing or create new)")
+  .option("--yes", "Auto-mode with defaults")
+  .option("--force", "Ignore existing .coolify.json")
+  .option("--name <name>", "App name")
+  .option("--link", "Link-only mode (don't create new apps)")
+  .action(initCommand);
+
 // List applications
 program
   .command("list")
@@ -152,6 +189,8 @@ program
   .description("Deploy an application (reads .coolify.json if no UUID)")
   .option("-f, --force", "Force rebuild without cache")
   .option("-t, --tag <tag>", "Deploy specific tag/version")
+  .option("--all", "Deploy all apps from .coolify.json in parallel")
+  .option("--service <name>", "Deploy specific service from .coolify.json")
   .action(deployCommand);
 
 // Logs command
@@ -159,10 +198,17 @@ program
   .command("logs [uuid]")
   .description("Get application logs (reads .coolify.json if no UUID)")
   .option("-n, --lines <number>", "Number of lines to retrieve", "50")
-  .option("-f, --follow", "Follow logs in real-time")
+  .option("-f, --follow", "Follow logs in real-time (polls every 2s)")
+  .option("--errors", "Show errors only")
+  .option("--since <duration>", "Show logs since duration (e.g. 1h, 30m, 2d)")
   .action((uuid, options) => {
     const lines = parseInt(options.lines, 10);
-    logsCommand(uuid, { lines, follow: options.follow });
+    logsCommand(uuid, {
+      lines,
+      follow: options.follow,
+      errors: options.errors,
+      since: options.since,
+    });
   });
 
 // Servers command
@@ -172,6 +218,13 @@ program
 
   .action((options) => serversCommand(options));
 
+// Status dashboard
+program
+  .command("status")
+  .description("Show status dashboard")
+  .option("-w, --watch", "Auto-refresh every 5s")
+  .action((options) => statusCommand(options));
+
 // Projects command
 program
   .command("projects")
@@ -179,6 +232,8 @@ program
 
   .option("--create <name>", "Create a new project with this name")
   .option("--description <desc>", "Project description (use with --create)")
+  .option("--show <uuid>", "Show project details with environments, apps, and databases")
+  .option("--apps <uuid>", "Show all applications in a project")
   .action((options) => projectsCommand(options));
 
 // Environments command
@@ -195,6 +250,11 @@ program
   .option("--set <KEY=VALUE>", "Set an environment variable")
   .option("--delete <KEY>", "Delete an environment variable")
   .option("--buildtime", "Mark variable as build-time only (use with --set)")
+  .option("--runtime-only", "Mark variable as runtime only, not build-time (use with --set)")
+  .option("--sync [file]", "Sync env vars from .env file (default: .env)")
+  .option("--dry-run", "Preview changes without applying (use with --sync)")
+  .option("--prune", "Delete vars not in file (use with --sync)")
+  .option("--table", "Show env vars in table format")
   .action((uuid, options) => envCommand(uuid, options));
 
 // Update application
@@ -224,6 +284,14 @@ program
   .option("--auto-deploy", "Enable auto-deploy on git push")
   .option("--no-auto-deploy", "Disable auto-deploy on git push")
   .option("--force-https", "Enable forced HTTPS redirect")
+  .option("--health-check-enabled", "Enable health check")
+  .option("--no-health-check-enabled", "Disable health check")
+  .option("--health-check-path <path>", "Health check path (e.g., /health)")
+  .option("--health-check-port <port>", "Health check port")
+  .option("--health-check-interval <seconds>", "Health check interval in seconds")
+  .option("--health-check-timeout <seconds>", "Health check timeout in seconds")
+  .option("--health-check-retries <n>", "Health check retries")
+  .option("--health-check-start-period <seconds>", "Health check start period in seconds")
   .action((uuid, options) => updateCommand({ uuid, ...options }));
 
 // Delete application
@@ -335,6 +403,12 @@ db.command("list").description("List all databases").action(dbListCommand);
 db.command("get <uuid>")
   .description("Get database details")
   .action(dbGetCommand);
+db.command("update <uuid>")
+  .description("Update database configuration")
+  .option("--public-port <port>", "Publish port (e.g., 127.0.0.1:5432 or 5432)")
+  .option("--is-public", "Make database publicly accessible")
+  .option("--no-is-public", "Make database private")
+  .action((uuid, options) => dbUpdateCommand(uuid, options));
 db.command("create <type>")
   .description(
     "Create database (postgresql, mysql, mariadb, mongodb, redis, keydb, clickhouse, dragonfly)",
@@ -479,11 +553,18 @@ program
   .description("Analyze a failed deployment (extract errors, suggest fixes)")
   .action(analyzeDeployCommand);
 
-// Show help by default
-program.action(() => {
-  console.log(chalk.cyan("Coolify MCP CLI v0.6.0"));
-  console.log(chalk.gray("Manage Coolify deployments from the command line\n"));
-  program.help();
+// Show help by default (or interactive menu if no args)
+program.action(async () => {
+  // If called without arguments, show interactive menu
+  if (process.argv.length <= 2) {
+    const { mainMenu } = await import("./commands/main-menu.js");
+    await mainMenu();
+  } else {
+    // Show help if called with unknown command
+    console.log(chalk.cyan("Coolify MCP CLI v0.8.0"));
+    console.log(chalk.gray("Manage Coolify deployments from the command line\n"));
+    program.help();
+  }
 });
 
 program.parse();

package/src/cli/name-resolver.ts

@@ -0,0 +1,228 @@
+/**
+ * Name-to-UUID resolver for CLI.
+ *
+ * Allows users to reference Coolify resources by friendly name instead
+ * of UUID. Caches API responses in-memory during the CLI session.
+ *
+ * @module
+ */
+
+import { isOk } from "@mks2508/no-throw";
+import { getCoolifyService } from "../coolify/index.js";
+import type { ICoolifyApplication } from "../coolify/types.js";
+import type { ICoolifyDatabase } from "../coolify/types.js";
+import type { ICoolifyProject } from "../coolify/types.js";
+import type { ICoolifyService as ICoolifyServiceType } from "../coolify/types.js";
+
+/** In-memory cache for API responses during a single CLI session. */
+const cache = {
+  apps: null as ICoolifyApplication[] | null,
+  databases: null as ICoolifyDatabase[] | null,
+  services: null as ICoolifyServiceType[] | null,
+  projects: null as ICoolifyProject[] | null,
+};
+
+/**
+ * Checks if a string looks like a Coolify UUID.
+ *
+ * Coolify UUIDs are lowercase alphanumeric strings, typically 20-30 chars.
+ *
+ * @param value - The string to check
+ * @returns True if the string looks like a UUID
+ */
+function looksLikeUuid(value: string): boolean {
+  return /^[a-z0-9]{16,40}$/.test(value);
+}
+
+/**
+ * Fetches and caches the list of applications from Coolify API.
+ *
+ * @returns Array of applications, or empty array on error
+ */
+async function getApps(): Promise<ICoolifyApplication[]> {
+  if (cache.apps) return cache.apps;
+
+  const coolify = getCoolifyService();
+  const initResult = await coolify.init();
+  if (isOk(initResult)) {
+    const result = await coolify.listApplications();
+    if (isOk(result)) {
+      cache.apps = result.value;
+      return cache.apps;
+    }
+  }
+  return [];
+}
+
+/**
+ * Fetches and caches the list of databases from Coolify API.
+ *
+ * @returns Array of databases, or empty array on error
+ */
+async function getDatabases(): Promise<ICoolifyDatabase[]> {
+  if (cache.databases) return cache.databases;
+
+  const coolify = getCoolifyService();
+  const initResult = await coolify.init();
+  if (isOk(initResult)) {
+    const result = await coolify.listDatabases();
+    if (isOk(result)) {
+      cache.databases = result.value;
+      return cache.databases;
+    }
+  }
+  return [];
+}
+
+/**
+ * Fetches and caches the list of services from Coolify API.
+ *
+ * @returns Array of services, or empty array on error
+ */
+async function getServices(): Promise<ICoolifyServiceType[]> {
+  if (cache.services) return cache.services;
+
+  const coolify = getCoolifyService();
+  const initResult = await coolify.init();
+  if (isOk(initResult)) {
+    const result = await coolify.listServices();
+    if (isOk(result)) {
+      cache.services = result.value;
+      return cache.services;
+    }
+  }
+  return [];
+}
+
+/**
+ * Resolves a name or UUID to a UUID.
+ *
+ * Accepts: UUID directly, app name, database name, or service name.
+ * Searches applications first, then databases, then services.
+ * Results are cached in-memory for the duration of the CLI session.
+ *
+ * @param nameOrUuid - A friendly name or UUID string
+ * @returns The resolved UUID, or null if not found
+ */
+export async function resolveNameOrUuid(
+  nameOrUuid: string,
+): Promise<string | null> {
+  if (looksLikeUuid(nameOrUuid)) return nameOrUuid;
+
+  const query = nameOrUuid.toLowerCase();
+
+  // Search applications
+  const apps = await getApps();
+  const app = apps.find((a) => a.name?.toLowerCase() === query);
+  if (app) return app.uuid;
+
+  // Search databases
+  const databases = await getDatabases();
+  const db = databases.find((d) => d.name?.toLowerCase() === query);
+  if (db) return db.uuid;
+
+  // Search services
+  const services = await getServices();
+  const svc = services.find((s) => s.name?.toLowerCase() === query);
+  if (svc) return svc.uuid;
+
+  return null;
+}
+
+/**
+ * Resolves a name or UUID specifically for applications.
+ *
+ * @param nameOrUuid - A friendly name or UUID string
+ * @returns The resolved application UUID, or null if not found
+ */
+export async function resolveAppNameOrUuid(
+  nameOrUuid: string,
+): Promise<string | null> {
+  if (looksLikeUuid(nameOrUuid)) return nameOrUuid;
+
+  const query = nameOrUuid.toLowerCase();
+  const apps = await getApps();
+  const app = apps.find((a) => a.name?.toLowerCase() === query);
+  return app?.uuid ?? null;
+}
+
+/**
+ * Resolves a name or UUID specifically for databases.
+ *
+ * @param nameOrUuid - A friendly name or UUID string
+ * @returns The resolved database UUID, or null if not found
+ */
+export async function resolveDbNameOrUuid(
+  nameOrUuid: string,
+): Promise<string | null> {
+  if (looksLikeUuid(nameOrUuid)) return nameOrUuid;
+
+  const query = nameOrUuid.toLowerCase();
+  const databases = await getDatabases();
+  const db = databases.find((d) => d.name?.toLowerCase() === query);
+  return db?.uuid ?? null;
+}
+
+/**
+ * Fetches and caches the list of projects from Coolify API.
+ *
+ * @returns Array of projects, or empty array on error
+ */
+async function getProjects(): Promise<ICoolifyProject[]> {
+  if (cache.projects) return cache.projects;
+
+  const coolify = getCoolifyService();
+  const initResult = await coolify.init();
+  if (isOk(initResult)) {
+    const result = await coolify.listProjects();
+    if (isOk(result)) {
+      cache.projects = result.value;
+      return cache.projects;
+    }
+  }
+  return [];
+}
+
+/**
+ * Resolves a name or UUID specifically for projects.
+ *
+ * @param nameOrUuid - A friendly name or UUID string
+ * @returns The resolved project UUID, or null if not found
+ */
+export async function resolveProjectNameOrUuid(
+  nameOrUuid: string,
+): Promise<string | null> {
+  if (looksLikeUuid(nameOrUuid)) return nameOrUuid;
+
+  const query = nameOrUuid.toLowerCase();
+  const projects = await getProjects();
+  const project = projects.find((p) => p.name?.toLowerCase() === query);
+  return project?.uuid ?? null;
+}
+
+/**
+ * Resolves a name or UUID specifically for services.
+ *
+ * @param nameOrUuid - A friendly name or UUID string
+ * @returns The resolved service UUID, or null if not found
+ */
+export async function resolveSvcNameOrUuid(
+  nameOrUuid: string,
+): Promise<string | null> {
+  if (looksLikeUuid(nameOrUuid)) return nameOrUuid;
+
+  const query = nameOrUuid.toLowerCase();
+  const services = await getServices();
+  const svc = services.find((s) => s.name?.toLowerCase() === query);
+  return svc?.uuid ?? null;
+}
+
+/**
+ * Clears the in-memory cache. Useful for testing or long-running sessions.
+ */
+export function clearResolverCache(): void {
+  cache.apps = null;
+  cache.databases = null;
+  cache.services = null;
+  cache.projects = null;
+}