@tolinax/ayoune-cli 2026.10.1 → 2026.11.1

package/lib/api/login.js

@@ -13,10 +13,14 @@ export const login = async () => {
     const token = randomAsciiString();
     const url = `${config.loginUrl}/ayoune?cli=${token}`;
     const clickable = terminalLink(chalk.cyan.underline(url), url);
-    console.log();
-    console.log(`  ${chalk.dim("Open this URL to authenticate:")}`);
-    console.log(`  ${clickable}`);
-    console.log();
+    // Print the auth URL to STDERR — the same stream the spinner uses — so we
+    // don't pollute stdout when a piped command triggers a re-login (e.g. 401
+    // refresh inside apiCallHandler). stdout is reserved for the data payload
+    // so `ay list contacts | jq` keeps working.
+    process.stderr.write("\n");
+    process.stderr.write(`  ${chalk.dim("Open this URL to authenticate:")}\n`);
+    process.stderr.write(`  ${clickable}\n`);
+    process.stderr.write("\n");
     const credentials = await waitForCredentials(token);
     return credentials;
 };

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,19 +4,29 @@ 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")
         .alias("j")
-        .description("Manage background jobs, automations, and triggers");
+        .description("Manage background jobs, automations, and triggers")
+        .addHelpText("after", `
+Examples:
+  ay jobs list                       List queued + scheduled jobs
+  ay jobs list --status failed       Show only failed jobs
+  ay jobs get <id>                   Inspect a single job
+  ay jobs retry <id>                 Retry a failed job
+  ay jobs cancel <id>                Cancel a queued job
+  ay jobs triggers list              List automation triggers
+  ay jobs notifications list         List recent notifications`);
     // ay jobs list
     jobs
         .command("list")
         .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 +56,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 +86,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 +146,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/createLoginCommand.js

@@ -9,6 +9,11 @@ export function createLoginCommand(program) {
         .command("login")
         .alias("auth")
         .description("Authenticate with your aYOUne account via browser or JWT token")
+        .addHelpText("after", `
+Examples:
+  ay login                           Open browser to authenticate
+  ay login --token <jwt>             Authenticate with an existing JWT
+  ay auth                            Alias of \`ay login\``)
         .action(async (_options, cmd) => {
         var _a, _b, _c, _d;
         try {

package/lib/commands/createLogoutCommand.js

@@ -7,6 +7,10 @@ export function createLogoutCommand(program) {
         .command("logout")
         .alias("signout")
         .description("Clear stored credentials and log out")
+        .addHelpText("after", `
+Examples:
+  ay logout                          Clear stored credentials
+  ay signout                         Alias of \`ay logout\``)
         .action(async (options) => {
         try {
             spinner.start({ text: "Clearing credentials" });