@superglue/cli 1.1.203 → 1.1.205

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +6 -7
  3. package/dist/cli.js +216 -215
  4. package/dist/skills/superglue/SKILL.md +73 -72
  5. package/dist/skills/superglue/references/access-rules.md +22 -27
  6. package/dist/skills/superglue/references/graphql.md +2 -6
  7. package/dist/skills/superglue/references/http.md +3 -3
  8. package/dist/skills/superglue/references/mongodb.md +1 -1
  9. package/dist/skills/superglue/references/mssql.md +4 -4
  10. package/dist/skills/superglue/references/odbc.md +1 -1
  11. package/dist/skills/superglue/references/postgres.md +1 -1
  12. package/dist/skills/superglue/references/redis.md +1 -1
  13. package/dist/skills/superglue/references/sftp-smb.md +5 -5
  14. package/dist/skills/superglue/references/suitecloud.md +1 -1
  15. package/dist/skills/superglue/references/superglue-info.md +4 -5
  16. package/package.json +1 -1
  17. package/skills/superglue/SKILL.md +73 -72
  18. package/skills/superglue/references/access-rules.md +22 -27
  19. package/skills/superglue/references/graphql.md +2 -6
  20. package/skills/superglue/references/http.md +3 -3
  21. package/skills/superglue/references/mongodb.md +1 -1
  22. package/skills/superglue/references/mssql.md +4 -4
  23. package/skills/superglue/references/odbc.md +1 -1
  24. package/skills/superglue/references/postgres.md +1 -1
  25. package/skills/superglue/references/redis.md +1 -1
  26. package/skills/superglue/references/sftp-smb.md +5 -5
  27. package/skills/superglue/references/suitecloud.md +1 -1
  28. package/skills/superglue/references/superglue-info.md +4 -5
