@superglue/cli 1.1.4 → 1.1.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superglue",
   "description": "Build, test, and manage superglue tools via the sg CLI. Use when working with superglue tools, systems, APIs, SDKs, or the sg command.",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "author": {
     "name": "superglue",
     "email": "hello@superglue.cloud"

package/README.md

@@ -87,7 +87,7 @@ sg tool save --draft <id>      # save it
 
 ## Documentation
 
-- [Agent-Driven Development](https://docs.superglue.cloud/getting-started/llm-driven-development) — Skill installation and agent setup
+- [CLI + Skills](https://docs.superglue.cloud/getting-started/cli-skills) — Skill installation and agent setup
 - [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

package/dist/cli.js

@@ -19947,6 +19947,7 @@ var require_utils = __commonJS({
     exports2.validateExternalUrl = validateExternalUrl;
     exports2.flattenAndNamespaceCredentials = flattenAndNamespaceCredentials;
     exports2.flattenAndNamespaceSystemUrls = flattenAndNamespaceSystemUrls;
+    exports2.slugify = slugify2;
     exports2.generateUniqueId = generateUniqueId;
     exports2.waitForSystemProcessing = waitForSystemProcessing;
     exports2.inferJsonSchema = inferJsonSchema;
@@ -20155,6 +20156,10 @@ var require_utils = __commonJS({
         return acc;
       }, {});
     }
+    function slugify2(value) {
+      const slug = value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+      return slug || "system";
+    }
     async function generateUniqueId({ baseId, exists }) {
       if (!await exists(baseId)) {
         return baseId;
@@ -21279,7 +21284,8 @@ var require_superglue_client = __commonJS({
        * Used for SDK/playground testing
        */
       async runToolConfig(params) {
-        const response = await this.restRequest("POST", "/v1/tools/run", {
+        const path6 = params.createRun ? "/v1/tools/run?createRun=true" : "/v1/tools/run";
+        const response = await this.restRequest("POST", path6, {
           tool: params.tool,
           payload: params.payload,
           credentials: params.credentials,
@@ -21779,7 +21785,7 @@ var import_node_util = require("util");
 // package.json
 var package_default = {
   name: "@superglue/cli",
-  version: "1.1.4",
+  version: "1.1.5",
   bin: {
     sg: "./dist/cli.js"
   },
@@ -21868,6 +21874,28 @@ async function getLatestNpmVersion() {
     return null;
   }
 }
+var updateCheckPromise = null;
+function startBackgroundUpdateCheck() {
+  updateCheckPromise = getLatestNpmVersion();
+}
+async function printUpdateNotification() {
+  if (!updateCheckPromise) return;
+  try {
+    const timeout = new Promise((resolve4) => {
+      const timer = setTimeout(() => resolve4(null), 2e3);
+      timer.unref();
+    });
+    const latest = await Promise.race([updateCheckPromise, timeout]);
+    if (latest && compareVersions(CLI_VERSION, latest) < 0) {
+      console.error("");
+      console.error(`${c.cyan}${c.bold}  Update available: ${CLI_VERSION} \u2192 ${latest}${c.reset}`);
+      console.error(`${c.cyan}  Run ${c.bold}sg update${c.reset}${c.cyan} to upgrade${c.reset}`);
+      console.error("");
+    }
+  } catch {
+  }
+  updateCheckPromise = null;
+}
 async function updateCli() {
   const latestVersion = await getLatestNpmVersion();
   if (!latestVersion) {
@@ -22583,7 +22611,7 @@ function registerRunCommand(parent, getContext2) {
       return arr;
     },
     []
-  ).option("--include-step-results", "Include raw step results").option("--include-config", "Include full tool config").action(async (opts) => {
+  ).option("--include-step-results", "Include raw step results").option("--include-config", "Include full tool config").option("--no-create-run", "Skip creating a run record in the backend").action(async (opts) => {
     const { config, client } = getContext2();
     const selectors = [opts.tool, opts.draft, opts.config, opts.configFile].filter(Boolean);
     if (selectors.length === 0) {
@@ -22594,6 +22622,10 @@ function registerRunCommand(parent, getContext2) {
       error("Only one of --tool, --draft, --config, or --config-file can be used");
       process.exit(1);
     }
+    if (opts.tool && opts.createRun === false) {
+      error("--no-create-run is not supported with --tool (saved tools always create runs)");
+      process.exit(1);
+    }
     const filePayloads = await parseFileFlags(opts.file, client);
     let payload = opts.payloadFile ? JSON.parse(fs6.readFileSync(opts.payloadFile, "utf-8")) : opts.payload ? JSON.parse(opts.payload) : void 0;
     if (payload) {
@@ -22619,7 +22651,8 @@ function registerRunCommand(parent, getContext2) {
           tool: toolConfig,
           payload,
           options: { requestSource: import_shared4.RequestSource.CLI },
-          traceId
+          traceId,
+          createRun: opts.createRun !== false
         });
         logSub.unsubscribe();
         spin.stop();
@@ -22906,7 +22939,7 @@ async function collectSensitiveCredentials(fields) {
   return creds;
 }
 function registerCreateCommand(parent, getContext2) {
-  parent.command("create").description("Create a new system").option("--config <file>", "JSON config file").option("--id <id>", "System ID").option("--name <name>", "Human-readable name").option("--url <url>", "API URL").option("--template <id>", "Template ID").option("--instructions <text>", "Specific instructions").option("--credentials <json>", "Non-sensitive credentials JSON").option("--sensitive-credentials <fields>", "Comma-separated sensitive credential field names").option("--docs-url <url>", "Documentation URL to scrape").option("--openapi-url <url>", "OpenAPI spec URL").addOption(
+  parent.command("create").description("Create a new system").option("--config <file>", "JSON config file").option("--id <id>", "System ID (derived from name if omitted)").option("--name <name>", "Human-readable name (required)").option("--url <url>", "API URL").option("--template <id>", "Template ID").option("--instructions <text>", "Specific instructions").option("--credentials <json>", "Non-sensitive credentials JSON").option("--sensitive-credentials <fields>", "Comma-separated sensitive credential field names").option("--docs-url <url>", "Documentation URL to scrape").option("--openapi-url <url>", "OpenAPI spec URL").addOption(
     new import_commander.Option("--env <environment>", "Environment: dev or prod (default: prod)").choices([
       "dev",
       "prod"
@@ -22972,10 +23005,17 @@ function registerCreateCommand(parent, getContext2) {
       const sensitive = await collectSensitiveCredentials(fields);
       systemInput.credentials = { ...systemInput.credentials, ...sensitive };
     }
-    if (!systemInput.id) {
-      error("System ID is required (--id)");
+    if (typeof systemInput.name !== "string" || systemInput.name.trim() === "") {
+      error("System name is required (--name)");
       process.exit(1);
     }
+    if (!systemInput.id) {
+      systemInput.id = (0, import_shared6.slugify)(systemInput.name.trim());
+      if (!systemInput.id) {
+        error("System ID could not be derived from name; use --id with letters or numbers");
+        process.exit(1);
+      }
+    }
     try {
       const spin = spinner(`Creating system ${c.bold}${systemInput.id}${c.reset}...`);
       const result = await client.createSystem(systemInput);
@@ -23599,6 +23639,7 @@ All Commands:
   sg tool build --id <id> --instruction <text>   Build a tool from flags (requires --steps)
   sg tool run --tool <id> [--payload <json>]     Run a saved tool
   sg tool run --draft <id> [--payload <json>]    Run a draft tool
+  sg tool run --config <json> [--no-create-run]   Run inline config (logs run by default)
   sg tool edit --tool <id> --patches <json>      Edit a tool via JSON Patch
   sg tool edit --draft <id> --patches <json>     Edit a draft via JSON Patch
   sg tool save --draft <id>                     Save a draft to the server
@@ -23607,7 +23648,7 @@ All Commands:
   sg tool find --id <id>                         Get full config of a tool
 
   sg system create --config <file>               Create a system from JSON config
-  sg system create --id <id> --url <url>         Create a system from flags
+  sg system create --name <name> --url <url>     Create a system from flags
   sg system edit --id <id>                       Edit a system's configuration
   sg system list                                 List all systems
   sg system find [query]                         Search systems by keyword
@@ -23671,15 +23712,20 @@ function extractFlagValue(argv, flag) {
   return void 0;
 }
 var subcommand = findSubcommand(process.argv);
+startBackgroundUpdateCheck();
+var runAndNotify = async (parsePromise) => {
+  await parsePromise;
+  await printUpdateNotification();
+};
 if (subcommand && commandsRequiringServer.includes(subcommand)) {
   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());
+    runAndNotify(checkVersionCompatibility(config.endpoint).then(() => program.parseAsync()));
   } else {
-    program.parse();
+    runAndNotify(program.parseAsync());
   }
 } else {
-  program.parse();
+  runAndNotify(program.parseAsync());
 }

package/dist/dist/cli.js

@@ -19947,6 +19947,7 @@ var require_utils = __commonJS({
     exports2.validateExternalUrl = validateExternalUrl;
     exports2.flattenAndNamespaceCredentials = flattenAndNamespaceCredentials;
     exports2.flattenAndNamespaceSystemUrls = flattenAndNamespaceSystemUrls;
+    exports2.slugify = slugify2;
     exports2.generateUniqueId = generateUniqueId;
     exports2.waitForSystemProcessing = waitForSystemProcessing;
     exports2.inferJsonSchema = inferJsonSchema;
@@ -20155,6 +20156,10 @@ var require_utils = __commonJS({
         return acc;
       }, {});
     }
+    function slugify2(value) {
+      const slug = value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+      return slug || "system";
+    }
     async function generateUniqueId({ baseId, exists }) {
       if (!await exists(baseId)) {
         return baseId;
@@ -21279,7 +21284,8 @@ var require_superglue_client = __commonJS({
        * Used for SDK/playground testing
        */
       async runToolConfig(params) {
-        const response = await this.restRequest("POST", "/v1/tools/run", {
+        const path6 = params.createRun ? "/v1/tools/run?createRun=true" : "/v1/tools/run";
+        const response = await this.restRequest("POST", path6, {
           tool: params.tool,
           payload: params.payload,
           credentials: params.credentials,
@@ -21779,7 +21785,7 @@ var import_node_util = require("util");
 // package.json
 var package_default = {
   name: "@superglue/cli",
-  version: "1.1.4",
+  version: "1.1.5",
   bin: {
     sg: "./dist/cli.js"
   },
@@ -21868,6 +21874,28 @@ async function getLatestNpmVersion() {
     return null;
   }
 }
+var updateCheckPromise = null;
+function startBackgroundUpdateCheck() {
+  updateCheckPromise = getLatestNpmVersion();
+}
+async function printUpdateNotification() {
+  if (!updateCheckPromise) return;
+  try {
+    const timeout = new Promise((resolve4) => {
+      const timer = setTimeout(() => resolve4(null), 2e3);
+      timer.unref();
+    });
+    const latest = await Promise.race([updateCheckPromise, timeout]);
+    if (latest && compareVersions(CLI_VERSION, latest) < 0) {
+      console.error("");
+      console.error(`${c.cyan}${c.bold}  Update available: ${CLI_VERSION} \u2192 ${latest}${c.reset}`);
+      console.error(`${c.cyan}  Run ${c.bold}sg update${c.reset}${c.cyan} to upgrade${c.reset}`);
+      console.error("");
+    }
+  } catch {
+  }
+  updateCheckPromise = null;
+}
 async function updateCli() {
   const latestVersion = await getLatestNpmVersion();
   if (!latestVersion) {
@@ -22583,7 +22611,7 @@ function registerRunCommand(parent, getContext2) {
       return arr;
     },
     []
-  ).option("--include-step-results", "Include raw step results").option("--include-config", "Include full tool config").action(async (opts) => {
+  ).option("--include-step-results", "Include raw step results").option("--include-config", "Include full tool config").option("--no-create-run", "Skip creating a run record in the backend").action(async (opts) => {
     const { config, client } = getContext2();
     const selectors = [opts.tool, opts.draft, opts.config, opts.configFile].filter(Boolean);
     if (selectors.length === 0) {
@@ -22594,6 +22622,10 @@ function registerRunCommand(parent, getContext2) {
       error("Only one of --tool, --draft, --config, or --config-file can be used");
       process.exit(1);
     }
+    if (opts.tool && opts.createRun === false) {
+      error("--no-create-run is not supported with --tool (saved tools always create runs)");
+      process.exit(1);
+    }
     const filePayloads = await parseFileFlags(opts.file, client);
     let payload = opts.payloadFile ? JSON.parse(fs6.readFileSync(opts.payloadFile, "utf-8")) : opts.payload ? JSON.parse(opts.payload) : void 0;
     if (payload) {
@@ -22619,7 +22651,8 @@ function registerRunCommand(parent, getContext2) {
           tool: toolConfig,
           payload,
           options: { requestSource: import_shared4.RequestSource.CLI },
-          traceId
+          traceId,
+          createRun: opts.createRun !== false
         });
         logSub.unsubscribe();
         spin.stop();
@@ -22906,7 +22939,7 @@ async function collectSensitiveCredentials(fields) {
   return creds;
 }
 function registerCreateCommand(parent, getContext2) {
-  parent.command("create").description("Create a new system").option("--config <file>", "JSON config file").option("--id <id>", "System ID").option("--name <name>", "Human-readable name").option("--url <url>", "API URL").option("--template <id>", "Template ID").option("--instructions <text>", "Specific instructions").option("--credentials <json>", "Non-sensitive credentials JSON").option("--sensitive-credentials <fields>", "Comma-separated sensitive credential field names").option("--docs-url <url>", "Documentation URL to scrape").option("--openapi-url <url>", "OpenAPI spec URL").addOption(
+  parent.command("create").description("Create a new system").option("--config <file>", "JSON config file").option("--id <id>", "System ID (derived from name if omitted)").option("--name <name>", "Human-readable name (required)").option("--url <url>", "API URL").option("--template <id>", "Template ID").option("--instructions <text>", "Specific instructions").option("--credentials <json>", "Non-sensitive credentials JSON").option("--sensitive-credentials <fields>", "Comma-separated sensitive credential field names").option("--docs-url <url>", "Documentation URL to scrape").option("--openapi-url <url>", "OpenAPI spec URL").addOption(
     new import_commander.Option("--env <environment>", "Environment: dev or prod (default: prod)").choices([
       "dev",
       "prod"
@@ -22972,10 +23005,17 @@ function registerCreateCommand(parent, getContext2) {
       const sensitive = await collectSensitiveCredentials(fields);
       systemInput.credentials = { ...systemInput.credentials, ...sensitive };
     }
-    if (!systemInput.id) {
-      error("System ID is required (--id)");
+    if (typeof systemInput.name !== "string" || systemInput.name.trim() === "") {
+      error("System name is required (--name)");
       process.exit(1);
     }
+    if (!systemInput.id) {
+      systemInput.id = (0, import_shared6.slugify)(systemInput.name.trim());
+      if (!systemInput.id) {
+        error("System ID could not be derived from name; use --id with letters or numbers");
+        process.exit(1);
+      }
+    }
     try {
       const spin = spinner(`Creating system ${c.bold}${systemInput.id}${c.reset}...`);
       const result = await client.createSystem(systemInput);
@@ -23599,6 +23639,7 @@ All Commands:
   sg tool build --id <id> --instruction <text>   Build a tool from flags (requires --steps)
   sg tool run --tool <id> [--payload <json>]     Run a saved tool
   sg tool run --draft <id> [--payload <json>]    Run a draft tool
+  sg tool run --config <json> [--no-create-run]   Run inline config (logs run by default)
   sg tool edit --tool <id> --patches <json>      Edit a tool via JSON Patch
   sg tool edit --draft <id> --patches <json>     Edit a draft via JSON Patch
   sg tool save --draft <id>                     Save a draft to the server
@@ -23607,7 +23648,7 @@ All Commands:
   sg tool find --id <id>                         Get full config of a tool
 
   sg system create --config <file>               Create a system from JSON config
-  sg system create --id <id> --url <url>         Create a system from flags
+  sg system create --name <name> --url <url>     Create a system from flags
   sg system edit --id <id>                       Edit a system's configuration
   sg system list                                 List all systems
   sg system find [query]                         Search systems by keyword
@@ -23671,15 +23712,20 @@ function extractFlagValue(argv, flag) {
   return void 0;
 }
 var subcommand = findSubcommand(process.argv);
+startBackgroundUpdateCheck();
+var runAndNotify = async (parsePromise) => {
+  await parsePromise;
+  await printUpdateNotification();
+};
 if (subcommand && commandsRequiringServer.includes(subcommand)) {
   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());
+    runAndNotify(checkVersionCompatibility(config.endpoint).then(() => program.parseAsync()));
   } else {
-    program.parse();
+    runAndNotify(program.parseAsync());
   }
 } else {
-  program.parse();
+  runAndNotify(program.parseAsync());
 }

package/dist/dist/skills/superglue/SKILL.md

@@ -12,6 +12,11 @@ description: "Build, test, deploy and integrate superglue tools via the sg CLI a
 1. **Check CLI exists**: Run `sg --version`. If it fails with `command not found`, install it: `npm install -g @superglue/cli`
 2. **Check superglue CLI config exists**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg init` (see below).
 
+**Calling systems and running tools**
+
+1. ALWAYS make sure you pull the relevant system context using `sg system find` before calling system endpoints and running inline JSON tools or building new tools.
+2. Use `sg system search-docs` to do a targeted keyword search of system docs if you're unsure about how a system works.
+
 **Authentication & Credentials:**
 
 - **Auth headers MUST be set explicitly** — credentials are NEVER auto-injected into requests or tool steps
@@ -173,34 +178,33 @@ sg tool find --id my-tool       # exact ID lookup (full config)
 
 **Required flags:**
 
-- `--id <id>` — System ID (lowercase, underscores only, no hyphens)
 - `--name <name>` — Human-readable display name
 - `--url <url>` — API base URL (auto-filled when using `--template`)
 
-**At least one of:**
+**Optional:**
 
+- `--id <id>` — System ID (lowercase, underscores only, no hyphens). Derived from `--name` if omitted.
 - `--template <id>` — Pre-configured template (auto-fills name and url if not provided)
-- `--url <url>` + `--name <name>` manually
 
 **Example with credentials (non-interactive — use this in AI agent / CI contexts):**
 
 ```bash
-sg system create --id my_api --name "My API" --url https://api.example.com \
+sg system create --name "My API" --url https://api.example.com \
   --credentials '{"api_key":"sk-xxx"}'
 ```
 
 **With template:**
 
 ```bash
-sg system create --id slack --name "Slack" --template slack
+sg system create --name "Slack" --template slack
 ```
 
 **Full flag reference:**
 
 | Flag                               | Description                                                                  |
 | ---------------------------------- | ---------------------------------------------------------------------------- |
-| `--id <id>`                        | System ID (lowercase, underscores only) — **REQUIRED**                       |
 | `--name <name>`                    | Human-readable name — **REQUIRED**                                           |
+| `--id <id>`                        | System ID (lowercase, underscores only) — derived from name if omitted       |
 | `--url <url>`                      | API base URL — **REQUIRED** (auto-filled by `--template`)                    |
 | `--template <id>`                  | Template ID (stripe, shopify, slack, etc.)                                   |
 | `--credentials <json>`             | Credentials JSON (use for ALL creds in non-interactive mode)                 |
@@ -530,7 +534,7 @@ Templates auto-populate endpoints and OAuth config. Use `sg system find` to disc
 
 ### OAuth Flow
 
-1. `sg system create --id gmail --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret`
+1. `sg system create --name "Gmail" --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret`
 2. `sg system oauth --system-id gmail --scopes "..."`
 3. User authenticates in browser → tokens saved automatically
 

package/dist/skills/superglue/SKILL.md

@@ -12,6 +12,11 @@ description: "Build, test, deploy and integrate superglue tools via the sg CLI a
 1. **Check CLI exists**: Run `sg --version`. If it fails with `command not found`, install it: `npm install -g @superglue/cli`
 2. **Check superglue CLI config exists**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg init` (see below).
 
+**Calling systems and running tools**
+
+1. ALWAYS make sure you pull the relevant system context using `sg system find` before calling system endpoints and running inline JSON tools or building new tools.
+2. Use `sg system search-docs` to do a targeted keyword search of system docs if you're unsure about how a system works.
+
 **Authentication & Credentials:**
 
 - **Auth headers MUST be set explicitly** — credentials are NEVER auto-injected into requests or tool steps
@@ -173,34 +178,33 @@ sg tool find --id my-tool       # exact ID lookup (full config)
 
 **Required flags:**
 
-- `--id <id>` — System ID (lowercase, underscores only, no hyphens)
 - `--name <name>` — Human-readable display name
 - `--url <url>` — API base URL (auto-filled when using `--template`)
 
-**At least one of:**
+**Optional:**
 
+- `--id <id>` — System ID (lowercase, underscores only, no hyphens). Derived from `--name` if omitted.
 - `--template <id>` — Pre-configured template (auto-fills name and url if not provided)
-- `--url <url>` + `--name <name>` manually
 
 **Example with credentials (non-interactive — use this in AI agent / CI contexts):**
 
 ```bash
-sg system create --id my_api --name "My API" --url https://api.example.com \
+sg system create --name "My API" --url https://api.example.com \
   --credentials '{"api_key":"sk-xxx"}'
 ```
 
 **With template:**
 
 ```bash
-sg system create --id slack --name "Slack" --template slack
+sg system create --name "Slack" --template slack
 ```
 
 **Full flag reference:**
 
 | Flag                               | Description                                                                  |
 | ---------------------------------- | ---------------------------------------------------------------------------- |
-| `--id <id>`                        | System ID (lowercase, underscores only) — **REQUIRED**                       |
 | `--name <name>`                    | Human-readable name — **REQUIRED**                                           |
+| `--id <id>`                        | System ID (lowercase, underscores only) — derived from name if omitted       |
 | `--url <url>`                      | API base URL — **REQUIRED** (auto-filled by `--template`)                    |
 | `--template <id>`                  | Template ID (stripe, shopify, slack, etc.)                                   |
 | `--credentials <json>`             | Credentials JSON (use for ALL creds in non-interactive mode)                 |
@@ -530,7 +534,7 @@ Templates auto-populate endpoints and OAuth config. Use `sg system find` to disc
 
 ### OAuth Flow
 
-1. `sg system create --id gmail --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret`
+1. `sg system create --name "Gmail" --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret`
 2. `sg system oauth --system-id gmail --scopes "..."`
 3. User authenticates in browser → tokens saved automatically
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superglue/cli",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "bin": {
     "sg": "./dist/cli.js"
   },

package/skills/superglue/SKILL.md

@@ -12,6 +12,11 @@ description: "Build, test, deploy and integrate superglue tools via the sg CLI a
 1. **Check CLI exists**: Run `sg --version`. If it fails with `command not found`, install it: `npm install -g @superglue/cli`
 2. **Check superglue CLI config exists**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg init` (see below).
 
+**Calling systems and running tools**
+
+1. ALWAYS make sure you pull the relevant system context using `sg system find` before calling system endpoints and running inline JSON tools or building new tools.
+2. Use `sg system search-docs` to do a targeted keyword search of system docs if you're unsure about how a system works.
+
 **Authentication & Credentials:**
 
 - **Auth headers MUST be set explicitly** — credentials are NEVER auto-injected into requests or tool steps
@@ -173,34 +178,33 @@ sg tool find --id my-tool       # exact ID lookup (full config)
 
 **Required flags:**
 
-- `--id <id>` — System ID (lowercase, underscores only, no hyphens)
 - `--name <name>` — Human-readable display name
 - `--url <url>` — API base URL (auto-filled when using `--template`)
 
-**At least one of:**
+**Optional:**
 
+- `--id <id>` — System ID (lowercase, underscores only, no hyphens). Derived from `--name` if omitted.
 - `--template <id>` — Pre-configured template (auto-fills name and url if not provided)
-- `--url <url>` + `--name <name>` manually
 
 **Example with credentials (non-interactive — use this in AI agent / CI contexts):**
 
 ```bash
-sg system create --id my_api --name "My API" --url https://api.example.com \
+sg system create --name "My API" --url https://api.example.com \
   --credentials '{"api_key":"sk-xxx"}'
 ```
 
 **With template:**
 
 ```bash
-sg system create --id slack --name "Slack" --template slack
+sg system create --name "Slack" --template slack
 ```
 
 **Full flag reference:**
 
 | Flag                               | Description                                                                  |
 | ---------------------------------- | ---------------------------------------------------------------------------- |
-| `--id <id>`                        | System ID (lowercase, underscores only) — **REQUIRED**                       |
 | `--name <name>`                    | Human-readable name — **REQUIRED**                                           |
+| `--id <id>`                        | System ID (lowercase, underscores only) — derived from name if omitted       |
 | `--url <url>`                      | API base URL — **REQUIRED** (auto-filled by `--template`)                    |
 | `--template <id>`                  | Template ID (stripe, shopify, slack, etc.)                                   |
 | `--credentials <json>`             | Credentials JSON (use for ALL creds in non-interactive mode)                 |
@@ -530,7 +534,7 @@ Templates auto-populate endpoints and OAuth config. Use `sg system find` to disc
 
 ### OAuth Flow
 
-1. `sg system create --id gmail --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret`
+1. `sg system create --name "Gmail" --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret`
 2. `sg system oauth --system-id gmail --scopes "..."`
 3. User authenticates in browser → tokens saved automatically