### Start Local Development Environment

Source: https://github.com/superglue-ai/superglue/blob/main/CONTRIBUTING.md

Starts both the backend and frontend applications in development mode. Ensure all dependencies are installed first.

```sh
npm run dev
```

--------------------------------

### Example MCP Server Setup in Cursor

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

This JSON configuration shows how to set up a Superglue MCP server within the Cursor IDE. It specifies the command to run, arguments including the MCP endpoint, and environment variables for authentication.

```json
{
"mcpServers": {
"superglue": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.superglue.ai",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer {YOUR_SUPERGLUE+API_KEY}"
}
}
}
}
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/superglue-ai/superglue/blob/main/CONTRIBUTING.md

Run this command in the project root to install all necessary npm packages for development.

```sh
npm install
```

--------------------------------

### Install and Publish with Telvine CLI

Source: https://github.com/superglue-ai/superglue/blob/main/plugins/superglue-integration-builder/README.md

Install the Telvine CLI, log in, publish the Superglue Agent Plugin, and access plugin metrics.

```bash
npm i -g telvine
telvine login
telvine publish ./plugins/superglue-integration-builder
telvine plugins metrics
```

--------------------------------

### Install Superglue TypeScript SDK

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/js/README.md

Install the Superglue client package using npm.

```bash
npm install @superglue/client
```

--------------------------------

### System Credential Example

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/data-handling.md

Illustrates how system credentials are made available using the <<>> syntax. Assumes system ID 'stripe' with an 'api_key'.

```javascript
// System id="stripe", credentials={ api_key: "sk_..." }
// Available as: <<stripe_api_key>>
```

--------------------------------

### Install Superglue CLI

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Install the Superglue CLI globally using npm. This command is used to set up the CLI in your target environment.

```bash
npm install -g @superglue/cli
```

--------------------------------

### Webhook Notification Setup

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/demos.md

This outlines the steps for setting up webhook delivery using webhook.site. It includes obtaining a token and posting the demo JSON to the generated webhook URL. The inspect URL is also provided for monitoring.

```bash
POST https://webhook.site/token
Accept: application/json
Content-Type: application/json

POST https://webhook.site/<uuid>
Content-Type: application/json

Inspect URL:
https://webhook.site/token/<uuid>/request/latest
or
https://webhook.site/token/<uuid>/requests?sorting=newest&per_page=5
```

--------------------------------

### Custom Rule Examples

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/access-rules.md

Provides examples of custom rule expressions used to control access based on request details. These expressions are evaluated against the resolved stepConfig object.

```javascript
// Block all POST requests to a specific endpoint
stepConfig.method !== "POST" || !stepConfig.url.includes("/admin");
```

```javascript
// Only allow GET requests to /api/v1/read endpoints
stepConfig.method === "GET" && stepConfig.url.includes("/api/v1/read");
```

```javascript
// Block requests with certain headers
!stepConfig.headers["x-dangerous-header"];
```

```javascript
// Block a specific datasource ID in the resolved body
!(typeof stepConfig.body === "object" && stepConfig.body?.datasource?.id === "blocked-id");
```

--------------------------------

### Find and Get System Config

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Search for systems by keyword or retrieve the full configuration of a specific system using its ID.

```bash
sg system find [query] Search systems by keyword
sg system find --id <id> Get full config of a system
```

--------------------------------

### Parameterized Query with RETURNING Clause

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Example of using parameterized queries with a `RETURNING *` clause to get inserted data. Values can be dynamically sourced from `sourceData`.

```json
{
  "query": "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
  "params": [
    "<<(sourceData) => sourceData.currentItem.name>>",
    "<<(sourceData) => sourceData.currentItem.email>>"
  ]
}
```

--------------------------------

### Redis String Operations

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/redis.md

Examples for common Redis string manipulation commands like GET, SET, MGET, and INCR.

```json
{ "command": "GET", "args": ["user:123:name"] }
```

```json
{ "command": "SET", "args": ["user:123:name", "Alice"] }
```

```json
{ "command": "MGET", "args": ["key1", "key2", "key3"] }
```

```json
{ "command": "INCR", "args": ["counter"] }
```

--------------------------------

### Configure and Use Superglue SDK

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/js/README.md

Configure the SDK with your API key and base URL, then use functions to interact with the Superglue AI API. Examples include listing tools, running tools synchronously, and running tools asynchronously with polling for completion.

```typescript
import { configure, listTools, runTool, getRun, cancelRun } from "@superglue/client";

