@superglue/cli 1.1.21 → 1.1.22

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

@@ -73,12 +73,14 @@ curl -X POST "$SUPERGLUE_API_ENDPOINT/v1/runs/{runId}/cancel" \
 
 ## SDK Installation
 
+**Always install the latest version** — older SDK versions may have known bugs (e.g. case-sensitivity issues on Linux in versions before 3.3.0).
+
 ```bash
 # TypeScript/JavaScript
-npm install @superglue/client
+npm install @superglue/client@latest
 
 # Python
-pip install superglue-client
+pip install --upgrade superglue-client
 ```
 
 Both SDKs are auto-generated from the OpenAPI spec (JS via orval, Python via openapi-python-client).

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

@@ -0,0 +1,207 @@
+# MSSQL
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_azure_sql",
+  url: "mssql://<<my_azure_sql_user>>:<<my_azure_sql_password>>@<<my_azure_sql_host>>:<<my_azure_sql_port>>/<<my_azure_sql_database>>",
+  body: '{"query": "SELECT * FROM users WHERE id = @param1", "params": [<<userId>>]}'
+}
+```
+
+Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
+
+`method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
+
+### Fields
+
+| Field      | Required | Notes                                                          |
+| ---------- | -------- | -------------------------------------------------------------- |
+| `url`      | yes      | Connection string with `<<credential>>` placeholders           |
+| `body`     | yes      | JSON string with `query` and optional `params`                 |
+| `systemId` | no       | Links system credentials for `<<systemId_credKey>>` resolution |
+
+### URL Format
+
+```
+mssql://user:password@host:port/database
+sqlserver://user:password@host:port/database
+```
+
+Both `mssql://` and `sqlserver://` are supported.
+
+**Azure SQL Database** — use the fully qualified server name:
+
+```
+mssql://myuser:mypassword@myserver.database.windows.net:1433/mydatabase
+```
+
+Azure SQL usernames often include `@servername` suffix (e.g., `myuser@myserver`). Encode the `@` as `%40` in the URL:
+
+```
+mssql://myuser%40myserver:mypassword@myserver.database.windows.net:1433/mydatabase
+```
+
+**Connection parameters** can be appended as query strings:
+
+```
+mssql://user:password@host:port/database?encrypt=true&trustServerCertificate=false
+```
+
+| Parameter                | Default | Notes                                   |
+| ------------------------ | ------- | --------------------------------------- |
+| `encrypt`                | `true`  | Required for Azure SQL                  |
+| `trustServerCertificate` | `false` | Whether to trust the server certificate |
+| `database`               | —       | Can be in URL path or query parameter   |
+
+### Body Format
+
+JSON string with `query` and optional `params` (or `values`):
+
+```json
+{
+  "query": "SELECT * FROM users WHERE age > @param1 AND status = @param2",
+  "params": [25, "active"]
+}
+```
+
+## Authentication
+
+### SQL Server Authentication (default)
+
+Credentials are embedded directly in the connection URL using `<<systemId_credentialKey>>` placeholders. Nothing is injected automatically.
+
+```
+mssql://<<my_db_user>>:<<my_db_password>>@<<my_db_host>>:<<my_db_port>>/<<my_db_database>>
+```
+
+### Azure Active Directory Authentication
+
+For Azure AD auth, store the following credential keys on the system alongside the standard connection fields:
+
+**Entra ID User + Password** — authenticates as an Azure AD user. Requires an Azure app registration.
+
+| Credential Key | Required | Notes                                                  |
+| -------------- | -------- | ------------------------------------------------------ |
+| `authType`     | yes      | `azure-active-directory-password`                      |
+| `clientId`     | yes      | Application (client) ID from Azure app registration    |
+| `tenantId`     | no       | Directory (tenant) ID                                  |
+| `user`         | yes      | Azure AD username (also accepts `username`, or in URL) |
+| `password`     | yes      | Azure AD password (or in URL)                          |
+
+`user` and `password` can be stored as credentials or embedded in the URL — credentials take precedence.
+
+```
+URL:  mssql://<<sys_user>>:<<sys_password>>@myserver.database.windows.net:1433/mydb
+Credentials: { authType, clientId, tenantId, user, password, host, port, database }
+```
+
+**Service Principal** — authenticates as an Azure AD application. No user/password needed in the URL.
+
+| Credential Key | Required | Notes                                             |
+| -------------- | -------- | ------------------------------------------------- |
+| `authType`     | yes      | `azure-active-directory-service-principal-secret` |
+| `clientId`     | yes      | Application (client) ID                           |
+| `clientSecret` | yes      | Client secret                                     |
+| `tenantId`     | yes      | Directory (tenant) ID                             |
+
+```
+URL:  mssql://myserver.database.windows.net:1433/mydb
+Credentials: { authType, clientId, clientSecret, tenantId, host, port, database }
+```
+
+The runtime authenticates entirely via the service principal credentials — no user or password is needed in the URL.
+
+## MSSQL Runtime Details
+
+### Schema Discovery
+
+superglue does not auto-introspect MSSQL schemas. Before building tools, always query the schema manually with `sg system call` to discover tables and columns:
+
+```json
+{
+  "query": "SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, IS_NULLABLE FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = 'dbo' ORDER BY TABLE_NAME, ORDINAL_POSITION"
+}
+```
+
+For Azure SQL or databases with non-default schemas, adjust the `TABLE_SCHEMA` filter or remove it to see all schemas.
+Always verify table and column names against the actual schema before building tools.
+
+### Parameterized Queries
+
+Always use parameterized queries with `@param1`, `@param2`, etc. This prevents SQL injection. The params array maps positionally: `params[0]` maps to `@param1`, `params[1]` maps to `@param2`, etc.
+
+```json
+{ "query": "SELECT * FROM orders WHERE customer_id = @param1", "params": ["<<customerId>>"] }
+```
+
+With expressions:
+
+```json
+{
+  "query": "INSERT INTO logs (message, level) VALUES (@param1, @param2)",
+  "params": ["<<(sourceData) => sourceData.message>>", "error"]
+}
+```
+
+With OUTPUT (MSSQL equivalent of RETURNING):
+
+```json
+{
+  "query": "INSERT INTO users (name, email) OUTPUT INSERTED.* VALUES (@param1, @param2)",
+  "params": [
+    "<<(sourceData) => sourceData.currentItem.name>>",
+    "<<(sourceData) => sourceData.currentItem.email>>"
+  ]
+}
+```
+
+### Return Value
+
+Returns the recordset — array of row objects with column names as keys.
+
+- `SELECT`: array of matching rows
+- `INSERT/UPDATE/DELETE` with `OUTPUT`: array of returned rows
+- Mutations without `OUTPUT`: empty array
+
+### Batch Operations
+
+Use a data selector returning an array to execute a query per item:
+
+```javascript
+// dataSelector: (sourceData) => sourceData.newUsers
+// body: {"query": "INSERT INTO users (name) VALUES (@param1)", "params": ["<<(sourceData) => sourceData.currentItem.name>>"]}
+```
+
+### Connection Pooling
+
+- Pools cached by connection string, max 10 clients per pool
+- 30s connection timeout, configurable request timeout
+- Idle pools cleaned up automatically
+- SSL/TLS encryption enabled by default for Azure SQL
+
+### Retry Behavior
+
+Default retries from server config. On final failure, error includes query text and params.
+
+## Common Pitfalls
+
+- Using `$1`, `$2` (PostgreSQL syntax) instead of `@param1`, `@param2` — MSSQL uses named `@param` parameters
+- Forgetting `OUTPUT INSERTED.*` on INSERT/UPDATE/DELETE when you need the result — without it the step returns an empty array
+- Accessing step result directly instead of via `.data` — database results follow the same envelope as all steps: `sourceData.stepId.data`
+- Not URL-encoding `@` in Azure SQL usernames — `myuser@myserver` must be `myuser%40myserver` in the connection URL
+
+## Error Recovery
+
+When an MSSQL step fails and the cause is not obvious:
+
+1. **Read the error message** — superglue includes the query text and params in the error. Check for syntax errors, missing columns, or type mismatches.
+2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
+3. **Check database-side access** — connection refused or permission denied errors typically mean the database user lacks access. Verify with the user that the credentials have the required grants.
+4. **Check Azure-specific issues** — if connecting to Azure SQL:
+   - Confirm the client IP is allowed in the Azure SQL firewall rules
+   - Verify the username includes the `@servername` suffix if required, properly encoded as `%40`
+   - Confirm `encrypt=true` is set (required for Azure SQL)
+5. **Verify parameter types** — MSSQL infers types from the values passed. Passing a string where a number is expected may cause implicit conversion errors. Ensure `params` values match expected column types.

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

