@aiaiai-pt/martha-cli 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [0.3.0] — 2026-05-10
+
+First-run UX for third-party developers and agent runtimes.
+
+### Added
+- `martha init` — interactive wizard that writes a profile to `~/.martha/config.yaml`. Two presets: `cloud` (martha.nomadriver.co + auth.nomadriver.co) and `local` (localhost:8080 + 8180). Idempotent with `--force`; rejects overwrites without it.
+- `martha doctor` — five-check diagnostic: API health, API/CLI version skew (via the new `GET /api/version` endpoint), Keycloak OIDC discovery, stored token validity, authenticated request. Exits non-zero only on FAIL, not WARN.
+- `martha skill` — prints the bundled `SKILL.md` to stdout. Agent runtimes that don't read filesystems by convention can now seed prompt context with `npx -y @aiaiai-pt/martha-cli@0.3.0 skill | head -200`.
+
+### Changed
+- Bundled binary is ~615 KB (small growth for the three new commands + their helpers).
+
+### Notes
+- Requires the Martha API to expose `GET /api/version` for the skew check; older APIs return 404 and `doctor` flags it as a warning, not a failure.
+- Skill discovery looks for `skills/martha-cli/SKILL.md` next to the bundle (npm install) or up the tree (dev checkout); both work.
+- Tracking: [#292](https://github.com/westeuropeco/martha/issues/292) Phase 1.
+
 ## [0.2.0] — 2026-05-09
 
 First public release on npm.

package/README.md

@@ -30,15 +30,20 @@ Requires Node.js >= 22.
 ## Quickstart
 
 ```bash
-# 1. Configure a profile (interactive wizard ships in 0.3.0; until then edit ~/.martha/config.yaml)
-martha config show
+# 1. Configure a profile — writes ~/.martha/config.yaml
+martha init                       # interactive (defaults to cloud preset)
+martha init --preset local        # localhost dev stack
+martha init --no-interactive --name staging --api-url https://...   # scripted
 
 # 2. Authenticate
 martha auth login                 # browser flow (PKCE)
 martha auth login --username u --password p   # headless
 export MARTHA_TOKEN=eyJhbGc...    # bypass login (CI / one-off)
 
-# 3. Run something
+# 3. Verify everything is wired up
+martha doctor                     # API + Keycloak + token + version skew
+
+# 4. Run something
 martha agents list
 martha functions list --json | jq '.[].name'
 martha chat my-agent "Summarise the latest task in tracker INGEST-42"
@@ -90,21 +95,19 @@ Exit codes: `0` success · `1` generic error · `2` auth failure · `3` not foun
 This package ships an agent-facing skill reference at `skills/martha-cli/SKILL.md` describing every command, JSON contract, and conceptual primitive (tenant, agent, function, task, etc.). Agent harnesses can pull it directly:
 
 ```bash
-# After global install
-cat $(npm root -g)/@aiaiai-pt/martha-cli/skills/martha-cli/SKILL.md
+# Print the skill to stdout (works for npm i -g and npx)
+martha skill
 
-# Or via npx (no install)
-npx -y -p @aiaiai-pt/martha-cli@latest sh -c 'cat $(dirname $(which martha))/../lib/node_modules/@aiaiai-pt/martha-cli/skills/martha-cli/SKILL.md' 2>/dev/null
+# Seed an agent's prompt context
+npx -y @aiaiai-pt/martha-cli@latest skill | head -200
 ```
 
-A first-class `martha skill` command lands in 0.3.0.
-
 ## Stability
 
 `0.x` releases may change CLI flags or JSON output between minor versions. Pin a version in CI/agent contexts:
 
 ```bash
-npx -y @aiaiai-pt/martha-cli@0.2.0 ...
+npx -y @aiaiai-pt/martha-cli@0.3.0 ...
 ```
 
 `1.0.0` will commit to a stable contract — see the [tracking issue](https://github.com/westeuropeco/martha/issues/292).

package/dist/index.js

@@ -1019,7 +1019,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;
@@ -10830,7 +10830,7 @@ function registerDefinitionCommands(program2, config) {
   function isJson() {
     return !!program2.opts().json;
   }
-  const listCmd = cmd.command("list").description(`List ${config.typeNamePlural}`).option("--inactive", "Include inactive items").option("--limit <n>", "Max results", "50");
+  const listCmd = cmd.command("list").description(`List ${config.typeNamePlural}`).option("--inactive", "Include inactive items").option("--limit <n>", "Max results per page", "50").option("--search <term>", "Case-insensitive substring filter on name (server-side)").option("--all", "Auto-paginate until every matching item is fetched (server caps at 500/page)");
   if (config.extraListOptions) {
     config.extraListOptions(listCmd);
   }
@@ -10840,17 +10840,65 @@ function registerDefinitionCommands(program2, config) {
     if (isNaN(limitN) || limitN < 1) {
       throw new CLIError("--limit must be a positive integer", 4 /* Validation */);
     }
-    const params = {
-      limit: String(limitN),
-      skip: "0"
-    };
+    const baseParams = {};
     if (!opts.inactive)
-      params.active_only = "true";
+      baseParams.active_only = "true";
+    if (opts.search)
+      baseParams.name_contains = String(opts.search);
     if (config.buildListParams) {
-      Object.assign(params, config.buildListParams(opts));
+      Object.assign(baseParams, config.buildListParams(opts));
+    }
+    let items;
+    let total;
+    if (opts.all) {
+      const pageSize = 500;
+      items = [];
+      let skip = 0;
+      while (true) {
+        const params = {
+          ...baseParams,
+          limit: String(pageSize),
+          skip: String(skip)
+        };
+        const res = await ctx.api.getRaw(config.apiPath, { params });
+        if (!res.ok) {
+          throw new CLIError(`List ${config.typeNamePlural} failed: HTTP ${res.status}`, 1 /* Error */);
+        }
+        const headerTotal = res.headers.get("x-total-count");
+        if (headerTotal !== null && total === undefined) {
+          total = Number(headerTotal);
+        }
+        const body = await res.json();
+        const pageItems = config.extractList(body);
+        items.push(...pageItems);
+        if (pageItems.length < pageSize)
+          break;
+        if (total !== undefined && items.length >= total)
+          break;
+        skip += pageSize;
+        if (skip > 50000) {
+          throw new CLIError(`Aborted --all after fetching ${items.length} ${config.typeNamePlural}; suspected pagination bug`, 1 /* Error */);
+        }
+      }
+    } else {
+      const params = {
+        ...baseParams,
+        limit: String(limitN),
+        skip: "0"
+      };
+      const res = await ctx.api.getRaw(config.apiPath, { params });
+      if (!res.ok) {
+        throw new CLIError(`List ${config.typeNamePlural} failed: HTTP ${res.status}`, 1 /* Error */);
+      }
+      const headerTotal = res.headers.get("x-total-count");
+      if (headerTotal !== null)
+        total = Number(headerTotal);
+      const data = await res.json();
+      items = config.extractList(data);
+      const bodyTotal = config.extractTotal?.(data);
+      if (bodyTotal !== undefined)
+        total = bodyTotal;
     }
-    const data = await ctx.api.get(config.apiPath, { params });
-    const items = config.extractList(data);
     if (isJson()) {
       console.log(JSON.stringify(items, null, 2));
       return;
@@ -10862,10 +10910,10 @@ function registerDefinitionCommands(program2, config) {
     for (const item of items) {
       console.log(config.listColumns.map((col, i) => col.accessor(item).padEnd(widths[i])).join("  "));
     }
-    const total = config.extractTotal?.(data);
     if (total !== undefined && total > items.length) {
+      const hint = opts.search ? `(narrow with --search or use --all)` : `(use --search <term> or --all to load everything)`;
       console.log(source_default.dim(`
-${items.length} of ${total} ${config.typeNamePlural} (use --limit ${total} to see all)`));
+${items.length} of ${total} ${config.typeNamePlural} ${hint}`));
     } else {
       console.log(source_default.dim(`
 ${items.length} ${config.typeNamePlural}`));
@@ -10995,7 +11043,7 @@ import { createInterface as createInterface2 } from "node:readline";
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.2.0";
+var CLI_VERSION = "0.3.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -11456,16 +11504,46 @@ Error: ${err instanceof Error ? err.message : String(err)}
 `);
 }
 async function runOneShot(ctx, sessionId, message, isJson, clientId, showTools, timeoutMs) {
+  const toolCalls = [];
+  function recordToolStatus(data) {
+    try {
+      const tools = JSON.parse(data);
+      for (const t of tools) {
+        const name = t.tool_name ?? t.tool_label;
+        if (!name)
+          continue;
+        toolCalls.push({ name, status: t.status });
+      }
+    } catch {}
+  }
+  function recordToolCall(data) {
+    try {
+      const parsed = JSON.parse(data);
+      if (parsed.name)
+        toolCalls.push({ name: parsed.name });
+    } catch {}
+  }
   const { response } = await sendMessage(ctx, sessionId, message, {
     clientId,
     timeoutMs,
-    onToolCall: showTools ? (data) => process.stderr.write(formatToolCall(data)) : undefined,
+    onToolStatus: isJson ? recordToolStatus : showTools ? (data) => {
+      recordToolStatus(data);
+      process.stderr.write(formatToolStatus(data));
+    } : undefined,
+    onToolCall: isJson ? recordToolCall : showTools ? (data) => {
+      recordToolCall(data);
+      process.stderr.write(formatToolCall(data));
+    } : undefined,
     onToolResult: showTools ? (data) => process.stderr.write(formatToolResult(data)) : undefined,
     onClear: showTools ? () => process.stderr.write(source_default.dim(`  --- tool iteration ---
 `)) : undefined
   });
   if (isJson) {
-    console.log(JSON.stringify({ session_id: sessionId, response }));
+    console.log(JSON.stringify({
+      session_id: sessionId,
+      response,
+      tool_calls: toolCalls
+    }));
   } else {
     console.log(response);
   }
@@ -15729,23 +15807,30 @@ async function resolveClientId(ctx, nameOrId) {
 async function resolveDefinitionId(ctx, type, name) {
   if (type === "agent")
     return name;
-  const path5 = type === "function" ? `${DEFS_API}/functions` : `${DEFS_API}/workflows`;
-  const data = await ctx.api.get(path5, {
-    params: { limit: "500", skip: "0" }
-  });
-  let items;
-  if (Array.isArray(data)) {
-    items = data;
-  } else if (data && typeof data === "object" && "items" in data) {
-    items = data.items;
-  } else {
-    throw new CLIError(`Unexpected response shape from ${type}s list`, 1 /* Error */);
-  }
-  const match = items.find((d) => String(d.name ?? "").toLowerCase() === name.toLowerCase());
-  if (!match) {
-    throw new CLIError(`${type} not found: '${name}'`, 3 /* NotFound */, `Run \`martha ${type}s list\` to see available ${type}s.`);
+  const listPath = type === "function" ? `${DEFS_API}/functions` : `${DEFS_API}/workflows`;
+  const exactPath = `${listPath}/${encodeURIComponent(name)}`;
+  try {
+    const exact = await ctx.api.get(exactPath);
+    if (exact && typeof exact === "object" && "id" in exact) {
+      return String(exact.id);
+    }
+  } catch (e) {
+    const code = e?.status ?? e?.statusCode;
+    if (code !== 404)
+      throw e;
   }