// Configure once at startup
configure({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://api.superglue.ai/v1", // optional
});

// List tools
const { data: tools } = await listTools({ page: 1, limit: 10 });
console.log(tools.data);

// Run a tool (sync - waits for completion)
const { data: run } = await runTool("your-tool-id", {
  inputs: { query: "latest AI news" },
  options: { async: false },
});
console.log(run.data);

// Run a tool (async - returns immediately)
const { data: asyncRun } = await runTool("your-tool-id", {
  inputs: { query: "latest AI news" },
  options: { async: true },
});

// Poll for completion
let status = asyncRun;
while (status.status === "running") {
  await new Promise((r) => setTimeout(r, 1000));
  const { data } = await getRun(status.runId);
  status = data;
}
if (status.status === "success") {
  console.log(status.data);
} else {
  console.error(status.error);
}

// Cancel a run
await cancelRun("run-id-to-cancel");

```

--------------------------------

### Run Superglue with Docker Compose

Source: https://github.com/superglue-ai/superglue/blob/main/docker/DOCKER.md

Starts the Superglue application using Docker Compose. Use the `--profile infra` flag to include bundled PostgreSQL and MinIO services.

```bash
docker compose up
```

```bash
docker compose --profile infra up
```

--------------------------------

### Payload Credential Example

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/data-handling.md

Shows how payload credentials passed at runtime are accessed directly using the <<>> syntax. Assumes a payload containing 'user_access_token'.

```javascript
// Payload: { user_access_token: "abc" }
// Available as: <<user_access_token>>
```

--------------------------------

### Redis Hash Operations

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/redis.md

Examples for common Redis hash commands including HGETALL, HGET, HSET, and HMGET.

```json
{ "command": "HGETALL", "args": ["user:123"] }
```

```json
{ "command": "HGET", "args": ["user:123", "email"] }
```

```json
{ "command": "HSET", "args": ["user:123", "email", "alice@example.com"] }
```

```json
{ "command": "HMGET", "args": ["user:123", "name", "email"] }
```

--------------------------------

### Single Operation

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/file-servers.md

Example of a single file server operation.

```APIDOC
## Single Operation Example

### Description
Performs a single file operation.

### Request Body
- **operation** (string) - Required - The operation to perform (e.g., "get").
- **path** (string) - Required - The path to the file or directory.
- **content** (string) - Optional - The content to write for "put" operations.

### Request Example
```json
{ "operation": "get", "path": "data/report.csv" }
```
```

--------------------------------

### URL Variable Syntax Example

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/file-servers.md

Demonstrates the use of variable syntax within URLs for dynamic credential injection. For password-based authentication, explicitly include credentials using placeholders.

```plaintext
sftp://<<mySystem_username>>:<<mySystem_password>>@host/path
```

--------------------------------

### Redis Set Operations

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/redis.md

Examples for common Redis set commands including SMEMBERS, SADD, and SISMEMBER.

```json
{ "command": "SMEMBERS", "args": ["tags:post:1"] }
```

```json
{ "command": "SADD", "args": ["tags:post:1", "redis", "database"] }
```

```json
{ "command": "SISMEMBER", "args": ["tags:post:1", "redis"] }
```

--------------------------------

### Parameterized Query Example

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Always use parameterized queries with `$1`, `$2`, etc., to prevent SQL injection. This example shows a simple parameter substitution.

```json
{ "query": "SELECT * FROM orders WHERE customer_id = $1", "params": ["<<customerId>>"] }
```

--------------------------------

### Batch Operations

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/file-servers.md

Example of performing multiple file server operations sequentially in a single batch.

```APIDOC
## Batch Operations Example

### Description
Performs multiple file operations sequentially using the same connection.

### Request Body
An array of operation objects. Each object follows the single operation format.

