@studiometa/forge-cli 0.4.3 → 0.4.5

package/dist/cli.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-import { S as isOutputFormat, a as createContext, b as ValidationError, c as colors, d as deleteToken, g as setToken, h as setOrganizationSlug, i as runCommand, l as setColorEnabled, m as getToken, n as exitWithValidationError, p as getOrganizationSlug, s as OutputFormatter, u as createConfigStore } from "./error-handler-ByMitiOr.js";
+import { S as isOutputFormat, _ as ApiError, a as createContext, b as ValidationError, c as colors, d as deleteToken, g as setToken, h as setOrganizationSlug, i as runCommand, l as setColorEnabled, m as getToken, n as exitWithValidationError, p as getOrganizationSlug, s as OutputFormatter, u as createConfigStore } from "./error-handler-peS_8nl4.js";
 import { activateCertificate, createAuditLogger, createBackupConfig, createCommand, createDatabaseUser, createMonitor, createNginxTemplate, createRedirectRule, createScheduledJob, createSecurityRule, deleteBackupConfig, deleteDatabaseUser, deleteMonitor, deleteNginxTemplate, deleteRedirectRule, deleteScheduledJob, deleteSecurityRule, deploySiteAndWait, getBackupConfig, getCertificate, getCommand, getDaemon, getDatabase, getDatabaseUser, getEnv, getFirewallRule, getMonitor, getNginxConfig, getNginxTemplate, getRecipe, getRedirectRule, getScheduledJob, getSecurityRule, getServer, getSite, getSshKey, getUser, listBackupConfigs, listCommands, listDaemons, listDatabaseUsers, listDatabases, listDeployments, listFirewallRules, listMonitors, listNginxTemplates, listRecipes, listRedirectRules, listScheduledJobs, listSecurityRules, listServers, listSites, listSshKeys, matchByName, rebootServer, restartDaemon, runRecipe, updateBackupConfig, updateDaemon, updateDatabaseUser, updateEnv, updateNginxConfig, updateNginxTemplate, updateRecipe, updateSecurityRule, updateSite } from "@studiometa/forge-core";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region src/audit.ts
 /**
 * Shared audit logger for CLI write operations.
 * Lazily initialized on first use.
@@ -13,6 +15,8 @@ function getCliAuditLogger() {
 	if (!_auditLogger) _auditLogger = createAuditLogger("cli");
 	return _auditLogger;
 }
+//#endregion
+//#region src/utils/command-router.ts
 /**
 * Creates a command router function that dispatches to the appropriate handler.
 */
@@ -55,6 +59,8 @@ function createCommandRouter(config) {
 		else await handler(ctx);
 	};
 }
+//#endregion
+//#region src/utils/resolve.ts
 /**
 * Smart resolution utilities for --server and --site options.
 *
@@ -106,6 +112,8 @@ async function resolveSiteId(value, serverId, execCtx) {
 	}
 	return String(partial[0].id);
 }
+//#endregion
+//#region src/commands/backups/handlers.ts
 async function backupsList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	if (!server) exitWithValidationError("server_id", "forge backups list --server <server_id>", ctx.formatter);
@@ -216,7 +224,9 @@ async function backupsDelete(args, ctx) {
 		ctx.formatter.success(`Backup configuration ${id} deleted.`);
 	}, ctx.formatter);
 }
-const handleBackupsCommand = createCommandRouter({
+//#endregion
+//#region src/commands/backups/command.ts
+var handleBackupsCommand = createCommandRouter({
 	resource: "backups",
 	handlers: {
 		list: backupsList,
@@ -232,6 +242,8 @@ const handleBackupsCommand = createCommandRouter({
 		"delete"
 	]
 });
+//#endregion
+//#region src/commands/backups/help.ts
 function showBackupsHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge backups list")} - List backup configurations on a server
@@ -309,6 +321,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge backups <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/completion.ts
 /**
 * Shell completion installation command
 */