@@ -0,0 +1,154 @@
+# PostgreSQL
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_postgres_db",
+  url: "postgres://<<my_postgres_db_user>>:<<my_postgres_db_password>>@<<my_postgres_db_host>>:<<my_postgres_db_port>>/<<my_postgres_db_database>>",
+  body: '{"query": "SELECT * FROM users WHERE id = $1", "params": [<<userId>>]}'
+}
+```
+
+Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
+
+`method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
+
+### Fields
+
+| Field      | Required | Notes                                                          |
+| ---------- | -------- | -------------------------------------------------------------- |
+| `url`      | yes      | Connection string with `<<credential>>` placeholders           |
+| `body`     | yes      | JSON string with `query` and optional `params`                 |
+| `systemId` | no       | Links system credentials for `<<systemId_credKey>>` resolution |
+
+### URL Format
+
+```
+postgres://user:password@host:port/database
+postgresql://user:password@host:port/database
+```
+
+Both `postgres://` and `postgresql://` are supported. Trailing slashes and extra slashes before query strings are cleaned automatically.
+
+### Body Format
+
+JSON string with `query` and optional `params` (or `values`):
+
+```json
+{ "query": "SELECT * FROM users WHERE age > $1 AND status = $2", "params": [25, "active"] }
+```
+
+## Authentication
+
+Credentials are embedded directly in the connection URL using `<<systemId_credentialKey>>` placeholders. Nothing is injected automatically.
+
+```
+postgres://<<my_db_user>>:<<my_db_password>>@<<my_db_host>>:<<my_db_port>>/<<my_db_database>>
+```
+
+Credential variables are resolved at runtime before connecting.
+
+## PostgreSQL Runtime Details
+
+### Schema Discovery
+
+superglue does not auto-introspect Postgres schemas. Before building tools, always query the schema manually with `sg system call` to discover tables and columns:
+
+```json
+{
+  "query": "SELECT table_name, column_name, data_type, is_nullable FROM information_schema.columns WHERE table_schema = 'public' ORDER BY table_name, ordinal_position"
+}
+```
+
+Always verify table and column names against the actual schema before building tools.
+
+### Parameterized Queries
+
+Always use parameterized queries with `$1`, `$2`, etc. — prevents SQL injection.
+
+```json
+{ "query": "SELECT * FROM orders WHERE customer_id = $1", "params": ["<<customerId>>"] }
+```
+
+With expressions:
+
+```json
+{
+  "query": "INSERT INTO logs (message, level) VALUES ($1, $2)",
+  "params": ["<<(sourceData) => sourceData.message>>", "error"]
+}
+```
+
+With RETURNING:
+
+```json
+{
+  "query": "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
+  "params": [
+    "<<(sourceData) => sourceData.currentItem.name>>",
+    "<<(sourceData) => sourceData.currentItem.email>>"
+  ]
+}
+```
+
+### Return Value
+
+Returns `result.rows` — array of row objects with column names as keys.
+
+- `SELECT`: array of matching rows
+- `INSERT/UPDATE/DELETE` with `RETURNING`: array of returned rows
+- Mutations without `RETURNING`: empty array
+
+### Batch Operations
+
+Use a data selector returning an array to execute a query per item:
+
+```javascript
+// dataSelector: (sourceData) => sourceData.newUsers
+// body: {"query": "INSERT INTO users (name) VALUES ($1)", "params": ["<<(sourceData) => sourceData.currentItem.name>>"]}
+```
+
+### Connection Pooling
+
+- Pools cached by connection string, max 10 clients, 30s connection timeout
+- Idle pools cleaned up automatically
+
+### SSL / TLS
+
+SSL is auto-configured based on the connection URL — you do not need to set it manually in most cases.
+
+**Default behavior (no `sslmode` in URL):**
+
+- `localhost` / `127.0.0.1` → SSL disabled
+- All other hosts → superglue probes the server to detect SSL support and enables it if the server accepts SSL handshakes. If the probe fails or times out, SSL is enabled as a safe default.
+
+**Explicit `sslmode` in URL** (appended as `?sslmode=...`):
+
+- `sslmode=disable` → SSL off
+- `sslmode=require` → SSL on, enforced
+- `sslmode=verify-ca` / `sslmode=verify-full` → SSL on, enforced; AWS RDS CA bundle loaded if present on disk
+- Any other sslmode value → SSL on, not enforced
+
+Server certificate chain validation is not performed by default; `verify-ca` / `verify-full` only flip the `enforce` flag and opportunistically load the RDS CA bundle. If strict chain validation matters for your deployment, terminate TLS at a trusted proxy.
+
+### Retry Behavior
+
+Default retries from server config. On final failure, error includes query text and params.
+
+## Common Pitfalls
+
+- Using string interpolation instead of parameterized queries — always use `$1`, `$2` with `params` array
+- Forgetting `RETURNING *` on INSERT/UPDATE/DELETE when you need the result — without it the step returns an empty array
+- Accessing step result directly instead of via `.data` — database results follow the same envelope as all steps: `sourceData.stepId.data`
+
+## Error Recovery
+
+When a PostgreSQL step fails and the cause is not obvious:
+
+1. **Read the error message** — superglue includes the query text and params in the error. Check for syntax errors, missing columns, or type mismatches.
+2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
+3. **Check database-side access** — connection refused or permission denied errors typically mean the database user lacks access to the database, schema, or table. Verify with the user that the credentials have the required grants.
+4. **Test the query directly** — use `sg system call` with a simplified version of the query to isolate whether the issue is the query itself, the parameters, or the connection.
+5. **Check for SSL/TLS issues** — if the error mentions SSL or handshake failure, check the SSL / TLS section above. For non-localhost servers that don't support SSL, add `?sslmode=disable` to the URL. For servers that require SSL, add `?sslmode=require`.

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