### Request Example
```json
[
  { "operation": "mkdir", "path": "backup" },
  { "operation": "get", "path": "data/report.csv" },
  { "operation": "put", "path": "backup/report.csv", "content": "data here" }
]
```
```

--------------------------------

### Redis List Operations

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/redis.md

Examples for common Redis list commands such as LRANGE, LPUSH, RPOP, and LLEN.

```json
{ "command": "LRANGE", "args": ["queue:tasks", "0", "-1"] }
```

```json
{ "command": "LPUSH", "args": ["queue:tasks", "task1"] }
```

```json
{ "command": "RPOP", "args": ["queue:tasks"] }
```

```json
{ "command": "LLEN", "args": ["queue:tasks"] }
```

--------------------------------

### Redis Key Operations

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/redis.md

Examples for common Redis key management commands such as KEYS, EXISTS, TTL, EXPIRE, DEL, and TYPE.

```json
{ "command": "KEYS", "args": ["user:*"] }
```

```json
{ "command": "EXISTS", "args": ["mykey"] }
```

```json
{ "command": "TTL", "args": ["session:abc"] }
```

```json
{ "command": "EXPIRE", "args": ["session:abc", "3600"] }
```

```json
{ "command": "DEL", "args": ["mykey"] }
```

```json
{ "command": "TYPE", "args": ["mykey"] }
```

--------------------------------

### Authentication Patterns

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/http-apis.md

Examples of common authentication methods for HTTP APIs, including Bearer tokens, API keys, and Basic Auth, using system variables.

```APIDOC
## Authentication Patterns

### Description
This section provides examples of how to configure authentication headers for HTTP requests. It is recommended to use system variables for sensitive information like access tokens and API keys. Modern APIs typically expect authentication details in headers.

### Bearer Token
```javascript
// Bearer token
{ "Authorization": "Bearer <<systemId_access_token>>" }
```

### API Key in Header
```javascript
// API key in header
{ "X-API-Key": "<<systemId_api_key>>" }
```

### Basic Auth
```javascript
// Basic Auth — auto-encoded to Base64, do NOT manually encode
{ "Authorization": "Basic <<systemId_username>>:<<systemId_password>>" }
```

### Runtime Credentials from Payload
```javascript
// Runtime credentials from payload
{ "Authorization": "Bearer <<(sourceData) => sourceData.user_access_token>>" }
```

**Note:** Headers starting with `x-` are treated as custom headers. Prefer authentication in headers unless API documentation explicitly states otherwise.
```

--------------------------------

### Get Operation

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/file-servers.md

Retrieves the content of a file, auto-parsed if possible.

```APIDOC
## get

### Description
Retrieves the content of a file. The content is auto-parsed based on the file type (e.g., CSV to objects, JSON to parsed object). For unsupported types, raw string content is returned.

### Method
get

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file.

