@caphub/cli 0.1.0 → 0.1.1

package/bin/caphub.js

@@ -13,6 +13,8 @@ const CONFIG_PATH = resolve(CONFIG_DIR, "config.json");
 
 const ROOT_HELP = `caphub
 
+Caphub is hosted infrastructure for agent-ready capabilities such as search and query expansion.
+
 purpose: root CLI for Caphub agent capabilities
 auth: CAPHUB_API_KEY env or ${CONFIG_PATH}
 api: ${DEFAULT_API_URL}
@@ -26,6 +28,19 @@ commands:
   auth logout           remove stored api key from local config
   <capability> <json>   run a capability directly, e.g. search or search-ideas
 
+agent workflow:
+  1. caphub capabilities
+  2. caphub help <capability>
+  3. caphub auth login --api-key csk_live_...
+  4. caphub <capability> '<json>'
+
+recovery:
+  no api key            caphub auth login --api-key csk_live_...
+  invalid api key       generate a new key in https://caphub.io/dashboard/
+  insufficient credits  top up in https://caphub.io/dashboard/
+  bad json              caphub help <capability>
+  capability unknown    caphub capabilities
+
 examples:
   caphub capabilities
   caphub auth login --api-key csk_live_...
@@ -33,6 +48,15 @@ examples:
   caphub search '{"queries":["site:github.com awesome ai agents"]}'
 `;
 
