@tolinax/ayoune-cli 2026.10.1 → 2026.11.0

package/lib/commands/_registry.js

@@ -240,6 +240,11 @@ export const COMMAND_REGISTRY = [
         description: "Provision aYOUne to a cloud provider (AWS / GCP / Azure / DigitalOcean / Hetzner)",
         loader: async () => (await import("./provision/index.js")).createProvisionCommand,
     },
+    {
+        name: "doctor",
+        description: "Run a health check on your local aYOUne environment",
+        loader: async () => (await import("./createDoctorCommand.js")).createDoctorCommand,
+    },
     {
         name: "context",
         aliases: ["ctx"],

package/lib/commands/aggregate/list.js

@@ -9,13 +9,14 @@ import { handleResponseFormatOptions } from "../../helpers/handleResponseFormatO
 import { spinner } from "../../../index.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { cliError } from "../../helpers/cliError.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addListSubcommand(agg, rootProgram) {
     agg
         .command("list")
         .alias("ls")
         .description("List saved aggregation queries")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .option("--search <term>", "Search by name")
         .action(async (options) => {
         var _a, _b, _c, _d, _e;

package/lib/commands/createActionsCommand.js

@@ -5,19 +5,20 @@ import { secureStorage } from "../helpers/secureStorage.js";
 import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR, EXIT_PERMISSION_DENIED } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createActionsCommand(program) {
     program
         .command("actions [search]")
         .alias("act")
         .description("Discover registered API actions from all services")
-        .addHelpText("after", `
-Examples:
-  ay actions                         List all API actions (interactive)
-  ay actions generate                Search actions matching "generate"
-  ay actions --namespace ai          List all AI actions
-  ay actions --host ai.ayoune.app    List actions for a specific host
-  ay actions --method POST           List only POST actions
-  ay actions --list-namespaces       List all available namespaces
+        .addHelpText("after", `
+Examples:
+  ay actions                         List all API actions (interactive)
+  ay actions generate                Search actions matching "generate"
+  ay actions --namespace ai          List all AI actions
+  ay actions --host ai.ayoune.app    List actions for a specific host
+  ay actions --method POST           List only POST actions
+  ay actions --list-namespaces       List all available namespaces
   ay actions -r table --columns "operationId,method,endpoint,host"`)
         .option("--namespace <ns>", "Filter by namespace (e.g. ai, crm, pm)")
         .option("--host <host>", "Filter by host")
@@ -25,8 +26,8 @@ Examples:
         .option("--capability <cap>", "Filter by capability")
         .option("--list-namespaces", "List all unique namespaces")
         .option("--list-hosts", "List all unique hosts")
-        .option("-p, --page <number>", "Page", parseInt, 1)
-        .option("-l, --limit <number>", "Limit", parseInt, 100)
+        .option("-p, --page <number>", "Page", parseInteger, 1)
+        .option("-l, --limit <number>", "Limit", parseInteger, 100)
         .action(async (search, options) => {
         var _a, _b, _c;
         try {

package/lib/commands/createAiCommand.js

@@ -7,6 +7,7 @@ import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
 import { getContextSummary, getContextForAI, hasActiveContext } from "../helpers/contextInjector.js";
+import { parseInteger } from "../helpers/parseInt.js";
 const AI_HOST = "ai.ayoune.app";
 export function createAiCommand(program) {
     const ai = program
@@ -51,8 +52,8 @@ export function createAiCommand(program) {
     // ay ai conversations — list AI conversations
     ai.command("conversations")
         .description("List AI conversations")
-        .option("-l, --limit <number>", "Limit", parseInt, 20)
-        .option("-p, --page <number>", "Page", parseInt, 1)
+        .option("-l, --limit <number>", "Limit", parseInteger, 20)
+        .option("-p, --page <number>", "Page", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -79,8 +80,8 @@ export function createAiCommand(program) {
     // ay ai prompts — list AI prompt templates
     ai.command("prompts")
         .description("List AI prompt templates")
-        .option("-l, --limit <number>", "Limit", parseInt, 20)
-        .option("-p, --page <number>", "Page", parseInt, 1)
+        .option("-l, --limit <number>", "Limit", parseInteger, 20)
+        .option("-p, --page <number>", "Page", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -141,11 +142,11 @@ export function createAiCommand(program) {
     // ay ai generate <type> <prompt> — generate content
     ai.command("generate <type> <prompt...>")
         .description("Generate content (text, image, video)")
-        .addHelpText("after", `
-Types: text, image, video
-
-Examples:
-  ay ai generate text "Write a product description for..."
+        .addHelpText("after", `
+Types: text, image, video
+
+Examples:
+  ay ai generate text "Write a product description for..."
   ay ai generate image "A modern office building"`)
         .action(async (type, promptWords, options) => {
         try {

package/lib/commands/createDbCommand.js

@@ -6,6 +6,7 @@ import { cliError } from "../helpers/cliError.js";
 import { handleResponseFormatOptions } from "../helpers/handleResponseFormatOptions.js";
 import { apiCallHandler } from "../api/apiCallHandler.js";
 import { initializeSettings } from "../helpers/initializeSettings.js";
+import { parseInteger } from "../helpers/parseInt.js";
 function maskUri(uri) {
     return uri.replace(/:\/\/([^:]+):([^@]+)@/, "://***:***@");
 }
@@ -97,7 +98,7 @@ Examples:
         .command("list")
         .alias("ls")
         .description("List configured database targets")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         var _a, _b, _c, _d, _e;
         try {

package/lib/commands/createDoctorCommand.js

@@ -0,0 +1,305 @@
+// `ay doctor` — single-screen health check for the customer's local
+// environment. Diagnoses everything that could prevent the rest of the CLI
+// from working: Docker / Compose installed, the user is logged in, the
+// stored JWT is still valid, the platform's auth endpoint is reachable, the
+// CLI's config dir is writable, and (optionally) which cloud-provider tools
+// are installed for `ay provision`.
+//
+// Output is a single screen with green / yellow / red indicators per check.
+// Designed as the first thing a confused user runs ("nothing works") so each
+// check has a one-line "fix it with X" hint when it fails.
+//
+// Heavy modules (jsonwebtoken, secureStorage, fetch) are loaded only inside
+// the action handler so the help screen stays as fast as the lazy
+// command-loading registry expects.
+import chalk from "chalk";
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from "fs";
+import path from "path";
+import os from "os";
+import { detectRuntime, runCommand } from "../helpers/dockerCompose.js";
+import { hasTool } from "./provision/_detectTools.js";
+import { cliError } from "../helpers/cliError.js";
+import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
+const SEVERITY_GLYPHS = {
+    ok: "✓",
+    warn: "!",
+    error: "✗",
+    info: "·",
+};
+const SEVERITY_COLORS = {
+    ok: chalk.green,
+    warn: chalk.yellow,
+    error: chalk.red,
+    info: chalk.dim,
+};
+function printCheck(r) {
+    const colour = SEVERITY_COLORS[r.severity];
+    const glyph = colour(SEVERITY_GLYPHS[r.severity]);
+    const label = r.label.padEnd(34);
+    const detail = r.detail ? chalk.dim(r.detail) : "";
+    console.log(`  ${glyph} ${label} ${detail}`);
+    if (r.hint && r.severity !== "ok") {
+        console.log(`      ${chalk.dim(r.hint)}`);
+    }
+}
+function printSection(title) {
+    console.log("");
+    console.log(chalk.cyan.bold(`  ${title}`));
+}
+/**
+ * Verify the user's CLI config dir at ~/.config/ayoune/ is writable.
+ * Creates the dir if missing and round-trips a tiny temp file.
+ */
+function checkConfigWritable() {
+    const dir = path.join(os.homedir(), ".config", "ayoune");
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const testFile = path.join(dir, `.doctor-${Date.now()}.tmp`);
+        writeFileSync(testFile, "ok", "utf-8");
+        unlinkSync(testFile);
+        return { label: "Config dir writable", severity: "ok", detail: dir };
+    }
+    catch (e) {
+        return {
+            label: "Config dir writable",
+            severity: "error",
+            detail: dir,
+            hint: `Could not write to config dir: ${e.message}`,
+        };
+    }
+}
+/** Verify Docker is installed (probe `docker --version`). */
+function checkDocker() {
+    const out = runCommand("docker --version 2>&1");
+    if (out.toLowerCase().includes("docker version")) {
+        return { label: "Docker", severity: "ok", detail: out };
+    }
+    return {
+        label: "Docker",
+        severity: "warn",
+        hint: "Install Docker Desktop: https://www.docker.com/products/docker-desktop/",
+    };
+}
+/** Verify Docker Compose is installed (uses the same probe as ay local). */
+function checkDockerCompose() {
+    const runtime = detectRuntime();
+    if (runtime === "compose") {
+        return { label: "Docker Compose", severity: "ok", detail: "compose plugin available" };
+    }
+    if (runtime === "kubernetes") {
+        return {
+            label: "Docker Compose",
+            severity: "info",
+            detail: "not installed (kubectl detected instead)",
+        };
+    }
+    return {
+        label: "Docker Compose",
+        severity: "warn",
+        hint: "Required by `ay local` and `ay setup`. Install Docker Desktop or the compose plugin.",
+    };
+}
+/**
+ * Check whether the user is logged in (token present in secureStorage) and
+ * whether the JWT has not yet expired. Lazy-loads jsonwebtoken via the
+ * existing decodeToken helper to keep the doctor command's own import graph
+ * thin.
+ */
+async function checkAuth() {
+    var _a;
+    const { secureStorage } = await import("../helpers/secureStorage.js");
+    const { decodeToken } = await import("../api/decodeToken.js");
+    const token = secureStorage.getItem("token");
+    if (!token) {
+        return [
+            {
+                label: "Logged in",
+                severity: "warn",
+                detail: "no token stored",
+                hint: "Run `ay login` to authenticate.",
+            },
+        ];
+    }
+    let decoded;
+    try {
+        decoded = decodeToken(token);
+    }
+    catch (e) {
+        return [
+            {
+                label: "Logged in",
+                severity: "error",
+                detail: "stored token is malformed",
+                hint: `Run \`ay logout && ay login\`. (${e.message})`,
+            },
+        ];
+    }
+    const payload = (_a = decoded === null || decoded === void 0 ? void 0 : decoded.payload) !== null && _a !== void 0 ? _a : {};
+    const username = payload.username || payload.email || payload._id || "(unknown)";
+    const exp = typeof payload.exp === "number" ? payload.exp : null;
+    const now = Math.floor(Date.now() / 1000);
+    const results = [
+        { label: "Logged in", severity: "ok", detail: String(username) },
+    ];
+    if (exp === null) {
+        results.push({
+            label: "Token expiry",
+            severity: "info",
+            detail: "no exp claim",
+        });
+    }
+    else if (exp < now) {
+        results.push({
+            label: "Token expiry",
+            severity: "error",
+            detail: `expired ${formatDelta(now - exp)} ago`,
+            hint: "Run `ay login` to refresh your session.",
+        });
+    }
+    else {
+        const remaining = exp - now;
+        const sev = remaining < 3600 ? "warn" : "ok";
+        results.push({
+            label: "Token expiry",
+            severity: sev,
+            detail: `expires in ${formatDelta(remaining)}`,
+            hint: sev === "warn" ? "Consider running `ay login` to refresh." : undefined,
+        });
+    }
+    if (payload.type === "superuser") {
+        results.push({ label: "Account type", severity: "info", detail: "superuser" });
+    }
+    else if (payload.type) {
+        results.push({ label: "Account type", severity: "info", detail: String(payload.type) });
+    }
+    return results;
+}
+/** Format a duration in seconds as a human-readable "Xh Ym" / "Xm" / "Xs" string. */
+function formatDelta(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    const mins = minutes % 60;
+    if (hours < 24)
+        return mins ? `${hours}h ${mins}m` : `${hours}h`;
+    const days = Math.floor(hours / 24);
+    const hrs = hours % 24;
+    return hrs ? `${days}d ${hrs}h` : `${days}d`;
+}
+/**
+ * Probe the platform's auth endpoint with native fetch + a short timeout.
+ * Anything 2xx/4xx counts as "reachable" — we only care that the network
+ * path works, not that the user is authorised.
+ */
+async function checkClusterReachable() {
+    const { config } = await import("../helpers/config.js");
+    const url = config.auditUrl.replace(/\/+$/, "") + "/healthz";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    const start = Date.now();
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        clearTimeout(timer);
+        const elapsed = Date.now() - start;
+        if (res.status < 500) {
+            return {
+                label: "Platform reachable",
+                severity: "ok",
+                detail: `${url} → ${res.status} in ${elapsed}ms`,
+            };
+        }
+        return {
+            label: "Platform reachable",
+            severity: "warn",
+            detail: `${url} → ${res.status} in ${elapsed}ms`,
+            hint: "Endpoint responded with a server error.",
+        };
+    }
+    catch (e) {
+        clearTimeout(timer);
+        return {
+            label: "Platform reachable",
+            severity: "error",
+            detail: e.name === "AbortError" ? "timeout after 5s" : e.message,
+            hint: `Could not reach ${url}. Check your network / firewall.`,
+        };
+    }
+}
+/** List which provision provider tools are present (informational, never errors). */
+function checkProviderTools() {
+    const tools = ["terraform", "aws", "gcloud", "az", "doctl"];
+    return tools.map((t) => ({
+        label: t,
+        severity: hasTool(t) ? "ok" : "info",
+        detail: hasTool(t) ? "installed" : "not installed",
+    }));
+}
+export function createDoctorCommand(program) {
+    program
+        .command("doctor")
+        .description("Run a health check on your local aYOUne environment")
+        .addHelpText("after", `
+Examples:
+  ay doctor                Run all checks
+  ay doctor --providers    Also list which cloud-provider tools are installed
+  ay doctor --quiet        Hide info-level checks (only show non-OK)`)
+        .option("--providers", "Also list cloud-provider CLI tools (terraform, aws, gcloud, az, doctl)", false)
+        .option("--quiet", "Hide info-level checks; only show warnings + errors", false)
+        .action(async (options) => {
+        try {
+            console.log(chalk.cyan.bold("\n  aYOUne Doctor"));
+            console.log(chalk.dim("  Diagnosing your local CLI environment..."));
+            const filter = (rs) => options.quiet ? rs.filter((r) => r.severity !== "ok" && r.severity !== "info") : rs;
+            // Run each check ONCE and reuse the results for both printing and the
+            // final tally. The tool detection probes shell out, so duplicating
+            // them would slow doctor down for no reason.
+            const env = [
+                checkConfigWritable(),
+                checkDocker(),
+                checkDockerCompose(),
+            ];
+            const authResults = await checkAuth();
+            const cluster = await checkClusterReachable();
+            printSection("Local environment");
+            for (const r of filter(env))
+                printCheck(r);
+            printSection("Authentication");
+            for (const r of filter(authResults))
+                printCheck(r);
+            printSection("Connectivity");
+            for (const r of filter([cluster]))
+                printCheck(r);
+            if (options.providers) {
+                printSection("Cloud provider tools (for ay provision)");
+                for (const r of filter(checkProviderTools()))
+                    printCheck(r);
+            }
+            // Exit code: 0 unless any error severity surfaced.
+            const allChecks = [...env, ...authResults, cluster];
+            const errors = allChecks.filter((r) => r.severity === "error").length;
+            const warns = allChecks.filter((r) => r.severity === "warn").length;
+            console.log("");
+            if (errors > 0) {
+                console.log(chalk.red(`  ✗ ${errors} error${errors === 1 ? "" : "s"}`) +
+                    (warns > 0 ? chalk.yellow(`, ${warns} warning${warns === 1 ? "" : "s"}`) : ""));
+                console.log("");
+                process.exit(1);
+            }
+            if (warns > 0) {
+                console.log(chalk.yellow(`  ! ${warns} warning${warns === 1 ? "" : "s"} — see hints above.`));
+                console.log("");
+                return;
+            }
+            console.log(chalk.green("  ✓ All checks passed."));
+            console.log("");
+        }
+        catch (e) {
+            cliError(e.message || "Doctor failed", EXIT_GENERAL_ERROR);
+        }
+    });
+}
+export default createDoctorCommand;

package/lib/commands/createExportCommand.js

@@ -6,6 +6,7 @@ import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
 import { sanitizeFields } from "../helpers/sanitizeFields.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createExportCommand(program) {
     const exp = program
         .command("export")
@@ -15,17 +16,17 @@ export function createExportCommand(program) {
     exp
         .command("run <collection>")
         .description("Export entries from a collection")
-        .addHelpText("after", `
-Examples:
-  ay export run contacts --format csv --fields "firstName,lastName,email"
-  ay export run products --format json --filter "status=active"
+        .addHelpText("after", `
+Examples:
+  ay export run contacts --format csv --fields "firstName,lastName,email"
+  ay export run products --format json --filter "status=active"
   ay export run invoices --format csv --filter "createdAt>2025-01-01" --save`)
         .option("--format <format>", "Export format (json, csv, yaml)", "csv")
         .option("--fields <fields>", "Comma-separated fields to include in export")
         .option("--filter <filters>", "Comma-separated key=value filters")
         .option("--sort <field>", "Sort by field (prefix with - for descending)", "-createdAt")
-        .option("-l, --limit <number>", "Limit results (0 = all)", parseInt, 0)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results (0 = all)", parseInteger, 0)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (collection, options) => {
         var _a, _b, _c, _d, _e;
         try {
@@ -115,8 +116,8 @@ Examples:
         .command("list")
         .alias("ls")
         .description("List previous exports")
-        .option("-l, --limit <number>", "Limit results", parseInt, 25)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 25)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b;
         try {
@@ -163,7 +164,7 @@ Examples:
     exp
         .command("configs")
         .description("List export configurations")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         var _a, _b;
         try {
@@ -189,8 +190,8 @@ Examples:
     exp
         .command("logs")
         .description("List export logs")
-        .option("-l, --limit <number>", "Limit results", parseInt, 25)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 25)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b;
         try {

package/lib/commands/createJobsCommand.js

@@ -4,6 +4,7 @@ import { saveFile } from "../helpers/saveFile.js";
 import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createJobsCommand(program) {
     const jobs = program
         .command("jobs")
@@ -15,8 +16,8 @@ export function createJobsCommand(program) {
         .alias("ls")
         .description("List scheduled/queued jobs")
         .option("--status <status>", "Filter: active, waiting, completed, failed, delayed")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -46,8 +47,8 @@ export function createJobsCommand(program) {
     jobs
         .command("triggers")
         .description("List automation triggers")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -76,8 +77,8 @@ export function createJobsCommand(program) {
         .alias("auto")
         .description("List automations")
         .option("--active", "Show only active automations")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -136,8 +137,8 @@ export function createJobsCommand(program) {
         .command("notifications")
         .alias("notify")
         .description("List recent notifications")
-        .option("-l, --limit <number>", "Limit results", parseInt, 25)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 25)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/createMonitorCommand.js

@@ -4,6 +4,7 @@ import { saveFile } from "../helpers/saveFile.js";
 import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createMonitorCommand(program) {
     const monitor = program
         .command("monitor")
@@ -13,15 +14,15 @@ export function createMonitorCommand(program) {
     monitor
         .command("logs [type]")
         .description("List recent platform logs (api, error, mail, ai, trigger, ...)")
-        .addHelpText("after", `
-Log types: api, error, mail, ai, trigger, doi, export, sms, whatsapp, production, setup, state, shop, score, sensor, stock, soi, reward, merge, download, post, webreceiver, work, computingentitieslogs, consumerapi, accessterminal, googleads
-
-Examples:
-  ay monitor logs error                 List recent error logs
-  ay monitor logs api -l 10             List last 10 API logs
+        .addHelpText("after", `
+Log types: api, error, mail, ai, trigger, doi, export, sms, whatsapp, production, setup, state, shop, score, sensor, stock, soi, reward, merge, download, post, webreceiver, work, computingentitieslogs, consumerapi, accessterminal, googleads
+
+Examples:
+  ay monitor logs error                 List recent error logs
+  ay monitor logs api -l 10             List last 10 API logs
   ay monitor logs ai -r table           List AI logs in table format`)
-        .option("-l, --limit <number>", "Limit results", parseInt, 25)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 25)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .option("--sort <field>", "Sort by field", "-createdAt")
         .action(async (type, options) => {
         var _a, _b, _c;
@@ -87,14 +88,14 @@ Examples:
         .command("list")
         .alias("ls")
         .description("List active alerts")
-        .addHelpText("after", `
-Examples:
-  ay monitor alerts list                          List all active alerts
-  ay monitor alerts list --severity critical      Show critical alerts only
-  ay monitor alerts list --type pod_crash          Filter by alert type
+        .addHelpText("after", `
+Examples:
+  ay monitor alerts list                          List all active alerts
+  ay monitor alerts list --severity critical      Show critical alerts only
+  ay monitor alerts list --type pod_crash          Filter by alert type
   ay monitor alerts list --status acknowledged    Show acknowledged alerts`)
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .option("--severity <level>", "Filter: info, warning, critical")
         .option("--type <type>", "Filter: pod_crash, oom_killed, image_pull_error, deployment_failed, pipeline_failed, cluster_unreachable, high_restart_count, custom")
         .option("--status <status>", "Filter: active, acknowledged, resolved", "active")
@@ -171,7 +172,7 @@ Examples:
     monitor
         .command("sessions")
         .description("List active user sessions")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -197,7 +198,7 @@ Examples:
     monitor
         .command("checks")
         .description("List monitoring checks and their results")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -224,7 +225,7 @@ Examples:
         .command("activeusers")
         .alias("users")
         .description("Show currently active users on the platform")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -251,7 +252,7 @@ Examples:
         .command("pagestats")
         .alias("pages")
         .description("View page view statistics")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/createPermissionsCommand.js

@@ -4,6 +4,7 @@ import { saveFile } from "../helpers/saveFile.js";
 import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR, EXIT_MISUSE } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createPermissionsCommand(program) {
     const perms = program
         .command("permissions")
@@ -20,8 +21,8 @@ export function createPermissionsCommand(program) {
         .alias("ls")
         .description("List permission requests")
         .option("--status <status>", "Filter by status (pending, approved, rejected)")
-        .option("-l, --limit <number>", "Limit results", parseInt, 25)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 25)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -134,8 +135,8 @@ export function createPermissionsCommand(program) {
         .alias("ls")
         .description("List user rights / permission assignments")
         .option("--userId <id>", "Filter by user ID")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -185,17 +186,17 @@ export function createPermissionsCommand(program) {
     perms
         .command("audit")
         .description("Audit permission changes and access logs")
-        .addHelpText("after", `
-Examples:
-  ay permissions audit --action delete --days 30
-  ay permissions audit --userId abc123 --collection contacts
+        .addHelpText("after", `
+Examples:
+  ay permissions audit --action delete --days 30
+  ay permissions audit --userId abc123 --collection contacts
   ay permissions audit --action create --days 7 --save`)
         .option("--userId <id>", "Filter by user ID")
         .option("--action <action>", "Filter by action (create, update, delete, login)")
         .option("--collection <name>", "Filter by collection")
-        .option("--days <number>", "Show entries from last N days", parseInt, 7)
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("--days <number>", "Show entries from last N days", parseInteger, 7)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/createSearchCommand.js

@@ -10,21 +10,22 @@ import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
 import { sanitizeFields } from "../helpers/sanitizeFields.js";
 import { getContextFilterParams } from "../helpers/contextInjector.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createSearchCommand(program) {
     program
         .command("search [collectionOrModule] [collectionOrQuery] [query]")
         .alias("find")
         .description("Search entries via the aYOUne Search Service")
-        .addHelpText("after", `
-Examples:
-  ay search consumers "John"                       Search via search service
-  ay search crm consumers "John"                   Search with explicit module
-  ay search -g "John"                              Global search across all collections (SSE)
-  ay search consumers "John" --one                 Find first match
-  ay search consumers "John" --field name          Search specific field
-  ay search contacts --filter "status=active"      Filter by field
-  ay search orders --filter "status=paid" --sort "-createdAt"
-  ay search consumers "John" --legacy              Use legacy module API
+        .addHelpText("after", `
+Examples:
+  ay search consumers "John"                       Search via search service
+  ay search crm consumers "John"                   Search with explicit module
+  ay search -g "John"                              Global search across all collections (SSE)
+  ay search consumers "John" --one                 Find first match
+  ay search consumers "John" --field name          Search specific field
+  ay search contacts --filter "status=active"      Filter by field
+  ay search orders --filter "status=paid" --sort "-createdAt"
+  ay search consumers "John" --legacy              Use legacy module API
   ay find invoices --filter "total>500" --count    Just count matches`)
         .option("-g, --global <query>", "Global search across all collections (SSE streaming)")
         .option("--field <name>", "Search in a specific field")
@@ -34,8 +35,8 @@ Examples:
         .option("--fields <fields>", "Comma-separated fields to return (projection)")
         .option("--sort <field>", "Sort by field (prefix with - for descending)", "-createdAt")
         .option("--count", "Only return count of matching entries", false)
-        .option("-l, --limit <number>", "Limit results", parseInt, 25)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 25)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (collectionOrModule, collectionOrQuery, query, options) => {
         try {
             const opts = { ...program.opts(), ...options };

package/lib/commands/createServicesCommand.js

@@ -6,6 +6,7 @@ import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
 import { aYOUneModules } from "../../data/modules.js";
 import { aYOUneServices } from "../../data/services.js";
+import { parseInteger } from "../helpers/parseInt.js";
 function buildServiceRegistry() {
     const services = [];
     // APIs from modules
@@ -70,9 +71,9 @@ export function createServicesCommand(program) {
         .command("endpoints <host>")
         .alias("ep")
         .description("List API endpoints for a service host")
-        .addHelpText("after", `
-Examples:
-  ay services endpoints ai.ayoune.app
+        .addHelpText("after", `
+Examples:
+  ay services endpoints ai.ayoune.app
   ay services endpoints crm-api.ayoune.app -r table`)
         .action(async (host, options) => {
         try {
@@ -117,7 +118,7 @@ Examples:
     svc
         .command("health [host]")
         .description("Check health of a service or all services")
-        .option("--timeout <ms>", "Request timeout in ms", parseInt, 5000)
+        .option("--timeout <ms>", "Request timeout in ms", parseInteger, 5000)
         .action(async (host, options) => {
         try {
             const opts = { ...program.opts(), ...options };

package/lib/commands/createSetupCommand.js

@@ -8,6 +8,7 @@ import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
 import { detectRuntime } from "../helpers/dockerCompose.js";
+import { printNextSteps } from "../helpers/printNextSteps.js";
 const AVAILABLE_MODULES = [
     { name: "CRM", value: "crm", description: "Customer Relationship Management" },
     { name: "Marketing", value: "marketing", description: "Marketing automation & campaigns" },
@@ -306,20 +307,16 @@ Examples:
                 await writeFile(valuesPath, valuesContent, "utf-8");
                 spinner.success({ text: "Configuration files generated!" });
                 spinner.stop();
-                console.log(chalk.green("\n  Generated files:"));
-                console.log(chalk.dim(`    ${envPath}`));
-                console.log(chalk.dim(`    ${valuesPath}`));
-                console.log(chalk.cyan("\n  Next steps:"));
-                console.log(chalk.dim("    1. Review and adjust the generated files"));
-                console.log(chalk.dim("    2. helm install ayoune tolinax/ayoune -f values.yaml"));
-                console.log(chalk.dim("    3. ay status  — verify all services are healthy\n"));
+                printNextSteps([
+                    "Review and adjust the generated files",
+                    "helm install ayoune tolinax/ayoune -f values.yaml",
+                    "ay status — verify all services are healthy",
+                ], { preamble: ["Generated files:", `  ${envPath}`, `  ${valuesPath}`] });
             }
             else {
                 spinner.success({ text: "Configuration files generated!" });
                 spinner.stop();
                 const profiles = ["core", ...answers.modules];
-                console.log(chalk.green("\n  Generated files:"));
-                console.log(chalk.dim(`    ${envPath}`));
                 // Offer to launch the stack right away. Skipped non-interactively
                 // (CI / piped) — that path keeps the original "next steps" output.
                 const canLaunch = process.stdin.isTTY && detectRuntime() === "compose";
@@ -339,10 +336,11 @@ Examples:
                     }
                 }
                 if (!launched) {
-                    console.log(chalk.cyan("\n  Next steps:"));
-                    console.log(chalk.dim("    1. Review and adjust the .env file"));
-                    console.log(chalk.dim(`    2. docker compose --profile ${profiles.join(" --profile ")} up -d`));
-                    console.log(chalk.dim("    3. ay status  — verify all services are healthy\n"));
+                    printNextSteps([
+                        "Review and adjust the .env file",
+                        `docker compose --profile ${profiles.join(" --profile ")} up -d`,
+                        "ay status — verify all services are healthy",
+                    ], { preamble: ["Generated files:", `  ${envPath}`] });
                 }
             }
             if (!answers.licenseKey) {

package/lib/commands/createSyncCommand.js

@@ -3,6 +3,7 @@ import { handleResponseFormatOptions } from "../helpers/handleResponseFormatOpti
 import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createSyncCommand(program) {
     const sync = program
         .command("sync")
@@ -11,10 +12,10 @@ export function createSyncCommand(program) {
     sync
         .command("repos")
         .description("Sync repositories from connected providers")
-        .addHelpText("after", `
-Examples:
-  ay sync repos                      Sync all repositories
-  ay sync repos --provider bitbucket  Sync only Bitbucket repos
+        .addHelpText("after", `
+Examples:
+  ay sync repos                      Sync all repositories
+  ay sync repos --provider bitbucket  Sync only Bitbucket repos
   ay sync repos --id <repoId>        Sync a specific repository`)
         .option("--provider <provider>", "Filter by provider (bitbucket, github)")
         .option("--id <repoId>", "Sync a specific repository by ID")
@@ -112,7 +113,7 @@ Examples:
         .command("pipelines")
         .description("Sync pipeline status from CI/CD providers")
         .option("--provider <provider>", "Filter by provider (bitbucket, github)")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         try {
             const opts = { ...program.opts(), ...options };

package/lib/commands/createTemplateCommand.js

@@ -4,6 +4,7 @@ import { saveFile } from "../helpers/saveFile.js";
 import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createTemplateCommand(program) {
     const tmpl = program
         .command("templates")
@@ -19,8 +20,8 @@ export function createTemplateCommand(program) {
         .alias("ls")
         .description("List email templates")
         .option("--search <query>", "Search by name")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -76,8 +77,8 @@ export function createTemplateCommand(program) {
         .command("list")
         .alias("ls")
         .description("List notification templates")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -129,7 +130,7 @@ export function createTemplateCommand(program) {
         .command("list")
         .alias("ls")
         .description("List report templates")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -162,8 +163,8 @@ export function createTemplateCommand(program) {
         .description("List available store templates")
         .option("--category <category>", "Filter by category")
         .option("--search <query>", "Search templates")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/createUsersCommand.js

@@ -5,6 +5,7 @@ import { saveFile } from "../helpers/saveFile.js";
 import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR, EXIT_MISUSE } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createUsersCommand(program) {
     const users = program
         .command("users")
@@ -18,8 +19,8 @@ export function createUsersCommand(program) {
         .option("--search <query>", "Search by name or email")
         .option("--role <roleId>", "Filter by role ID")
         .option("--active", "Show only active users")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -138,8 +139,8 @@ export function createUsersCommand(program) {
         .alias("ls")
         .description("List teams")
         .option("--search <query>", "Search teams by name")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {
@@ -230,7 +231,7 @@ export function createUsersCommand(program) {
         .command("list")
         .alias("ls")
         .description("List available roles")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/createWebhooksCommand.js

@@ -4,6 +4,7 @@ import { saveFile } from "../helpers/saveFile.js";
 import { spinner } from "../../index.js";
 import { EXIT_GENERAL_ERROR, EXIT_MISUSE } from "../exitCodes.js";
 import { cliError } from "../helpers/cliError.js";
+import { parseInteger } from "../helpers/parseInt.js";
 export function createWebhooksCommand(program) {
     const hooks = program
         .command("webhooks")
@@ -14,8 +15,8 @@ export function createWebhooksCommand(program) {
         .command("list")
         .alias("ls")
         .description("List registered webhooks")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
-        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
+        .option("-p, --page <number>", "Page number", parseInteger, 1)
         .action(async (options) => {
         var _a, _b;
         try {
@@ -124,7 +125,7 @@ export function createWebhooksCommand(program) {
     hooks
         .command("templates")
         .description("List available webhook templates")
-        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-l, --limit <number>", "Limit results", parseInteger, 50)
         .action(async (options) => {
         var _a, _b;
         try {

package/lib/commands/deploy/alerts.js

@@ -7,13 +7,14 @@ import { saveFile } from "../../helpers/saveFile.js";
 import { spinner } from "../../../index.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { cliError } from "../../helpers/cliError.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addAlertsSubcommands(deploy, rootProgram) {
     deploy
         .command("alerts")
         .description("List active deployment alerts")
         .option("--severity <level>", "Filter: critical, warning, info")
         .option("--type <type>", "Filter: pod_crash, oom_killed, image_pull_error, deployment_failed, pipeline_failed, cluster_unreachable, high_restart_count, custom")
-        .option("-l, --limit <number>", "Limit", parseInt, 50)
+        .option("-l, --limit <number>", "Limit", parseInteger, 50)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/deploy/clusters.js

@@ -8,6 +8,7 @@ import { saveFile } from "../../helpers/saveFile.js";
 import { spinner } from "../../../index.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { cliError } from "../../helpers/cliError.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addClustersSubcommands(deploy, rootProgram) {
     // ay deploy clusters
     deploy
@@ -18,7 +19,7 @@ export function addClustersSubcommands(deploy, rootProgram) {
 Examples:
   ay deploy clusters                   List all clusters
   ay deploy clusters -r table          Show clusters in table format`)
-        .option("-l, --limit <number>", "Limit", parseInt, 50)
+        .option("-l, --limit <number>", "Limit", parseInteger, 50)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/deploy/deployments.js

@@ -11,6 +11,7 @@ import { spinner } from "../../../index.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { cliError } from "../../helpers/cliError.js";
 import { getDeployToken } from "./_token.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addDeploymentsSubcommands(deploy, rootProgram) {
     // ay deploy list
     deploy
@@ -21,8 +22,8 @@ export function addDeploymentsSubcommands(deploy, rootProgram) {
         .option("--namespace <ns>", "Filter by namespace")
         .option("--health <status>", "Filter: healthy, degraded, crashed, pending")
         .option("-q, --search <term>", "Search by name")
-        .option("-l, --limit <number>", "Limit", parseInt, 50)
-        .option("-p, --page <number>", "Page", parseInt, 1)
+        .option("-l, --limit <number>", "Limit", parseInteger, 50)
+        .option("-p, --page <number>", "Page", parseInteger, 1)
         .action(async (options) => {
         var _a, _b;
         try {
@@ -85,7 +86,7 @@ Examples:
   ay deploy logs 64a1b2c3d4e5 --follow       Stream logs in real-time (SSE)
   ay deploy logs 64a1b2c3d4e5 --tail 100     Last 100 log lines`)
         .option("-f, --follow", "Stream logs in real-time (Server-Sent Events)")
-        .option("--tail <lines>", "Number of recent log lines", parseInt, 50)
+        .option("--tail <lines>", "Number of recent log lines", parseInteger, 50)
         .action(async (id, options) => {
         try {
             const opts = { ...rootProgram.opts(), ...options };

package/lib/commands/deploy/pipelines.js

@@ -10,6 +10,7 @@ import { saveFile } from "../../helpers/saveFile.js";
 import { spinner } from "../../../index.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { cliError } from "../../helpers/cliError.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addPipelinesSubcommands(deploy, rootProgram) {
     // ay deploy pipelines
     deploy
@@ -18,7 +19,7 @@ export function addPipelinesSubcommands(deploy, rootProgram) {
         .description("List recent CI/CD pipelines")
         .option("--repo <slug>", "Filter by repository slug")
         .option("--result <result>", "Filter: SUCCESSFUL, FAILED, STOPPED, EXPIRED")
-        .option("-l, --limit <number>", "Limit", parseInt, 20)
+        .option("-l, --limit <number>", "Limit", parseInteger, 20)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/deploy/plans.js

@@ -8,6 +8,7 @@ import { saveFile } from "../../helpers/saveFile.js";
 import { spinner } from "../../../index.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { cliError } from "../../helpers/cliError.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addPlansSubcommands(deploy, rootProgram) {
     const plans = deploy.command("plans").description("Manage multi-step deployment plans");
     // ay deploy plans list
@@ -15,8 +16,8 @@ export function addPlansSubcommands(deploy, rootProgram) {
         .command("list")
         .alias("ls")
         .description("List deployment plans")
-        .option("-l, --limit <number>", "Limit", parseInt, 50)
-        .option("-p, --page <number>", "Page", parseInt, 1)
+        .option("-l, --limit <number>", "Limit", parseInteger, 50)
+        .option("-p, --page <number>", "Page", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/deploy/pods.js

@@ -8,6 +8,7 @@ import { saveFile } from "../../helpers/saveFile.js";
 import { spinner } from "../../../index.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { cliError } from "../../helpers/cliError.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addPodsSubcommands(deploy, rootProgram) {
     // ay deploy pods
     deploy
@@ -17,7 +18,7 @@ export function addPodsSubcommands(deploy, rootProgram) {
         .option("--namespace <ns>", "Filter by namespace")
         .option("--status <status>", "Filter: Running, Pending, Failed, Succeeded, Unknown")
         .option("--deployment <name>", "Filter by deployment")
-        .option("-l, --limit <number>", "Limit", parseInt, 100)
+        .option("-l, --limit <number>", "Limit", parseInteger, 100)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/deploy/repos.js

@@ -8,6 +8,7 @@ import { saveFile } from "../../helpers/saveFile.js";
 import { spinner } from "../../../index.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { cliError } from "../../helpers/cliError.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addReposSubcommands(deploy, rootProgram) {
     const repos = deploy.command("repos").description("Manage git repositories");
     // ay deploy repos list
@@ -16,8 +17,8 @@ export function addReposSubcommands(deploy, rootProgram) {
         .alias("ls")
         .description("List registered repositories")
         .option("--provider <provider>", "Filter: bitbucket, github")
-        .option("-l, --limit <number>", "Limit", parseInt, 50)
-        .option("-p, --page <number>", "Page", parseInt, 1)
+        .option("-l, --limit <number>", "Limit", parseInteger, 50)
+        .option("-p, --page <number>", "Page", parseInteger, 1)
         .action(async (options) => {
         var _a, _b, _c;
         try {

package/lib/commands/functions/list.js

@@ -5,13 +5,14 @@ import { handleResponseFormatOptions } from "../../helpers/handleResponseFormatO
 import { cliError } from "../../helpers/cliError.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { FN_MODULE, FN_COLLECTION } from "./_shared.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addListSubcommand(fns, rootProgram) {
     fns
         .command("list")
         .alias("ls")
         .description("List user functions for the current customer")
-        .option("-l, --limit <n>", "Limit results", (v) => parseInt(v, 10), 50)
-        .option("-p, --page <n>", "Page number", (v) => parseInt(v, 10), 1)
+        .option("-l, --limit <n>", "Limit results", parseInteger, 50)
+        .option("-p, --page <n>", "Page number", parseInteger, 1)
         .option("--trigger <type>", "Filter by trigger type (cron, http, event, manual, queue)")
         .option("--search <q>", "Search by name or slug")
         .action(async (options) => {

package/lib/commands/functions/logs.js

@@ -10,6 +10,7 @@ import { handleResponseFormatOptions } from "../../helpers/handleResponseFormatO
 import { cliError } from "../../helpers/cliError.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { FN_MODULE, FN_COLLECTION, resolveFunction } from "./_shared.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 function printLogLines(entries) {
     var _a, _b, _c, _d, _e;
     for (const entry of entries) {
@@ -25,7 +26,7 @@ export function addLogsSubcommand(fns, rootProgram) {
         .command("logs <id-or-slug>")
         .description("Show execution logs for a function")
         .option("-f, --follow", "Poll for new log entries every 2s", false)
-        .option("-t, --tail <n>", "Number of recent entries to show", (v) => parseInt(v, 10), 50)
+        .option("-t, --tail <n>", "Number of recent entries to show", parseInteger, 50)
         .option("--json", "Output raw JSON instead of formatted lines", false)
         .action(async (idOrSlug, options) => {
         var _a;

package/lib/commands/functions/versions.js

@@ -8,11 +8,12 @@ import { handleResponseFormatOptions } from "../../helpers/handleResponseFormatO
 import { cliError } from "../../helpers/cliError.js";
 import { EXIT_GENERAL_ERROR } from "../../exitCodes.js";
 import { FN_MODULE, FN_COLLECTION, resolveFunction } from "./_shared.js";
+import { parseInteger } from "../../helpers/parseInt.js";
 export function addVersionsSubcommand(fns, rootProgram) {
     fns
         .command("versions <id-or-slug>")
         .description("Show version history for a function")
-        .option("-l, --limit <n>", "Limit results", (v) => parseInt(v, 10), 50)
+        .option("-l, --limit <n>", "Limit results", parseInteger, 50)
         .action(async (idOrSlug, options) => {
         var _a, _b, _c, _d, _e;
         try {

package/lib/commands/provision/hetzner.js

@@ -23,6 +23,7 @@ import { requireTool } from "./_detectTools.js";
 import { runBaseWizard } from "./_wizard.js";
 import { writeState } from "./_stateFile.js";
 import { spawn } from "child_process";
+import { parseInteger } from "../../helpers/parseInt.js";
 const HETZNER_REGIONS = ["nbg1", "fsn1", "hel1", "ash", "hil", "sin"];
 const HETZNER_INSTANCE_SIZES = ["cax21", "cax31", "cax41", "ccx13", "ccx23", "ccx33"];
 /** Stream a command (NOT docker compose) to the user's terminal. */
@@ -44,7 +45,7 @@ export function addHetznerSubcommand(prov) {
         .option("--token <token>", "Hetzner Cloud API token (or set HCLOUD_TOKEN)")
         .option("--region <region>", `Hetzner location (${HETZNER_REGIONS.join(", ")})`, "nbg1")
         .option("--size <size>", `Server type (${HETZNER_INSTANCE_SIZES.join(", ")})`, "cax21")
-        .option("--servers <n>", "Number of worker nodes", (v) => parseInt(v, 10), 3)
+        .option("--servers <n>", "Number of worker nodes", parseInteger, 3)
         .option("--dry-run", "Render terraform.tfvars and run `terraform plan` only", false)
         .option("-y, --yes", "Skip the final apply confirmation prompt", false)
         .action(async (options) => {

package/lib/helpers/printNextSteps.js

@@ -0,0 +1,34 @@
+// Tiny shared helper for the "Next steps" footer that several commands print
+// at the end of a successful run (setup, provision, local up, ...). The goal
+// is consistent visual framing across the CLI without taking on a `boxen`
+// dep — boxen is ~30 KB and we already keep the dep tree thin on purpose.
+//
+// Usage:
+//   printNextSteps([
+//     "Review the .env file",
+//     "docker compose --profile core up -d",
+//     "ay status — verify all services are healthy",
+//   ]);
+//
+// Or with a heading:
+//   printNextSteps(steps, { title: "Almost done!" });
+//
+// The output goes through console.log so it inherits whatever stdout is
+// hooked up (a TTY in normal use, /dev/null when piped). It does NOT use the
+// spinner — call this AFTER spinner.success/spinner.stop so it doesn't
+// fight the spinner's rendering loop.
+import chalk from "chalk";
+export function printNextSteps(steps, opts = {}) {
+    var _a;
+    if (opts.preamble && opts.preamble.length > 0) {
+        console.log("");
+        for (const line of opts.preamble) {
+            console.log(chalk.green(`  ${line}`));
+        }
+    }
+    console.log(chalk.cyan(`\n  ${(_a = opts.title) !== null && _a !== void 0 ? _a : "Next steps:"}`));
+    steps.forEach((step, i) => {
+        console.log(chalk.dim(`    ${i + 1}. ${step}`));
+    });
+    console.log("");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tolinax/ayoune-cli",
-  "version": "2026.10.1",
+  "version": "2026.11.0",
   "description": "CLI for the aYOUne Business-as-a-Service platform",
   "type": "module",
   "main": "./index.js",