### Returns
Auto-parsed file content or raw string.
```

--------------------------------

### Redis Sorted Set Operations

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/redis.md

Examples for common Redis sorted set commands like ZRANGE, ZADD, and ZRANK.

```json
{ "command": "ZRANGE", "args": ["leaderboard", "0", "-1", "WITHSCORES"] }
```

```json
{ "command": "ZADD", "args": ["leaderboard", "100", "player1"] }
```

```json
{ "command": "ZRANK", "args": ["leaderboard", "player1"] }
```

--------------------------------

### Redis URL Format Examples

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/redis.md

Use 'redis://' for standard connections and 'rediss://' for TLS-encrypted connections. The database number is optional and defaults to 0.

```text
redis://user:password@host:port/database
rediss://user:password@host:port/database   (TLS)
```

--------------------------------

### File Server URL Formats

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/file-servers.md

Examples of URL formats for different file server protocols. Note the specific port assignments and authentication methods.

```plaintext
ftp://user:password@host:port/basePath       (port 21)
ftps://user:password@host:port/basePath      (port 21, TLS)
sftp://user:password@host:port/basePath      (port 22)
smb://user:password@host/sharename/basePath  (port 445)
smb://domain\user:password@host/sharename/   (domain auth)
```

--------------------------------

### Azure SQL Database Connection URL

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Example of a connection URL for Azure SQL Database, including the fully qualified server name and port.

```plaintext
mssql://myuser:mypassword@myserver.database.windows.net:1433/mydatabase
```

--------------------------------

### List and Get Run Details

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

List all tool execution runs, optionally filtered by tool ID, or retrieve detailed information about a specific run using its ID.

```bash
sg run list [toolId] List runs, optionally filtered by tool
sg run get <runId> Get details of a specific run
```

--------------------------------

### Batch Operations via Loop (PostgreSQL)

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Execute a query for each item in an array returned by a data selector. This example uses PostgreSQL syntax for INSERT.

```javascript
// dataSelector: (sourceData) => sourceData.newUsers
// body: {"query": "INSERT INTO users (name) VALUES ($1)", "params": ["<<(sourceData) => sourceData.currentItem.name>>"]}
```

--------------------------------

### SQL Server / Azure SQL Parameterized Query with Expressions

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Example of an INSERT statement using parameterized queries with expressions to dynamically set values from source data.

```json
{
  "query": "INSERT INTO logs (message, level) VALUES (@param1, @param2)",
  "params": ["<<(sourceData) => sourceData.message>>", "error"]
}
```

--------------------------------

### SourceData Structure Example

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/data-handling.md

Illustrates the cumulative state available to data selectors, variable expressions, and transforms, including original payload fields, previous step results, and the current item in a loop.

```javascript
sourceData = {
  // Original payload fields at ROOT level (NOT under .payload)
  userId: "abc",
  date: "2024-01-15",
  companies: ["acme", "globex"],

  // Previous step results, keyed by step ID
  getUsers: { currentItem: {}, data: { users: [...] }, success: true },
  fetchDetails: [
    { currentItem: { id: 1 }, data: { name: "Alice" }, success: true },
    { currentItem: { id: 2 }, data: { name: "Bob" }, success: true },
  ],

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

  // Runtime file map — see file-handling skill for full reference
  __files__: { ... }
}
```

--------------------------------

### SQL Server / Azure SQL URL Formats

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Examples of connection URL formats for Microsoft SQL Server and Azure SQL databases. Supports both mssql:// and sqlserver:// protocols.

```plaintext
mssql://user:password@host:port/database
sqlserver://user:password@host:port/database
```

--------------------------------

### Create System from Flags

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Create a system using command-line flags for its name and URL. This is a quick way to set up simple system integrations.

```bash
sg system create --name <name> --url <url> Create a system from flags
```

--------------------------------

### Create a Basic Client

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/python/README.md

Instantiate the client to interact with the Superglue AI API. Ensure the base URL is correctly set.

```python
from superglue_client import Client

client = Client(base_url="https://api.example.com")
```

--------------------------------

### Create System from Config

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Create a new system from a JSON configuration file. Systems represent integrations with external services like APIs or databases.

```bash
sg system create --config <file> Create a system from JSON config
```

--------------------------------

### Pagination Stop Condition Examples

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/http-apis.md

Examples of JavaScript expressions used to define stop conditions for pagination. These conditions determine when to stop making further requests.

```javascript
"!response.data.meta.next_cursor"; // no next cursor
```

```javascript
"response.data.items.length === 0"; // empty page
```

```javascript
"response.data.hasMore === false"; // explicit flag
```

```javascript
"pageInfo.totalFetched >= 1000"; // item cap
```

--------------------------------

### CLI Configuration

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Set up the Superglue CLI configuration. This is a fundamental step before using other CLI commands.

```bash
sg init Set up CLI configuration
```

--------------------------------

### Create Dev System for Prod

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/systems-handling.md

Use this to create a new development system linked to an existing production system. Always request new credentials for sandbox environments.

```javascript
create_system({
  id: "salesforce",
  environment: "dev",
  url: "https://sandbox.salesforce.com",
  credentials: { client_secret: "", api_key: "" }
})
```

--------------------------------

### Build and Run Superglue (All-in-One)

Source: https://github.com/superglue-ai/superglue/blob/main/docker/DOCKER.md

Builds the Superglue Docker image and runs it as a single container. Ensure to map the necessary ports and provide environment variables via an .env file.

```bash
docker build -t superglue:latest -f docker/Dockerfile .
docker run -p 3001:3001 -p 3002:3002 --env-file .env superglue:latest
```

--------------------------------

### Reference Files with Suffixes in Step Configurations

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/tool-building.md

When referencing files in step configurations, always use `.raw`, `.base64`, or `.extracted` suffixes. Bare `file::<key>` references are invalid and will cause runtime errors.

```javascript
"content": "file::my_csv.raw"
```

```javascript
"data": "file::my_csv.extracted"
```

--------------------------------

### Get Run Status

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/js/README.md

Poll for the status and results of an asynchronous tool run using its run ID.

```typescript
import { getRun } from "@superglue/client";