+class ApiError extends Error {
+  constructor(message, status = 0, data = null) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.data = data;
+  }
+}
+
 function readConfig() {
   try {
     return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
@@ -82,22 +106,27 @@ async function fetchJson(url, { method = "GET", body, apiKey = "" } = {}) {
   const headers = { "Content-Type": "application/json" };
   if (apiKey) headers["X-API-Key"] = apiKey;
 
-  const resp = await fetch(url, {
-    method,
-    headers,
-    ...(body ? { body: JSON.stringify(body) } : {}),
-  });
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method,
+      headers,
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+  } catch (error) {
+    throw new ApiError(`request failed: ${error.message}`, 0, null);
+  }
 
   const text = await resp.text();
   let data;
   try {
     data = text ? JSON.parse(text) : {};
   } catch {
-    throw new Error(`non-JSON response from ${url} (HTTP ${resp.status})`);
+    throw new ApiError(`non-JSON response from ${url} (HTTP ${resp.status})`, resp.status, null);
   }
 
   if (!resp.ok) {
-    throw new Error(data?.error || `HTTP ${resp.status}`);
+    throw new ApiError(data?.error || `HTTP ${resp.status}`, resp.status, data);
   }
 
   return data;
@@ -109,8 +138,67 @@ function parseFlag(args, name) {
   return args[idx + 1] || "";
 }
 
+function buildRecoveryHints(error, context = {}) {
+  const hints = [];
+  const capability = context.capability || "<capability>";
+  const message = String(error?.message || "").toLowerCase();
+  const status = Number(error?.status || 0);
+
+  if (status === 401 || message.includes("missing x-api-key header")) {
+    hints.push("login: caphub auth login --api-key csk_live_...");
+  }
+
+  if (status === 403 || message.includes("invalid api key")) {
+    hints.push("generate a new key in https://caphub.io/dashboard/");
+    hints.push("login again: caphub auth login --api-key csk_live_...");
+  }
+
+  if (status === 402 || message.includes("insufficient credits")) {
+    hints.push("top up credits in https://caphub.io/dashboard/");
+    hints.push("check account state: caphub auth whoami");
+  }
+
+  if (
+    status === 400 ||
+    message.includes("queries array is required") ||
+    message.includes("unsupported function") ||
+    message.includes("input must be valid json") ||
+    message.includes("input json is required")
+  ) {
+    hints.push(`capability contract: caphub help ${capability}`);
+  }
+
+  if (message.includes("request failed:")) {
+    hints.push(`api url: ${getApiUrl()}`);
+    hints.push(`health: curl -sS ${getApiUrl()}/health`);
+  }
+
+  if (!hints.length) {
+    hints.push("discover capabilities: caphub capabilities");
+    hints.push(`capability contract: caphub help ${capability}`);
+  }
+
+  return hints;
+}
+
+function failWithHints(message, error, context = {}) {
+  const lines = [`Error: ${message}`];
+  const hints = buildRecoveryHints(error, context);
+  if (hints.length) {
+    lines.push("", "next:");
+    for (const hint of hints) lines.push(`  - ${hint}`);
+  }
+  fail(lines.join("\n"));
+}
+
 function printCapabilities(payload) {
-  const lines = ["caphub capabilities", ""];
+  const lines = [
+    "caphub capabilities",
+    "",
+    "Live capabilities available through the current API.",
+    "Use 'caphub help <capability>' before first use.",
+    "",
+  ];
   for (const capability of payload.capabilities || []) {
     lines.push(`/${capability.capability} - ${capability.purpose}`);
     if (capability.credits) lines.push(`  credits: ${capability.credits}`);
@@ -137,6 +225,15 @@ function printCapabilityHelp(payload) {
     "",
     "output:",
     JSON.stringify(payload.output_contract, null, 2),
+    payload.notes_for_agents?.length ? "" : null,
+    payload.notes_for_agents?.length ? "notes:" : null,
+    ...(payload.notes_for_agents || []).map((note) => `- ${note}`),
+    "",
+    "common recovery:",
+    "- auth missing: caphub auth login --api-key csk_live_...",
+    "- auth invalid: generate a new key in https://caphub.io/dashboard/",
+    "- low credits: top up in https://caphub.io/dashboard/",
+    `- bad payload: caphub help ${payload.capability}`,
   ].filter(Boolean);
   process.stdout.write(`${lines.join("\n")}\n`);
 }
@@ -170,7 +267,7 @@ async function commandAuth(args) {
   if (sub === "login") {
     const apiKey = parseFlag(args, "--api-key") || getApiKey();
     const apiUrl = parseFlag(args, "--api-url") || getApiUrl();
-    if (!apiKey) fail("Error: auth login requires --api-key or CAPHUB_API_KEY.");
+    if (!apiKey) fail("Error: auth login requires --api-key or CAPHUB_API_KEY.\n\nnext:\n  - caphub auth login --api-key csk_live_...");
     writeConfig({
       ...config,
       api_key: apiKey,
@@ -182,7 +279,7 @@ async function commandAuth(args) {
 
   if (sub === "whoami") {
     const apiKey = getApiKey();
-    if (!apiKey) fail(`Error: no api key configured. Use 'caphub auth login --api-key ...' or set ${CONFIG_PATH}.`);
+    if (!apiKey) fail(`Error: no api key configured.\n\nnext:\n  - caphub auth login --api-key csk_live_...\n  - or set api_key in ${CONFIG_PATH}`);
     const payload = await fetchJson(`${getApiUrl()}/v1/me`, { apiKey });
     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
     return;
@@ -201,7 +298,11 @@ async function commandAuth(args) {
 
 async function commandCapability(capability, args) {
   const apiKey = getApiKey();
-  if (!apiKey) fail(`Error: CAPHUB_API_KEY is required, or set api_key in ${CONFIG_PATH}.`);
+  if (!apiKey) {
+    fail(
+      `Error: no api key configured for capability "${capability}".\n\nnext:\n  - caphub auth login --api-key csk_live_...\n  - then retry: caphub ${capability} '<json>'\n  - contract: caphub help ${capability}`
+    );
+  }
 
   if (args[0] === "--help" || args[0] === "help") {
     await commandHelp([capability]);
@@ -211,14 +312,14 @@ async function commandCapability(capability, args) {
   const arg = args[0];
   const rawInput = arg ?? (process.stdin.isTTY ? "" : await readStdin());
   if (!rawInput.trim()) {
-    fail(`Error: input JSON is required. Run 'caphub help ${capability}' for the contract.`);
+    fail(`Error: input JSON is required.\n\nnext:\n  - caphub help ${capability}\n  - then run: caphub ${capability} '<json>'`);
   }
 
   let body;
   try {
     body = JSON.parse(rawInput);
   } catch {
-    fail("Error: input must be valid JSON.");
+    fail(`Error: input must be valid JSON.\n\nnext:\n  - caphub help ${capability}\n  - pass exactly one JSON object`);
   }
 
   if (!("function" in body)) body.function = capability;
@@ -258,4 +359,10 @@ async function main() {
   await commandCapability(cmd, args.slice(1));
 }
 
-await main().catch((error) => fail(`Error: ${error.message}`));
+await main().catch((error) => {
+  const cmd = process.argv[2];
+  const capability = cmd && !["help", "--help", "-h", "capabilities", "auth", "--version", "-v", "version"].includes(cmd)
+    ? cmd
+    : undefined;
+  failWithHints(error.message || "unknown error", error, { capability });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caphub/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Root CLI for Caphub agent capabilities",
   "type": "module",
   "bin": {