superglue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

superglue CLI (

sg

) — Agent Reference

superglue CLI（

sg

）—— Agent参考文档

CRITICAL RULES — READ FIRST

重要规则 — 请先阅读

Pre-requisites for using the CLI

Check CLI exists: Run

sg --version

. If it fails with

command not found

, install it:

npm install -g @superglue/cli

Check superglue CLI config exists: Run
```
sg system list
```
. If it fails with
```
fetch failed
```
or auth errors, the CLI needs configuration via
```
sg init
```
(see below).

Calling systems and running tools

ALWAYS make sure you pull the relevant system context using
```
sg system find
```
before calling system endpoints and running inline JSON tools or building new tools.
Use
```
sg system search-docs
```
to do a targeted keyword search of system docs if you're unsure about how a system works.

Authentication & Credentials:

Auth headers MUST be set explicitly — credentials are NEVER auto-injected into requests or tool steps
Every request step (in tools AND
```
sg system call
```
) must include the appropriate auth header using
```
<<systemId_credentialKey>>
```
syntax
OAuth systems also require explicit headers — only token refresh is automatic

Saving Tools:

Don't save a tool without explicit user confirmation — always ask "Should I save this tool?" first
After
```
sg tool build
```
+
```
sg tool run
```
, present results to the user and wait for approval
Only run
```
sg tool save --draft <id>
```
after the user explicitly confirms

Credentials in Non-Interactive Environments (AI Agents, CI):