// Assuming 'status' is the object returned from an async runTool call
const { data } = await getRun(status.runId);
console.log(data);
```

--------------------------------

### System URL Resolution and Usage

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/data-handling.md

Demonstrates how system URLs are resolved and used within step configurations, enabling environment-agnostic tools. Assumes a system ID 'salesforce' with a base URL.

```javascript
// System id="salesforce", url="https://mycompany.salesforce.com"
// Available as: <<salesforce_url>>

// Step config:
{
  "url": "<<salesforce_url>>/services/data/v58.0/sobjects/Account",
  "headers": { "Authorization": "Bearer <<salesforce_access_token>>" }
}
```

--------------------------------

### Build Tool from Flags

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Build a tool using command-line flags for its instruction and steps. This method is an alternative to using a config file.

```bash
sg tool build --id <id> --instruction <text> Build a tool from flags (requires --steps)
```

--------------------------------

### Development Commands

Source: https://github.com/superglue-ai/superglue/blob/main/CLAUDE.md

Common npm scripts for development, testing, and linting.

```bash
npm run dev        # Start all (turbo)
npm run test       # Vitest
npm run lint:fix   # Prettier
npm run type-check # TS check
```

--------------------------------

### Execute Async Task with Worker Pools

Source: https://github.com/superglue-ai/superglue/blob/main/CLAUDE.md

Example of how to run an asynchronous task using the worker pools for CPU-intensive operations.

```typescript
authReq.workerPools.toolExecution.runTask(runId, payload);
```

--------------------------------

### Search System Documentation

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Search the documentation for a specific system using keywords. This helps in understanding how to interact with a system.

```bash
sg system search-docs --system-id <id> -k <kw> Search system documentation
```

--------------------------------

### Redis Scan Operations

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/redis.md

Examples for safe iteration using SCAN and HSCAN commands, allowing for pattern matching and count limits.

```json
{ "command": "SCAN", "args": ["0", "MATCH", "user:*", "COUNT", "100"] }
```

```json
{ "command": "HSCAN", "args": ["myhash", "0", "MATCH", "field*"] }
```

--------------------------------

### Configuration

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/js/README.md

Configure the Superglue client with your API key and an optional base URL.

```typescript
import { configure } from "@superglue/client";

configure({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://api.superglue.ai/v1", // optional
});
```

--------------------------------

### System URL Availability and Usage

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/systems-handling.md

Illustrates how system URLs are made available and used within step configurations to avoid hardcoding base URLs.

```text
System id="salesforce", url="https://mycompany.salesforce.com"
→ Available as: <<salesforce_url>>