@@ -1,4 +1,4 @@
-# Redis Steps
+# Redis
 
 ## Step Configuration
 
@@ -11,9 +11,19 @@
 }
 ```
 
-Configure the connection URL depending on which credentials are saved in the stored Redis system - reference them accordingly.
+Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
 
-## URL Format
+`method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for Redis steps.
+
+### Fields
+
+| Field      | Required | Notes                                                          |
+| ---------- | -------- | -------------------------------------------------------------- |
+| `url`      | yes      | Connection string with `<<credential>>` placeholders           |
+| `body`     | yes      | JSON: single command object or array for pipeline              |
+| `systemId` | no       | Links system credentials for `<<systemId_credKey>>` resolution |
+
+### URL Format
 
 ```
 redis://user:password@host:port/database
@@ -21,20 +31,18 @@ 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 (defaults to 0 if omitted; max depends on the server's `databases` config, commonly 16)
-
-All credential variables are resolved before connecting. Trailing slashes are cleaned.
+- `rediss://` for TLS-encrypted connections (Redis Cloud, AWS ElastiCache with encryption)
+- `/database` is the database number (defaults to 0; max depends on server config, commonly 16)
 
-## Body Format
+### 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 string with `command` (required) and optional `args` array:
 
 ```json
 { "command": "GET", "args": ["mykey"] }
 ```
 
