@superglue/cli 1.1.7 → 1.1.8

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.7",
+  "version": "0.1.0",
   "author": {
     "name": "superglue",
     "email": "hello@superglue.cloud"
@@ -9,12 +9,5 @@
   "homepage": "https://superglue.cloud",
   "repository": "https://github.com/superglue-ai/cli",
   "license": "MIT",
-  "keywords": [
-    "systems",
-    "integration",
-    "cli",
-    "tools",
-    "automation",
-    "api"
-  ]
+  "keywords": ["systems", "integration", "cli", "tools", "automation", "api"]
 }

package/dist/cli.js

@@ -2390,7 +2390,7 @@ var require_templates = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.systemOptions = exports2.systems = void 0;
-    exports2.findTemplateForSystem = findTemplateForSystem3;
+    exports2.findTemplateForSystem = findTemplateForSystem4;
     exports2.uniqueKeywords = uniqueKeywords;
     exports2.enrichWithTemplate = enrichWithTemplate;
     exports2.getOAuthConfig = getOAuthConfig;
@@ -2407,6 +2407,15 @@ var require_templates = __commonJS({
         preferredAuthType: "apikey",
         keywords: ["database", "sql", "postgres", "postgresql", "api key", "tables"]
       },
+      redis_direct: {
+        name: "redis_direct",
+        apiUrl: "redis://<<username>>:<<password>>@<<host>>:<<port>>/<<database>>",
+        regex: "^.*(rediss?://).*$",
+        icon: "redis",
+        docsUrl: "https://redis.io/docs/latest/commands/",
+        preferredAuthType: "apikey",
+        keywords: ["database", "cache", "redis", "key-value", "nosql", "api key"]
+      },
       stripe: {
         name: "stripe",
         apiUrl: "https://api.stripe.com",
@@ -4784,8 +4793,146 @@ HEADERS: { "Authorization": "Bearer <<token>>", "Content-Type": "application/jso
     Tenant-Specific Endpoints: Multi-tenant apps need tenant ID in OAuth URLs (/04a63d67.../oauth2/v2.0/authorize) instead of /common endpoint
     Credentials Needed: Application (client) ID + Client Secret (generated under Certificates & secrets - copy the Value immediately, not the Secret ID)
     API Permissions: Add Microsoft Graph permissions (e.g., Sites.ReadWrite.All) under API permissions, then grant admin consent if you have admin rights
-    Scopes Must Include: Always add offline_access scope to get refresh tokens for long-term access without re-authentication 
+    Scopes Must Include: Always add offline_access scope to get refresh tokens for long-term access without re-authentication
     `
+      },
+      dynamics365_sales: {
+        name: "dynamics365_sales",
+        apiUrl: "https://<<org>>.crm<<region_number>>.dynamics.com/api/data/v9.2",
+        regex: "^.*(crm\\d*\\.dynamics\\.com|dynamicscrm).*$",
+        icon: "lucide:square-percent",
+        docsUrl: "https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/query-data-web-api",
+        preferredAuthType: "oauth",
+        oauth: {
+          authUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+          tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+          scopes: "https://<<org>>.crm<<region_number>>.dynamics.com/user_impersonation offline_access",
+          grant_type: "authorization_code"
+        },
+        keywords: [
+          "accounts",
+          "contacts",
+          "leads",
+          "opportunities",
+          "quotes",
+          "salesorders",
+          "salesorderdetails",
+          "products",
+          "incidents",
+          "campaigns",
+          "invoices",
+          "competitors",
+          "teams",
+          "systemusers",
+          "businessunits",
+          "odata",
+          "dynamics",
+          "crm",
+          "dynamics 365 sales",
+          "dataverse",
+          "oauth"
+        ],
+        systemSpecificInstructions: `Dynamics 365 Sales \u2014 Dataverse Web API v9.2
+
+REQUIRED HEADERS (in addition to Authorization):
+- OData-MaxVersion: 4.0
+- OData-Version: 4.0
+- If-None-Match: null (recommended \u2014 prevents stale cached data, especially on $expand queries)
+
+QUERY BEHAVIOR:
+- $skip is NOT supported. Use @odata.nextLink for pagination (default page size 5000, control with Prefer: odata.maxpagesize=<n>).
+- PAGINATION IN SUPERGLUE: Use cursorBased pagination with cursorPath "@odata.nextLink":
+  pagination: { type: "cursorBased", pageSize: "5000", cursorPath: "@odata.nextLink" }
+  The cursor is a full URL \u2014 use <<cursor>> as the step URL (set the initial URL via a "cursor" input variable).
+- $apply is supported for aggregations.
+- Lookup fields (foreign keys) are named _<field>_value \u2014 e.g. _parentaccountid_value, _customerid_value.
+- To get formatted/display values (e.g. option set labels, currency formatting), add header: Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"
+- FetchXML: GET /api/data/v9.2/<entity>?fetchXml=<url_encoded_xml> for complex aggregations and outer joins that OData $expand cannot express.
+- Max URL length is 32KB. For long queries, wrap in a $batch POST request (raises limit to 64KB).
+- Max individual OData URL segment is 260 chars \u2014 use parameter aliases (@p1=value) to shorten segments.
+
+WRITE SPECIFICS:
+- PATCH doubles as an upsert when the target record doesn't exist (by ID or alternate key). Use If-Match: * to prevent accidental creates. Use If-None-Match: * to prevent accidental updates.
+- Setting lookups on write: use @odata.bind \u2014 e.g. "parentaccountid@odata.bind": "/accounts(<guid>)"
+- Disassociating a lookup: set the navigation property to null (without @odata.bind), e.g. "parentcustomerid_account": null
+
+RATE LIMITS (Service Protection):
+- 429 Too Many Requests returned when limits exceeded. Always implement Retry-After handling.
+- Per-user limits per 5-min window: 6,000 requests, 20 min combined execution time, 52+ concurrent requests.
+- These are per web server \u2014 actual capacity varies by environment.
+
+DISCOVERING CUSTOM ENTITIES:
+GET /api/data/v9.2/EntityDefinitions?$filter=IsCustomEntity eq true&$select=LogicalName,DisplayName
+`
+      },
+      dynamics365_business_central: {
+        name: "dynamics365_business_central",
+        apiUrl: "https://api.businesscentral.dynamics.com/v2.0/<<environment>>/api/v2.0",
+        regex: "^.*(businesscentral\\.dynamics\\.com|business[\\s\\-]?central).*$",
+        icon: "lucide:landmark",
+        docsUrl: "https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/",
+        preferredAuthType: "oauth",
+        oauth: {
+          authUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+          tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+          scopes: "https://api.businesscentral.dynamics.com/.default offline_access",
+          grant_type: "authorization_code"
+        },
+        keywords: [
+          "customers",
+          "vendors",
+          "items",
+          "salesOrders",
+          "salesInvoices",
+          "salesQuotes",
+          "purchaseOrders",
+          "purchaseInvoices",
+          "generalLedgerEntries",
+          "journals",
+          "accounts",
+          "employees",
+          "dimensions",
+          "warehouses",
+          "inventory",
+          "odata",
+          "dynamics",
+          "erp",
+          "business central",
+          "finance",
+          "oauth"
+        ],
+        systemSpecificInstructions: `Dynamics 365 Business Central \u2014 API v2.0
+
+COMPANY SCOPING: All entities are scoped under a company. List companies first: GET /api/v2.0/companies, then access entities at /companies(<id>)/<entity>.
+
+WRITE SPECIFICS:
+- Updates REQUIRE an If-Match header with the entity's @odata.etag value \u2014 omitting it will fail.
+- Do NOT insert child records belonging to the same parent in parallel \u2014 causes locks. Use $batch to serialize them.
+- Transactional $batch: add Isolation: snapshot header for all-or-nothing batch operations. Max 100 operations per $batch.
+
+PAGINATION: Uses @odata.nextLink (a full URL for the next page). In superglue, use offsetBased pagination with $top and $skip since BC supports $skip:
+  pagination: { type: "offsetBased", pageSize: "1000" }
+  queryParams: { "$top": "<<limit>>", "$skip": "<<offset>>" }
+
+QUERY LIMITS:
+- Max page size: 20,000 entities per response (returns 413 if exceeded).
+- Max request body size: 350 MB.
+- Request timeout: 8 minutes \u2014 long-running requests get 408 or 504.
+- Use Data-Access-Intent: ReadOnly header on GET requests that don't need latest data (routes to read replica, reduces load).
+
+RATE LIMITS:
+- 429 Too Many Requests when limits exceeded. Always implement Retry-After handling.
+- Per-user: 6,000 requests per 5-min sliding window, 5 concurrent requests, 100 max connections.
+
+PERFORMANCE GOTCHAS:
+- Avoid temp-table-based API pages with >100 records \u2014 no caching, poor pagination.
+- Calculated/complex fields on API pages are expensive. Prefer stored values.
+- API pages/queries are up to 10x faster than SOAP endpoints \u2014 always prefer API v2.0.
+
+WEBHOOKS: Supports up to 200 webhook subscriptions for entity change notifications via /subscriptions.
+
+CUSTOM APIs: Publishers expose custom API pages at /api/{publisher}/{group}/{version}/companies(<id>)/<endpoint>, NOT under /api/v2.0/.
+`
       },
       redis: {
         name: "redis",
@@ -5409,7 +5556,7 @@ EXAMPLE WORKFLOWS:
         icon: system.icon || "default"
       }))
     ];
-    function findTemplateForSystem3(system) {
+    function findTemplateForSystem4(system) {
       if (system.templateName && exports2.systems[system.templateName]) {
         return { key: system.templateName, template: exports2.systems[system.templateName] };
       }
@@ -5451,7 +5598,7 @@ EXAMPLE WORKFLOWS:
       return [...new Set(keywords)];
     }
     function enrichWithTemplate(input) {
-      const match = findTemplateForSystem3(input);
+      const match = findTemplateForSystem4(input);
       if (!match) {
         return input;
       }
@@ -5488,7 +5635,7 @@ EXAMPLE WORKFLOWS:
         tokenContentType: creds.tokenContentType,
         extraHeaders
       };
-      const match = findTemplateForSystem3(system);
+      const match = findTemplateForSystem4(system);
       const templateOAuth = match?.template.oauth;
       return {
         tokenAuthMethod: storedConfig.tokenAuthMethod ?? templateOAuth?.tokenAuthMethod,
@@ -5500,7 +5647,7 @@ EXAMPLE WORKFLOWS:
       if (system.credentials?.token_url) {
         return system.credentials.token_url;
       }
-      const match = findTemplateForSystem3(system);
+      const match = findTemplateForSystem4(system);
       if (match?.template.oauth?.tokenUrl) {
         return match.template.oauth.tokenUrl;
       }
@@ -19977,6 +20124,8 @@ var require_utils = __commonJS({
     var getConnectionProtocol2 = (url) => {
       if (url.startsWith("postgres://") || url.startsWith("postgresql://"))
         return "postgres";
+      if (url.startsWith("redis://") || url.startsWith("rediss://"))
+        return "redis";
       if (url.startsWith("ftp://") || url.startsWith("ftps://") || url.startsWith("sftp://"))
         return "sftp";
       if (url.startsWith("smb://"))
@@ -21785,7 +21934,7 @@ var import_node_util = require("util");
 // package.json
 var package_default = {
   name: "@superglue/cli",
-  version: "1.1.7",
+  version: "1.1.8",
   bin: {
     sg: "./dist/cli.js"
   },
@@ -22935,12 +23084,21 @@ 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 (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(
+  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 \u2014 auto-fills URL, OAuth config, and credentials. Auto-detected from URL if omitted."
+  ).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"
     ])
-  ).action(async (opts) => {
+  ).addHelpText("after", () => {
+    const oauthTemplates = Object.entries(import_shared6.systems).filter(([, t]) => t.oauth).map(([key, t]) => `  ${key.padEnd(24)} ${t.name}`).join("\n");
+    return `
+OAuth templates (use with --template or auto-detected from URL):
+${oauthTemplates}
+`;
+  }).action(async (opts) => {
     const { client } = getContext2();
     let systemInput;
     if (opts.config) {
@@ -22973,14 +23131,34 @@ function registerCreateCommand(parent, getContext2) {
         environment: opts.env === "dev" || opts.env === "prod" ? opts.env : void 0
       };
     }
-    if (opts.template) {
-      const template = import_shared6.systems[opts.template];
+    let templateKey = opts.template;
+    let template;
+    if (templateKey) {
+      template = import_shared6.systems[templateKey];
       if (!template) {
         error(
-          `Template not found: ${opts.template}. Available: ${Object.keys(import_shared6.systems).join(", ")}`
+          `Template not found: ${templateKey}. Available: ${Object.keys(import_shared6.systems).join(", ")}`
         );
         process.exit(1);
       }
+    } else if (systemInput.url || systemInput.name || systemInput.id) {
+      const match = (0, import_shared6.findTemplateForSystem)({
+        url: systemInput.url,
+        name: systemInput.name,
+        id: systemInput.id
+      });
+      if (match) {
+        templateKey = match.key;
+        template = match.template;
+        if (process.stderr.isTTY) {
+          process.stderr.write(
+            `${c.dim}Auto-detected template: ${c.bold}${templateKey}${c.reset}${c.dim} (use --template to override)${c.reset}
+`
+          );
+        }
+      }
+    }
+    if (template && templateKey) {
       const oauthCreds = {};
       if (template.oauth) {
         if (template.oauth.authUrl) oauthCreds.auth_url = template.oauth.authUrl;
@@ -22992,7 +23170,7 @@ function registerCreateCommand(parent, getContext2) {
         ...systemInput,
         name: systemInput.name || template.name,
         url: systemInput.url || template.apiUrl,
-        templateName: opts.template,
+        templateName: templateKey,
         credentials: { ...oauthCreds, ...systemInput.credentials }
       };
     }
@@ -23031,12 +23209,14 @@ function registerCreateCommand(parent, getContext2) {
       if (process.argv.includes("--json") || !process.stdout.isTTY) {
         output({
           success: true,
-          system: { id: result.id, name: result.name, url: result.url }
+          system: { id: result.id, name: result.name, url: result.url },
+          ...templateKey ? { template: templateKey } : {}
         });
       } else {
         success(`System created: ${c.bold}${result.id}${c.reset}`, {
           name: result.name,
-          url: result.url
+          url: result.url,
+          ...templateKey ? { template: templateKey } : {}
         });
       }
     } catch (err) {

package/dist/skills/superglue/SKILL.md

@@ -235,21 +235,26 @@ sg system call --url "postgres://<<my_db_host>>:5432/mydb" \
   --system-id my_db \
   --body '{"query":"SELECT * FROM users LIMIT 5"}'
 
+# Redis command
+sg system call --url "redis://<<my_redis_host>>:6379/0" \
+  --system-id my_redis \
+  --body '{"command":"HGETALL","args":["user:123"]}'
+
 # File server (SFTP)
 sg system call --url "sftp://<<my_sftp_host>>:22/data" \
   --system-id my_sftp \
   --body '{"operation":"list","path":"/"}'
 ```
 
-| Flag                | Description                                               |
-| ------------------- | --------------------------------------------------------- |
-| `--url <url>`       | Full URL with protocol (http/https/postgres/sftp/ftp/smb) |
-| `--system-id <id>`  | System ID for credential injection                        |
-| `--method <method>` | HTTP method (GET, POST, PUT, DELETE, PATCH)               |
-| `--headers <json>`  | HTTP headers JSON with credential placeholders            |
-| `--body <string>`   | Request body (JSON string)                                |
-| `--env <env>`       | Environment: `dev` or `prod`                              |
-| `--file <key=path>` | File references (repeatable)                              |
+| Flag                | Description                                                            |
+| ------------------- | ---------------------------------------------------------------------- |
+| `--url <url>`       | Full URL with protocol (http/https/postgres/redis/rediss/sftp/ftp/smb) |
+| `--system-id <id>`  | System ID for credential injection                                     |
+| `--method <method>` | HTTP method (GET, POST, PUT, DELETE, PATCH)                            |
+| `--headers <json>`  | HTTP headers JSON with credential placeholders                         |
+| `--body <string>`   | Request body (JSON string)                                             |
+| `--env <env>`       | Environment: `dev` or `prod`                                           |
+| `--file <key=path>` | File references (repeatable)                                           |
 
 **`sg system search-docs`** — Search system documentation.
 
@@ -366,15 +371,26 @@ All step config fields support `<<variable>>` placeholders:
 | -------------------------- | --------------------------- |
 | `<<fieldName>>`            | Payload field or credential |
 | `<<systemId_credKey>>`     | System credential           |
+| `<<sg_auth_email>>`        | Email of authenticated user |
 | `<<(sourceData) => expr>>` | JavaScript expression       |
 
 **CRITICAL**: Simple `<<varName>>` only works for **top-level keys**. No dots, no nesting.
 
-- VALID: `<<userId>>`, `<<currentItem>>`, `<<stripe_api_key>>`
+- VALID: `<<userId>>`, `<<currentItem>>`, `<<stripe_api_key>>`, `<<sg_auth_email>>`
 - INVALID: `<<currentItem.id>>`, `<<sourceData.userId>>` — these FAIL at runtime
 
 For nested access, use arrow functions: `<<(sourceData) => sourceData.currentItem.id>>`
 
+### Context Variables
+
+Context variables provide information about the execution environment:
+
+- `<<sg_auth_email>>` — Email of the authenticated user who triggered the tool
+
+**Use case**: Personalize tool outputs based on who runs the tool (e.g., user-specific permissions, account lookups, audit logging).
+
+**Important**: `sg_auth_email` is NOT available in scheduled executions. Tools using `<<sg_auth_email>>` will fail if run via scheduler.
+
 ### sourceData Object
 
 `sourceData` is the cumulative state available to all JS expressions (data selectors, transforms, variable expressions):
@@ -442,7 +458,7 @@ Empty arrays are valid — the step simply skips execution.
 
 ### Two Step Types
 
-**Request step** (HTTP, Postgres, FTP/SFTP/SMB) — makes an API call:
+**Request step** (HTTP, Postgres, Redis, FTP/SFTP/SMB) — makes an API call:
 
 ```json
 {
@@ -534,9 +550,31 @@ Templates auto-populate endpoints and OAuth config. Use `sg system find` to disc
 
 ### OAuth Flow
 
-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
+**IMPORTANT:** For OAuth systems, always use `--template` when creating the system. Templates auto-configure OAuth URLs, token exchange settings, and scopes. Without a template, OAuth will likely fail or require manual credential setup.
+
+If you don't know the template ID, the CLI auto-detects it from the URL — but using `--template` explicitly is more reliable.
+
+**Step 1: Create the system with template and credentials**
+
+```bash
+# Best: explicit template (auto-fills URL and OAuth config)
+sg system create --name "Gmail" --template gmail \
+  --credentials '{"client_id":"...","client_secret":"..."}'
+
+# Also works: URL-based auto-detection (template inferred from googleapis.com)
+sg system create --name "Gmail" --url https://gmail.googleapis.com \
+  --credentials '{"client_id":"...","client_secret":"..."}'
+```
+
+**Step 2: Authenticate via OAuth**
+
+```bash
+sg system oauth --system-id gmail --scopes "https://www.googleapis.com/auth/gmail.readonly"
+```
+
+**Step 3:** User authenticates in browser → tokens saved automatically
+
+**Common OAuth templates:** gmail, google_drive, google_calendar, google_sheets, slack, salesforce, github, jira, confluence, notion, airtable, hubspot, shopify, dropbox, zoom, microsoft_365
 
 ### System IDs
 
@@ -608,6 +646,7 @@ For detailed documentation on specific topics, read these files in the `referenc
 | ------------------------------------- | ------------------------------------------------------------------------------------------------ |
 | `references/integration.md`           | **READ THIS** when deploying tools to production - SDK usage, REST API, webhooks, error handling |
 | `references/databases.md`             | Building tools that query PostgreSQL/MySQL databases                                             |
+| `references/redis.md`                 | Building tools that interact with Redis (commands, pipelines, data types)                        |
 | `references/file-servers.md`          | Building tools that interact with FTP/SFTP/SMB file servers                                      |
 | `references/transforms-and-output.md` | Complex data transformations, output shaping, JS sandbox constraints                             |
 

package/dist/skills/superglue/references/redis.md

@@ -0,0 +1,190 @@
+# Redis Steps
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_redis",
+  url: "redis://<<my_redis_username>>:<<my_redis_password>>@<<my_redis_host>>:<<my_redis_port>>/<<my_redis_database>>",
+  method: "POST",            // ignored for Redis but required by schema
+  body: '{"command": "GET", "args": ["<<keyName>>"]}'
+}
+```
+
+Configure the connection URL depending on which credentials are saved in the stored Redis system - reference them accordingly.
+
+## URL Format
+
+```
+redis://user:password@host:port/database
+rediss://user:password@host:port/database   (TLS)
+```
+
+- `redis://` for standard connections
+- `rediss://` for TLS-encrypted connections (e.g. Redis Cloud, AWS ElastiCache with encryption)
+- `/database` is the database number (0-15), defaults to 0 if omitted
+
+All credential variables are resolved before connecting. Trailing slashes are cleaned.
+
+## Body Format
+
+JSON string with `command` (required) and optional `args` array. Body can be a single command object or an array of commands (pipelined in a single round-trip):
+
+```json
+{ "command": "GET", "args": ["mykey"] }
+```
+
+Multiple commands:
+
+```json
+[
+  { "command": "GET", "args": ["user:1:name"] },
+  { "command": "HGETALL", "args": ["user:1"] }
+]
+```
+
+### Common Commands
+
+**String operations:**
+
+```json
+{ "command": "GET", "args": ["user:123:name"] }
+{ "command": "SET", "args": ["user:123:name", "Alice"] }
+{ "command": "MGET", "args": ["key1", "key2", "key3"] }
+{ "command": "INCR", "args": ["counter"] }
+```
+
+**Hash operations:**
+
+```json
+{ "command": "HGETALL", "args": ["user:123"] }
+{ "command": "HGET", "args": ["user:123", "email"] }
+{ "command": "HSET", "args": ["user:123", "email", "alice@example.com"] }
+{ "command": "HMGET", "args": ["user:123", "name", "email"] }
+```
+
+**List operations:**
+
+```json
+{ "command": "LRANGE", "args": ["queue:tasks", "0", "-1"] }
+{ "command": "LPUSH", "args": ["queue:tasks", "task1"] }
+{ "command": "RPOP", "args": ["queue:tasks"] }
+{ "command": "LLEN", "args": ["queue:tasks"] }
+```
+
+**Set operations:**
+
+```json
+{ "command": "SMEMBERS", "args": ["tags:post:1"] }
+{ "command": "SADD", "args": ["tags:post:1", "redis", "database"] }
+{ "command": "SISMEMBER", "args": ["tags:post:1", "redis"] }
+```
+
+**Sorted set operations:**
+
+```json
+{ "command": "ZRANGE", "args": ["leaderboard", "0", "-1", "WITHSCORES"] }
+{ "command": "ZADD", "args": ["leaderboard", "100", "player1"] }
+{ "command": "ZRANK", "args": ["leaderboard", "player1"] }
+```
+
+**Key operations:**
+
+```json
+{ "command": "KEYS", "args": ["user:*"] }
+{ "command": "EXISTS", "args": ["mykey"] }
+{ "command": "TTL", "args": ["session:abc"] }
+{ "command": "EXPIRE", "args": ["session:abc", "3600"] }
+{ "command": "DEL", "args": ["mykey"] }
+{ "command": "TYPE", "args": ["mykey"] }
+```
+
+**Scan (safe iteration):**
+
+```json
+{ "command": "SCAN", "args": ["0", "MATCH", "user:*", "COUNT", "100"] }
+{ "command": "HSCAN", "args": ["myhash", "0", "MATCH", "field*"] }
+```
+
+### Dynamic Arguments with Variables
+
+```json
+{ "command": "GET", "args": ["<<(sourceData) => `user:${sourceData.userId}:profile`>>"] }
+```
+
+```json
+{ "command": "HSET", "args": ["<<userKey>>", "<<fieldName>>", "<<fieldValue>>"] }
+```
+
+## Connection Management
+
+- A fresh connection is created per execution and closed after completion
+- TLS auto-configured for `rediss://` URLs (with `rejectUnauthorized: false`)
+- 5-second connection timeout, 30-second command timeout
+- Array commands (pipeline) run on a single connection for efficiency
+
+## Retry Logic
+
+Default retries from server config. On final failure, error includes command and args.
+
+## Return Value
+
+Returns the raw Redis response:
+
+- `GET` / `HGET`: string or null
+- `HGETALL`: object with field-value pairs (flattened array from Redis, parsed by ioredis)
+- `LRANGE` / `SMEMBERS` / `KEYS`: array of strings
+- `SET` / `DEL` / `EXPIRE`: "OK" or integer
+- `INCR` / `LLEN` / `SADD`: integer
+- `MGET` / `HMGET`: array (nulls for missing keys)
+- `SCAN` / `HSCAN`: array of [cursor, results]
+
+## Multiple Commands (Pipeline)
+
+Pass an array of commands to execute them in a single round-trip (like FTP/SFTP batch operations):
+
+```json
+[
+  { "command": "GET", "args": ["user:1:name"] },
+  { "command": "HGETALL", "args": ["user:1"] },
+  { "command": "LRANGE", "args": ["tasks", "0", "-1"] }
+]
+```
+
+Returns an array of results, one per command:
+
+```json
+[
+  { "command": "GET", "result": "Alice" },
+  { "command": "HGETALL", "result": ["name", "Alice", "email", "alice@example.com"] },
+  { "command": "LRANGE", "result": ["task3", "task2", "task1"] }
+]
+```
+
+If an individual command fails, that entry has `error` instead of `result`:
+
+```json
+[
+  { "command": "GET", "result": "Alice" },
+  { "command": "WRONGCMD", "error": "ERR unknown command 'WRONGCMD'" }
+]
+```
+
+A single command returns a single result. Multiple commands return an array — same pattern as FTP/SFTP operations.
+
+## Batch Operations via Loop
+
+Use a data selector returning an array to execute a command per item:
+
+```javascript
+// dataSelector: (sourceData) => sourceData.userIds
+// body: {"command": "HGETALL", "args": ["<<(sourceData) => `user:${sourceData.currentItem}`>>"]}
+```
+
+## Important Notes
+
+- All args must be strings (Redis protocol is text-based) - numbers are auto-coerced
+- Use `SCAN` instead of `KEYS` in production for large keyspaces
+- `HGETALL` returns an empty object `{}` for non-existent keys
+- Use array body for multi-command pipelines instead of separate steps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superglue/cli",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "bin": {
     "sg": "./dist/cli.js"
   },
@@ -15,6 +15,7 @@
     "fast-json-patch": "^3.1.1"
   },
   "devDependencies": {
+    "@superglue/shared": "file:../shared",
     "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"