Step config: { "url": "<<salesforce_url>>/services/data/v58.0/sobjects/Account" }
```

--------------------------------

### Azure SQL Database Connection URL with Encoded User

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Example of an Azure SQL Database connection URL where the '@' symbol in the username is URL-encoded as '%40'.

```plaintext
mssql://myuser%40myserver:mypassword@myserver.database.windows.net:1433/mydatabase
```

--------------------------------

### Frontend Component Import Pattern

Source: https://github.com/superglue-ai/superglue/blob/main/CLAUDE.md

Illustrates how to import and use UI components, including utility functions for classnames. Always check existing components before creating new ones.

```typescript
import { cn } from "@/src/lib/general-utils";
import { Button } from "@/src/components/ui/button";
```

--------------------------------

### Build and Run Superglue Server Only

Source: https://github.com/superglue-ai/superglue/blob/main/docker/DOCKER.md

Builds a Docker image for the Superglue API server only and runs it. This is a lighter option if the web UI is not needed. Map port 3002 and provide environment variables.

```bash
docker build -t superglue-server:latest -f docker/Dockerfile.server .
docker run -p 3002:3002 --env-file .env superglue-server:latest
```

--------------------------------

### Edit and List Systems

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Edit an existing system's configuration or list all managed systems. These commands are essential for system lifecycle management.

```bash
sg system edit --id <id> Edit a system's configuration
sg system list List all systems
```

--------------------------------

### Parameterized Query with Expressions

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Use expressions within the `params` array for dynamic value generation. This example inserts a message and level into a logs table.

```json
{
  "query": "INSERT INTO logs (message, level) VALUES ($1, $2)",
  "params": ["<<(sourceData) => sourceData.message>>", "error"]
}
```

--------------------------------

### SQL Server / Azure SQL URL with Connection Parameters

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Demonstrates how to include connection parameters like encryption and certificate trust settings as a query string in the database URL.

```plaintext
mssql://user:password@host:port/database?encrypt=true&trustServerCertificate=false
```

--------------------------------

### URL Best Practices for HTTP Requests

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/http-apis.md

Illustrates recommended and acceptable ways to specify URLs in HTTP requests, emphasizing the use of system URL variables for environment-agnostic configurations.

```typescript
{ "url": "<<salesforce_url>>/services/data/v58.0/sobjects/Account" }
```

```typescript
{ "url": "https://api.stripe.com/v1/customers" }
```

```typescript
{ "url": "https://mycompany.salesforce.com/services/data/v58.0/sobjects/Account" }
```

--------------------------------

### Build Tool from Config

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Build a tool from a JSON configuration file. This command is used for defining and creating new tools within Superglue.

```bash
sg tool build --config <file> Build a tool from a JSON config
```

--------------------------------

### Create an Authenticated Client

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/python/README.md

Use `SuperglueClient` for endpoints requiring authentication. Provide your API token during instantiation.

```python
from superglue_client import SuperglueClient

client = SuperglueClient(base_url="https://api.example.com", token="SuperSecretToken")
```

--------------------------------

### Create System with Template ID

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/systems-handling.md

Use `templateId` to auto-populate system details like URL, name, and OAuth metadata. Some templates may also include system-specific instructions.

```javascript
create_system({ id: "slack", templateId: "slack" })
```

--------------------------------

### Superglue CLI Usage

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Basic usage of the Superglue CLI, showing available options and commands. Use this to understand the CLI's capabilities.

```bash
Usage: sg [options] [command]

superglue CLI — build, run, and manage integration tools

Options:
  -V, --version output the version number
  --api-key <key> superglue API key
  --endpoint <url> superglue API endpoint
  --json force JSON output
  -h, --help display help for command

Commands:
  init [options] Set up superglue CLI configuration
  update [options] Update the superglue CLI to the latest version
  skill [topic] Print the superglue skill reference (SKILL.md) for AI agents
  tool Manage superglue tools
  system Manage superglue systems
  run View tool execution runs
  help [command] display help for command
```

--------------------------------

### URL Best Practices

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/http-apis.md

Guidelines for constructing URLs, emphasizing the use of system URL variables for environment-agnostic configurations.

```APIDOC
## URL Best Practices

### Description
It is recommended to use system URL variables for base URLs to ensure your configurations work across different environments (development, production) without modification. This approach makes your tools environment-agnostic.

### Recommended Usage
```typescript
// RECOMMENDED: Environment-agnostic (works with dev/prod switching)
{ "url": "<<salesforce_url>>/services/data/v58.0/sobjects/Account" }
```

### Acceptable Usage
```typescript
// ACCEPTABLE: When URL differs significantly from system base URL
{ "url": "https://api.stripe.com/v1/customers" }
```

### Avoid
```typescript
// AVOID: Hardcoding URLs that match the system's base URL
{ "url": "https://mycompany.salesforce.com/services/data/v58.0/sobjects/Account" }
```