@@ -322,7 +336,7 @@ _forge_completions() {
   prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
   # Main commands
-  commands="config servers s sites deployments d databases db database-users daemons env nginx certificates certs firewall-rules fw ssh-keys backups commands scheduled-jobs user monitors nginx-templates security-rules redirect-rules recipes completion help"
+  commands="config servers s sites deployments d databases db database-users daemons env nginx certificates certs firewall-rules fw ssh ssh-keys backups commands scheduled-jobs user monitors nginx-templates security-rules redirect-rules recipes completion help"
 
   # Subcommands for each command
   local config_cmds="set get delete"
@@ -349,7 +363,7 @@ _forge_completions() {
   local completion_cmds="bash zsh fish"
 
   # Global options
-  options="--token --server --site -f --format --no-color -h --help -v --version --name --command --content --from --to --provider --frequency --type --operator --threshold --minutes --key --port --ip-address --user --script --servers --domain --password --credential-id --region --size --project-type --directory"
+  options="--token --server --site -f --format --no-color -h --help -v --version --name --command --content --from --to --provider --frequency --type --operator --threshold --minutes --key --port --ip-address --user --private --dry-run --script --servers --domain --password --credential-id --region --size --project-type --directory"
 
   # Format options
   local formats="json human table"
@@ -486,6 +500,7 @@ _forge() {
         'certs:Manage SSL certificates (alias)'
         'firewall-rules:Manage firewall rules'
         'fw:Manage firewall rules (alias)'
+        'ssh:Open an SSH session to a server'
         'ssh-keys:Manage SSH keys'
         'backups:Manage backup configurations'
         'commands:Manage site commands'
@@ -775,6 +790,7 @@ complete -c forge -f -n "__fish_use_subcommand" -a "certificates" -d "Manage SSL
 complete -c forge -f -n "__fish_use_subcommand" -a "certs" -d "Manage SSL certificates (alias)"
 complete -c forge -f -n "__fish_use_subcommand" -a "firewall-rules" -d "Manage firewall rules"
 complete -c forge -f -n "__fish_use_subcommand" -a "fw" -d "Manage firewall rules (alias)"
+complete -c forge -f -n "__fish_use_subcommand" -a "ssh" -d "Open an SSH session to a server"
 complete -c forge -f -n "__fish_use_subcommand" -a "ssh-keys" -d "Manage SSH keys"
 complete -c forge -f -n "__fish_use_subcommand" -a "backups" -d "Manage backup configurations"
 complete -c forge -f -n "__fish_use_subcommand" -a "commands" -d "Manage site commands"
@@ -1053,6 +1069,8 @@ function handleCompletionCommand(shell, options = {}) {
 		process.exit(1);
 	}
 }
+//#endregion
+//#region src/commands/certificates/handlers.ts
 function requireServerSiteDomainRaw(ctx, usage) {
 	const server = String(ctx.options.server ?? "");
 	const site = String(ctx.options.site ?? "");
@@ -1104,7 +1122,9 @@ async function certificatesActivate(args, ctx) {
 		ctx.formatter.success(`Certificate for domain ${domainId} activated.`);
 	}, ctx.formatter);
 }
-const handleCertificatesCommand = createCommandRouter({
+//#endregion
+//#region src/commands/certificates/command.ts
+var handleCertificatesCommand = createCommandRouter({
 	resource: "certificates",
 	handlers: {
 		get: [certificatesGet, "args"],
@@ -1112,6 +1132,8 @@ const handleCertificatesCommand = createCommandRouter({
 	},
 	writeSubcommands: ["activate"]
 });
+//#endregion
+//#region src/commands/certificates/help.ts
 function showCertificatesHelp(subcommand) {
 	if (subcommand === "get") console.log(`
 ${colors.bold("forge certificates get")} - Get certificate for a domain
@@ -1150,6 +1172,8 @@ ${colors.bold("NOTE:")}
 Run ${colors.cyan("forge certificates <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/commands/handlers.ts
 function requireServerAndSiteRaw$2(ctx, usage) {
 	const server = String(ctx.options.server ?? "");
 	const site = String(ctx.options.site ?? "");
@@ -1219,7 +1243,9 @@ async function commandsCreate(ctx) {
 		ctx.formatter.success("Command queued for execution.");
 	}, ctx.formatter);
 }
-const handleCommandsCommand = createCommandRouter({
+//#endregion
+//#region src/commands/commands/command.ts
+var handleCommandsCommand = createCommandRouter({
 	resource: "commands",
 	handlers: {
 		list: commandsList,
@@ -1229,6 +1255,8 @@ const handleCommandsCommand = createCommandRouter({
 	},
 	writeSubcommands: ["create"]
 });
+//#endregion
+//#region src/commands/commands/help.ts
 function showCommandsHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge commands list")} - List commands executed on a site
@@ -1278,6 +1306,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge commands <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/config.ts
 /**
 * Config command — manage forge configuration
 */
@@ -1362,6 +1392,8 @@ function handleConfigCommand(subcommand, args, options) {
 function maskToken(token) {
 	return token.length > 8 ? `${token.slice(0, 4)}${"*".repeat(token.length - 8)}${token.slice(-4)}` : "****";
 }
+//#endregion
+//#region src/commands/daemons/handlers.ts
 async function daemonsList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	if (!server) exitWithValidationError("server_id", "forge daemons list --server <server_id>", ctx.formatter);
@@ -1443,7 +1475,9 @@ async function daemonsRestart(args, ctx) {
 		ctx.formatter.success(`Daemon ${id} restarted.`);
 	}, ctx.formatter);
 }
-const handleDaemonsCommand = createCommandRouter({
+//#endregion
+//#region src/commands/daemons/command.ts
+var handleDaemonsCommand = createCommandRouter({
 	resource: "daemons",
 	handlers: {
 		list: daemonsList,
@@ -1454,6 +1488,8 @@ const handleDaemonsCommand = createCommandRouter({
 	},
 	writeSubcommands: ["restart", "update"]
 });
+//#endregion
+//#region src/commands/daemons/help.ts
 function showDaemonsHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge daemons list")} - List daemons on a server
@@ -1498,6 +1534,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge daemons <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/databases/handlers.ts
 async function databasesList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	if (!server) exitWithValidationError("server_id", "forge databases list --server <server_id>", ctx.formatter);
@@ -1532,7 +1570,9 @@ async function databasesGet(args, ctx) {
 		]);
 	}, ctx.formatter);
 }
-const handleDatabasesCommand = createCommandRouter({
+//#endregion
+//#region src/commands/databases/command.ts
+var handleDatabasesCommand = createCommandRouter({
 	resource: "databases",
 	handlers: {
 		list: databasesList,
@@ -1540,6 +1580,8 @@ const handleDatabasesCommand = createCommandRouter({
 		get: [databasesGet, "args"]
 	}
 });
+//#endregion
+//#region src/commands/databases/help.ts
 function showDatabasesHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge databases list")} - List databases on a server
@@ -1577,6 +1619,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge databases <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/database-users/handlers.ts
 async function databaseUsersList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	if (!server) exitWithValidationError("server_id", "forge database-users list --server <server_id>", ctx.formatter);
@@ -1677,7 +1721,9 @@ async function databaseUsersDelete(args, ctx) {
 		ctx.formatter.success(`Database user ${id} deleted.`);
 	}, ctx.formatter);
 }
-const handleDatabaseUsersCommand = createCommandRouter({
+//#endregion
+//#region src/commands/database-users/command.ts
+var handleDatabaseUsersCommand = createCommandRouter({
 	resource: "database-users",
 	handlers: {
 		list: databaseUsersList,
@@ -1693,6 +1739,8 @@ const handleDatabaseUsersCommand = createCommandRouter({
 		"delete"
 	]
 });
+//#endregion
+//#region src/commands/database-users/help.ts
 function showDatabaseUsersHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge database-users list")} - List database users on a server
@@ -1761,6 +1809,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge database-users <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/deployments/handlers.ts
 async function deploymentsList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	const site = String(ctx.options.site ?? "");
@@ -1803,14 +1853,17 @@ async function deploymentsDeploy(ctx) {
 				process.stdout.write(chunk);
 			} : void 0
 		}, execCtx);
-		if (!streamLogs) process.stderr.write("\n");
+		if (streamLogs) process.stdout.write("\n");
+		else process.stderr.write("\n");
 		const elapsedSec = (result.data.elapsed_ms / 1e3).toFixed(1);
-		if (result.data.status === "success") ctx.formatter.success(`Deployment succeeded for site ${site_id} (${elapsedSec}s).`);
-		else ctx.formatter.error(`Deployment failed for site ${site_id} (${elapsedSec}s).`);
 		if (!streamLogs && result.data.log) ctx.formatter.output(result.data.log);
+		if (result.data.status === "success") ctx.formatter.success(`Deployment succeeded for site ${site_id} (${elapsedSec}s).`);
+		else throw new ApiError(`Deployment failed for site ${site_id} (${elapsedSec}s).`);
 	}, ctx.formatter);
 }
-const handleDeploymentsCommand = createCommandRouter({
+//#endregion
+//#region src/commands/deployments/command.ts
+var handleDeploymentsCommand = createCommandRouter({
 	resource: "deployments",
 	handlers: {
 		list: deploymentsList,
@@ -1819,6 +1872,8 @@ const handleDeploymentsCommand = createCommandRouter({
 	},
 	writeSubcommands: ["deploy"]
 });
+//#endregion
+//#region src/commands/deployments/help.ts
 function showDeploymentsHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge deployments list")} - List deployments for a site
@@ -1864,6 +1919,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge deployments <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/env/handlers.ts
 async function envGet(ctx) {
 	const server = String(ctx.options.server ?? "");
 	const site = String(ctx.options.site ?? "");
@@ -1900,7 +1957,9 @@ async function envUpdate(ctx) {
 		ctx.formatter.success("Environment variables updated.");
 	}, ctx.formatter);
 }
-const handleEnvCommand = createCommandRouter({
+//#endregion
+//#region src/commands/env/command.ts
+var handleEnvCommand = createCommandRouter({
 	resource: "env",
 	handlers: {
 		get: envGet,
@@ -1908,6 +1967,8 @@ const handleEnvCommand = createCommandRouter({
 	},
 	writeSubcommands: ["update"]
 });
+//#endregion
+//#region src/commands/env/help.ts
 function showEnvHelp(subcommand) {
 	if (subcommand === "get") console.log(`
 ${colors.bold("forge env get")} - Get environment variables
@@ -1940,6 +2001,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge env <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/firewall-rules/handlers.ts
 async function firewallRulesList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	if (!server) exitWithValidationError("server_id", "forge firewall-rules list --server <server_id>", ctx.formatter);
@@ -1980,7 +2043,9 @@ async function firewallRulesGet(args, ctx) {
 		]);
 	}, ctx.formatter);
 }
-const handleFirewallRulesCommand = createCommandRouter({
+//#endregion
+//#region src/commands/firewall-rules/command.ts
+var handleFirewallRulesCommand = createCommandRouter({
 	resource: "firewall-rules",
 	handlers: {
 		list: firewallRulesList,
@@ -1988,6 +2053,8 @@ const handleFirewallRulesCommand = createCommandRouter({
 		get: [firewallRulesGet, "args"]
 	}
 });
+//#endregion
+//#region src/commands/firewall-rules/help.ts
 function showFirewallRulesHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge firewall-rules list")} - List firewall rules on a server
@@ -2021,6 +2088,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge firewall-rules <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/monitors/handlers.ts
 async function monitorsList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	if (!server) exitWithValidationError("server_id", "forge monitors list --server <server_id>", ctx.formatter);
@@ -2106,7 +2175,9 @@ async function monitorsDelete(args, ctx) {
 		ctx.formatter.success(`Monitor ${id} deleted.`);
 	}, ctx.formatter);
 }
-const handleMonitorsCommand = createCommandRouter({
+//#endregion
+//#region src/commands/monitors/command.ts
+var handleMonitorsCommand = createCommandRouter({
 	resource: "monitors",
 	handlers: {
 		list: monitorsList,
@@ -2117,6 +2188,8 @@ const handleMonitorsCommand = createCommandRouter({
 	},
 	writeSubcommands: ["create", "delete"]
 });
+//#endregion
+//#region src/commands/monitors/help.ts
 function showMonitorsHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge monitors list")} - List monitors on a server
@@ -2173,6 +2246,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge monitors <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/nginx/handlers.ts
 async function nginxGet(ctx) {
 	const server = String(ctx.options.server ?? "");
 	const site = String(ctx.options.site ?? "");
@@ -2209,7 +2284,9 @@ async function nginxUpdate(ctx) {
 		ctx.formatter.success("Nginx configuration updated.");
 	}, ctx.formatter);
 }
-const handleNginxCommand = createCommandRouter({
+//#endregion
+//#region src/commands/nginx/command.ts
+var handleNginxCommand = createCommandRouter({
 	resource: "nginx",
 	handlers: {
 		get: nginxGet,
@@ -2217,6 +2294,8 @@ const handleNginxCommand = createCommandRouter({
 	},
 	writeSubcommands: ["update"]
 });
+//#endregion
+//#region src/commands/nginx/help.ts
 function showNginxHelp(subcommand) {
 	if (subcommand === "get") console.log(`
 ${colors.bold("forge nginx get")} - Get nginx configuration
@@ -2248,6 +2327,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge nginx <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/nginx-templates/handlers.ts
 async function nginxTemplatesList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	if (!server) exitWithValidationError("server_id", "forge nginx-templates list --server <server_id>", ctx.formatter);
@@ -2312,11 +2393,14 @@ async function nginxTemplatesUpdate(args, ctx) {
 	await runCommand(async () => {
 		const token = ctx.getToken();
 		const execCtx = ctx.createExecutorContext(token);
+		const server_id = await resolveServerId(server, execCtx);
+		const name = ctx.options.name ? String(ctx.options.name) : void 0;
+		const content = ctx.options.content ? String(ctx.options.content) : void 0;
 		const result = await updateNginxTemplate({
-			server_id: await resolveServerId(server, execCtx),
+			server_id,
 			id,
-			name: ctx.options.name ? String(ctx.options.name) : void 0,
-			content: ctx.options.content ? String(ctx.options.content) : void 0
+			name,
+			content
 		}, execCtx);
 		ctx.formatter.outputOne(result.data, [
 			"id",
@@ -2340,7 +2424,9 @@ async function nginxTemplatesDelete(args, ctx) {
 		ctx.formatter.success(`Nginx template ${id} deleted.`);
 	}, ctx.formatter);
 }
-const handleNginxTemplatesCommand = createCommandRouter({
+//#endregion
+//#region src/commands/nginx-templates/command.ts
+var handleNginxTemplatesCommand = createCommandRouter({
 	resource: "nginx-templates",
 	handlers: {
 		list: nginxTemplatesList,
@@ -2356,6 +2442,8 @@ const handleNginxTemplatesCommand = createCommandRouter({
 		"delete"
 	]
 });
+//#endregion
+//#region src/commands/nginx-templates/help.ts
 function showNginxTemplatesHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge nginx-templates list")} - List Nginx templates on a server
@@ -2423,6 +2511,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge nginx-templates <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/recipes/handlers.ts
 async function recipesList(ctx) {
 	await runCommand(async () => {
 		const token = ctx.getToken();
@@ -2491,7 +2581,9 @@ async function recipesRun(args, ctx) {
 		ctx.formatter.success(`Recipe ${id} dispatched to ${servers.length} server(s).`);
 	}, ctx.formatter);
 }
-const handleRecipesCommand = createCommandRouter({
+//#endregion
+//#region src/commands/recipes/command.ts
+var handleRecipesCommand = createCommandRouter({
 	resource: "recipes",
 	handlers: {
 		list: recipesList,
@@ -2502,6 +2594,8 @@ const handleRecipesCommand = createCommandRouter({
 	},
 	writeSubcommands: ["update", "run"]
 });
+//#endregion
+//#region src/commands/recipes/help.ts
 function showRecipesHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge recipes list")} - List all recipes
@@ -2553,6 +2647,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge recipes <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/redirect-rules/handlers.ts
 function requireServerAndSiteRaw$1(ctx, usage) {
 	const server = String(ctx.options.server ?? "");
 	const site = String(ctx.options.site ?? "");
@@ -2643,7 +2739,9 @@ async function redirectRulesDelete(args, ctx) {
 		ctx.formatter.success(`Redirect rule ${id} deleted.`);
 	}, ctx.formatter);
 }
-const handleRedirectRulesCommand = createCommandRouter({
+//#endregion
+//#region src/commands/redirect-rules/command.ts
+var handleRedirectRulesCommand = createCommandRouter({
 	resource: "redirect-rules",
 	handlers: {
 		list: redirectRulesList,
@@ -2654,6 +2752,8 @@ const handleRedirectRulesCommand = createCommandRouter({
 	},
 	writeSubcommands: ["create", "delete"]
 });
+//#endregion
+//#region src/commands/redirect-rules/help.ts
 function showRedirectRulesHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge redirect-rules list")} - List redirect rules for a site
@@ -2711,6 +2811,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge redirect-rules <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/scheduled-jobs/handlers.ts
 async function scheduledJobsList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	const site = ctx.options.site ? String(ctx.options.site) : void 0;
@@ -2741,10 +2843,11 @@ async function scheduledJobsGet(args, ctx) {
 		const token = ctx.getToken();
 		const execCtx = ctx.createExecutorContext(token);
 		const server_id = await resolveServerId(server, execCtx);
+		const site_id = site ? await resolveSiteId(site, server_id, execCtx) : void 0;
 		const result = await getScheduledJob({
 			server_id,
 			id,
-			site_id: site ? await resolveSiteId(site, server_id, execCtx) : void 0
+			site_id
 		}, execCtx);
 		ctx.formatter.outputOne(result.data, [
 			"id",
@@ -2799,15 +2902,18 @@ async function scheduledJobsDelete(args, ctx) {
 		const token = ctx.getToken();
 		const execCtx = ctx.createExecutorContext(token);
 		const server_id = await resolveServerId(server, execCtx);
+		const site_id = site ? await resolveSiteId(site, server_id, execCtx) : void 0;
 		await deleteScheduledJob({
 			server_id,
 			id,
-			site_id: site ? await resolveSiteId(site, server_id, execCtx) : void 0
+			site_id
 		}, execCtx);
 		ctx.formatter.success(`Scheduled job ${id} deleted.`);
 	}, ctx.formatter);
 }
-const handleScheduledJobsCommand = createCommandRouter({
+//#endregion
+//#region src/commands/scheduled-jobs/command.ts
+var handleScheduledJobsCommand = createCommandRouter({
 	resource: "scheduled-jobs",
 	handlers: {
 		list: scheduledJobsList,
@@ -2818,6 +2924,8 @@ const handleScheduledJobsCommand = createCommandRouter({
 	},
 	writeSubcommands: ["create", "delete"]
 });
+//#endregion
+//#region src/commands/scheduled-jobs/help.ts
 function showScheduledJobsHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge scheduled-jobs list")} - List scheduled jobs on a server
@@ -2871,6 +2979,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge scheduled-jobs <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/security-rules/handlers.ts
 function requireServerAndSiteRaw(ctx, usage) {
 	const server = String(ctx.options.server ?? "");
 	const site = String(ctx.options.site ?? "");
@@ -2986,7 +3096,9 @@ async function securityRulesDelete(args, ctx) {
 		ctx.formatter.success(`Security rule ${id} deleted.`);
 	}, ctx.formatter);
 }
-const handleSecurityRulesCommand = createCommandRouter({
+//#endregion
+//#region src/commands/security-rules/command.ts
+var handleSecurityRulesCommand = createCommandRouter({
 	resource: "security-rules",
 	handlers: {
 		list: securityRulesList,
@@ -3002,6 +3114,8 @@ const handleSecurityRulesCommand = createCommandRouter({
 		"delete"
 	]
 });
+//#endregion
+//#region src/commands/security-rules/help.ts
 function showSecurityRulesHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge security-rules list")} - List security rules for a site
@@ -3071,6 +3185,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge security-rules <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/servers/handlers.ts
 /**
 * CLI handlers for servers commands.
 * Delegates all HTTP logic to forge-core executors.
@@ -3120,7 +3236,9 @@ async function serversReboot(args, ctx) {
 		ctx.formatter.success(`Server ${server_id} reboot initiated.`);
 	}, ctx.formatter);
 }
-const handleServersCommand = createCommandRouter({
+//#endregion
+//#region src/commands/servers/command.ts
+var handleServersCommand = createCommandRouter({
 	resource: "servers",
 	handlers: {
 		list: serversList,
@@ -3130,6 +3248,8 @@ const handleServersCommand = createCommandRouter({
 	},
 	writeSubcommands: ["reboot"]
 });
+//#endregion
+//#region src/commands/servers/help.ts
 function showServersHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge servers list")} - List all servers
@@ -3200,6 +3320,8 @@ ${colors.bold("EXAMPLES:")}
 Run ${colors.cyan("forge servers <subcommand> --help")} for subcommand details.
 `);
 }
+//#endregion
+//#region src/commands/sites/handlers.ts
 async function sitesList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	if (!server) exitWithValidationError("server_id", "forge sites list --server <server_id>", ctx.formatter);
@@ -3275,7 +3397,9 @@ async function sitesUpdate(args, ctx) {
 		]);
 	}, ctx.formatter);
 }
-const handleSitesCommand = createCommandRouter({
+//#endregion
+//#region src/commands/sites/command.ts
+var handleSitesCommand = createCommandRouter({
 	resource: "sites",
 	handlers: {
 		list: sitesList,
@@ -3284,6 +3408,8 @@ const handleSitesCommand = createCommandRouter({
 		update: [sitesUpdate, "args"]
 	}
 });
+//#endregion
+//#region src/commands/sites/help.ts
 function showSitesHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge sites list")} - List sites on a server
@@ -3334,6 +3460,172 @@ ${colors.bold("EXAMPLES:")}
 Run ${colors.cyan("forge sites <subcommand> --help")} for subcommand details.
 `);
 }
+/**
+* Resolve the concrete user/host/port to connect to.
+*
+* @throws {ValidationError} when the selected IP is not available yet, or the port override is invalid.
+*/
+function resolveSshTarget(server, options = {}) {
+	const user = options.user?.trim() || "forge";
+	const host = options.private ? server.private_ip_address : server.ip_address;
+	if (!host) {
+		const which = options.private ? "private IP address" : "IP address";
+		const hints = [server.is_ready ? "The server is ready but no address is available — check the Forge dashboard." : "The server is still provisioning. Wait until it is ready, then try again.", options.private ? void 0 : "Use --private to connect over the private network."].filter((hint) => Boolean(hint));
+		throw new ValidationError(`Server "${server.name}" has no ${which} available`, "server", hints);
+	}
+	let port = server.ssh_port;
+	if (options.port !== void 0) {
+		const parsed = Number(options.port);
+		if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) throw new ValidationError(`Invalid SSH port "${options.port}"`, "port", ["Port must be an integer between 1 and 65535."]);
+		port = parsed;
+	}
+	return {
+		user,
+		host,
+		port
+	};
+}
+/**
+* Build the argument list passed to the `ssh` binary.
+*
+* Any {@link remoteCommand} is appended after the connection flags, so
+* `forge ssh web uptime` runs `uptime` remotely and exits.
+*/
+function buildSshArgs(target, remoteCommand = []) {
+	const args = [
+		`${target.user}@${target.host}`,
+		"-p",
+		String(target.port)
+	];
+	if (remoteCommand.length > 0) args.push(...remoteCommand);
+	return args;
+}
+//#endregion
+//#region src/commands/ssh/handlers.ts
+/**
+* CLI handler for `forge ssh` — open an interactive SSH session to a server.
+*
+* Resolves the server, reads its connection details from the API, then hands
+* off to the local `ssh` binary with an inherited stdio (interactive) session.
+*/
+/**
+* Connect to a server over SSH.
+*
+* @param server - Server ID or name (resolved via {@link resolveServerId}).
+* @param remote - Optional remote command to run instead of an interactive shell.
+* @param ctx - CLI command context.
+*/
+async function sshConnect(server, remote, ctx) {
+	if (!server) exitWithValidationError("server", "forge ssh <server> [command...]", ctx.formatter);
+	await runCommand(async () => {
+		const token = ctx.getToken();
+		const execCtx = ctx.createExecutorContext(token);
+		const server_id = await resolveServerId(server, execCtx);
+		const { data } = await getServer({ server_id }, execCtx);
+		const target = resolveSshTarget(data, {
+			user: typeof ctx.options.user === "string" ? ctx.options.user : void 0,
+			private: ctx.options.private === true,
+			port: typeof ctx.options.port === "string" ? ctx.options.port : void 0
+		});
+		const sshArgs = buildSshArgs(target, remote);
+		const printable = `ssh ${sshArgs.join(" ")}`;
+		if (ctx.formatter.isJson()) {
+			ctx.formatter.output({
+				command: printable,
+				...target,
+				args: sshArgs
+			});
+			return;
+		}
+		if (ctx.options["dry-run"] === true) {
+			console.log(printable);
+			return;
+		}
+		const auditArgs = {
+			server: server_id,
+			user: target.user,
+			host: target.host,
+			port: target.port
+		};
+		try {
+			const child = spawnSync("ssh", sshArgs, { stdio: "inherit" });
+			if (child.error) throw child.error;
+			getCliAuditLogger().log({
+				source: "cli",
+				resource: "ssh",
+				action: "connect",
+				args: auditArgs,
+				status: "success"
+			});
+			if (typeof child.status === "number" && child.status !== 0) process.exit(child.status);
+		} catch (err) {
+			getCliAuditLogger().log({
+				source: "cli",
+				resource: "ssh",
+				action: "connect",
+				args: auditArgs,
+				status: "error",
+				error: err instanceof Error ? err.message : String(err)
+			});
+			throw err;
+		}
+	}, ctx.formatter);
+}
+//#endregion
+//#region src/commands/ssh/command.ts
+/**
+* Route the top-level `forge ssh` command.
+*
+* Unlike resource commands there is no sub-action: the first positional is the
+* server, and any remaining positionals form an optional remote command.
+*/
+async function handleSshCommand(server, remote, options) {
+	await sshConnect(server, remote, createContext(options));
+}
+//#endregion
+//#region src/commands/ssh/help.ts
+function showSshHelp() {
+	console.log(`
+${colors.bold("forge ssh")} - Open an SSH session to a server
+
+${colors.bold("USAGE:")}
+  forge ssh <server> [command...] [options]
+
+${colors.bold("ARGUMENTS:")}
+  <server>            Server ID or name (required)
+  [command...]        Optional remote command to run, then exit
+
+${colors.bold("OPTIONS:")}
+  --user <name>       SSH user (default: forge)
+  --private           Connect over the private IP address
+  --port <n>          Override the server's SSH port
+  --dry-run           Print the ssh command instead of connecting
+  -f, --format json   Print the resolved connection details as JSON
+  -h, --help          Show this help
+
+${colors.bold("EXAMPLES:")}
+  # Interactive session (connects as forge@<ip>)
+  forge ssh my-server
+
+  # Connect as a custom user
+  forge ssh my-server --user deploy
+
+  # Use the private network
+  forge ssh my-server --private
+
+  # Run a one-off remote command
+  forge ssh my-server uptime
+
+  # Just show the command that would run
+  forge ssh my-server --dry-run
+
+${colors.bold("NOTES:")}
+  Requires your local SSH key to be authorized on the server; this command
+  launches ssh, it does not upload keys.
+`);
+}
+//#endregion
+//#region src/commands/ssh-keys/handlers.ts
 async function sshKeysList(ctx) {
 	const server = String(ctx.options.server ?? "");
 	if (!server) exitWithValidationError("server_id", "forge ssh-keys list --server <server_id>", ctx.formatter);
@@ -3368,7 +3660,9 @@ async function sshKeysGet(args, ctx) {
 		]);
 	}, ctx.formatter);
 }
-const handleSshKeysCommand = createCommandRouter({
+//#endregion
+//#region src/commands/ssh-keys/command.ts
+var handleSshKeysCommand = createCommandRouter({
 	resource: "ssh-keys",
 	handlers: {
 		list: sshKeysList,
@@ -3376,6 +3670,8 @@ const handleSshKeysCommand = createCommandRouter({
 		get: [sshKeysGet, "args"]
 	}
 });
+//#endregion
+//#region src/commands/ssh-keys/help.ts
 function showSshKeysHelp(subcommand) {
 	if (subcommand === "list" || subcommand === "ls") console.log(`
 ${colors.bold("forge ssh-keys list")} - List SSH keys on a server
@@ -3406,6 +3702,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge ssh-keys <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/commands/user/handlers.ts
 async function userGet(ctx) {
 	await runCommand(async () => {
 		const token = ctx.getToken();
@@ -3413,10 +3711,14 @@ async function userGet(ctx) {
 		ctx.formatter.output(result.data);
 	}, ctx.formatter);
 }
-const handleUserCommand = createCommandRouter({
+//#endregion
+//#region src/commands/user/command.ts
+var handleUserCommand = createCommandRouter({
 	resource: "user",
 	handlers: { get: userGet }
 });
+//#endregion
+//#region src/commands/user/help.ts
 function showUserHelp(subcommand) {
 	if (subcommand === "get") console.log(`
 ${colors.bold("forge user get")} - Get the authenticated user profile
@@ -3442,6 +3744,8 @@ ${colors.bold("OPTIONS:")}
 Run ${colors.cyan("forge user <subcommand> --help")} for details.
 `);
 }
+//#endregion
+//#region src/utils/args.ts
 function parseArgs(argv = process.argv.slice(2)) {
 	const options = {};
 	const positional = [];
@@ -3478,7 +3782,9 @@ function parseArgs(argv = process.argv.slice(2)) {
 		positional
 	};
 }
-var VERSION = "0.4.3";
+//#endregion
+//#region src/cli.ts
+var VERSION = "0.4.5";
 function showHelp() {
 	console.log(`
 ${colors.bold("forge")} v${VERSION}
@@ -3537,6 +3843,9 @@ ${colors.bold("COMMANDS:")}
     list, ls            List firewall rules (requires --server)
     get <id>            Get firewall rule details (requires --server)
 
+  ssh <server>        Open an SSH session to a server
+                        --user <name> (default: forge), --private, --port <n>
+
   ssh-keys            Manage SSH keys
     list, ls            List SSH keys (requires --server)
     get <id>            Get SSH key details (requires --server)
@@ -3739,6 +4048,13 @@ async function main() {
 				}
 				await handleFirewallRulesCommand(subcommand ?? "list", positional, options);
 				break;
+			case "ssh":
+				if (wantsHelp) {
+					showSshHelp();
+					process.exit(0);
+				}
+				await handleSshCommand(subcommand, positional, options);
+				break;
 			case "ssh-keys":
 				if (wantsHelp) {
 					showSshKeysHelp(subcommand);
@@ -3830,5 +4146,6 @@ main().catch((error) => {
 	console.error(colors.red("Unhandled error:"), error);
 	process.exit(1);
 });
+//#endregion
 
 //# sourceMappingURL=cli.js.map