package/dist/skills/superglue/references/superglue-info.md CHANGED
@@ -44,11 +44,11 @@ Users can generate and manage API keys on the standalone **API Keys** page (`/ap
44
44
 
45
45
  Each key carries an access scope, set at creation and editable later. A scope is a surface plus an action: the surfaces are **API & CLI** (everything except MCP, including the agent and the CLI) and **MCP** (assistants connected over MCP), and the actions are **read**, **write**, and **execute**. Writing covers creating, changing, and deleting. Executing covers running tools and talking to the agent, so a key with only read and write cannot run anything. MCP requests are always tool calls, so that surface only takes execute. Keys created before scoping keep full access. A scope only narrows a key; it never grants more than the owner's role permissions. A scoped key cannot reach the API keys endpoints at all, so it can neither widen itself nor read another key's value. Full access is therefore its own choice at creation, not the result of selecting every surface: a key that holds every scope is still a scoped key and still cannot manage API keys. A request outside the scope returns 403.
46
46
 
47
- Two limits are worth stating plainly. Execute reaches the agent, and the agent's own tools create and edit systems, credentials, and roles, so an execute scope is not a run-only scope — only the owner's role permissions bound it. And scopes apply to API keys alone: an MCP client that connects through OAuth instead of a key is unscoped and carries the user's full authority.
47
+ Two limits are worth stating plainly. Execute reaches the agent, and the agent's own tools create and edit connections, tools, and roles, so an execute scope is not a run-only scope — only the owner's role permissions bound it. And scopes apply to API keys alone: an MCP client that connects through OAuth instead of a key is unscoped and carries the user's full authority.
48
48
 
49
49
  ## Interfaces
50
50
 
51
- - **Web app** — primary UI for building, testing, and managing tools and systems
51
+ - **Web app** — primary UI for building, testing, and managing tools and connections
52
52
  - **TypeScript/Python SDK** — https://superglue.ai/docs/sdk/overview/
53
53
  - **REST API** — https://superglue.ai/docs/api/
54
54
  - **MCP Server** — https://superglue.ai/docs/mcp/using-the-mcp/
@@ -76,7 +76,7 @@ If a customer's system requires IP allowlisting for firewall rules, security gro
76
76
 
77
77
  Use this section as the source of truth for high-level web app navigation. Do not invent UI locations that are not listed here.
78
78
 
79
- Brain contains context-source setup, playbooks, artifacts, and files. Capabilities contains project-attachable systems and tools. Credentials, MCP servers, and schedules configure execution but are not project members. Projects are managed separately and group selected context and capabilities without changing RBAC.
79
+ Brain contains context-source setup, playbooks, artifacts, and files. Capabilities contains tools, connections, MCP servers, and schedules; tools are project-attachable, the others configure execution. A system is only the system ID that groups connections and tool steps. Projects are managed separately and group selected context and capabilities without changing RBAC.
80
80
 
81
81
  The persistent left sidebar contains these top-level items:
82
82
 
@@ -88,8 +88,7 @@ The persistent left sidebar contains these top-level items:
88
88
  - **Files** (`/files`) — uploaded source material.
89
89
  - **Capabilities** — expandable group for connected and executable resources:
90
90
  - **Tools** (`/tools`, detail at `/tools/{toolId}`) — saved tools; opens the tool playground for editing, testing, and running.
91
- - **Systems** (`/systems`, detail at `/systems/{systemId}`) — connected external systems with credentials and documentation.
92
- - **Credentials** (`/credentials`) — manage the credentials you own for each system, and the credentials shared with you. Admins and members open it inside the normal app shell from the sidebar. API keys are not managed here.
91
+ - **Connections** (`/connections`, detail at `/connections/{connectionId}`) — connections to external services, grouped by system id, with secret status per connection; yours and the ones shared with you. A system ID is a namespace derived from existing connections; no system record is created. API keys are not managed here.
93
92
  - **MCP Servers** (`/mcp-servers`) — manage and export named MCP server endpoints. Use the MCP documentation for behavior, permissions, and client setup.
94
93
  - **Schedules** (`/schedules`) — scheduled and recurring tool runs.
95
94
  - **Control Panel** (`/admin`) — expandable group for organization and account administration:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@superglue/cli",
3
- "version": "1.1.203",
3
+ "version": "1.1.205",
4
4
  "bin": {
5
5
  "sg": "./dist/cli.js"
6
6
  },
package/skills/superglue/SKILL.md CHANGED
@@ -27,7 +27,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
27
27
  | `sg skill sftp-smb` | SFTP, FTP, and SMB operations, file upload/download semantics, path handling |
28
28
  | `sg skill suitecloud` | NetSuite SuiteCloud deploys: custom fields, record types, scripts; validate, preview, deploy |
29
29
  | `sg skill file-handling` | File detection, parsing, `file::` reference syntax, lazy base64 access, transform-produced files |
30
- | `sg skill access-rules` | RBAC roles, resource grants, and tool/system permissions (enterprise only) |
30
+ | `sg skill access-rules` | RBAC roles, resource grants, and tool/credential permissions (enterprise only) |
31
31
 
32
32
  ## CRITICAL RULES — READ FIRST
33
33
 
@@ -40,7 +40,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
40
40
  **Calling systems and running tools**
41
41
 
42
42
  1. ALWAYS pull the relevant system context using `sg system find` before calling system endpoints and before building tools.
43
- 2. Use `sg system search-docs` for a targeted keyword search of system docs when unsure how a system works.
43
+ 2. Consult provider documentation when an API or service behavior is unclear.
44
44
 
45
45
  **Authentication & Credentials**
46
46
 
@@ -101,11 +101,11 @@ Verify with `sg whoami` or `sg system list` — should return authenticated cont
101
101
 
102
102
  Set via `SUPERGLUE_CLI_PRESET` env var or `config.json` as `"preset"`. Legacy `sg init --preset` still writes this value for existing scripts.
103
103
 
104
- | Preset | Description |
105
- | --------- | -------------------------------------------------------------------------------------------------------------- |
106
- | `runner` | Run saved tools by ID only. Read-only lookups. No building/editing |
107
- | `builder` | Runner + build/edit/save tools, call systems, manage MCP servers, schedules, and project tasks. No system CRUD |
108
- | `admin` | Full access (default) |
104
+ | Preset | Description |
105
+ | --------- | ----------------------------------------------------------------------------------------------------------- |
106
+ | `runner` | Run saved tools by ID only. Read-only lookups. No building/editing |
107
+ | `builder` | Runner + build/edit/save tools, call systems, manage connections, MCP servers, schedules, and project tasks |
108
+ | `admin` | Full access (default) |
109
109
 
110
110
  Blocked commands print a clear error showing the current preset and how to change it.
111
111
 
@@ -125,8 +125,8 @@ Blocked commands print a clear error showing the current preset and how to chang
125
125
  ### Building a Tool
126
126
 
127
127
  1. **Load relevant protocol references** via `sg skill <topic>` based on the systems involved (http, postgres, graphql, etc.)
128
- 2. Use `sg system find` for every involved system — note the available secret names and the system URL
129
- 3. Use `sg system search-docs` for each system — look up endpoints, auth patterns, pagination, response structure
128
+ 2. Use `sg system find` for every involved system — note the available secret names and the connection URL
129
+ 3. Consult provider documentation for endpoints, authentication, pagination, and response structure.
130
130
  4. Use `sg system call` to test 1-2 primary endpoints — verify response structure and field names before building
131
131
  5. Call `sg tool build --config '{...}'` with the full tool config (see Reference → Tool Config Schema)
132
132
  6. Test with `sg tool run --draft <draftId>`. Use `--include-step-results` to inspect raw step data
@@ -141,14 +141,22 @@ Blocked commands print a clear error showing the current preset and how to chang
141
141
  4. Apply with `sg tool edit --tool <toolId> --patches '[...]'` (or `--draft <draftId>` for drafts)
142
142
  5. Re-run to verify behavior
143
143
 
144
- ### Creating/Editing a System
144
+ ### Connecting a System
145
145
 
146
- 1. Search for an existing system first: `sg system find <query>`
147
- 2. If creating: `sg system create --name "..." --url "..." --credentials '{...}'`. Prefer `--template <id>` when one exists — it auto-fills URL and OAuth config
148
- 3. For OAuth: `sg system oauth --system-id <id> [--scopes "..."]` opens a browser flow. User approves → tokens saved automatically
149
- 4. For non-OAuth secrets: `sg system credentials set --system-id <id> --credentials '{...}'`
146
+ Systems are derived: a connection namespace is derived from existing connections. There is no system record to create or edit; you create and edit your connection.
147
+
148
+ Removed commands (`sg system create`, `edit`, `credentials`, and `search-docs`) return a deprecation error with `sg update` and replacement guidance. Removed system API endpoints return HTTP 410 with the same guidance. Run `sg update`, then use connection commands; use `sg system find --id <id>` for system knowledge. Legacy `/credentials` API aliases remain available with deprecation headers.
149
+
150
+ 1. Read the relevant tool's namespace first, then inspect existing namespaces with `sg system find <query>` and the connections you can access under one with `sg system connection list --system-id <id>`. Reuse that exact id, even when other users' connections are hidden. For a new namespace, use the template id, not its display name. Without a template, choose a descriptive id. Keep account labels in connection names; separate namespaces when tools need distinct services or environments.
151
+ 2. Save your connection under the id: `sg system connection set --system-id <id> --url "..." --credentials '{...}' --authentication '{"type":"api_key"}'`. `--authentication` or `--oauth-app-id` is required when creating a connection; use `{"type":"none"}` for unauthenticated systems. Use the saved connection's returned `systemId` in later commands, tool steps, and placeholders.
152
+ 3. For OAuth: discover reusable apps with `sg system oauth-apps [--system-id <id>]` and link one with `--oauth-app-id <id>`. When several apps fit, ask the user which one to use. A new client ID and secret creates a reusable org app automatically, including default scopes. Otherwise add the client config with `--authentication '{"type":"oauth2",...}'`, then `sg system oauth --system-id <id> [--scopes "..."]` opens a browser flow. Omit `--scopes` to use saved connection scopes. Supply it to replace the set, including more or fewer scopes; `--scopes ""` requests none. Overrides are saved on the connection and do not change app defaults. User approves → tokens saved to your connection
153
+ 4. For private systems: `--tunnel-id <id>` binds a Secure Gateway tunnel to the connection
150
154
  5. Verify connectivity with `sg system call`
151
- 6. For updates: `sg system edit --id <id>` with the fields to change
155
+ 6. For updates: re-run `sg system connection set --system-id <id>` with the fields to change. When the namespace holds several connections, pass `--connection-id <id>` from `sg system connection list` to `set`, `clear`, `oauth`, and `call`; without it, `set` and `oauth` target your default or oldest owned connection
156
+
157
+ A connection linked to an OAuth app uses the app's client ID, client secret, and token URL; app secret rotations reach every linked connection. Other authentication fields are copied on selection and stay connection-specific; scope edits remain local. Changing the client ID or token URL detaches the connection and requires its own client secret; `--oauth-app-id ""` also detaches and must be sent together with the connection's own client secret. Changing client settings retains tokens and supplemental secrets; authorize again afterward. Managed secrets stay hidden and restricted to approved provider endpoints.
158
+
159
+ When selecting an OAuth app on an existing non-OAuth connection, also pass `--authentication '{"type":"oauth2"}'`. An app-only update to a non-OAuth connection returns a validation error.
152
160
 
153
161
  ### Running a Tool (Ad-hoc)
154
162
 
@@ -235,32 +243,30 @@ sg project task edit --project <projectId> --id <taskId> --labels blocked
235
243
 
236
244
  Agents familiar with the web agent (its native tools and the `superglue` node module used inside `run_command`) can map them directly to CLI commands:
237
245
 
238
- | Web agent tool | CLI command | Notes |
239
- | ------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------ |
240
- | `tools.writeTool` (superglue module; new id) | `sg tool build --config '{...}'` | CLI is not AI-powered — you provide the full JSON config |
241
- | `tools.writeTool` (superglue; saved id) | `sg tool edit --tool <id> --patches '[...]'` | JSON Patch (RFC 6902). Use `--draft <id>` for drafts |
242
- | `tools.runTool` | `sg tool run --tool <id>` / `--draft <id>` | Add `--include-step-results` to inspect per-step data |
243
- | `run_command` with `vfs` for `/org/tools/` | `sg tool find --id <id>` / `sg tool find <q>` | Full config with `--id`, compact search with a query string |
244
- | `tools.writeSystem` (superglue module; new id) | `sg system create --name "..." --url "..."` | Use `--template <id>` when available |
245
- | `tools.writeSystem` (superglue; saved) | `sg system edit --id <id> ...` | Edits the system with that exact ID |
246
- | `run_command` with `vfs` for `/org/systems/` | `sg system find <query>` / `--id <id>` | Returns secret-key presence and the system URL |
247
- | Credentials VFS / saved credentials | `sg system credentials get/set/clear` | Manage the current user's credentials for a system |
248
- | `tools.callSystem` | `sg system call --system-id <id> --url <url>` | Ad-hoc calls; credential and auth header are added server-side |
249
- | `run_command search` | `sg system search-docs --system-id <id> -k` | Targeted keyword search over ingested system docs |
250
- | `authenticate_oauth` | `sg system oauth --system-id <id> [--scopes]` | Opens browser flow. Supports `--grant-type client_credentials` too |
251
- | `run_command` with `vfs` for `/org/runs/` | `sg run list` / `sg run get <runId>` | Filter `list` by `--tool`, `--status`, `--source`, `--limit` |
252
- | `run_command` with `vfs` for `/org/mcp-servers/` | `sg mcp list` / `sg mcp find --id <id>` | Returns endpoint, auth mode, selected tool IDs, and client config |
253
- | `tools.writeMcpServer` (superglue module; new) | `sg mcp create --name <n> --tool <id>` | Creates a named MCP endpoint for selected saved tools |
254
- | `tools.writeMcpServer` (superglue) | `sg mcp edit --id <id> ...` | Edits name, auth mode, description, or selected tool IDs |
255
- | `tools.writeSchedule` (superglue module; new) | `sg schedule create --tool <id> --cron <expr>` | Creates a cron schedule for a saved tool |
256
- | `tools.writeSchedule` (superglue; id) | `sg schedule edit --tool <id> --id <schedule>` | Updates, enables, or disables an existing schedule |
257
- | `run_command` with `vfs` for `/projects/` | `sg project list` / `sg project task list` | Tasks are listed in board order with `position` |
258
- | `tools.writeTask` (superglue module; no id) | `sg project task create --project <id>` | Same fields; `--position` places the task in its column |
259
- | `tools.writeTask` (superglue module; id) | `sg project task edit --project <p> --id <t>` | Updates only the given fields, including `--position` |
260
- | `tools.writeProjectLabel` (superglue module) | `sg project label create` / `label edit` | Same fields; `sg project label delete` has no module equivalent |
261
- | (no direct equivalent) | `sg login`, `sg update`, `sg skill` | CLI-specific setup, updater, and this reference system |
262
-
263
- Web-agent-only concepts with no CLI equivalent: `run_command`'s virtual filesystem (CLI uses concrete `sg` subcommands), `authenticate_oauth`'s dedicated MCP `authenticate` tool (CLI uses `sg system oauth`), and `setup_gateway` (the gateway install command is created in the web app).
246
+ | Web agent tool | CLI command | Notes |
247
+ | ------------------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
248
+ | `tools.writeTool` (superglue module; new id) | `sg tool build --config '{...}'` | CLI is not AI-powered — you provide the full JSON config |
249
+ | `tools.writeTool` (superglue; saved id) | `sg tool edit --tool <id> --patches '[...]'` | JSON Patch (RFC 6902). Use `--draft <id>` for drafts |
250
+ | `tools.runTool` | `sg tool run --tool <id>` / `--draft <id>` | Add `--include-step-results` to inspect per-step data |
251
+ | `run_command` with `vfs` for `/org/tools/` | `sg tool find --id <id>` / `sg tool find <q>` | Full config with `--id`, compact search with a query string |
252
+ | `tools.writeConnection` | `sg system connection set --system-id <id>` | Creates or updates your connection under its namespace |
253
+ | `run_command` with `vfs` for `/org/connections/` | `sg system find <query>` / `--id <id>` | Returns your connection's secret names, url, and auth type |
254
+ | `/org/connections/<id>.json` | `sg system connection list/get/set/clear` | Manage your connection; `--connection-id` targets a specific one |
255
+ | `tools.callSystem` | `sg system call --system-id <id> --url <url>` | Ad-hoc calls; connection and auth header are added server-side; `--connection-id` matches `credentialId` |
256
+ | `create_connection` | `sg system connection set` and `sg system oauth` | Saves configuration and secrets, then opens OAuth when needed |
257
+ | `run_command` with `vfs` for `/org/runs/` | `sg run list` / `sg run get <runId>` | Filter `list` by `--tool`, `--status`, `--source`, `--limit` |
258
+ | `run_command` with `vfs` for `/org/mcp-servers/` | `sg mcp list` / `sg mcp find --id <id>` | Returns endpoint, auth mode, selected tool IDs, and client config |
259
+ | `tools.writeMcpServer` (superglue module; new) | `sg mcp create --name <n> --tool <id>` | Creates a named MCP endpoint for selected saved tools |
260
+ | `tools.writeMcpServer` (superglue) | `sg mcp edit --id <id> ...` | Edits name, auth mode, description, or selected tool IDs |
261
+ | `tools.writeSchedule` (superglue module; new) | `sg schedule create --tool <id> --cron <expr>` | Creates a cron schedule for a saved tool |
262
+ | `tools.writeSchedule` (superglue; id) | `sg schedule edit --tool <id> --id <schedule>` | Updates, enables, or disables an existing schedule |
263
+ | `run_command` with `vfs` for `/projects/` | `sg project list` / `sg project task list` | Tasks are listed in board order with `position` |
264
+ | `tools.writeTask` (superglue module; no id) | `sg project task create --project <id>` | Same fields; `--position` places the task in its column |
265
+ | `tools.writeTask` (superglue module; id) | `sg project task edit --project <p> --id <t>` | Updates only the given fields, including `--position` |
266
+ | `tools.writeProjectLabel` (superglue module) | `sg project label create` / `label edit` | Same fields; `sg project label delete` has no module equivalent |
267
+ | (no direct equivalent) | `sg login`, `sg update`, `sg skill` | CLI-specific setup, updater, and this reference system |
268
+
269
+ Web-agent-only concepts with no CLI equivalent: `run_command`'s virtual filesystem (CLI uses concrete `sg` subcommands), `create_connection`'s secure input form (CLI accepts secrets through connection commands), and `setup_gateway` (the gateway install command is created in the web app).
264
270
 
265
271
  ### Command Reference
266
272
 
@@ -290,18 +296,17 @@ sg tool find --id my-tool --fields instruction,inputSchema # only selected top-
290
296
  **System commands:**
291
297
 
292
298
  ```bash
293
- sg system create --name "My API" --url https://api.example.com --credentials '{"api_key":"sk-xxx"}'
294
- sg system create --name "Slack" --template slack
295
- sg system edit --id my_api --credentials '{...}'
299
+ sg system connection set --system-id my_api --url https://api.example.com --credentials '{"api_key":"sk-xxx"}' --authentication '{"type":"api_key"}'
300
+ sg system connection set --system-id slack --credentials '{}' --authentication '{"type":"oauth2"}' # template id as system id
296
301
  sg system list
297
302
  sg system find slack
298
303
  sg system find --id my_api
299
- sg system credentials get --system-id my_api
300
- sg system credentials set --system-id my_api --credentials '{"api_key":"sk-xxx"}'
301
- sg system credentials clear --system-id my_api
304
+ sg system connection list --system-id my_api
305
+ sg system connection get --system-id my_api
306
+ sg system connection set --system-id my_api --credentials '{"api_key":"sk-xxx"}'
307
+ sg system connection clear --system-id my_api
302
308
  sg system call --system-id my_api --url "<<my_api_url>>/users"
303
309
  sg system call --system-id my_api --url https://api.example.com/users --headers '{"X-API-Key":"<<my_api_api_key>>"}'
304
- sg system search-docs --system-id slack -k "send message channels"
305
310
  sg system oauth --system-id gmail --scopes "https://www.googleapis.com/auth/gmail.modify"
306
311
  sg system oauth --system-id my_api --grant-type client_credentials --scopes "read write"
307
312
  ```
@@ -551,12 +556,12 @@ For each step in order:
551
556
 
552
557
  All user-provided JS runs in an isolated Deno sandbox.
553
558
 
554
- ### Credentials and Systems
559
+ ### Connections and placeholders
555
560
 
556
- Secrets are referenced by name as `<<systemId_credentialKey>>` and resolved from the selected credential at execution time. You MUST explicitly reference them:
561
+ Secrets are referenced by name as `<<systemId_credentialKey>>` and resolved from the selected connection at execution time. You MUST explicitly reference them:
557
562
 
558
563
  ```
559
- System id="stripe", selected credential has secret named: api_key
564
+ System id="stripe", selected connection has secret named: api_key
560
565
  → Available as: <<stripe_api_key>>
561
566
  ```
562
567
 
@@ -571,40 +576,36 @@ System id="stripe", selected credential has secret named: api_key
571
576
 
572
577
  Basic auth auto-encodes: if the value after `Basic ` isn't already base64, the engine encodes it.
573
578
 
574
- **System URL variables** — use these instead of hardcoding base URLs. They resolve the URL of the exact referenced system ID:
579
+ **Connection URL variables** — use these instead of hardcoding base URLs. They resolve the URL of the selected connection for the exact referenced system ID:
575
580
 
576
581
  ```json
577
582
  { "url": "<<salesforce_url>>/services/data/v58.0/sobjects/Account" }
578
583
  ```
579
584
 
580
- `<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Set an override with `sg system credentials set --system-id <id> --credentials '{...}' --url <url>` when each tenant has its own host; pass an empty string to clear it.
585
+ `<<systemId_url>>` resolves to the selected connection's `url`. Set it with `sg system connection set --system-id <id> --credentials '{...}' --url <url>` when each tenant has its own host; pass an empty string to clear it.
581
586
 
582
587
  **Credential lifecycle:**
583
588
 
584
589
  - Pass all secret values via `--credentials '{"api_key":"...","client_secret":"..."}'` on create/edit
585
- - Use `sg system credentials set --system-id <id> --credentials '{...}'` to save secrets in the current API-key user's credential
586
- - Use `sg system credentials get --system-id <id>` to inspect the current user's secret names and whether each has a non-empty value; secret values are never returned
590
+ - Use `sg system connection set --system-id <id> --credentials '{...}'` to save secrets on the current API-key user's connection
591
+ - Use `sg system connection get --system-id <id>` to inspect the current user's secret names and whether each has a non-empty value; secret values are never returned
587
592
  - OAuth tokens (`access_token`, `refresh_token`) auto-refresh before each step execution
588
593
  - Non-sensitive fields (`client_id`, `auth_url`, `token_url`) can be submitted alongside secrets in the same `--credentials` JSON
589
594
 
590
- **System IDs:** lowercase letters, numbers, underscores only — no hyphens. Used for credential namespacing.
595
+ **System IDs:** a system ID groups connections and resolves tool steps and placeholders. Use existing IDs exactly as written, including case; a tool can reference an ID that no connection uses yet, so create a connection with that exact ID. For a new ID, use the matching template's `id`, such as `hubspot`; otherwise use lowercase letters, digits, and underscores, such as `acme_billing`. The server saves IDs as sent and does not correct them. Do not rename a working system ID to match a template.
591
596
 
592
- **Templates:** auto-populate endpoints and OAuth config. `sg system find` lists available templates.
597
+ **Templates:** matched by system id (or connection url) and supply display and OAuth defaults. `sg system find --id <id>` shows the matched template.
593
598
 
594
599
  - **Preconfigured OAuth** (no user `client_id`/`client_secret` needed): slack, salesforce, asana, notion, airtable, jira, confluence
595
600
  - **Common OAuth templates:** gmail, googleDrive, googleCalendar, googleSheets, slack, salesforce, github, jira, confluence, notion, airtable, hubspot, shopify, dropbox, zoom, microsoft
596
601
 
597
- **Custom OAuth (no template):** must include `client_id`, `client_secret`, `auth_url`, `token_url` in credentials at create time — or add later with `sg system edit`:
602
+ **Custom OAuth (no template):** put the client config on your connection's authentication:
598
603
 
599
604
  ```bash
600
- sg system create --name "My API" --url https://api.example.com \
601
- --credentials '{"client_id":"...","client_secret":"...","auth_url":"https://example.com/oauth/authorize","token_url":"https://example.com/oauth/token"}'
605
+ sg system connection set --system-id my_api --url https://api.example.com --credentials '{}' \
606
+ --authentication '{"type":"oauth2","clientId":"...","clientSecret":"...","authUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token"}'
602
607
  ```
603
608
 
604
- **Tags:** do not add tags by default. Add tags only when the user explicitly requests them or when existing systems show a clear tag or grouping convention that applies. Reuse exact existing tag values; do not invent new tags. Tags are metadata only. Tools and credentials always reference the exact system ID.
605
-
606
- **System-specific instructions:** systems may include `specificInstructions` from the user (visible in `sg system find` output). Follow them when present — they override general patterns.
607
-
608
609
  ### Tool Editing (JSON Patch)
609
610
 
610
611
  `sg tool edit` applies RFC 6902 JSON Patch operations. Each operation:
@@ -672,13 +673,13 @@ curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API
672
673
 
673
674
  ## Common Pitfalls
674
675
 
675
- - **Guessing API endpoints** — always verify with `sg system search-docs` or `sg system call` first
676
+ - **Guessing API endpoints** — verify against provider documentation, then check uncertain request shapes with `sg system call`
676
677
  - **`systemId` in the wrong place** — it belongs inside `step.config.systemId`, not on the step object
677
678
  - **`<<(sourceData) => sourceData.payload.X>>`** — payload fields are at root level of `sourceData`, not under `.payload`
678
679
  - **`<<currentItem.id>>`** — must use arrow function syntax: `<<(sourceData) => sourceData.currentItem.id>>`
679
680
  - **Hardcoded pagination params** — use `<<page>>`, `<<offset>>`, `<<cursor>>`, `<<limit>>`
680
- - **Missing auth headers** — credentials are never automatically included in any protocol, including for OAuth systems (only token refresh is automatic)
681
- - **Hardcoded base URLs** — prefer system URL variables (`<<systemId_url>>`) so tools follow the referenced system's configured URL
681
+ - **Missing auth headers** — credentials are never automatically included in any protocol, including for OAuth connections (only token refresh is automatic)
682
+ - **Hardcoded base URLs** — prefer connection URL variables (`<<systemId_url>>`) so tools follow the selected connection's URL
682
683
  - **Empty `instruction`** — never leave the tool-level `instruction` blank
683
684
  - **Adding `outputSchema` unsolicited** — only add when the user explicitly requests a specific response structure
684
685
  - **Multi-line `outputTransform`** — must be a single-line JS string (no literal newlines or tabs)
@@ -706,7 +707,7 @@ For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, MongoDB, Gra
706
707
  3. Use `sg system find --id <systemId>` to verify the stored secret names match what the step references
707
708
  4. For HTTP: run `sg skill http` and follow the error recovery section (endpoint vs system isolation, credential scopes, rate limiting)
708
709
  5. For databases: run `sg skill postgres` or `sg skill mssql` — SSL/TLS and schema issues are common causes
709
- 6. Use `sg system search-docs` and web search to verify the current API shape. APIs change across versions
710
+ 6. Consult provider documentation and web search to verify the current API shape. APIs change across versions
710
711
 
711
712
  ### Authentication failures
712
713
 
@@ -715,11 +716,11 @@ For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, MongoDB, Gra
715
716
  3. For custom OAuth: verify `client_id`, `client_secret`, `auth_url`, `token_url` are all present. Confirm the redirect URI is registered on the provider's OAuth app
716
717
  4. Check scopes — 403 / empty responses often mean the token lacks required scopes
717
718
 
718
- ### System creation fails
719
+ ### Connection save fails
719
720
 
720
- 1. Check for an existing system with the same ID — use `sg system edit` to update instead
721
- 2. Ensure `id` uses only lowercase letters, numbers, and underscores (no hyphens)
722
- 3. For templated systems, verify the template ID is correct (`sg system find` lists available templates)
721
+ 1. Check for an existing connection under the id with `sg system connection get --system-id <id>`; `set` updates it in place
722
+ 2. Ensure the id uses only lowercase letters, numbers, underscores, and hyphens
723
+ 3. For templated systems, use the template id as the system id so the template applies
723
724
 
724
725
  ### Data selector / transform returns wrong data
725
726
 
package/skills/superglue/references/access-rules.md CHANGED
@@ -1,13 +1,13 @@
1
1
  # Access Rules (RBAC)
2
2
 
3
- On superglue, roles define active resource grants for tools and systems. Users can have multiple roles. Roles and access rules are only available on enterprise organizations.
3
+ On superglue, roles define active resource grants for tools, credentials, playbooks, artifacts, files, and projects. Systems are not a resource: a system id is a plain string on connections and tool steps. Users can have multiple roles. Roles and access rules are only available on enterprise organizations.
4
4
 
5
5
  ## Data Model
6
6
 
7
7
  ```typescript
8
8
  interface ResourceGrant {
9
9
  roleId: string;
10
- resourceRef: "tool:<encodedId>" | "system:<encodedId>" | "tool:*" | "system:*";
10
+ resourceRef: "<kind>:<encodedId>" | "<kind>:*"; // kind: tool | credential | playbook | artifact | file | project
11
11
  permissions: Array<"viewer" | "editor">;
12
12
  source: "access_rule" | "ownership" | "share";
13
13
  grantedByUserId?: string;
@@ -28,10 +28,8 @@ Only active grants where `revokedAt` is empty contribute to access. `editor` imp
28
28
 
29
29
  ## Resource Refs
30
30
 
31
- - `tool:<encodedToolId>` — one specific tool.
32
- - `system:<encodedSystemId>` — one specific system.
33
- - `tool:*` — every current and future tool.
34
- - `system:*` — every current and future system.
31
+ - `<kind>:<encodedId>` — one specific resource, for example `tool:<toolId>` or `credential:<connectionId>`.
32
+ - `<kind>:*` — every current and future resource of that kind.
35
33
 
36
34
  Resource ids are URL-encoded inside `resourceRef`; use shared helpers rather than hand-building refs.
37
35
 
@@ -48,26 +46,25 @@ Current configured role access and ownership grants are generally stored as `edi
48
46
  - `ownership` — authorization projection from the resource creator.
49
47
  - `share` — explicit sharing with an organization user or role.
50
48
 
51
- Ownership source of truth remains the tool/system row. Ownership grants are a permission projection and should be preserved by ordinary role edits.
49
+ Ownership source of truth remains the resource row. Ownership grants are a permission projection and should be preserved by ordinary role edits.
52
50
 
53
51
  ## Visibility and Execution Surfaces
54
52
 
55
53
  - **Tools** — list/detail, agent views, VFS, REST detail, and tool history use tool `viewer`.
56
- - **Systems** — list/detail, agent views, VFS, docs, credentials, and `sg system call` use system `viewer`.
57
- - **Execution** — running a tool requires tool `viewer` plus system `viewer` for every referenced system.
58
- - **Editing** — updating tools/systems requires `editor`.
59
- - **Runs** — visible only when the user has tool `viewer` and system `viewer` for every captured system.
54
+ - **Connections** — usable with credential `viewer`; changing secrets, name, url, auth, or tunnel requires credential `editor`. System IDs and system knowledge are metadata, not access-controlled resources. `sg system call` needs an accessible connection only when the request uses secrets or the connection url.
55
+ - **Execution** — running a tool requires tool `viewer` plus an accessible connection for every referenced system id: an explicit credentials id, the user's starred default, or their longest-held accessible connection.
56
+ - **Editing** — updating a tool requires tool `editor`.
57
+ - **Runs** — visible with tool `viewer`, limited to the member's own runs when the organization setting "members see only own runs" is on (the default). Admins see all runs.
60
58
  - **Schedules** — visibility follows current tool behavior; editing requires tool `editor`.
61
- - **MCP** — config shows configured tools; runtime registration uses tool `viewer`, and execution still checks referenced systems.
59
+ - **MCP** — config shows configured tools; runtime registration uses tool `viewer`, and execution still needs a connection for every referenced system id.
62
60
 
63
61
  ## Multi-Role Semantics
64
62
 
65
63
  Users can have multiple roles. Resolution is union:
66
64
 
67
- | Layer | Semantics |
68
- | ------- | -------------------------------------------------------------------------- |
69
- | Tools | If any active grant targets a tool, that grant's permission is effective |
70
- | Systems | If any active grant targets a system, that grant's permission is effective |
65
+ | Layer | Semantics |
66
+ | ------------ | ------------------------------------------------------------------------------ |
67
+ | Any resource | If any active grant targets the resource, that grant's permission is effective |
71
68
 
72
69
  Assigned roles can add access but cannot remove access granted by another role.
73
70
 
@@ -76,7 +73,7 @@ Assigned roles can add access but cannot remove access granted by another role.
76
73
  Every user has exactly one base role:
77
74
 
78
75
  - **`admin`** — built-in editor access to resources except credentials. Credentials require ownership or explicit grants. New organizations give admins no credential wildcard. Credential grants are editable. Name and description cannot be changed. Cannot be deleted.
79
- - **`member`** — default for org team members. New organizations seed it with wildcard `editor` grants for tools and systems. Access-rule grants can be narrowed. Name and description cannot be changed. Cannot be deleted.
76
+ - **`member`** — default for org team members. New organizations seed it with a wildcard `editor` grant for tools. Access-rule grants can be narrowed. Name and description cannot be changed. Cannot be deleted.
80
77
  - **`service_account`** — API-only users that admins create through `/v1/service-accounts`. Starts with no grants; only its grants are editable. Users cannot be switched to or from it. Service accounts can run granted tools and manage their own credential sets, but cannot log in, use MCP, or read runs.
81
78
 
82
79
  Users can also have additional custom roles on top of their base role. Custom roles are fully editable and can be created/deleted.
@@ -86,31 +83,29 @@ Users can also have additional custom roles on top of their base role. Custom ro
86
83
  Personal roles are per-user containers for ownership and user-targeted share grants.
87
84
 
88
85
  - Each user can have at most one personal role.
89
- - Ownership grants are added automatically when a user creates a tool or system.
86
+ - Ownership grants are added automatically when a user creates a tool, connection, playbook, artifact, file, or project.
90
87
  - Personal role grants are unioned with the user's other roles.
91
88
  - Ordinary role edits preserve personal roles and their ownership/share grants.
92
89
 
93
90
  ## Sharing Semantics
94
91
 
95
- Sharing supports saved tools, systems, credentials, projects, playbooks, artifacts, and files.
92
+ Sharing supports saved tools, connections, projects, playbooks, artifacts, and files.
96
93
 
97
94
  - Targets are organization users or roles. The admin role and personal roles cannot be role targets.
98
95
  - User-targeted shares live on personal roles; role-targeted shares live on the selected role.
99
96
  - Sharing requires resource `editor` access. Direct shares grant `viewer` or `editor` through `source: "share"`.
100
97
  - Editors can update or remove direct shares. Removing one preserves ownership, access-rule grants, and access from other roles.
101
- - Credential sharing and revocation require the credential owner or an admin, even when another user has credential `editor`.
102
- - Recipients can remove their own direct share, including credential shares, without editor access.
103
- - Tool sharing grants missing system `viewer` access when the actor can pass it on. Otherwise, nothing is shared.
104
- - Tool sharing does not share credentials. Credential sharing also grants missing viewer access to its owning system.
105
- - Removing a tool or credential share does not remove the required-system shares it created.
106
- - Sharing systems or playbooks does not cascade to their tools, systems, or credentials.
98
+ - Connection sharing and revocation require the connection owner or an admin, even when another user has connection `editor`.
99
+ - Recipients can remove their own direct share, including connection shares, without editor access.
100
+ - Sharing a tool shares only the tool. The recipient still needs a connection for every system id it references.
101
+ - Sharing playbooks does not cascade to their tools or connections.
107
102
  - Project sharing can include manageable current members when requested. It does not share future members or revoke member shares later.
108
103
 
109
104
  ## Auto-Grant On Resource Creation
110
105
 
111
- When a user creates a new tool or system, the backend automatically grants ownership access to the creator's personal role:
106
+ When a user creates a new resource, the backend automatically grants ownership access to the creator's personal role:
112
107
 
113
108
  - New tool created -> `ownership` grant on `tool:<toolId>` with `editor`.
114
- - New system created -> `ownership` grant on `system:<systemId>` with `editor`.
109
+ - New connection created -> `ownership` grant on `credential:<connectionId>` with `editor`.
115
110
 
116
111
  This only affects the creator's personal role, not base roles or additional custom roles.
package/skills/superglue/references/graphql.md CHANGED
@@ -96,11 +96,7 @@ Note the `cursorPath` and `stopCondition` must account for the GraphQL `data` wr
96
96
 
97
97
  ### Schema Discovery
98
98
 
99
- Superglue automatically introspects GraphQL schemas during documentation fetching. When a system URL contains "graphql", introspection is the first strategy tried — the full schema is fetched and stored as system documentation.
100
-
101
- Use `sg system search-docs` to query the stored schema for types, fields, and arguments before building tools. This is more reliable than manual introspection and works even when the API has introspection disabled for external callers.
102
-
103
- If the schema is not available via `sg system search-docs` (e.g. the system was created without a GraphQL URL, or introspection was blocked), test manually with `sg system call`:
99
+ Use saved schemas or provider documentation when available. When the schema is unknown, probe the endpoint with `sg system call`:
104
100
 
105
101
  ```json
106
102
  { "query": "{ __typename }" }
@@ -126,6 +122,6 @@ When a GraphQL step fails:
126
122
 
127
123
  1. **Check GraphQL-level errors** — even 200 responses can contain `errors` in the response body. Check `sourceData.stepId.data.errors` for field-level or validation errors.
128
124
  2. **Verify the endpoint works** — use `sg system call` with `{ "query": "{ __typename }" }` to confirm connectivity and auth before debugging the query itself.
129
- 3. **Check schema compatibility** — fields, types, and arguments change between API versions. Use `sg system search-docs` to check the auto-introspected schema first. If unavailable, use targeted `__type` queries or web search to verify the current schema.
125
+ 3. **Check schema compatibility** — fields, types, and arguments change between API versions. Check saved schemas, provider documentation, or targeted `__type` queries against the current API version.
130
126
  4. **Verify variables match the query signature** — GraphQL type mismatches (e.g. passing a string where `ID!` is expected) cause validation errors. Check that variable types in the query match what you're passing.
131
127
  5. **Check for auth scope issues** — some GraphQL APIs return partial data with `null` fields and errors when the token lacks required scopes for specific fields.
package/skills/superglue/references/http.md CHANGED
@@ -259,7 +259,7 @@ When an HTTP step downloads a file (PDF, CSV, binary response), set `outputFile:
259
259
  ## Common Pitfalls
260
260
 
261
261
  - Hardcoding base URLs instead of using `<<systemId_url>>`.
262
- - Wrong slash at the `<<systemId_url>>` join. The placeholder resolves to the selected credential's `url` override when set, else the system's `url`, exactly as stored — it may or may not end in `/`. Read the `url` shown by `sg system find` and write the path so there is exactly one `/` between base and path: against a base with no trailing slash, `<<systemId_url>>crm/v3/...` becomes a broken host (`https://api.hubapi.comcrm/...`) that silently hits the wrong server; against a base ending in `/`, a leading `/` produces `//`.
262
+ - Wrong slash at the `<<systemId_url>>` join. The placeholder resolves to the selected connection's `url`, exactly as stored — it may or may not end in `/`. Read `url` from `sg system connection get --system-id <systemId>` and write the path so there is exactly one `/` between base and path: against a base with no trailing slash, `<<systemId_url>>crm/v3/...` becomes a broken host (`https://api.hubapi.comcrm/...`) that silently hits the wrong server; against a base ending in `/`, a leading `/` produces `//`.
263
263
  - Forgetting auth headers entirely — nothing is injected automatically, including for OAuth systems (only token refresh is automatic)
264
264
  - Forgetting `outputFile: true` on steps that download files the user wants
265
265
  - Putting pagination variables in the config but not setting a `pagination` block, or vice versa
@@ -273,8 +273,8 @@ When an HTTP step fails and the cause is not immediately clear:
273
273
 
274
274
  1. **Isolate endpoint vs system-level issues** — use `sg system call` to test a different endpoint on the same system. If multiple endpoints fail, the issue is likely global authentication or system configuration. If only one fails, the issue is endpoint-specific (wrong URL, missing params, incorrect method or authentication scopes).
275
275
 
276
- 2. **Check credential scopes and system-side configuration** — a 403 or empty response often means the API key or OAuth token lacks required scopes, or the resource is restricted server-side. Use `sg system search-docs` or a web search to look up required scopes/permissions for the endpoint.
276
+ 2. **Check credential scopes and system-side configuration** — a 403 or empty response often means the API key or OAuth token lacks required scopes, or the resource is restricted server-side. Consult provider documentation or web search for the endpoint’s required scopes and permissions.
277
277
 
278
- 3. **Verify request shape against API docs** — use `sg system search-docs` and web search to confirm the endpoint URL, required headers, query parameters, body format, and expected method. APIs change across versions. Search for the error message and the endpoint in docs and online.
278
+ 3. **Verify request shape against API docs** — consult provider documentation and web search to confirm the endpoint URL, required headers, query parameters, body format, and expected method. APIs change across versions. Search for the error message and the endpoint in docs and online.
279
279
 
280
280
  4. **Check for rate limiting** — 429 errors are retried automatically with backoff, but persistent 429s may mean the API key has hit a quota. Check API dashboard or docs for rate limit details.
package/skills/superglue/references/mongodb.md CHANGED
@@ -13,7 +13,7 @@
13
13
 
14
14
  Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
15
15
 
16
- `<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
16
+ `<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
17
17
 
18
18
  `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for MongoDB steps.
19
19
 
package/skills/superglue/references/mssql.md CHANGED
@@ -13,9 +13,9 @@
13
13
  }
14
14
  ```
15
15
 
16
- Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
16
+ Configure the connection URL based on the selected connection's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
17
17
 
18
- `<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
18
+ `<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
19
19
 
20
20
  `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
21
21
 
@@ -95,7 +95,7 @@ mssql://<<my_db_user>>:<<my_db_password>>@<<my_db_host>>:<<my_db_port>>/<<my_db_
95
95
 
96
96
  ### Windows Authentication (NTLM)
97
97
 
98
- For on-prem SQL Servers that only accept Windows domain logins (no SQL auth), add secrets with these names to the credential:
98
+ For on-prem SQL Servers that only accept Windows domain logins (no SQL auth), add secrets with these names to the connection:
99
99
 
100
100
  | Secret Name | Required | Notes |
101
101
  | ----------- | -------- | ----------------------------------------------------- |
@@ -113,7 +113,7 @@ Alternatively, pass the domain as a `?domain=CORP` query parameter on the URL
113
113
 
114
114
  ### Azure Active Directory Authentication
115
115
 
116
- For Azure AD auth, add secrets with the following names to the credential alongside the standard connection fields:
116
+ For Azure AD auth, add secrets with the following names to the connection alongside the standard connection fields:
117
117
 
118
118
  **Entra ID User + Password** — authenticates as an Azure AD user. Requires an Azure app registration.
119
119
 
package/skills/superglue/references/odbc.md CHANGED
@@ -13,7 +13,7 @@
13
13
 
14
14
  Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
15
15
 
16
- `<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
16
+ `<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
17
17
 
18
18
  `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
19
19
 
package/skills/superglue/references/postgres.md CHANGED
@@ -13,7 +13,7 @@
13
13
 
14
14
  Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
15
15
 
16
- `<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
16
+ `<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
17
17
 
18
18
  `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
19
19
 
package/skills/superglue/references/redis.md CHANGED
@@ -13,7 +13,7 @@
13
13
 
14
14
  Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
15
15
 
16
- `<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
16
+ `<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
17
17
 
18
18
  `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for Redis steps.
19
19