Using `<<systemId_url>>` allows the same tool configuration to be used across different environments by dynamically resolving the URL based on the execution mode.
```

--------------------------------

### SQL Server / Azure SQL Parameterized Query

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Example of a parameterized query for selecting orders based on a customer ID. Always use parameterized queries to prevent SQL injection.

```json
{ "query": "SELECT * FROM orders WHERE customer_id = @param1", "params": ["<<customerId>>"] }
```

--------------------------------

### Build for Production

Source: https://github.com/superglue-ai/superglue/blob/main/CONTRIBUTING.md

Compiles and bundles the project for a production deployment. This command is typically used before releasing a new version.

```sh
npm run build
```

--------------------------------

### List and Find Tools

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

List all saved tools or search for tools by keyword or ID. These commands help in managing and discovering available tools.

```bash
sg tool list List all saved tools
sg tool find [query] Search tools by keyword
sg tool find --id <id> Get full config of a tool
```

--------------------------------

### Run Inline Tool Config

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Execute a tool directly from an inline JSON configuration. This allows for quick execution of ad-hoc tool logic.

```bash
sg tool run --config <json> [--payload <json>] Run inline config
```

--------------------------------

### Add REST Endpoint with registerApiModule

Source: https://github.com/superglue-ai/superglue/blob/main/CLAUDE.md

Example of registering a new REST API module using the `registerApiModule` pattern. Ensure to import necessary types and helpers. Use `sendError` for error handling and `addTraceHeader` for response enrichment.

```typescript
import { registerApiModule } from "./registry.js";
import { sendError, addTraceHeader } from "./response-helpers.js";
import type { AuthenticatedFastifyRequest, RouteHandler } from "./types.js";

const myHandler: RouteHandler = async (request, reply) => {
  const authReq = request as AuthenticatedFastifyRequest;
  const params = request.params as { id: string };
  const metadata = authReq.toMetadata();
  
  const data = await authReq.datastore.someMethod({ orgId: authReq.authInfo.orgId });
  
  if (!data) {
    return sendError(reply, 404, "Not found");
  }
  
  return addTraceHeader(reply, authReq.traceId).code(200).send({ data });
};

registerApiModule({
  name: "my-feature",
  routes: [
    {
      method: "GET",
      path: "/my-endpoint",
      handler: myHandler,
      permissions: { type: "read", resource: "my-resource" },
    },
  ],
});
```

--------------------------------

### Accessing Skill Reference

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/superglue-concepts.md

Print the Superglue skill reference for AI agents. It is crucial to read this reference before using sg commands for detailed usage instructions.

```bash
sg skill                        Print the main SKILL.md reference
sg skill databases              Print the databases reference
sg skill integration            Print the SDK/REST/webhook reference
sg skill file-servers           Print the file servers reference
sg skill data-handling          Print the data handling reference
sg skill file-handling          Print the file handling reference
sg skill http-apis              Print the HTTP APIs reference
sg skill redis                  Print the Redis reference
```

--------------------------------

### Accessing currentItem in Step Configuration

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/data-handling.md

Demonstrates different ways to access and transform the currentItem within step configurations.

```string
<<currentItem>>                                           // whole value
```

```string
<<(sourceData) => sourceData.currentItem.id>>             // property
```

```string
<<(sourceData) => sourceData.currentItem.name.toUpperCase()>>  // with transform
```

--------------------------------

### PostgreSQL Step Configuration

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Configure the connection URL using stored database system credentials. Ensure all credential variables are correctly referenced.

```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>>]}'
}
```

--------------------------------

### Mkdir Operation

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/file-servers.md

Creates a new directory.

```APIDOC
## mkdir

### Description
Creates a new directory.

### Method
mkdir