-  return String(match.id);
+  let suggestion = "";
+  try {
+    const fuzzy = await ctx.api.get(listPath, {
+      params: { name_contains: name, limit: "5", skip: "0" }
+    });
+    const items = Array.isArray(fuzzy) ? fuzzy : fuzzy && typeof fuzzy === "object" && ("items" in fuzzy) ? fuzzy.items : [];
+    const names = items.map((d) => String(d.name ?? "")).filter((n) => n.length > 0).slice(0, 5);
+    if (names.length > 0) {
+      suggestion = `Did you mean: ${names.join(", ")}?`;
+    }
+  } catch {}
+  throw new CLIError(`${type} not found: '${name}'`, 3 /* NotFound */, suggestion || `Run \`martha ${type}s list --search ${name}\` to find it.`);
 }
 function formatDate(val) {
   if (!val)
@@ -16231,7 +16316,11 @@ ${clients.length} client(s)`));
     const result = await ctx.api.get(`${API}/${clientId}`);
     const assetBaseUrl = getEmbedAssetBaseUrl(ctx.profile.api_url);
     if (isJson()) {
-      console.log(JSON.stringify({ ...result, asset_base_url: assetBaseUrl, embed_credentials: credentials }, null, 2));
+      console.log(JSON.stringify({
+        ...result,
+        asset_base_url: assetBaseUrl,
+        embed_credentials: credentials
+      }, null, 2));
       return;
     }
     printEmbedSummary(result, assetBaseUrl);
@@ -16331,7 +16420,9 @@ ${clients.length} client(s)`));
       const manifestPath = `/api/embed/manifest/${encodeURIComponent(key)}`;
       const manifest = await ctx.api.get(manifestPath, { headers: { Origin: origin } });
       const deniedUrl = `${deriveMarthaWebOrigin(ctx.profile.api_url)}${manifestPath}`;