-Multiple commands:
+For pipelines, pass an array of command objects (executed in a single round-trip):
 
 ```json
 [
@@ -43,115 +51,39 @@ Multiple commands:
 ]
 ```
 
-### 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"] }
-```
+All args must be strings — numbers are auto-coerced.
 
-**Hash operations:**
+Dynamic arguments with variables:
 
 ```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"] }
+{ "command": "GET", "args": ["<<(sourceData) => `user:${sourceData.userId}:profile`>>"] }
 ```
 
-**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"] }
-```
+## Authentication
 
-**Set operations:**
+Credentials are embedded directly in the connection URL using `<<systemId_credentialKey>>` placeholders. Nothing is injected automatically.
 
-```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"] }
+redis://<<my_redis_username>>:<<my_redis_password>>@<<my_redis_host>>:<<my_redis_port>>/<<my_redis_database>>
 ```
 
-**Key operations:**
+## Redis Runtime Details
 
-```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"] }
-```
+### Return Values
 
-**Scan (safe iteration):**
+| Command type                 | Returns                                                                                                                                |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET`, `HGET`                | string or null                                                                                                                         |
+| `HGETALL`                    | flat array of alternating field-value pairs, e.g. `["name", "Alice", "email", "alice@example.com"]`. Empty array for non-existent keys |
+| `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]`                                                                                                           |
 
-```json
-{ "command": "SCAN", "args": ["0", "MATCH", "user:*", "COUNT", "100"] }
-{ "command": "HSCAN", "args": ["myhash", "0", "MATCH", "field*"] }
-```
+### Pipeline Results
 
-### 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 (currently uses `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`: flat array of alternating field-value pairs (e.g., `["name", "Alice", "email", "alice@example.com"]`)
-- `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:
+A single command returns a single result. An array of commands returns an array of results:
 
 ```json
 [
@@ -161,18 +93,13 @@ Returns an array of results, one per command:
 ]
 ```
 