### Parameters
#### Path Parameters
- **path** (string) - Required - The path for the new directory.
```

--------------------------------

### Reference Specific Files in Multi-File Steps

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/tool-building.md

For multi-file steps, use bracket notation with the specific filename to reference a particular file from the output.

```javascript
"content": "file::downloadStep[\"report.csv\"].raw"
```

--------------------------------

### Reference Files from Previous Step Output

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/tool-building.md

When referencing files produced by a previous step, use the step ID followed by the file key and the appropriate suffix (e.g., `.raw`).

```javascript
"content": "file::downloadStep.raw"
```

--------------------------------

### Tool Configuration with File Bindings

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/tool-building.md

Illustrates how the input schema is structured when file bindings are used during tool building. This schema defines the expected input shape for the frontend and agent UI.

```typescript
{
  type: "object",
  properties: {
    payload: { ... },
    __files__: { ... },
    credentials: { ... }
  }
}
```

--------------------------------

### Run Unit Tests

Source: https://github.com/superglue-ai/superglue/blob/main/CONTRIBUTING.md

Executes all unit tests for the project. This command should be run before committing code to ensure all tests pass.

```sh
npm run test
```

--------------------------------

### Database/Redis/File Server Request Step Configuration

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/tool-building.md

Defines the configuration for request steps connecting to databases, Redis, or file servers. Note that HTTP-specific fields like method and headers are omitted.

```typescript
{
  type: "request",
  systemId?: string,
  url: string,
  body: string
}
```

--------------------------------

### List Tools

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/js/README.md

Retrieve a list of available tools with pagination.

```typescript
import { listTools } from "@superglue/client";

const { data: tools } = await listTools({ page: 1, limit: 10 });
console.log(tools.data);
```

--------------------------------

### Generate Superglue TypeScript SDK

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/js/README.md

Generate the Superglue TypeScript SDK from the OpenAPI specification using the npm run generate command.

```bash
npm run generate
```

--------------------------------

### HTTP Authentication Patterns

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/http-apis.md

Demonstrates common authentication methods for HTTP APIs, including Bearer tokens, API keys, Basic Auth, and runtime credentials from the payload.

```javascript
{ "Authorization": "Bearer <<systemId_access_token>>" }
```

```javascript
{ "X-API-Key": "<<systemId_api_key>>" }
```

```javascript
{ "Authorization": "Basic <<systemId_username>>:<<systemId_password>>" }
```

```javascript
{ "Authorization": "Bearer <<(sourceData) => sourceData.user_access_token>>" }
```

--------------------------------

### Client with Request/Response Event Hooks

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/python/README.md

Customize client behavior by adding event hooks for requests and responses. This allows for logging or other pre/post-processing logic.

```python
from superglue_client import Client

def log_request(request):
    print(f"Request event hook: {request.method} {request.url} - Waiting for response")

def log_response(response):
    request = response.request
    print(f"Response event hook: {request.method} {request.url} - Status {response.status_code}")

client = Client(
    base_url="https://api.example.com",
    httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}},
)
```

--------------------------------

### SMB Connection String Format

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/file-servers.md

Use this format for SMB connections, injecting credentials via placeholders. For private systems, use the Secure Gateway host format.

```plaintext
smb://<<systemId_username>>:<<systemId_password>>@fileserver.example.com/ShareName
```

--------------------------------

### Microsoft SQL Server / Azure SQL Step Configuration

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Configure a request step to connect to a Microsoft SQL Server or Azure SQL database. Ensure credentials and database details are correctly referenced.

```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>>]}'
}
```

--------------------------------

### Client with Custom SSL Certificate

Source: https://github.com/superglue-ai/superglue/blob/main/packages/sdk/python/README.md

Configure the client to use a custom SSL certificate bundle for verification. This is useful for internal servers or specific security requirements.

```python
client = SuperglueClient(
    base_url="https://internal_api.example.com",
    token="SuperSecretToken",
    verify_ssl="/path/to/certificate_bundle.pem",
)
```

--------------------------------

### SQL Server / Azure SQL INSERT with OUTPUT Clause

Source: https://github.com/superglue-ai/superglue/blob/main/packages/web/src/lib/agent/skills/content/databases.md

Demonstrates an INSERT statement using the OUTPUT clause (MSSQL equivalent of RETURNING) to return inserted rows. Parameters are mapped positionally.

```json
{
  "query": "INSERT INTO users (name, email) OUTPUT INSERTED.* VALUES (@param1, @param2)",
  "params": [
    "<<(sourceData) => sourceData.currentItem.name>>",
    "<<(sourceData) => sourceData.currentItem.email>>"
  ]
}
```