Pass ALL credentials (including secrets) directly via
--credentials
JSON — do NOT use
```
--sensitive-credentials
```
(it requires an interactive TTY which agents don't have)
Ask the user to provide secret values, then pass them in
```
--credentials '{"api_key":"sk-xxx"}'
```

使用CLI的前提条件

检查CLI是否存在：运行
```
sg --version
```
。如果提示
```
command not found
```
，则进行安装：
```
npm install -g @superglue/cli
```
检查superglue CLI配置是否存在：运行
```
sg system list
```
。如果提示
```
fetch failed
```
或认证错误，则需要通过
```
sg init
```
配置CLI（见下文）。

调用系统与运行工具

在调用系统端点、运行内联JSON工具或构建新工具之前，务必使用
```
sg system find
```
获取相关系统上下文。
如果你不确定系统的工作方式，请使用
```
sg system search-docs
```
对系统文档进行针对性关键词搜索。

认证与凭证：

必须显式设置认证头 — 凭证绝不会自动注入到请求或工具步骤中
每个请求步骤（工具和
```
sg system call
```
中）都必须使用
```
<<systemId_credentialKey>>
```
语法包含适当的认证头
OAuth系统也需要显式设置头 — 仅令牌刷新是自动的

保存工具：

未经用户明确确认，请勿保存工具 — 务必先询问“是否需要我保存此工具？”
在执行
```
sg tool build
```
+
```
sg tool run
```
后，将结果呈现给用户并等待批准
仅在用户明确确认后，再运行
```
sg tool save --draft <id>
```

非交互式环境中的凭证（AI Agent、CI）：

通过
--credentials
JSON直接传递所有凭证（包括密钥） — 请勿使用
```
--sensitive-credentials
```
（它需要交互式TTY，而Agent不具备此环境）
请用户提供密钥值，然后通过
```
--credentials '{"api_key":"sk-xxx"}'
```
传递

Installation & Setup

安装与设置

Installing the CLI

安装CLI

bash

npm install -g @superglue/cli

After installation, the

sg

command is available globally.

bash

npm install -g @superglue/cli

安装完成后，

sg

命令将在全局可用。

Initialization (REQUIRED before first use)

初始化（首次使用前必须完成）

The CLI will not work until configured with an API key. The endpoint defaults to

https://api.superglue.cloud

if not specified.

Option A: Interactive setup (recommended for humans)

bash

sg init

This prompts for:

API Key (required) — get one at https://app.superglue.cloud/admin?view=api-keys
API Endpoint — defaults to
```
https://api.superglue.cloud
```
Web Endpoint — for OAuth callbacks, auto-derived from API endpoint
Output mode —
```
stdout
```
(default) or
```
stdout+file
```
Config location — project-local (
```
.superglue/config.json
```
) or global (
```
~/.superglue/config.json
```
)

It verifies the connection before saving. On success it creates the config file, a

drafts/

directory, and updates

.gitignore

if using local config.

Option B: Environment variables (recommended for CI and AI agents)

sg init

is not practical (non-interactive environments, CI, AI agents), set these env vars instead:

bash

export SUPERGLUE_API_KEY="your-api-key"
export SUPERGLUE_API_ENDPOINT="https://api.superglue.cloud"  # optional, this is the default

With these set, all

sg

commands work without a config file.

Option C: CLI flags (per-command override)

bash

sg system list --api-key "your-key" --endpoint "https://api.superglue.cloud"

在配置API密钥之前，CLI无法正常工作。如果未指定端点，默认值为

https://api.superglue.cloud

。

选项A：交互式设置（推荐人类用户使用）

bash

sg init

此命令会提示你输入：

API密钥（必填） — 可在https://app.superglue.cloud/admin?view=api-keys获取
API端点 — 默认值为
```
https://api.superglue.cloud
```
Web端点 — 用于OAuth回调，从API端点自动派生
输出模式 —
```
stdout
```
（默认）或
```
stdout+file
```
配置位置 — 项目本地（
```
.superglue/config.json
```
）或全局（
```
~/.superglue/config.json
```
）

在保存配置之前，它会验证连接是否正常。成功后，将创建配置文件、

drafts/

目录，如果使用本地配置，还会更新

.gitignore

。

选项B：环境变量（推荐CI和AI Agent使用）

如果

sg init

不可行（非交互式环境、CI、AI Agent），则设置以下环境变量：

bash

export SUPERGLUE_API_KEY="your-api-key"
export SUPERGLUE_API_ENDPOINT="https://api.superglue.cloud"  # 可选，此为默认值

设置完成后，所有

sg

命令无需配置文件即可正常工作。

选项C：CLI标志（按命令覆盖配置）

bash

sg system list --api-key "your-key" --endpoint "https://api.superglue.cloud"

Config Resolution Order

配置解析顺序

CLI flags > environment variables > config file (local

.superglue/config.json

> global

~/.superglue/config.json

CLI标志 > 环境变量 > 配置文件（本地

.superglue/config.json

> 全局

~/.superglue/config.json

）。

Verifying Setup

验证设置

After configuring, verify the connection works:

bash

sg system list    # should return a list (possibly empty) without errors

配置完成后，验证连接是否正常：

bash

sg system list    # 应返回列表（可能为空）且无错误

Quick Start

快速开始

bash

sg system list
sg tool build --config '{"id":"...","instruction":"...","steps":[...]}'
sg tool run --draft <draftId>
sg tool save --draft <draftId>

bash

sg system list
sg tool build --config '{"id":"...","instruction":"...","steps":[...]}'
sg tool run --draft <draftId>
sg tool save --draft <draftId>

Global Flags

全局标志

Flag	Description
`--json`	Force JSON output (auto-enabled in non-TTY)
`--api-key <key>`	Override API key
`--endpoint <url>`	Override API endpoint

标志	描述
`--json`	强制输出JSON格式（在非TTY环境下自动启用）
`--api-key <key>`	覆盖API密钥
`--endpoint <url>`	覆盖API端点

Command Reference

命令参考

sg init

sg init

Interactive setup — API key, endpoint, output mode. Creates

.superglue/

交互式设置 — API密钥、端点、输出模式。创建

.superglue/

目录。

Tool Commands

工具命令

sg tool build
— Register a tool config. Returns a

draftId

. Not AI-powered — you provide the full config.

bash

sg tool build --config '{"id":"...","steps":[...]}'  # inline JSON
sg tool build --id my-tool --instruction "..." --steps steps.json --payload '{"key":"val"}'
sg tool build --config tool.json                    # from file

--config <file-or-json>

| Full JSON config (file path or inline JSON string) | |

--id <id>

| Tool ID (kebab-case) | |

--instruction <text>

| Human-readable description | |

--steps <file>

| JSON file with steps array | |

--payload <json>

| Sample payload | |

--file <key=path>

| Attach file reference |

sg tool run
— Execute a draft or saved tool. Streams live execution logs to the terminal.

bash

sg tool run --draft <draftId> --payload '{"userId":"123"}'
sg tool run --tool my-tool --payload-file payload.json

--draft <id>

--tool <id>

| Draft ID or saved tool ID | |

--payload <json>

--payload-file <path>

| Payload | |

--include-step-results

| Include raw step results | |

--include-config

| Include full tool config |

sg tool edit
— Apply JSON Patch (RFC 6902) operations.

bash

sg tool edit --draft <draftId> --patches '[{"op":"replace","path":"/steps/0/config/url","value":"..."}]'
sg tool edit --tool my-tool --patches patches.json

--patches <json-or-file>

| JSON Patch array (inline or file) |

sg tool save
— Persist draft to database. Deletes draft file on success.

bash

sg tool save --draft <draftId>

sg tool list
/
sg tool find

bash

sg tool list                    # all non-archived tools
sg tool find "shopify orders"   # search (compact results)
sg tool find --id my-tool       # exact ID lookup (full config)

sg tool build
— 注册工具配置。返回

draftId

。非AI驱动 — 你需要提供完整配置。

bash

sg tool build --config '{"id":"...","steps":[...]}'  # 内联JSON
sg tool build --id my-tool --instruction "..." --steps steps.json --payload '{"key":"val"}'
sg tool build --config tool.json                    # 从文件加载

--config <file-or-json>

| 完整JSON配置（文件路径或内联JSON字符串） | |

--id <id>

| 工具ID（短横线命名格式） | |

--instruction <text>

| 人类可读的描述 | |

--steps <file>

| 包含步骤数组的JSON文件 | |

--payload <json>

| 示例负载 | |

--file <key=path>

| 附加文件引用 |

sg tool run
— 执行草稿或已保存的工具。将实时执行日志流式传输到终端。

bash

sg tool run --draft <draftId> --payload '{"userId":"123"}'
sg tool run --tool my-tool --payload-file payload.json

--draft <id>

--tool <id>

| 草稿ID或已保存的工具ID | |

--payload <json>

--payload-file <path>

| 负载 | |

--include-step-results

| 包含原始步骤结果 | |

--include-config

| 包含完整工具配置 |

sg tool edit
— 应用JSON Patch（RFC 6902）操作。

bash

sg tool edit --draft <draftId> --patches '[{"op":"replace","path":"/steps/0/config/url","value":"..."}]'
sg tool edit --tool my-tool --patches patches.json

--patches <json-or-file>

| JSON Patch数组（内联或文件） |

sg tool save
— 将草稿持久化到数据库。成功后删除草稿文件。

bash

sg tool save --draft <draftId>

sg tool list
/
sg tool find

bash

sg tool list                    # 所有未归档的工具
sg tool find "shopify orders"   # 搜索（精简结果）
sg tool find --id my-tool       # 精确ID查找（完整配置）

System Commands

系统命令

sg system create

Required flags:

```
--name <name>
```
— Human-readable display name
```
--url <url>
```
— API base URL (auto-filled when using
```
--template
```
)

Optional:

```
--id <id>
```
— System ID (lowercase, underscores only, no hyphens). Derived from
```
--name
```
if omitted.
```
--template <id>
```
— Pre-configured template (auto-fills name and url if not provided)

Example with credentials (non-interactive — use this in AI agent / CI contexts):

bash

sg system create --name "My API" --url https://api.example.com \
  --credentials '{"api_key":"sk-xxx"}'

With template:

bash

sg system create --name "Slack" --template slack

Full flag reference:

Flag	Description
`--name <name>`	Human-readable name — REQUIRED
`--id <id>`	System ID (lowercase, underscores only) — derived from name if omitted
`--url <url>`	API base URL — REQUIRED (auto-filled by `--template` )
`--template <id>`	Template ID (stripe, shopify, slack, etc.)
`--credentials <json>`	Credentials JSON (use for ALL creds in non-interactive mode)
`--sensitive-credentials <fields>`	Comma-separated fields for masked input (TTY only — do NOT use in AI agents)
`--docs-url <url>`	Documentation URL to scrape
`--openapi-url <url>`	OpenAPI spec URL
`--env <environment>`	Environment: `dev` or `prod` (default: prod)

sg system edit
— Update system config or credentials. Supports

--env dev|prod

. sg system list
/
sg system find
— List or search systems.

find

supports

--env dev|prod

sg system call
— CRITICAL for tool building. Make authenticated calls to APIs, databases, and file servers. Use this to:

Explore API endpoints and response structures
Verify field names and data shapes BEFORE building tools

bash

undefined

sg system create

必填标志：

```
--name <name>
```
— 人类可读的显示名称
```
--url <url>
```
— API基础URL（使用
```
--template
```
时自动填充）

可选标志：

```
--id <id>
```
— 系统ID（仅小写字母和下划线，无短横线）。如果省略，将从
```
--name
```
派生。
```
--template <id>
```
— 预配置模板（自动填充名称和URL，如果未提供）

带凭证的示例（非交互式 — AI Agent/CI环境使用）：

bash

sg system create --name "My API" --url https://api.example.com \
  --credentials '{"api_key":"sk-xxx"}'

使用模板的示例：

bash

sg system create --name "Slack" --template slack

完整标志参考：

标志	描述
`--name <name>`	人类可读名称 — 必填
`--id <id>`	系统ID（仅小写字母和下划线） — 如果省略，将从名称派生
`--url <url>`	API基础URL — 必填（使用 `--template` 时自动填充）
`--template <id>`	模板ID（stripe、shopify、slack等）
`--credentials <json>`	凭证JSON（非交互式模式下用于所有凭证）
`--sensitive-credentials <fields>`	逗号分隔的掩码输入字段（仅TTY环境可用 — 请勿在AI Agent中使用）
`--docs-url <url>`	要抓取的文档URL
`--openapi-url <url>`	OpenAPI规范URL
`--env <environment>`	环境： `dev` 或 `prod` （默认：prod）

sg system edit
— 更新系统配置或凭证。支持

--env dev|prod

。 sg system list
/
sg system find
— 列出或搜索系统。

find

支持

--env dev|prod

。

sg system call
— 工具构建的关键命令。对API、数据库和文件服务器进行认证调用。可用于：

探索API端点和响应结构
在构建工具之前验证字段名称和数据格式

bash

undefined

POST request with auth and body

带认证和请求体的POST请求

sg system call --url https://api.example.com/users
--system-id my_api
--method POST
--headers '{"Authorization":"Bearer <<my_api_access_token>>"}'
--body '{"name":"test"}'

Database query (Postgres)

数据库查询（Postgres）

sg system call --url "postgres://<<my_db_host>>:5432/mydb"
--system-id my_db
--body '{"query":"SELECT * FROM users LIMIT 5"}'

File server (SFTP)

文件服务器（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)                              |

**`sg system search-docs`** — Search system documentation.

```bash
sg system search-docs --system-id slack -k "send message channels"

sg system oauth
— Authenticate via OAuth.

bash

sg system oauth --system-id gmail --scopes "https://www.googleapis.com/auth/gmail.readonly"
sg system oauth --system-id my_api --grant-type client_credentials --scopes "read write"

--system-id <id>

| Required | |

--scopes <scopes>

| Space-separated OAuth scopes (required) | |

--grant-type <type>

authorization_code

(default) or

client_credentials

sg system call --url "sftp://<<my_sftp_host>>:22/data"
--system-id my_sftp
--body '{"operation":"list","path":"/"}'


| 标志                | 描述                                               |
| ------------------- | -------------------------------------------------- |
| `--url <url>`       | 带协议的完整URL（http/https/postgres/sftp/ftp/smb） |
| `--system-id <id>`  | 用于凭证注入的系统ID                                |
| `--method <method>` | HTTP方法（GET、POST、PUT、DELETE、PATCH）           |
| `--headers <json>`  | 带凭证占位符的HTTP头JSON                            |
| `--body <string>`   | 请求体（JSON字符串）                                |
| `--env <env>`       | 环境：`dev`或`prod`                                 |
| `--file <key=path>` | 文件引用（可重复使用）                              |

**`sg system search-docs`** — 搜索系统文档。

```bash
sg system search-docs --system-id slack -k "send message channels"

sg system oauth
— 通过OAuth进行认证。

bash

sg system oauth --system-id gmail --scopes "https://www.googleapis.com/auth/gmail.readonly"
sg system oauth --system-id my_api --grant-type client_credentials --scopes "read write"

--system-id <id>

| 必填 | |

--scopes <scopes>

| 空格分隔的OAuth权限范围（必填） | |

--grant-type <type>

authorization_code

（默认）或

client_credentials

Run Commands

运行命令

sg run list
— List execution runs. Filter by

--tool

--status

--source

--limit

. sg run get <runId>
— Get run details.

--fetch-results

to include data.

sg run list
— 列出执行运行记录。可通过

--tool

、

--status

、

--source

、

--limit

进行筛选。 sg run get <runId>
— 获取运行详情。使用

--fetch-results

包含数据。

Tool Configuration — Full Schema

工具配置 — 完整 Schema

json

{
  "id": "kebab-case-tool-name",
  "instruction": "Brief human-readable description of what this tool does",
  "steps": [
    {
      "id": "unique-step-id",
      "config": {
        "systemId": "example_system",
        "url": "https://api.example.com/endpoint?param=<<payload_field>>",
        "method": "GET",
        "headers": {
          "Authorization": "Bearer <<example_system_access_token>>"
        },
        "queryParams": { "limit": "10" },
        "body": "{ \"key\": \"<<payload_field>>\" }"
      },
      "dataSelector": "(sourceData) => sourceData.previousStep.data.items",
      "failureBehavior": "fail"
    }
  ],
  "outputTransform": "(sourceData) => sourceData.stepId.data",
  "outputSchema": { "type": "object", "properties": {} },
  "inputSchema": { "type": "object", "properties": {} }
}

json

{
  "id": "kebab-case-tool-name",
  "instruction": "Brief human-readable description of what this tool does",
  "steps": [
    {
      "id": "unique-step-id",
      "config": {
        "systemId": "example_system",
        "url": "https://api.example.com/endpoint?param=<<payload_field>>",
        "method": "GET",
        "headers": {
          "Authorization": "Bearer <<example_system_access_token>>"
        },
        "queryParams": { "limit": "10" },
        "body": "{ \"key\": \"<<payload_field>>\" }"
      },
      "dataSelector": "(sourceData) => sourceData.previousStep.data.items",
      "failureBehavior": "fail"
    }
  ],
  "outputTransform": "(sourceData) => sourceData.stepId.data",
  "outputSchema": { "type": "object", "properties": {} },
  "inputSchema": { "type": "object", "properties": {} }
}

Step Config Fields (Request Steps)

步骤配置字段（请求步骤）

Field	Type	Description
`type`	string	`"request"` (default, can be omitted)
`systemId`	string	System whose credentials to use
`url`	string	Full URL with `<<variable>>` placeholders
`method`	string	HTTP method
`headers`	object	HTTP headers with credential placeholders
`queryParams`	object	URL query parameters
`body`	string	Request body (JSON string with placeholders)
`pagination`	object	Auto-pagination config (see below)

字段	类型	描述
`type`	字符串	`"request"` （默认，可省略）
`systemId`	字符串	要使用其凭证的系统ID
`url`	字符串	带 `<<variable>>` 占位符的完整URL
`method`	字符串	HTTP方法
`headers`	对象	带凭证占位符的HTTP头
`queryParams`	对象	URL查询参数
`body`	字符串	请求体（带占位符的JSON字符串）
`pagination`	对象	自动分页配置（见下文）

Step Config Fields (Transform Steps)

步骤配置字段（转换步骤）

Field	Type	Description
`type`	string	`"transform"` — REQUIRED for transform steps
`transformCode`	string	JS function: `(sourceData) => transformedData`

字段	类型	描述
`type`	字符串	`"transform"` — 转换步骤必须指定此值
`transformCode`	字符串	JS函数： `(sourceData) => transformedData`

Step Behavior Fields

步骤行为字段

Field	Type	Description
`dataSelector`	string	JS function controlling step input and loop mode
`failureBehavior`	string	`fail` (default) or `continue`

字段	类型	描述
`dataSelector`	字符串	控制步骤输入和循环模式的JS函数
`failureBehavior`	字符串	`fail` （默认）或 `continue`

Credential Placeholders

凭证占位符

System credentials are namespaced as

<<systemId_credentialKey>>

and resolved server-side at execution time. You MUST explicitly reference them in headers.

系统凭证以

<<systemId_credentialKey>>

命名，并在执行时由服务器端解析。你必须在头中显式引用它们。

Auth Header Patterns

认证头示例

json

{"Authorization": "Bearer <<stripe_api_key>>"}
{"Authorization": "Bearer <<gmail_access_token>>"}
{"X-API-Key": "<<my_api_api_key>>"}
{"Authorization": "Basic <<my_api_username>>:<<my_api_password>>"}

Basic auth is auto-encoded: if the value after

Basic

isn't already base64, the engine encodes it automatically.

json

{"Authorization": "Bearer <<stripe_api_key>>"}
{"Authorization": "Bearer <<gmail_access_token>>"}
{"X-API-Key": "<<my_api_api_key>>"}
{"Authorization": "Basic <<my_api_username>>:<<my_api_password>>"}

基础认证会自动编码：如果

Basic

后的值不是base64格式，引擎会自动对其进行编码。

Credential Lifecycle

凭证生命周期

Non-sensitive creds (
```
client_id
```
,
```
auth_url
```
, etc.) are stored via
```
--credentials
```
Sensitive creds (
```
api_key
```
,
```
client_secret
```
) — in non-interactive mode (AI agents, CI), pass via
```
--credentials
```
JSON. In interactive TTY, use
```
--sensitive-credentials
```
for masked input, or set
```
SUPERGLUE_CRED_<FIELD>
```
env vars.
OAuth tokens (
```
access_token
```
,
```
refresh_token
```
) are auto-refreshed before each step execution

非敏感凭证（
```
client_id
```
、
```
auth_url
```
等）通过
```
--credentials
```
存储
敏感凭证（
```
api_key
```
、
```
client_secret
```
） — 在非交互式环境（AI Agent、CI）中，通过
```
--credentials
```
JSON传递。在交互式TTY环境中，使用
```
--sensitive-credentials
```
进行掩码输入，或设置
```
SUPERGLUE_CRED_<FIELD>
```
环境变量。
OAuth令牌（
```
access_token
```
、
```
refresh_token
```
）在每个步骤执行前自动刷新

Variables and Data Flow

变量与数据流

Variable Syntax

变量语法

All step config fields support

<<variable>>

placeholders:

Syntax	Resolves to
`<<fieldName>>`	Payload field or credential
`<<systemId_credKey>>`	System credential
`<<(sourceData) => expr>>`	JavaScript expression

CRITICAL: Simple

<<varName>>

only works for top-level keys. No dots, no nesting.

VALID:

<<userId>>

<<currentItem>>

<<stripe_api_key>>

INVALID:
```
<<currentItem.id>>
```
,
```
<<sourceData.userId>>
```
— these FAIL at runtime

For nested access, use arrow functions:

<<(sourceData) => sourceData.currentItem.id>>

所有步骤配置字段都支持

<<variable>>

占位符：

语法	解析目标
`<<fieldName>>`	负载字段或凭证
`<<systemId_credKey>>`	系统凭证
`<<(sourceData) => expr>>`	JavaScript表达式

重要提示：简单的

<<varName>>

仅适用于顶级键。不支持点语法，不支持嵌套。

有效：

<<userId>>

、

<<currentItem>>

、

<<stripe_api_key>>

无效：
```
<<currentItem.id>>
```
、
```
<<sourceData.userId>>
```
— 这些会在运行时失败

对于嵌套访问，请使用箭头函数：

<<(sourceData) => sourceData.currentItem.id>>

sourceData Object

sourceData对象

sourceData

is the cumulative state available to all JS expressions (data selectors, transforms, variable expressions):

javascript

sourceData = {
  // Payload fields at ROOT level (NEVER use sourceData.payload.*)
  userId: "123",
  date: "2024-01-15",

  // Previous step results, keyed by step ID
  // Object-selector step:
  getUsers: { currentItem: {}, data: { users: [...] }, success: true },
  // Array-selector (loop) step:
  fetchDetails: [
    { currentItem: "id1", data: { name: "Alice" }, success: true },
    { currentItem: "id2", data: { name: "Bob" }, success: true },
  ],

  // Current loop item (only set inside a looping step's config)
  currentItem: { id: 1 },

  // Credentials (flattened, namespaced)
  systemId_access_token: "...",
  systemId_api_key: "..."
}

sourceData

是所有JS表达式（数据选择器、转换、变量表达式）可用的累积状态：

javascript

sourceData = {
  // 根级别的负载字段（绝不要使用sourceData.payload.*）
  userId: "123",
  date: "2024-01-15",

  // 之前步骤的结果，按步骤ID键存储
  // 对象选择器步骤：
  getUsers: { currentItem: {}, data: { users: [...] }, success: true },
  // 数组选择器（循环）步骤：
  fetchDetails: [
    { currentItem: "id1", data: { name: "Alice" }, success: true },
    { currentItem: "id2", data: { name: "Bob" }, success: true },
  ],

  // 当前循环项（仅在循环步骤的配置中设置）
  currentItem: { id: 1 },

  // 凭证（扁平化、命名空间化）
  systemId_access_token: "...",
  systemId_api_key: "..."
}

Step Result Envelope

步骤结果信封

Every step result is wrapped in an envelope — you MUST account for this.

Object selector (or no selector) — step runs once:

javascript

sourceData.stepId = { currentItem: <selectorOutput>, data: <apiResponse>, success: true }
// Access the API response:
sourceData.stepId.data
sourceData.stepId.data.users

Array selector — step loops, result is an array of envelopes:

javascript

sourceData.stepId = [
  { currentItem: <item1>, data: <response1>, success: true },
  { currentItem: <item2>, data: <response2>, success: true },
  ...
]

每个步骤结果都被包裹在信封中 — 你必须考虑这一点。

对象选择器（或无选择器） — 步骤运行一次：

javascript

sourceData.stepId = { currentItem: <selectorOutput>, data: <apiResponse>, success: true }
// 访问API响应：
sourceData.stepId.data
sourceData.stepId.data.users

数组选择器 — 步骤循环运行，结果是信封数组：

javascript

sourceData.stepId = [
  { currentItem: <item1>, data: <response1>, success: true },
  { currentItem: <item2>, data: <response2>, success: true },
  ...
]

Data Selectors

数据选择器

Control what a step receives as input and whether it loops:

Return type	Behavior
Single object	Step runs once with that object
Array	Step runs once per item (loop mode)
`undefined` / `null`	Step receives full sourceData

In loop mode,

sourceData.currentItem

is set to the current array element.

Empty arrays are valid — the step simply skips execution.

控制步骤接收的输入以及是否循环：

返回类型	行为
单个对象	步骤使用该对象运行一次
数组	步骤针对每个项运行一次（循环模式）
`undefined` / `null`	步骤接收完整的sourceData

在循环模式下，

sourceData.currentItem

被设置为当前数组元素。

空数组是有效的 — 步骤将直接跳过执行。

Two Step Types

两种步骤类型

Request step (HTTP, Postgres, FTP/SFTP/SMB) — makes an API call:

json

{
  "id": "get-users",
  "config": {
    "type": "request",
    "systemId": "my_api",
    "url": "https://api.example.com/users",
    "method": "GET",
    "headers": { "Authorization": "Bearer <<my_api_access_token>>" }
  }
}

Transform step — pure JavaScript, no API call. Use when a subsequent request step needs reshaped data:

json

{
  "id": "format-data",
  "config": {
    "type": "transform",
    "transformCode": "(sourceData) => sourceData.getUsers.data.map(u => ({ id: u.id, name: u.fullName }))"
  }
}

Transform steps do NOT have:

systemId

url

method

headers

body

queryParams

, or

pagination

. The

transformCode

function receives

sourceData

(same object available everywhere) and its return value becomes

.data

in the step envelope.

When to use each:

Need	Use
Filter/reshape data for a SUBSEQUENT request step	Transform step ( `config.type: "transform"` )
Shape the final tool output	`outputTransform` (runs after all steps, has a slightly different schema than transform only steps)
Select input / control looping for a step	`dataSelector` on the step
Inline data computation in URL/body/headers	`<<(sourceData) => ...>>` expressions

请求步骤（HTTP、Postgres、FTP/SFTP/SMB） — 发起API调用：

json

{
  "id": "get-users",
  "config": {
    "type": "request",
    "systemId": "my_api",
    "url": "https://api.example.com/users",
    "method": "GET",
    "headers": { "Authorization": "Bearer <<my_api_access_token>>" }
  }
}

转换步骤 — 纯JavaScript，无API调用。当后续请求步骤需要重新格式化的数据时使用：

json

{
  "id": "format-data",
  "config": {
    "type": "transform",
    "transformCode": "(sourceData) => sourceData.getUsers.data.map(u => ({ id: u.id, name: u.fullName }))"
  }
}

转换步骤不包含：

systemId

、

url

、

method

、

headers

、

body

、

queryParams

或

pagination

。

transformCode

函数接收

sourceData

（与其他地方可用的对象相同），其返回值将成为步骤信封中的

.data

。

何时使用每种步骤：

需求	使用方式
为后续请求步骤过滤/重新格式化数据	转换步骤（ `config.type: "transform"` ）
格式化工具的最终输出	`outputTransform` （在所有步骤之后运行，其架构与仅转换步骤略有不同）
选择步骤输入 / 控制步骤循环	步骤上的 `dataSelector`
在URL/请求体/头中内联数据计算	`<<(sourceData) => ...>>` 表达式

Execution Pipeline

执行流程

For each step in order:

Build

sourceData

{ ...originalPayload, ...previousStepResults, ...credentials }

Run
```
dataSelector(sourceData)
```
→ determines single vs loop execution
For each item: merge
```
currentItem
```
into
```
sourceData
```
, resolve
```
<<>>
```
variables, execute step
- Request step: makes the HTTP/DB/FTP call, raw response becomes
```
.data
```
- Transform step: runs
```
transformCode(sourceData)
```
  , return value becomes
```
.data
```

Wrap result:

{ currentItem, data, success }

and store in

sourceData[stepId]

After all steps: run
```
outputTransform(sourceData)
```
to shape final output

按顺序处理每个步骤：

构建

sourceData

：

{ ...originalPayload, ...previousStepResults, ...credentials }

运行
```
dataSelector(sourceData)
```
→ 确定单次执行还是循环执行
针对每个项：将
```
currentItem
```
合并到
```
sourceData
```
中，解析
```
<<>>
```
变量，执行步骤
- 请求步骤：发起HTTP/DB/FTP调用，原始响应成为
```
.data
```
- 转换步骤：运行
```
transformCode(sourceData)
```
  ，返回值成为
```
.data
```

包装结果：

{ currentItem, data, success }

并存储在

sourceData[stepId]

中

所有步骤完成后：运行
```
outputTransform(sourceData)
```
以格式化最终输出

HTTP API Patterns

HTTP API模式

Pagination

分页

json

{
  "pagination": {
    "type": "offset|cursor|page",
    "pageSize": 100,
    "cursorPath": "$.nextPageToken",
    "stopCondition": "(response) => !response.hasMore"
  }
}

Type	How it works
`offset`	Increments `offset` param by `pageSize` each page
`cursor`	Extracts next cursor from `cursorPath` , sends as query param
`page`	Increments `page` query param

All types stop when

stopCondition

returns true, response is empty, or max pages reached.

json

{
  "pagination": {
    "type": "offset|cursor|page",
    "pageSize": 100,
    "cursorPath": "$.nextPageToken",
    "stopCondition": "(response) => !response.hasMore"
  }
}

类型	工作原理
`offset`	每页将 `offset` 参数增加 `pageSize`
`cursor`	从 `cursorPath` 提取下一个游标，作为查询参数发送
`page`	递增 `page` 查询参数

当

stopCondition

返回true、响应为空或达到最大页数时，所有类型的分页都会停止。

Systems

系统

Credential Model

凭证模型

```
credentials
```
— all credentials passed as JSON via
```
--credentials
```
```
sensitiveCredentials
```
— interactive masked prompt for secrets (TTY only, NOT for AI agents or CI)
For AI agents / non-interactive use: pass ALL credentials (including secrets like api_key, client_secret) directly via
```
--credentials '{"api_key":"..."}'
```
. Ask the user to provide the secret values, then include them in the JSON.
For human interactive use: use
```
--sensitive-credentials
```
for masked input of secrets

```
credentials
```
— 所有凭证通过
```
--credentials
```
以JSON形式传递
```
sensitiveCredentials
```
— 交互式掩码输入密钥（仅TTY环境可用，不适合AI Agent或CI）
AI Agent/非交互式使用： 通过
```
--credentials '{"api_key":"..."}'
```
直接传递所有凭证（包括api_key、client_secret等密钥）。请用户提供密钥值，然后将其包含在JSON中。
人类交互式使用： 使用
```
--sensitive-credentials
```
进行密钥的掩码输入

Templates

模板

Templates auto-populate endpoints and OAuth config. Use

sg system find

to discover available templates.

Preconfigured OAuth (no user client_id/secret needed): slack, salesforce, asana, notion, airtable, jira, confluence

模板会自动填充端点和OAuth配置。使用

sg system find

发现可用模板。

预配置OAuth（无需用户提供client_id/secret）：slack、salesforce、asana、notion、airtable、jira、confluence

OAuth Flow

OAuth流程

sg system create --name "Gmail" --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret

sg system oauth --system-id gmail --scopes "..."

User authenticates in browser → tokens saved automatically

sg system create --name "Gmail" --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret

sg system oauth --system-id gmail --scopes "..."

用户在浏览器中完成认证 → 令牌自动保存

System IDs

系统ID

Lowercase letters, numbers, underscores only — no hyphens
Used for credential namespacing:
```
<<systemId_credKey>>
```

仅允许小写字母、数字和下划线 — 禁止短横线
用于凭证命名空间：
```
<<systemId_credKey>>
```

Debugging Failed Tools

调试失败的工具

Debug Workflow

调试流程

Run with
```
--include-step-results
```
to see raw step responses
Check each step's
```
data
```
field — is the API returning what you expect?
Verify credential placeholders match
```
sg system find --id <systemId>
```
placeholder list
Test API calls directly with
sg system call
— isolate whether the issue is auth, endpoint, or transform

使用
```
--include-step-results
```
运行，查看原始步骤响应
检查每个步骤的
```
data
```
字段 — API返回的结果是否符合预期？
验证凭证占位符是否与
```
sg system find --id <systemId>
```
返回的占位符列表匹配
使用
sg system call
直接测试API调用 — 隔离问题是出在认证、端点还是转换上

Deploying Tools to Production

将工具部署到生产环境

After building and saving a tool, integrate it into your application:

构建并保存工具后，将其集成到你的应用中：

REST API (Any Language)

REST API（任意语言）

bash

undefined

bash

undefined

Run a tool

运行工具

curl -X POST "https://api.superglue.cloud/v1/tools/{toolId}/run"
-H "Authorization: Bearer $SUPERGLUE_API_KEY"
-H "Content-Type: application/json"
-d '{"inputs": {"userId": "123"}}'

Webhook trigger (async, fire-and-forget)

Webhook触发（异步，即发即弃）

curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API_KEY"
-H "Content-Type: application/json"
-d '{"userId": "123"}'

undefined

curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API_KEY"
-H "Content-Type: application/json"
-d '{"userId": "123"}'

undefined

TypeScript SDK

typescript

import { configure, runTool } from "@superglue/client";
configure({ apiKey: process.env.SUPERGLUE_API_KEY!, baseUrl: "https://api.superglue.cloud/v1" });
const response = await runTool("my-tool-id", { inputs: { userId: "123" } });
// response.data is a Run object: { runId, toolId, status, data, error, metadata }

typescript

import { configure, runTool } from "@superglue/client";
configure({ apiKey: process.env.SUPERGLUE_API_KEY!, baseUrl: "https://api.superglue.cloud/v1" });
const response = await runTool("my-tool-id", { inputs: { userId: "123" } });
// response.data是Run对象：{ runId, toolId, status, data, error, metadata }

Python SDK

python

import os
from superglue_client import AuthenticatedClient
from superglue_client.api.tools import run_tool
from superglue_client.models.run_request import RunRequest
from superglue_client.models.run_request_inputs import RunRequestInputs

client = AuthenticatedClient(base_url="https://api.superglue.cloud/v1", token=os.environ["SUPERGLUE_API_KEY"])
with client as c:
    result = run_tool.sync("my-tool-id", client=c, body=RunRequest(inputs=RunRequestInputs.from_dict({"userId": "123"})))

python

import os
from superglue_client import AuthenticatedClient
from superglue_client.api.tools import run_tool
from superglue_client.models.run_request import RunRequest
from superglue_client.models.run_request_inputs import RunRequestInputs

client = AuthenticatedClient(base_url="https://api.superglue.cloud/v1", token=os.environ["SUPERGLUE_API_KEY"])
with client as c:
    result = run_tool.sync("my-tool-id", client=c, body=RunRequest(inputs=RunRequestInputs.from_dict({"userId": "123"})))

Reference Files

参考文件

For detailed documentation on specific topics, read these files in the

references/

directory:

File	When to read
`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/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

Important: When the user asks about integrating superglue into their codebase, deploying tools, using the SDK, or calling tools from code, you MUST read

references/integration.md

for complete examples.

有关特定主题的详细文档，请阅读

references/

目录中的以下文件：

文件	阅读时机
`references/integration.md`	务必阅读此文件，当你将工具部署到生产环境时 - SDK使用、REST API、Webhook、错误处理
`references/databases.md`	构建查询PostgreSQL/MySQL数据库的工具时阅读
`references/file-servers.md`	构建与FTP/SFTP/SMB文件服务器交互的工具时阅读
`references/transforms-and-output.md`	处理复杂数据转换、输出格式化、JS沙箱约束时阅读

重要提示： 当用户询问如何将superglue集成到代码库、部署工具、使用SDK或从代码中调用工具时，你必须阅读

references/integration.md

以获取完整示例。

Draft Management

草稿管理

Drafts live in

.superglue/drafts/<draftId>.json

. Created by

build

, updated by

edit

, deleted by

save

. Ephemeral — not persisted across sessions.

草稿存储在

.superglue/drafts/<draftId>.json

中。由

build

创建，

edit

更新，

save

删除。临时存储 — 不会跨会话持久化。

File References

文件引用

Attach files with

--file key=path

. Reference in payloads with

file::<key>

. Auto-parsed to JSON.

bash

sg tool run --draft <id> --payload '{"data": "file::mysheet"}' --file mysheet=data.xlsx

使用

--file key=path

附加文件。在负载中使用

file::<key>

引用。会自动解析为JSON。

bash

sg tool run --draft <id> --payload '{"data": "file::mysheet"}' --file mysheet=data.xlsx

superglue

Original

Translation

superglue CLI (sg) — Agent Reference

superglue CLI（sg）—— Agent参考文档

CRITICAL RULES — READ FIRST

重要规则 — 请先阅读

Installation & Setup

安装与设置

Installing the CLI

安装CLI

Initialization (REQUIRED before first use)

初始化（首次使用前必须完成）

Config Resolution Order

配置解析顺序

Verifying Setup

验证设置

Quick Start

快速开始

Global Flags

全局标志

Command Reference

命令参考

sg init

sg init

Tool Commands

工具命令

System Commands

系统命令

POST request with auth and body

带认证和请求体的POST请求

Database query (Postgres)

数据库查询（Postgres）

File server (SFTP)

文件服务器（SFTP）

Run Commands

运行命令

Tool Configuration — Full Schema

工具配置 — 完整 Schema

Step Config Fields (Request Steps)

步骤配置字段（请求步骤）

Step Config Fields (Transform Steps)

步骤配置字段（转换步骤）

Step Behavior Fields

步骤行为字段

Credential Placeholders

凭证占位符

Auth Header Patterns

认证头示例

Credential Lifecycle

凭证生命周期

Variables and Data Flow

变量与数据流

Variable Syntax

变量语法

sourceData Object

sourceData对象

Step Result Envelope

步骤结果信封

Data Selectors

数据选择器

Two Step Types

两种步骤类型

Execution Pipeline

执行流程

HTTP API Patterns

HTTP API模式

Pagination

分页

Systems

系统

Credential Model

凭证模型

Templates

模板

OAuth Flow

OAuth流程

System IDs

系统ID

Debugging Failed Tools

superglue CLI (
`sg`
) — Agent Reference

superglue CLI（
`sg`
）—— Agent参考文档

`sg init`

`sg init`