@superglue/cli 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,79 @@
+# superglue CLI
+
+[![npm](https://img.shields.io/npm/v/@superglue/cli?style=flat-square&logo=npm)](https://www.npmjs.com/package/@superglue/cli)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+Build, test, and manage superglue API integration tools from the command line.
+
+## What is superglue?
+
+- AI-powered tool builder that works with any API, database or file storage server
+- Abstracts away authentication, documentation handling and data mapping between systems
+- Self-heals tools: when steps fail due to upstream API changes, superglue can auto-repair failures
+
+## Installation
+
+### As npm package
+
+```bash
+npm install -g @superglue/cli
+sg --help
+```
+
+### As Claude Code Plugin
+
+```
+/plugin install github:superglue-ai/cli
+```
+
+## Quick Start
+
+```bash
+sg init                        # guided setup
+sg system list                 # verify connection
+sg tool build --config '...'   # build a tool
+sg tool run --draft <id>       # test it
+sg tool save --draft <id>      # save it
+```
+
+## Commands
+
+### Tools
+
+- `sg tool build` — Build a tool from config
+- `sg tool run` — Run a draft or saved tool
+- `sg tool edit` — Edit via JSON Patch
+- `sg tool save` — Save a draft
+- `sg tool list` — List saved tools
+- `sg tool find` — Search tools
+
+### Systems
+
+- `sg system create` — Create a system
+- `sg system edit` — Edit system config
+- `sg system list` — List systems
+- `sg system find` — Search systems
+- `sg system call` — Make authenticated API calls
+- `sg system oauth` — Authenticate via OAuth
+- `sg system docs` — Search system documentation
+
+### Runs
+
+- `sg run list` — List execution runs
+- `sg run get` — Get run details
+
+## Documentation
+
+- [Full CLI Reference](./skills/superglue/SKILL.md) — Complete command documentation
+- [superglue Docs](https://docs.superglue.cloud) — Platform documentation
+- [API Reference](https://docs.superglue.cloud/api-reference/) — REST API docs
+
+## Related
+
+- [superglue Web App](https://app.superglue.cloud) — Visual tool builder
+- [@superglue/client](https://www.npmjs.com/package/@superglue/client) — TypeScript SDK
+- [superglue-client](https://pypi.org/project/superglue-client/) — Python SDK
+
+## License
+
+MIT

package/dist/cli.js

@@ -21645,7 +21645,9 @@ function resolveConfig(flags) {
 function writeConfig(config, preferLocal) {
   const dir = getConfigDir(preferLocal);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(path.join(dir, "config.json"), JSON.stringify(config, null, 2) + "\n");
+  fs.writeFileSync(path.join(dir, "config.json"), JSON.stringify(config, null, 2) + "\n", {
+    mode: 384
+  });
 }
 function ensureConfigDirs(config, preferLocal) {
   const draftsDir = path.join(getConfigDir(preferLocal), "drafts");
@@ -21677,6 +21679,125 @@ var import_shared2 = __toESM(require_dist2());
 
 // src/output.ts
 var readline = __toESM(require("readline"));
+
+// src/version.ts
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+
+// package.json
+var package_default = {
+  name: "@superglue/cli",
+  version: "1.1.0",
+  bin: {
+    sg: "./dist/cli.js"
+  },
+  files: [
+    "dist/",
+    "skills/",
+    "skills.md"
+  ],
+  dependencies: {
+    commander: "^13.0.0",
+    "fast-json-patch": "^3.1.1"
+  },
+  devDependencies: {
+    "@superglue/shared": "file:../shared",
+    "@types/node": "^20.0.0",
+    tsup: "^8.0.0",
+    typescript: "^5.0.0"
+  },
+  scripts: {
+    build: "tsup && (cp -r skills dist/ 2>/dev/null || true)",
+    dev: "tsup --watch",
+    "type-check": "tsc --noEmit",
+    prepublishOnly: "npm run build"
+  },
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// src/version.ts
+var execAsync = (0, import_node_util.promisify)(import_node_child_process.exec);
+var CLI_VERSION = package_default.version;
+function parseVersionPart(part) {
+  const match = part.match(/^(\d+)(?:-(.+))?$/);
+  if (match) {
+    return { numeric: parseInt(match[1], 10), prerelease: match[2] || null };
+  }
+  return { numeric: 0, prerelease: part };
+}
+function compareVersions(a, b) {
+  const partsA = a.split(".");
+  const partsB = b.split(".");
+  const maxLen = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < maxLen; i++) {
+    const parsedA = parseVersionPart(partsA[i] || "0");
+    const parsedB = parseVersionPart(partsB[i] || "0");
+    if (parsedA.numeric < parsedB.numeric) return -1;
+    if (parsedA.numeric > parsedB.numeric) return 1;
+    if (parsedA.prerelease === null && parsedB.prerelease !== null) return 1;
+    if (parsedA.prerelease !== null && parsedB.prerelease === null) return -1;
+    if (parsedA.prerelease !== null && parsedB.prerelease !== null) {
+      if (parsedA.prerelease < parsedB.prerelease) return -1;
+      if (parsedA.prerelease > parsedB.prerelease) return 1;
+    }
+  }
+  return 0;
+}
+async function checkVersionCompatibility(endpoint) {
+  try {
+    const healthUrl = `${endpoint.replace(/\/$/, "")}/v1/health`;
+    const response = await fetch(healthUrl, { signal: AbortSignal.timeout(3e3) });
+    if (!response.ok) return;
+    const health = await response.json();
+    if (!health.minCliVersion) return;
+    if (compareVersions(CLI_VERSION, health.minCliVersion) < 0) {
+      console.error("");
+      console.error(`${c.yellow}${c.bold}\u26A0 CLI version ${CLI_VERSION} is outdated.${c.reset}`);
+      console.error(
+        `${c.yellow}  Server requires at least v${health.minCliVersion}. Run: ${c.bold}sg update${c.reset}`
+      );
+      console.error("");
+    }
+  } catch {
+  }
+}
+async function getLatestNpmVersion() {
+  try {
+    const response = await fetch("https://registry.npmjs.org/@superglue/cli/latest", {
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return data.version || null;
+  } catch {
+    return null;
+  }
+}
+async function updateCli() {
+  const latestVersion = await getLatestNpmVersion();
+  if (!latestVersion) {
+    return { success: false, message: "Could not fetch latest version from npm" };
+  }
+  if (compareVersions(CLI_VERSION, latestVersion) >= 0) {
+    return { success: true, message: `Already on latest version (${CLI_VERSION})` };
+  }
+  try {
+    await execAsync("npm install -g @superglue/cli@latest");
+    return {
+      success: true,
+      message: `Updated from ${CLI_VERSION} to ${latestVersion}`
+    };
+  } catch (err) {
+    return {
+      success: false,
+      message: `Update failed: ${err.message}. Try manually: npm install -g @superglue/cli@latest`
+    };
+  }
+}
+
+// src/output.ts
 var isJsonMode = () => process.argv.includes("--json") || !process.stdout.isTTY;
 var c = {
   reset: "\x1B[0m",
@@ -21729,7 +21850,7 @@ function banner() {
     const after = line.slice(last + 1);
     console.log(`  ${before}${inv}${inside}${rst}${after}`);
   });
-  console.log(`  ${d}  CLI v0.1.0${rst}`);
+  console.log(`  ${d}  CLI v${CLI_VERSION}${rst}`);
   console.log("");
 }
 function spinner(message) {
@@ -21782,6 +21903,11 @@ function error(message, details) {
     if (details) prettyPrint(details, 4);
   }
 }
+function warn(message) {
+  if (!isJsonMode()) {
+    console.log(`  ${c.yellow}\u26A0${c.reset} ${message}`);
+  }
+}
 function info(message) {
   if (!isJsonMode()) {
     console.log(`  ${c.dim}${message}${c.reset}`);
@@ -21974,22 +22100,25 @@ async function promptHidden(message) {
     let input = "";
     const onData = (ch) => {
       const s = ch.toString();
-      if (s === "\n" || s === "\r") {
-        if (process.stdin.isTTY) process.stdin.setRawMode(false);
-        process.stdin.removeListener("data", onData);
-        process.stdout.write("\n");
-        rl.close();
-        resolve4(input);
-      } else if (s === "") {
-        process.exit(0);
-      } else if (s === "\x7F" || s === "\b") {
-        if (input.length > 0) {
-          input = input.slice(0, -1);
-          process.stdout.write("\b \b");
+      for (const char of s) {
+        if (char === "\n" || char === "\r") {
+          if (process.stdin.isTTY) process.stdin.setRawMode(false);
+          process.stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          rl.close();
+          resolve4(input);
+          return;
+        } else if (char === "") {
+          process.exit(130);
+        } else if (char === "\x7F" || char === "\b") {
+          if (input.length > 0) {
+            input = input.slice(0, -1);
+            process.stdout.write("\b \b");
+          }
+        } else {
+          input += char;
+          process.stdout.write(`${c.dim}\u2022${c.reset}`);
         }
-      } else {
-        input += s;
-        process.stdout.write(`${c.dim}\u2022${c.reset}`);
       }
     };
     process.stdin.on("data", onData);
@@ -22151,9 +22280,11 @@ var path3 = __toESM(require("path"));
 function getDraftsDir() {
   return path3.join(getConfigDir(), "drafts");
 }
+function encodeDraftId(draftId) {
+  return Buffer.from(draftId, "utf-8").toString("base64url");
+}
 function getDraftPath(draftId) {
-  const safeName = draftId.replace(/[^a-zA-Z0-9_-]/g, "_");
-  return path3.join(getDraftsDir(), `${safeName}.json`);
+  return path3.join(getDraftsDir(), `${encodeDraftId(draftId)}.json`);
 }
 function writeDraft(draft) {
   const dir = getDraftsDir();
@@ -22471,11 +22602,11 @@ function registerEditCommand(parent, getContext2) {
       draftId: workingDraftId,
       config: {
         ...patchedConfig,
-        instruction: originalConfig.instruction || patchedConfig.instruction,
+        instruction: patchedConfig.instruction ?? originalConfig.instruction,
         updatedAt: (/* @__PURE__ */ new Date()).toISOString()
       },
       systemIds: patchedConfig.systemIds || [],
-      instruction: patchedConfig.instruction || "",
+      instruction: patchedConfig.instruction ?? "",
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     writeDraft(draft);
@@ -22541,8 +22672,8 @@ function registerSaveCommand(parent, getContext2) {
       process.exit(1);
     }
     const toolId = opts.id || draft.config.id;
+    const spin = spinner(`Saving tool ${c.bold}${toolId}${c.reset}...`);
     try {
-      const spin = spinner(`Saving tool ${c.bold}${toolId}${c.reset}...`);
       const saved = await client.upsertWorkflow(toolId, {
         ...draft.config,
         id: toolId,
@@ -22564,6 +22695,7 @@ function registerSaveCommand(parent, getContext2) {
         console.log("");
       }
     } catch (err) {
+      spin.stop();
       error(err.message);
       process.exit(1);
     }
@@ -22602,7 +22734,7 @@ function registerFindCommand(parent, getContext2) {
         output({ success: true, tool });
         return;
       }
-      const searchQuery = query || "*";
+      const searchQuery = (query || "").trim() || "*";
       if (searchQuery === "*") {
         const { items } = await client.listWorkflows(100);
         const tools = items.filter((t) => !t.archived).map((t) => ({
@@ -22703,10 +22835,10 @@ function registerCreateCommand(parent, getContext2) {
         if (template.oauth.client_id) oauthCreds.client_id = template.oauth.client_id;
       }
       systemInput = {
+        ...systemInput,
         name: systemInput.name || template.name,
-        url: template.apiUrl,
+        url: systemInput.url || template.apiUrl,
         templateName: opts.template,
-        ...systemInput,
         credentials: { ...oauthCreds, ...systemInput.credentials }
       };
     }
@@ -22805,7 +22937,9 @@ function registerEditCommand2(parent, getContext2) {
             url: opts.scrapeUrl,
             keywords
           });
-        } catch {
+        } catch (scrapeErr) {
+          const errMsg = scrapeErr instanceof Error ? scrapeErr.message : String(scrapeErr || "Unknown error");
+          warn(`Documentation scrape failed for ${opts.scrapeUrl}: ${errMsg}`);
         }
       }
       spin.stop();
@@ -22921,14 +23055,29 @@ function registerCallCommand(parent, getContext2) {
     if (body && Object.keys(filePayloads).length > 0) {
       try {
         let parsed = JSON.parse(body);
-        for (const [k, v] of Object.entries(parsed)) {
-          if (typeof v === "string" && v.startsWith("file::")) {
-            const key = v.slice(6);
-            if (key in filePayloads) parsed[k] = filePayloads[key];
+        const resolveFileRefs = (obj) => {
+          if (typeof obj === "string" && obj.startsWith("file::")) {
+            const key = obj.slice(6);
+            if (key in filePayloads) return filePayloads[key];
+            error(
+              `Unresolved file reference: file::${key}. Available: ${Object.keys(filePayloads).join(", ") || "(none)"}`
+            );
+            process.exit(1);
           }
-        }
+          if (Array.isArray(obj)) return obj.map(resolveFileRefs);
+          if (obj && typeof obj === "object") {
+            const result = {};
+            for (const [k, v] of Object.entries(obj)) {
+              result[k] = resolveFileRefs(v);
+            }
+            return result;
+          }
+          return obj;
+        };
+        parsed = resolveFileRefs(parsed);
         body = JSON.stringify(parsed);
-      } catch {
+      } catch (err) {
+        if (err.message?.startsWith("Unresolved file reference")) throw err;
       }
     }
     const autoExec = process.argv.includes("--yes") || process.argv.includes("-y") || shouldAutoExecute(config.policies.callSystem, method, opts.url);
@@ -23041,13 +23190,13 @@ function registerDocsCommand(parent, getContext2) {
 }
 
 // src/commands/system/oauth.ts
-var import_node_child_process = require("child_process");
+var import_node_child_process2 = require("child_process");
 var import_shared8 = __toESM(require_dist2());
 function openBrowser(url) {
   const platform = process.platform;
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
   const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-  (0, import_node_child_process.spawn)(cmd, args, { detached: true, stdio: "ignore" }).unref();
+  (0, import_node_child_process2.spawn)(cmd, args, { detached: true, stdio: "ignore" }).unref();
 }
 async function pollForTokens(client, systemId, originalToken, timeoutMs = 3e5, intervalMs = 2e3) {
   const start = Date.now();
@@ -23207,12 +23356,12 @@ function registerSystemCommands(program2, getContext2) {
 
 // src/commands/run/list.ts
 function registerListCommand(parent, getContext2) {
-  parent.command("list").description("List recent runs").option("--tool <id>", "Filter by tool ID").option("--status <status>", "Filter by status (running, success, failed, aborted)").option("--source <sources>", "Comma-separated request sources").option("--user <userId>", "Filter by user ID").option("--system-id <id>", "Filter by system ID").option("--limit <n>", "Max results", "10").option("--offset <n>", "Skip first N results", "0").option("--search <text>", "Full-text search").action(async (opts) => {
+  parent.command("list").description("List recent runs").option("--tool <id>", "Filter by tool ID").option("--status <status>", "Filter by status (running, success, failed, aborted)").option("--source <sources>", "Comma-separated request sources").option("--user <userId>", "Filter by user ID").option("--system-id <id>", "Filter by system ID").option("--limit <n>", "Max results", "10").option("--offset <n>", "Skip first N results", "0").action(async (opts) => {
     const { client } = getContext2();
     try {
       const limit = Math.min(parseInt(opts.limit, 10) || 10, 50);
       const offset = parseInt(opts.offset, 10) || 0;
-      const page = Math.floor(offset / limit) + 1;
+      const page = Math.ceil((offset + 1) / limit);
       const requestSources = opts.source?.split(",").filter(Boolean);
       const result = await client.listRuns({
         toolId: opts.tool,
@@ -23295,109 +23444,6 @@ function registerRunCommands(program2, getContext2) {
   registerGetCommand(run, getContext2);
 }
 
-// src/version.ts
-var import_node_child_process2 = require("child_process");
-var import_node_util = require("util");
-
-// package.json
-var package_default = {
-  name: "@superglue/cli",
-  version: "1.0.0",
-  bin: {
-    sg: "./dist/cli.js"
-  },
-  files: [
-    "dist/",
-    "skills/",
-    "skills.md"
-  ],
-  dependencies: {
-    commander: "^13.0.0",
-    "fast-json-patch": "^3.1.1"
-  },
-  devDependencies: {
-    "@superglue/shared": "file:../shared",
-    "@types/node": "^20.0.0",
-    tsup: "^8.0.0",
-    typescript: "^5.0.0"
-  },
-  scripts: {
-    build: "tsup && cp -r skills dist/ 2>/dev/null || true",
-    dev: "tsup --watch",
-    "type-check": "tsc --noEmit",
-    prepublishOnly: "npm run build"
-  },
-  publishConfig: {
-    access: "public"
-  }
-};
-
-// src/version.ts
-var execAsync = (0, import_node_util.promisify)(import_node_child_process2.exec);
-var CLI_VERSION = package_default.version;
-function compareVersions(a, b) {
-  const partsA = a.split(".").map(Number);
-  const partsB = b.split(".").map(Number);
-  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
-    const numA = partsA[i] || 0;
-    const numB = partsB[i] || 0;
-    if (numA < numB) return -1;
-    if (numA > numB) return 1;
-  }
-  return 0;
-}
-async function checkVersionCompatibility(endpoint) {
-  try {
-    const healthUrl = `${endpoint.replace(/\/$/, "")}/v1/health`;
-    const response = await fetch(healthUrl, { signal: AbortSignal.timeout(3e3) });
-    if (!response.ok) return;
-    const health = await response.json();
-    if (!health.minCliVersion) return;
-    if (compareVersions(CLI_VERSION, health.minCliVersion) < 0) {
-      console.error("");
-      console.error(`${c.yellow}${c.bold}\u26A0 CLI version ${CLI_VERSION} is outdated.${c.reset}`);
-      console.error(
-        `${c.yellow}  Server requires at least v${health.minCliVersion}. Run: ${c.bold}sg update${c.reset}`
-      );
-      console.error("");
-    }
-  } catch {
-  }
-}
-async function getLatestNpmVersion() {
-  try {
-    const response = await fetch("https://registry.npmjs.org/@superglue/cli/latest", {
-      signal: AbortSignal.timeout(5e3)
-    });
-    if (!response.ok) return null;
-    const data = await response.json();
-    return data.version || null;
-  } catch {
-    return null;
-  }
-}
-async function updateCli() {
-  const latestVersion = await getLatestNpmVersion();
-  if (!latestVersion) {
-    return { success: false, message: "Could not fetch latest version from npm" };
-  }
-  if (compareVersions(CLI_VERSION, latestVersion) >= 0) {
-    return { success: true, message: `Already on latest version (${CLI_VERSION})` };
-  }
-  try {
-    await execAsync("npm install -g @superglue/cli@latest");
-    return {
-      success: true,
-      message: `Updated from ${CLI_VERSION} to ${latestVersion}`
-    };
-  } catch (err) {
-    return {
-      success: false,
-      message: `Update failed: ${err.message}. Try manually: npm install -g @superglue/cli@latest`
-    };
-  }
-}
-
 // src/commands/update.ts
 function registerUpdateCommand(program2) {
   program2.command("update").description("Update the superglue CLI to the latest version").option("--check", "Only check for updates, don't install").action(async (opts) => {
@@ -23506,12 +23552,22 @@ function findSubcommand(argv) {
   }
   return void 0;
 }
+function extractFlagValue(argv, flag) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith(`${flag}=`)) {
+      return arg.slice(flag.length + 1);
+    }
+    if (arg === flag && i + 1 < argv.length) {
+      return argv[i + 1];
+    }
+  }
+  return void 0;
+}
 var subcommand = findSubcommand(process.argv);
 if (subcommand && commandsRequiringServer.includes(subcommand)) {
-  const apiKeyIdx = process.argv.indexOf("--api-key");
-  const endpointIdx = process.argv.indexOf("--endpoint");
-  const cliApiKey = apiKeyIdx !== -1 ? process.argv[apiKeyIdx + 1] : void 0;
-  const cliEndpoint = endpointIdx !== -1 ? process.argv[endpointIdx + 1] : void 0;
+  const cliApiKey = extractFlagValue(process.argv, "--api-key");
+  const cliEndpoint = extractFlagValue(process.argv, "--endpoint");
   const config = resolveConfig({ apiKey: cliApiKey, endpoint: cliEndpoint });
   if (config.apiKey) {
     checkVersionCompatibility(config.endpoint).then(() => program.parse());

package/dist/skills/superglue/SKILL.md

@@ -227,14 +227,14 @@ sg system oauth --system-id my_api --grant-type client_credentials --scopes "rea
     {
       "id": "unique-step-id",
       "config": {
-        "systemId": "system-id",
-        "url": "https://api.example.com/endpoint?param=<<payload.field>>",
+        "systemId": "example_system",
+        "url": "https://api.example.com/endpoint?param=<<payload_field>>",
         "method": "GET",
         "headers": {
-          "Authorization": "Bearer <<system-id_access_token>>"
+          "Authorization": "Bearer <<example_system_access_token>>"
         },
         "queryParams": { "limit": "10" },
-        "body": "{ \"key\": \"<<payload.field>>\" }"
+        "body": "{ \"key\": \"<<payload_field>>\" }"
       },
       "dataSelector": "(sourceData) => sourceData.previousStep.data.items",
       "transformCode": "(items) => items.map(i => ({ id: i.id, name: i.name }))",

package/dist/skills/superglue/references/file-servers.md

@@ -75,7 +75,7 @@ Downloaded files are all parsed automatically:
 
 - String → written as-is
 - Buffer → written directly
-- Object/Array → JSON.stringified with 2-space indent
+- Object/Array → `JSON.stringify` with 2-space indent
 
 ## Connection Details
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superglue/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "bin": {
     "sg": "./dist/cli.js"
   },
@@ -20,7 +20,7 @@
     "typescript": "^5.0.0"
   },
   "scripts": {
-    "build": "tsup && cp -r skills dist/ 2>/dev/null || true",
+    "build": "tsup && (cp -r skills dist/ 2>/dev/null || true)",
     "dev": "tsup --watch",
     "type-check": "tsc --noEmit",
     "prepublishOnly": "npm run build"

package/skills/superglue/SKILL.md

@@ -227,14 +227,14 @@ sg system oauth --system-id my_api --grant-type client_credentials --scopes "rea
     {
       "id": "unique-step-id",
       "config": {
-        "systemId": "system-id",
-        "url": "https://api.example.com/endpoint?param=<<payload.field>>",
+        "systemId": "example_system",
+        "url": "https://api.example.com/endpoint?param=<<payload_field>>",
         "method": "GET",
         "headers": {
-          "Authorization": "Bearer <<system-id_access_token>>"
+          "Authorization": "Bearer <<example_system_access_token>>"
         },
         "queryParams": { "limit": "10" },
-        "body": "{ \"key\": \"<<payload.field>>\" }"
+        "body": "{ \"key\": \"<<payload_field>>\" }"
       },
       "dataSelector": "(sourceData) => sourceData.previousStep.data.items",
       "transformCode": "(items) => items.map(i => ({ id: i.id, name: i.name }))",

package/skills/superglue/references/file-servers.md

@@ -75,7 +75,7 @@ Downloaded files are all parsed automatically:
 
 - String → written as-is
 - Buffer → written directly
-- Object/Array → JSON.stringified with 2-space indent
+- Object/Array → `JSON.stringify` with 2-space indent
 
 ## Connection Details