-      const denied = await fetch(deniedUrl, { headers: { Origin: deniedOrigin } });
+      const denied = await fetch(deniedUrl, {
+        headers: { Origin: deniedOrigin }
+      });
       if (denied.status !== 403) {
         throw new CLIError(`Denied-origin manifest check expected 403, got ${denied.status}`, 1 /* Error */);
       }
@@ -16742,6 +16833,362 @@ ${pages.length} pages`));
   });
 }
 
+// src/commands/init.ts
+import readline from "node:readline/promises";
+init_config();
+init_errors();
+var PRESETS = {
+  cloud: {
+    name: "cloud",
+    api_url: "https://martha.nomadriver.co",
+    keycloak_url: "https://auth.nomadriver.co",
+    keycloak_realm: "frank"
+  },
+  local: {
+    name: "local",
+    api_url: "http://localhost:8080",
+    keycloak_url: "http://localhost:8180",
+    keycloak_realm: "frank"
+  }
+};
+async function prompt2(rl, question, fallback) {
+  const answer = await rl.question(`  ${question} ${source_default.dim(`[${fallback}]`)} `);
+  return answer.trim() || fallback;
+}
+async function initCommand(opts) {
+  const presetKey = opts.preset ?? "cloud";
+  const preset = PRESETS[presetKey];
+  if (!preset) {
+    throw new CLIError(`Unknown preset: ${presetKey}. Choose one of: ${Object.keys(PRESETS).join(", ")}.`, 4 /* Validation */);
+  }
+  const profileName = opts.name ?? presetKey;
+  const config = loadConfig();
+  if (config.profiles[profileName] && !opts.force) {
+    throw new CLIError(`Profile ${source_default.cyan(profileName)} already exists. Re-run with --force to overwrite, or pass --profile <name> to add a new one.`, 5 /* Conflict */);
+  }
+  const interactive = !opts.noInteractive && process.stdin.isTTY && !opts.apiUrl && !opts.keycloakUrl && !opts.keycloakRealm;
+  let profile = {
+    api_url: opts.apiUrl ?? preset.api_url,
+    keycloak_url: opts.keycloakUrl ?? preset.keycloak_url,
+    keycloak_realm: opts.keycloakRealm ?? preset.keycloak_realm,
+    auth_type: "oidc"
+  };
+  if (interactive) {
+    console.log(source_default.bold(`
+Martha CLI — first-run setup
+`));
+    console.log(`  Preset:  ${source_default.cyan(preset.name)}`);
+    console.log(`  Profile: ${source_default.cyan(profileName)}`);
+    console.log(`  Press enter to accept defaults, or type a new value.
+`);
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    try {
+      profile.api_url = await prompt2(rl, "API URL:     ", profile.api_url);
+      profile.keycloak_url = await prompt2(rl, "Keycloak URL:", profile.keycloak_url);
+      profile.keycloak_realm = await prompt2(rl, "Keycloak realm:", profile.keycloak_realm);
+    } finally {
+      rl.close();
+    }
+  }
+  config.profiles[profileName] = profile;
+  config.current_profile = profileName;
+  saveConfig(config);
+  console.log();
+  console.log(source_default.green(`Profile saved.
+`));
+  console.log(`  Profile:     ${source_default.cyan(profileName)}`);
+  console.log(`  API URL:     ${profile.api_url}`);
+  console.log(`  Keycloak:    ${profile.keycloak_url}`);
+  console.log(`  Realm:       ${profile.keycloak_realm}`);
+  console.log();
+  console.log(source_default.dim("  Next:"));
+  console.log(source_default.dim("    martha auth login                    # browser PKCE"));
+  console.log(source_default.dim("    martha auth login --service-account  # CI/agent"));
+  console.log(source_default.dim("    martha doctor                        # verify setup"));
+}
+function registerInitCommand(program2) {
+  program2.command("init").description("Create or update a profile in ~/.martha/config.yaml").option("--preset <name>", "Preset: cloud or local", "cloud").option("--name <name>", "Profile name (defaults to preset name)").option("--force", "Overwrite an existing profile").option("--api-url <url>", "Override the API URL").option("--keycloak-url <url>", "Override the Keycloak URL").option("--keycloak-realm <realm>", "Override the Keycloak realm").option("--no-interactive", "Skip prompts; use defaults / overrides only").action(async (opts) => {
+    await initCommand(opts);
+  });
+}
+
+// src/commands/doctor.ts
+var FETCH_TIMEOUT_MS = 5000;
+async function fetchJSON(url, init) {
+  const res = await fetch(url, {
+    ...init,
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  });
+  let json = null;
+  const ct = res.headers.get("content-type") ?? "";
+  if (ct.includes("application/json")) {
+    json = await res.json().catch(() => null);
+  }
+  return { ok: res.ok, status: res.status, json };
+}
+async function checkApiHealth(ctx) {
+  const url = `${ctx.profile.api_url}/health`;
+  try {
+    const { ok, status, json } = await fetchJSON(url);
+    if (ok && json?.status === "healthy") {
+      return {
+        name: "API health",
+        status: "pass",
+        detail: ctx.profile.api_url
+      };
+    }
+    return {
+      name: "API health",
+      status: "fail",
+      detail: `${url} → HTTP ${status}`,
+      remedy: "Check api_url in ~/.martha/config.yaml."
+    };
+  } catch (err) {
+    return {
+      name: "API health",
+      status: "fail",
+      detail: `${url} unreachable: ${err instanceof Error ? err.message : String(err)}`,
+      remedy: "Check api_url + your network."
+    };
+  }
+}
+async function checkApiVersion(ctx) {
+  const url = `${ctx.profile.api_url}/api/version`;
+  try {
+    const { ok, status, json } = await fetchJSON(url);
+    if (!ok || !json) {
+      if (status === 404) {
+        return {
+          name: "API version",
+          status: "warn",
+          detail: `${url} → 404 (server predates /api/version)`,
+          remedy: "Server upgrade recommended; harmless for now."
+        };
+      }
+      return {
+        name: "API version",
+        status: "fail",
+        detail: `${url} → HTTP ${status}`
+      };
+    }
+    const v = json;
+    const apiV = v.api_version ?? "unknown";
+    const minCli = v.min_cli_version;
+    if (minCli && compareSemver(CLI_VERSION, minCli) < 0) {
+      return {
+        name: "API version",
+        status: "fail",
+        detail: `api=${apiV} requires CLI >= ${minCli} (you have ${CLI_VERSION})`,
+        remedy: "Upgrade: npm i -g @aiaiai-pt/martha-cli@latest"
+      };
+    }
+    return {
+      name: "API version",
+      status: "pass",
+      detail: `api=${apiV} cli=${CLI_VERSION}`
+    };
+  } catch (err) {
+    return {
+      name: "API version",
+      status: "warn",
+      detail: `${url} unreachable: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+async function checkKeycloak(ctx) {
+  const url = `${ctx.profile.keycloak_url}/realms/${ctx.profile.keycloak_realm}/.well-known/openid-configuration`;
+  try {
+    const { ok, status, json } = await fetchJSON(url);
+    if (ok && json?.issuer) {
+      return {
+        name: "Keycloak",
+        status: "pass",
+        detail: `${ctx.profile.keycloak_url} (realm=${ctx.profile.keycloak_realm})`
+      };
+    }
+    return {
+      name: "Keycloak",
+      status: "fail",
+      detail: `${url} → HTTP ${status}`,
+      remedy: `Verify keycloak_url + keycloak_realm in ~/.martha/config.yaml.`
+    };
+  } catch (err) {
+    return {
+      name: "Keycloak",
+      status: "fail",
+      detail: `${url} unreachable: ${err instanceof Error ? err.message : String(err)}`,
+      remedy: "Check keycloak_url + your network."
+    };
+  }
+}
+function checkAuth(ctx) {
+  const tokens = ctx.tokenStore.getTokens(ctx.profileName);
+  if (!tokens) {
+    return {
+      name: "Auth",
+      status: "warn",
+      detail: "no token stored",
+      remedy: "Run `martha auth login` (or set MARTHA_CLIENT_ID/SECRET for service accounts)."
+    };
+  }
+  const expired = ctx.tokenStore.isExpired(ctx.profileName);
+  if (expired) {
+    return {
+      name: "Auth",
+      status: "warn",
+      detail: `token expired (${tokens.auth_type})`,
+      remedy: "Run `martha auth login` to refresh."
+    };
+  }
+  const expiresAt = new Date(tokens.expires_at * 1000);
+  return {
+    name: "Auth",
+    status: "pass",
+    detail: `${tokens.auth_type} (${tokens.username ?? "n/a"}, exp ${expiresAt.toLocaleString()})`
+  };
+}
+async function checkAuthenticatedRequest(ctx) {
+  const tokens = ctx.tokenStore.getTokens(ctx.profileName);
+  if (!tokens || ctx.tokenStore.isExpired(ctx.profileName)) {
+    return {
+      name: "API auth",
+      status: "warn",
+      detail: "skipped — no valid token"
+    };
+  }
+  const url = `${ctx.profile.api_url}/api/admin/definitions/agents`;
+  try {
+    const { ok, status } = await fetchJSON(url, {
+      headers: { Authorization: `Bearer ${tokens.access_token}` }
+    });
+    if (ok) {
+      return { name: "API auth", status: "pass", detail: "token accepted" };
+    }
+    if (status === 401) {
+      return {
+        name: "API auth",
+        status: "fail",
+        detail: "401 — token rejected by API",
+        remedy: "Token may be for a different realm or expired. Re-run `martha auth login`."
+      };
+    }
+    if (status === 403) {
+      return {
+        name: "API auth",
+        status: "warn",
+        detail: "403 — token valid but lacks role for /api/admin/definitions/agents"
+      };
+    }
+    return {
+      name: "API auth",
+      status: "fail",
+      detail: `${url} → HTTP ${status}`
+    };
+  } catch (err) {
+    return {
+      name: "API auth",
+      status: "warn",
+      detail: `unreachable: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+function compareSemver(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10));
+  const pb = b.split(".").map((n) => parseInt(n, 10));
+  for (let i = 0;i < 3; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da !== db)
+      return da - db;
+  }
+  return 0;
+}
+function statusGlyph(s) {
+  if (s === "pass")
+    return source_default.green("PASS");
+  if (s === "warn")
+    return source_default.yellow("WARN");
+  return source_default.red("FAIL");
+}
+async function doctorCommand(ctx) {
+  console.log(source_default.bold(`Martha CLI doctor
+`));
+  console.log(`  Profile:     ${source_default.cyan(ctx.profileName)}`);
+  console.log(`  CLI version: ${CLI_VERSION}`);
+  console.log();
+  const results = [];
+  results.push(await checkApiHealth(ctx));
+  results.push(await checkApiVersion(ctx));
+  results.push(await checkKeycloak(ctx));
+  results.push(checkAuth(ctx));
+  results.push(await checkAuthenticatedRequest(ctx));
+  for (const r of results) {
+    console.log(`  ${statusGlyph(r.status)}  ${r.name.padEnd(14)} ${source_default.dim(r.detail)}`);
+    if (r.remedy) {
+      console.log(`         ${source_default.dim("→ " + r.remedy)}`);
+    }
+  }
+  const failures = results.filter((r) => r.status === "fail").length;
+  const warnings = results.filter((r) => r.status === "warn").length;
+  console.log();
+  if (failures > 0) {
+    console.log(source_default.red(`  ${failures} check(s) failed.`));
+    process.exitCode = 1;
+  } else if (warnings > 0) {
+    console.log(source_default.yellow(`  All required checks passed (${warnings} warning(s)).`));
+  } else {
+    console.log(source_default.green(`  All checks passed.`));
+  }
+}
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("Run diagnostic checks against the active profile").action(async () => {
+    const ctx = createContext({
+      profileOverride: program2.opts().profile,
+      verbose: program2.opts().verbose
+    });
+    if (program2.opts().apiUrl) {
+      ctx.profile.api_url = program2.opts().apiUrl;
+    }
+    await doctorCommand(ctx);
+  });
+}
+
+// src/commands/skill.ts
+init_errors();
+import fs9 from "node:fs";
+import path5 from "node:path";
+import { fileURLToPath } from "node:url";
+function locateSkill() {
+  const here = path5.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path5.join(here, "skills", "martha-cli", "SKILL.md"),
+    path5.join(here, "..", "skills", "martha-cli", "SKILL.md"),
+    path5.join(here, "..", "..", "..", "skills", "martha-cli", "SKILL.md"),
+    path5.join(here, "..", "..", "skills", "martha-cli", "SKILL.md")
+  ];
+  for (const p of candidates) {
+    if (fs9.existsSync(p))
+      return p;
+  }
+  return null;
+}
+async function skillCommand() {
+  const skillPath = locateSkill();
+  if (!skillPath) {
+    throw new CLIError("SKILL.md not found in the installed package. Reinstall via `npm i -g @aiaiai-pt/martha-cli` or `npx -y @aiaiai-pt/martha-cli@latest skill`.", 1 /* Error */);
+  }
+  const body = fs9.readFileSync(skillPath, "utf-8");
+  process.stdout.write(body);
+}
+function registerSkillCommand(program2) {
+  program2.command("skill").description("Print the bundled agent skill reference (SKILL.md) to stdout").action(async () => {
+    await skillCommand();
+  });
+}
+
 // src/index.ts
 var program2 = new Command;
 program2.name("martha").description("Terminal-first client for the Martha AI platform").version(CLI_VERSION).option("--profile <name>", "Use a named profile").option("--json", "Machine-readable JSON output").option("--quiet", "Suppress non-essential output").option("--verbose", "Verbose logging").option("--no-color", "Disable color output").option("--api-url <url>", "Override API base URL");
@@ -16802,6 +17249,9 @@ registerMessagingCommands(program2);
 registerClientCommands(program2);
 registerModelsCommand(program2);
 registerSessionCommands(program2);
+registerInitCommand(program2);
+registerDoctorCommand(program2);
+registerSkillCommand(program2);
 async function main() {
   try {
     await program2.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {