ninedeploy 0.10.5 → 0.16.0

package/src/client.ts

@@ -0,0 +1,137 @@
+import { createClient, type NineDeployClient } from '@ninedeploy/sdk';
+import { loadConfig, saveConfig } from './config.js';
+
+export type { NineDeployClient };
+
+/**
+ * In-flight dedup: when several commands race 401s (batch scripts), the
+ * refresh must happen ONCE — replaying the same refresh token twice would
+ * revoke it server-side and log the session out.
+ */
+let refreshInflight: Promise<boolean> | null = null;
+
+/**
+ * Endpoints that exchange credentials for tokens (or run before a session
+ * exists). A 401 there is a real answer — never refresh-and-retry it.
+ * r193: every `/auth/` path used to be skipped, so the authenticated ones
+ * (`/auth/me`, `/auth/tokens`, `/auth/sessions`, 2FA, passkey registration)
+ * failed permanently once the 15-minute access token expired.
+ * Keep byte-identical to apps/web/src/lib/api.ts — the web copy also exempts
+ * `oidc/<slug>/link` (an authenticated route); this copy had drifted and
+ * would have re-inherited the r193 failure the moment a CLI command wired
+ * auth.oidc.link().
+ */
+export const NO_REFRESH_PATH =
+  /\/(?:v1\/setup|v1\/auth\/(?:login|refresh|register|logout|forgot-password|reset-password|status|oidc\/(?!providers(?:\/|$|\?)|[^/]+\/link(?:$|\?))|passkey\/login\/))/;
+
+/**
+ * r550: join the configured base URL and an API path by string concatenation.
+ * `new URL('/v1/…', base)` resolves the path against the ORIGIN, silently
+ * dropping a sub-path prefix (`https://host/ninedeploy` → `https://host/v1/…`)
+ * — a panel published behind a path prefix answered every raw call with the
+ * front proxy's 404. The SDK has always concatenated; this keeps the raw
+ * paths (exports, imports, the log WebSocket) in line with it.
+ */
+export function apiUrl(path: string, baseUrl: string = loadConfig().baseUrl): string {
+  return `${baseUrl.replace(/\/+$/, '')}${path}`;
+}
+
+async function refreshSession(baseUrl: string, refreshToken: string): Promise<boolean> {
+  try {
+    const res = await fetch(apiUrl('/v1/auth/refresh', baseUrl), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) return false;
+    const data = (await res.json()) as { tokens?: { accessToken?: string; refreshToken?: string } };
+    const tokens = data.tokens;
+    if (!tokens?.accessToken || !tokens.refreshToken) return false;
+    saveConfig({ ...loadConfig(), token: tokens.accessToken, refreshToken: tokens.refreshToken });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mint a fresh access token from the saved refresh token (single-flight,
+ * persisted). Resolves false when there is no refresh token or the server
+ * refused it — the caller then surfaces its original 401.
+ */
+export async function refreshAccessToken(baseUrl: string = loadConfig().baseUrl): Promise<boolean> {
+  const refreshToken = loadConfig().refreshToken;
+  if (!refreshToken) return false;
+  refreshInflight ??= refreshSession(baseUrl, refreshToken).finally(() => {
+    refreshInflight = null;
+  });
+  return refreshInflight;
+}
+
+/** fetch() with the dashboard's 401 → refresh → retry-once semantics. */
+async function fetchWithRefresh(baseUrl: string, input: string, init?: RequestInit): Promise<Response> {
+  const res = await fetch(input, init);
+  if (res.status !== 401) return res;
+  if (NO_REFRESH_PATH.test(input)) return res;
+  if (!(await refreshAccessToken(baseUrl))) return res;
+  const headers = new Headers(init?.headers);
+  const fresh = loadConfig().token;
+  if (fresh) headers.set('Authorization', `Bearer ${fresh}`);
+  return fetch(input, { ...init, headers });
+}
+
+/**
+ * r550: authenticated raw fetch for the endpoints the SDK cannot model
+ * (binary exports, the octet-stream import). These used to call fetch()
+ * directly with the saved bearer and no refresh: once the 15-minute access
+ * token expired, `system export` / `system import` / `services export` failed
+ * with a bare 401 while every SDK-backed command kept working. Same base-URL
+ * join and refresh-and-retry as getClient().
+ */
+export async function authedFetch(path: string, init: RequestInit = {}): Promise<Response> {
+  const cfg = loadConfig();
+  const headers = new Headers(init.headers);
+  if (cfg.token) headers.set('Authorization', `Bearer ${cfg.token}`);
+  return fetchWithRefresh(cfg.baseUrl, apiUrl(path, cfg.baseUrl), { ...init, headers });
+}
+
+/**
+ * True when `token` is a JWT whose `exp` falls within `skewMs` from now.
+ * Opaque API tokens (and anything undecodable) report false — they carry no
+ * client-visible expiry, so the server's answer is the only authority.
+ */
+export function tokenExpiresSoon(token: string | undefined, skewMs = 60_000, now = Date.now()): boolean {
+  if (!token) return false;
+  const part = token.split('.')[1];
+  if (!part) return false;
+  try {
+    const payload = JSON.parse(Buffer.from(part, 'base64url').toString('utf8')) as { exp?: unknown };
+    return typeof payload.exp === 'number' && payload.exp * 1000 - skewMs <= now;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build an SDK client configured from the saved CLI config.
+ *
+ * The 401 wrapper mirrors the dashboard's `fetchWithRefresh`: the server's
+ * access token lives only ~15 minutes (NINEDEPLOY_JWT_ACCESS_TTL) and the
+ * CLI used to persist ONLY that token — every scripted/CI session died a
+ * quarter hour after login. On a 401 from any non-auth endpoint the saved
+ * refresh token mints a fresh pair (single-flight, persisted) and the request
+ * retries once with the new bearer. Auth endpoints manage their own tokens
+ * and must not loop.
+ */
+export function getClient(): NineDeployClient {
+  const cfg = loadConfig();
+  return createClient({
+    baseUrl: cfg.baseUrl,
+    getToken: () => loadConfig().token,
+    // Volume-file uploads and log tailing can be slow; still bounded so a
+    // stalled backend cannot hang a CI runner forever.
+    timeoutMs: 120_000,
+    fetch: (input, init) => fetchWithRefresh(cfg.baseUrl, input, init),
+  });
+}

package/src/commands/backupPolicy.ts

@@ -0,0 +1,123 @@
+/**
+ * `ninedeploy databases backup-policy get|set <dbId>` — 0.12 per-database
+ * backup policy: cron schedule, retention and destination. A database with
+ * no saved policy is on the built-in schedule (daily, 7 kept, active
+ * destination).
+ */
+import type { BackupPolicy, BackupPolicyInput } from '@ninedeploy/sdk';
+import type { NineDeployClient } from '../client.js';
+import { c, error, header, info, spinner, success } from '../lib/format.js';
+
+/** Canonical decimal ids only — the server's `parseId` rule (F537). */
+const CANONICAL_ID = /^[1-9]\d*$/;
+const num = (v: string, usage: string): number => {
+  const n = CANONICAL_ID.test(v) ? Number(v) : Number.NaN;
+  if (!Number.isSafeInteger(n)) {
+    error(usage);
+    throw new Error(usage);
+  }
+  return n;
+};
+
+/** The presets the web card offers. */
+export const BACKUP_CRON_PRESETS: Record<string, string> = {
+  daily: '0 3 * * *',
+  '6h': '0 */6 * * *',
+  weekly: '0 3 * * 0',
+};
+
+function printPolicy(p: BackupPolicy): void {
+  header('Backup policy');
+  if (!p.configured) {
+    info(`Schedule:    built-in (daily, ${p.retainCount} kept, active destination)`);
+    info(c.dim('No policy saved — `ninedeploy databases backup-policy set` creates one.'));
+    return;
+  }
+  info(`Enabled:     ${p.enabled ? 'yes' : c.yellow('no — no scheduled backups')}`);
+  info(`Cron:        ${p.cron}`);
+  info(`Keep:        ${p.retainCount} local`);
+  info(`Remote keep: ${p.localOnly ? '—' : (p.retainRemoteCount ?? `same as local (${p.retainCount})`)}`);
+  info(`Destination: ${p.localOnly ? 'local only' : p.destinationId != null ? `#${p.destinationId}` : 'active destination'}`);
+  if (p.nextRunAt) info(`Next run:    ${p.nextRunAt}`);
+}
+
+/** `ninedeploy databases backup-policy get <dbId>` */
+export async function backupPolicyGet(client: NineDeployClient, idStr: string): Promise<void> {
+  const id = num(idStr, 'Usage: ninedeploy databases backup-policy get <dbId>');
+  try {
+    printPolicy(await spinner('Reading backup policy', () => client.backups.getPolicy(id)));
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+  }
+}
+
+export interface BackupPolicySetOpts {
+  cron?: string;
+  preset?: string;
+  keep?: string;
+  keepRemote?: string;
+  destination?: string;
+  enable?: boolean;
+  disable?: boolean;
+}
+
+const intOpt = (v: string | undefined, flag: string): number | undefined => {
+  if (v === undefined) return undefined;
+  if (!/^\d+$/.test(v)) throw new Error(`${flag} must be a whole number`);
+  return Number(v);
+};
+
+/**
+ * Build the PUT body: the current policy (or the built-in defaults) with the
+ * given flags applied — PUT replaces, so unset flags keep today's values.
+ */
+export function mergePolicyInput(current: BackupPolicy, opts: BackupPolicySetOpts): BackupPolicyInput {
+  if (opts.enable && opts.disable) throw new Error('Use either --enable or --disable, not both');
+  if (opts.cron && opts.preset) throw new Error('Use either --cron or --preset, not both');
+  let cron = opts.cron ?? current.cron ?? undefined;
+  if (opts.preset) {
+    cron = BACKUP_CRON_PRESETS[opts.preset];
+    if (!cron) throw new Error(`--preset must be one of: ${Object.keys(BACKUP_CRON_PRESETS).join(', ')}`);
+  }
+  if (!cron) throw new Error('No schedule yet: pass --cron "<5-field expression>" or --preset daily|6h|weekly');
+  let destinationId = current.destinationId;
+  let localOnly = current.localOnly;
+  if (opts.destination !== undefined) {
+    const d = opts.destination.trim().toLowerCase();
+    if (d === 'local') {
+      localOnly = true;
+      destinationId = null;
+    } else if (d === 'active' || d === 'default') {
+      localOnly = false;
+      destinationId = null;
+    } else if (CANONICAL_ID.test(d)) {
+      localOnly = false;
+      destinationId = Number(d);
+    } else {
+      throw new Error('--destination must be a destination id, "active" or "local"');
+    }
+  }
+  const keepRemote = intOpt(opts.keepRemote, '--keep-remote');
+  return {
+    enabled: opts.disable ? false : opts.enable ? true : current.enabled,
+    cron,
+    retainCount: intOpt(opts.keep, '--keep') ?? current.retainCount,
+    retainRemoteCount: localOnly ? null : (keepRemote ?? current.retainRemoteCount),
+    destinationId,
+    localOnly,
+  };
+}
+
+/** `ninedeploy databases backup-policy set <dbId> [--cron|--preset] [--keep] [--keep-remote] [--destination] [--enable|--disable]` */
+export async function backupPolicySet(client: NineDeployClient, idStr: string, opts: BackupPolicySetOpts): Promise<void> {
+  const id = num(idStr, 'Usage: ninedeploy databases backup-policy set <dbId> [options]');
+  try {
+    const current = await client.backups.getPolicy(id);
+    const input = mergePolicyInput(current, opts);
+    const saved = await spinner('Saving backup policy', () => client.backups.setPolicy(id, input));
+    success('Backup policy saved.');
+    printPolicy(saved);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+  }
+}

package/src/commands/branding.ts

@@ -0,0 +1,83 @@
+/**
+ * `ninedeploy branding {get,set}` — Sprint 4, Gap G-30.
+ *
+ * Operator-side wrapper around the four branding fields the panel
+ * can override: `logoUrl`, `primaryColor`, `supportEmail`,
+ * `footerHtml`. The CLI is the canonical way to set them when
+ * provisioning a fresh instance (the panel is the read path; the
+ * CLI is the write path operators actually use at the terminal).
+ */
+import type { NineDeployClient } from '../client.js';
+import { error, header, info, success } from '../lib/format.js';
+
+export interface BrandingStatus {
+  logoUrl: string | null;
+  primaryColor: string | null;
+  supportEmail: string | null;
+  footerHtml: string | null;
+}
+
+export interface BrandingSetOptions {
+  logoUrl?: string;
+  primaryColor?: string;
+  supportEmail?: string;
+  footerHtml?: string;
+}
+
+// ── `ninedeploy branding get` ─────────────────────────────────────────────
+
+/** Pure entry point — same shape used by the CLI action and the unit test. */
+export async function brandingGet(client: NineDeployClient): Promise<BrandingStatus> {
+  return await client.branding.get();
+}
+
+export async function brandingGetAction(client: NineDeployClient): Promise<void> {
+  header('Branding');
+  let result: BrandingStatus;
+  try {
+    result = await brandingGet(client);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  info(`logoUrl:      ${result.logoUrl ?? '(default)'}`);
+  info(`primaryColor: ${result.primaryColor ?? '(default)'}`);
+  info(`supportEmail: ${result.supportEmail ?? '(default)'}`);
+  info(`footerHtml:   ${result.footerHtml ? `${result.footerHtml.length} chars` : '(default)'}`);
+}
+
+// ── `ninedeploy branding set` ─────────────────────────────────────────────
+
+/** Pure entry point — same shape used by the CLI action and the unit test. */
+export async function brandingSet(
+  client: NineDeployClient,
+  opts: BrandingSetOptions = {},
+): Promise<{ ok: boolean }> {
+  if (
+    opts.logoUrl === undefined &&
+    opts.primaryColor === undefined &&
+    opts.supportEmail === undefined &&
+    opts.footerHtml === undefined
+  ) {
+    throw new Error('At least one of --logo-url, --primary-color, --support-email, --footer-html is required');
+  }
+  return await client.branding.set(opts);
+}
+
+export async function brandingSetAction(
+  client: NineDeployClient,
+  opts: BrandingSetOptions = {},
+): Promise<void> {
+  header('Branding set');
+  let result: Awaited<ReturnType<typeof brandingSet>>;
+  try {
+    result = await brandingSet(client, opts);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  success(`Branding updated (${Object.keys(opts).filter((k) => opts[k as keyof BrandingSetOptions] !== undefined).join(', ')})`);
+  void result;
+}

package/src/commands/buildCache.ts

@@ -0,0 +1,72 @@
+/**
+ * `ninedeploy build-cache stats` — Sprint 3, Gap G-01, PR-A.
+ *
+ * Operator-side view of the build cache plugin. The plugin is the
+ * source of truth (it owns the schema and the cache registration);
+ * this module is just a thin CLI surface that calls the same HTTP
+ * endpoint the panel will use, so the values an operator sees here
+ * are the same values the deploy pipeline will read.
+ */
+import type { NineDeployClient } from '../client.js';
+import { error, header, info, success } from '../lib/format.js';
+
+export interface BuildCacheBackendStats {
+  name: string;
+  entries: number;
+  totalBytes: number;
+  hits: number;
+  misses: number;
+  stores: number;
+  evictions: number;
+}
+
+export interface BuildCacheStats {
+  backends: BuildCacheBackendStats[];
+  totals: Omit<BuildCacheBackendStats, 'name'>;
+}
+
+// ── `ninedeploy build-cache stats` ────────────────────────────────────────
+
+/** Pure entry point — same shape used by the CLI action and the unit test. */
+export async function buildCacheStats(client: NineDeployClient): Promise<BuildCacheStats> {
+  return await client.buildCache.stats();
+}
+
+export async function buildCacheStatsAction(client: NineDeployClient): Promise<void> {
+  header('Build cache stats');
+  let result: BuildCacheStats;
+  try {
+    result = await buildCacheStats(client);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  if (result.backends.length === 0) {
+    info('No build-cache backends are registered. PR-A ships the inline driver; install one via Settings → Plugins.');
+    return;
+  }
+  for (const b of result.backends) {
+    info(`Backend: ${b.name}`);
+    info(`  entries:   ${b.entries}`);
+    info(`  bytes:     ${b.totalBytes}`);
+    info(`  hits:      ${b.hits}`);
+    info(`  misses:    ${b.misses}`);
+    info(`  stores:    ${b.stores}`);
+    info(`  evictions: ${b.evictions}`);
+  }
+  info('Totals:');
+  info(`  entries:   ${result.totals.entries}`);
+  info(`  bytes:     ${result.totals.totalBytes}`);
+  info(`  hits:      ${result.totals.hits}`);
+  info(`  misses:    ${result.totals.misses}`);
+  info(`  stores:    ${result.totals.stores}`);
+  info(`  evictions: ${result.totals.evictions}`);
+  success(`Done. Hit rate: ${hitRate(result.totals)}%`);
+}
+
+function hitRate(t: { hits: number; misses: number }): string {
+  const total = t.hits + t.misses;
+  if (total === 0) return '0.0';
+  return ((t.hits / total) * 100).toFixed(1);
+}

package/src/commands/certificates.ts

@@ -0,0 +1,208 @@
+/**
+ * `ninedeploy certificates {list,expiring}` — G-15 cert
+ * inventory CLI. The server-side surface is in
+ * `lib/certificateInventory.ts`; the CLI is a thin
+ * renderer around `client.traefik.{certificateInventory,
+ * expiringCertificates}`.
+ */
+import { readFileSync } from 'node:fs';
+import type { CustomCertificateSaved } from '@ninedeploy/sdk';
+import type { NineDeployClient } from '../client.js';
+import { prompt } from '../prompts.js';
+import { c, error, header, info, kv, spinner, success, table } from '../lib/format.js';
+import { plain } from './sources.js';
+
+const num = (v: string, usage: string): number => {
+  const n = Number(v);
+  if (Number.isNaN(n)) {
+    error(usage);
+    throw new Error(usage);
+  }
+  return n;
+};
+
+const STATUS_COLOR: Record<string, (s: string) => string> = {
+  valid: c.green,
+  'expiring-soon': c.yellow,
+  expired: c.red,
+  unknown: c.dim,
+};
+
+export async function certificatesList(
+  client: NineDeployClient,
+  opts: { threshold?: string } = {},
+): Promise<void> {
+  const threshold = opts.threshold ? num(opts.threshold, 'Usage: --threshold <days>') : 30;
+  const report = await spinner('Reading inventory', () =>
+    client.traefik.certificateInventory({ threshold }),
+  );
+  header('Certificate inventory');
+  info(`Total:      ${report.summary.total}`);
+  info(`Valid:      ${c.green(String(report.summary.valid))}`);
+  info(`Expiring:   ${c.yellow(String(report.summary.expiringSoon))} (within ${report.summary.expiringThresholdDays}d)`);
+  if (report.summary.expired > 0) {
+    info(`Expired:    ${c.red(String(report.summary.expired))}`);
+  }
+  info(`Fetched:    ${new Date(report.summary.fetchedAt).toLocaleString()}`);
+  if (report.certificates.length === 0) {
+    info('No certificates registered yet.');
+    return;
+  }
+  console.log();
+  table(
+    report.certificates.map((cert) => ({
+      host: cert.host,
+      status: (STATUS_COLOR[cert.status] ?? c.dim)(cert.status),
+      daysToExpiry: cert.daysToExpiry != null ? String(cert.daysToExpiry) : c.dim('—'),
+      expiresAt: cert.notAfter ? new Date(cert.notAfter).toLocaleString() : c.dim('—'),
+      autoRenew: cert.autoRenew ? 'yes' : c.dim('no'),
+    })),
+    ['host', 'status', 'daysToExpiry', 'expiresAt', 'autoRenew'],
+  );
+}
+
+export async function certificatesExpiring(
+  client: NineDeployClient,
+  opts: { days?: string } = {},
+): Promise<void> {
+  const days = opts.days ? num(opts.days, 'Usage: --days <days>') : 30;
+  const res = await spinner('Reading inventory', () =>
+    client.traefik.expiringCertificates({ days }),
+  );
+  header(`Certificates expiring within ${days} days`);
+  info(`Count: ${res.count}`);
+  if (res.count === 0) {
+    info('(none)');
+    return;
+  }
+  console.log();
+  table(
+    res.certificates.map((cert) => ({
+      host: cert.host,
+      status: (STATUS_COLOR[cert.status] ?? c.dim)(cert.status),
+      daysToExpiry: cert.daysToExpiry != null ? String(cert.daysToExpiry) : c.dim('—'),
+      expiresAt: cert.notAfter ? new Date(cert.notAfter).toLocaleString() : c.dim('—'),
+    })),
+    ['host', 'status', 'daysToExpiry', 'expiresAt'],
+  );
+}
+
+// ── Custom certificates (0.14) ─────────────────────────────────────────────
+// `ninedeploy certificates custom list|upload|replace|delete` — operator-only
+// uploaded certificates (`/v1/traefik/certificates/custom`). The PEM files are
+// read from paths; no response carries a private key. Names, hostnames,
+// subjects and issuers come from the certificate itself, so they go through
+// the F1011 sanitiser.
+
+const certMessage = (err: unknown): string => plain(err instanceof Error ? err.message : String(err));
+
+function certId(raw: string | undefined): number {
+  const t = (raw ?? '').trim();
+  return /^[1-9]\d*$/.test(t) && Number.isSafeInteger(Number(t)) ? Number(t) : 0;
+}
+
+function readPemPair(opts: { cert?: string; key?: string }, usage: string): { certPem: string; keyPem: string } | null {
+  if (!opts.cert || !opts.key) {
+    error(usage);
+    return null;
+  }
+  try {
+    return { certPem: readFileSync(opts.cert, 'utf8').trim(), keyPem: readFileSync(opts.key, 'utf8').trim() };
+  } catch (err) {
+    error(`Could not read the PEM files: ${certMessage(err)}`);
+    return null;
+  }
+}
+
+function printSaved(cert: CustomCertificateSaved): void {
+  kv('Hostnames', cert.hostnames.map(plain).join(', '));
+  kv('Expires', new Date(cert.notAfter).toLocaleString());
+  kv('Covers', cert.coveredDomains.length > 0 ? cert.coveredDomains.map((d) => plain(d.hostname)).join(', ') : c.gray('no domains yet'));
+  for (const w of cert.warnings) console.log(`  ${c.yellow('!')} ${c.yellow(plain(w))}`);
+}
+
+/** `ninedeploy certificates custom list` */
+export async function certificatesCustomList(client: NineDeployClient): Promise<void> {
+  try {
+    const certs = await spinner('Reading uploaded certificates', () => client.traefik.customCertificates.list());
+    header('Uploaded certificates');
+    if (certs.length === 0) {
+      info('No certificates uploaded. Add one with `ninedeploy certificates custom upload --name <n> --cert <path> --key <path>`.');
+      return;
+    }
+    table(
+      certs.map((cert) => ({
+        id: cert.id,
+        name: plain(cert.name),
+        hostnames: cert.hostnames.map(plain).join(', '),
+        expires: cert.expired ? c.red(`expired ${new Date(cert.notAfter).toLocaleDateString()}`) : new Date(cert.notAfter).toLocaleDateString(),
+        issuer: cert.issuer ? plain(cert.issuer) : c.dim('—'),
+        covers: cert.coveredDomains.length > 0 ? cert.coveredDomains.map((d) => plain(d.hostname)).join(', ') : c.dim('—'),
+      })),
+      ['id', 'name', 'hostnames', 'expires', 'issuer', 'covers'],
+    );
+  } catch (err) {
+    error(certMessage(err));
+  }
+}
+
+/** `ninedeploy certificates custom upload --name <n> --cert <path> --key <path>` */
+export async function certificatesCustomUpload(
+  client: NineDeployClient,
+  opts: { name?: string; cert?: string; key?: string } = {},
+): Promise<void> {
+  const usage = 'Usage: ninedeploy certificates custom upload --name <name> --cert <chain.pem> --key <key.pem>';
+  const name = opts.name?.trim();
+  if (!name) return error(usage);
+  const pem = readPemPair(opts, usage);
+  if (!pem) return;
+  try {
+    const cert = await spinner('Verifying and uploading', () => client.traefik.customCertificates.upload({ name, ...pem }));
+    success(`Certificate "${plain(cert.name)}" uploaded (id: ${cert.id})`);
+    printSaved(cert);
+  } catch (err) {
+    error(certMessage(err));
+  }
+}
+
+/** `ninedeploy certificates custom replace <id> --cert <path> --key <path> [--name <n>]` */
+export async function certificatesCustomReplace(
+  client: NineDeployClient,
+  idArg: string,
+  opts: { name?: string; cert?: string; key?: string } = {},
+): Promise<void> {
+  const usage = 'Usage: ninedeploy certificates custom replace <id> --cert <chain.pem> --key <key.pem> [--name <name>]';
+  const id = certId(idArg);
+  if (!id) return error(usage);
+  const pem = readPemPair(opts, usage);
+  if (!pem) return;
+  const name = opts.name?.trim();
+  try {
+    const cert = await spinner('Verifying and replacing', () =>
+      client.traefik.customCertificates.replace(id, { ...(name ? { name } : {}), ...pem }),
+    );
+    success(`Certificate #${id} replaced`);
+    printSaved(cert);
+  } catch (err) {
+    error(certMessage(err));
+  }
+}
+
+/** `ninedeploy certificates custom delete <id> [--yes]` */
+export async function certificatesCustomDelete(client: NineDeployClient, idArg: string, opts: { yes?: boolean } = {}): Promise<void> {
+  const id = certId(idArg);
+  if (!id) return error('Usage: ninedeploy certificates custom delete <id> [--yes]');
+  if (!opts.yes) {
+    const confirm = await prompt(`Type "delete" to remove certificate #${id} (covered domains fall back to ACME)`, '');
+    if (confirm.trim() !== 'delete') {
+      info('Aborted.');
+      return;
+    }
+  }
+  try {
+    await spinner('Deleting the certificate', () => client.traefik.customCertificates.delete(id));
+    success(`Certificate #${id} deleted`);
+  } catch (err) {
+    error(certMessage(err));
+  }
+}