-If an individual command fails, that entry has `error` instead of `result`:
+If an individual command in a pipeline fails, that entry has `error` instead of `result`:
 
 ```json
-[
-  { "command": "GET", "result": "Alice" },
-  { "command": "WRONGCMD", "error": "ERR unknown command 'WRONGCMD'" }
-]
+{ "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
+### Batch Operations
 
 Use a data selector returning an array to execute a command per item:
 
@@ -181,9 +108,32 @@ Use a data selector returning an array to execute a command per item:
 // body: {"command": "HGETALL", "args": ["<<(sourceData) => `user:${sourceData.currentItem}`>>"]}
 ```
 
-## Important Notes
+Prefer array body pipelines over loop-based batch when commands are independent and don't depend on each other's results.
+
+### Connection Management
+
+- Fresh connection created per execution, closed after completion
+- TLS auto-configured for `rediss://` URLs (`rejectUnauthorized: false`)
+- 5-second connection timeout, 30-second command timeout
+- Pipeline commands run on a single connection
+
+### Retry Behavior
+
+Default retries from server config. On final failure, error includes command and args.
+
+## Common Pitfalls
+
+- Using `KEYS` in production on large keyspaces — use `SCAN` with `MATCH` pattern instead
+- Expecting `HGETALL` to return an object — it returns a flat alternating array `[field, value, field, value, ...]`
+- Accessing step result directly instead of via `.data` — Redis results follow the same envelope as all steps: `sourceData.stepId.data`
+- Using separate steps for independent commands that could be pipelined in a single array body
+
+## Error Recovery
+
+When a Redis step fails:
 
-- 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 array `[]` for non-existent keys
-- Use array body for multi-command pipelines instead of separate steps
+1. **Read the error message** — superglue includes the command and args in the error. Check for unknown commands, wrong argument counts, or type errors (e.g. running a list command on a string key).
+2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test with a simple `PING` command via `sg system call`.
+3. **Check connectivity and access** — connection refused errors typically mean the Redis server is unreachable or requires TLS (`rediss://`). AUTH errors mean the password is wrong or the user lacks access.
+4. **Check key types** — Redis commands are type-specific. Running `GET` on a hash key or `HGETALL` on a string key returns a `WRONGTYPE` error. Use `TYPE` command via `sg system call` to check a key's type before building.
+5. **Verify TLS requirements** — if the error mentions connection reset or handshake failure, try switching between `redis://` and `rediss://`.