Commands

The CLI outputs JSON by default. These global flags can be placed before a command:

Flag	Description
--api-key <key>	Override the API key for headless auth
--endpoint <url>	Override the superglue API endpoint
--table	Human-readable table output (default: JSON)
--full	Disable truncation of large fields

Run sg <command> --help to inspect the exact interface installed locally.

Authentication

sg login

Authenticate the CLI through the browser. Stores an OAuth session in ~/.superglue/auth.json.

sg login
sg login --no-browser
sg login --save-config --global

Flag	Description
--web-endpoint <url>	superglue web app endpoint
--no-browser	Print the login URL instead of opening a browser
--save-config	Persist endpoint settings to config.json
--global	Save endpoint config globally (~/.superglue/config.json)

sg logout

Remove the stored OAuth session from ~/.superglue/auth.json.

sg logout

No flags.

sg whoami

Show the authenticated user and organization.

sg whoami

No flags.

sg init

Legacy API-key setup for headless environments. Prefer sg login. The command is hidden from sg --help but remains available for existing scripts.

sg init

Flag	Description
--web-endpoint <url>	Web endpoint for OAuth callbacks
--output-mode <mode>	stdout or stdout+file (default: stdout)
--output-dir <dir>	Output directory for stdout+file mode (default: .superglue/output)
--global	Save config globally (~/.superglue/) instead of locally
--preset <preset>	runner, builder, or admin (default: admin)

sg update

Update the CLI to the latest version.

sg update
sg update --check

Flag	Description
--check	Only check for updates without installing

sg skill

Print the skill reference (SKILL.md) for AI agents, or a specific topic reference.

sg skill
sg skill postgres
sg skill integration

Takes an optional positional topic argument. Available topics: superglue-info, integration, http, graphql, postgres, mssql, odbc, redis, mongodb, sftp-smb, file-handling, access-rules.

Tool commands

sg tool build

Build a new tool from a config file or individual flags.

sg tool build --config tool.json
sg tool build --id my-tool --instruction "Fetch user data" --steps steps.json

Flag	Description
--config <file>	JSON config file or inline JSON
--id <id>	Tool ID (kebab-case)
--instruction <text>	Human-readable tool instruction
--steps <file>	JSON file containing steps array
--output-transform <code>	JS output transform function
--output-schema <file>	JSON file for output schema
--payload <json>	Sample payload JSON
--file <key=path>	File reference (repeatable)

Provide either --config or --id + --instruction + --steps.

sg tool run

Execute a draft, saved tool, or inline config.

sg tool run --tool my-tool --payload '{"userId": "123"}'
sg tool run --draft abc123
sg tool run --config '{"id":"inline","instruction":"...","steps":[...]}'
sg tool run --config-file tool.json --payload-file payload.json

Flag	Description
--tool <id>	Saved tool ID
--draft <id>	Draft ID from build
--config <json>	Inline tool config JSON
--config-file <path>	Tool config JSON file
--payload <json>	JSON payload
--payload-file <path>	JSON payload file
--file <key=path>	File reference (repeatable)
--include-step-results	Include raw step results in output
--include-config	Include full tool config in output
--state-fixture <json>	Seed sourceData.persistedState for this run only
--state-fixture-file <path>	Seed the run’s persistent state from a JSON file
--timeout <ms>	Per-request timeout; minimum 1000ms

Exactly one of --tool, --draft, --config, or --config-file is required. A state fixture does not change the tool’s saved state; use sg tool state for that.

sg tool edit

Edit a tool or draft using JSON Patch operations (RFC 6902).

sg tool edit --tool my-tool --patches '[{"op":"replace","path":"/instruction","value":"New instruction"}]'
sg tool edit --draft abc123 --patches patches.json

Flag	Description
--tool <id>	Saved tool ID
--draft <id>	Draft ID
--patches <json-or-file>	JSON Patch array (inline or file path) — required

One of --tool or --draft is required. Editing a saved tool creates a new draft.

sg tool save

Persist a draft to the server.

sg tool save --draft abc123
sg tool save --draft abc123 --id custom-tool-id

Flag	Description
--draft <id>	Draft ID — required
--id <customId>	Custom ID for the saved tool (defaults to the draft’s tool ID)

sg tool list

List all saved tools.

sg tool list
sg tool list --limit 50 --offset 50

Flag	Description
--limit <n>	Max results (default: 25, max: 1000)
--offset <n>	Skip the first N results (default: 0)

sg tool find

Search tools by query or look up by exact ID.

sg tool find "user data"
sg tool find --id my-tool
sg tool find --id my-tool --fields instruction,inputSchema
sg tool find

Flag	Description
--id <exactId>	Exact tool ID lookup
--fields <fields>	Comma-separated top-level fields to return (requires --id)

When called with no arguments or *, lists all tools. Otherwise performs a keyword search across tool IDs, names, and instructions.

sg tool state

Inspect, replace, or reset a saved tool’s persistent state.

sg tool state get my-tool
sg tool state set my-tool --state '{"cursor":"2026-09-01T00:00:00Z"}'
sg tool state set my-tool --state-file state.json
sg tool state reset my-tool

Subcommand	Description
get <toolId>	Show the tool’s current persistent state
set <toolId>	Replace the whole state from --state <json> or --state-file <path>
reset <toolId>	Delete every state key so the next run cold-starts

set replaces all keys and is subject to the same key and size limits as run-time state writes. State is stored unencrypted; never put credential values in it.

System commands

A system ID is a namespace string. It exists when a connection carries it or a tool step references it. Each connection holds one identity for a service: secrets, URL, authentication config, optional Secure Gateway tunnel, and usage instructions.

sg system list

List system IDs derived from connections and tools.

sg system list

Flag	Description
--limit <n>	Max results (default: 25)
--offset <n>	Skip the first N results (default: 0)

sg system find

Search system IDs by query or look up one by exact ID.

sg system find "payment"
sg system find --id my_api

Flag	Description
--id <exactId>	Exact system ID lookup

--id returns your secret names and their <<systemId_secretName>> placeholders.

sg system oauth-apps

List reusable OAuth apps. Client secrets are never returned.

sg system oauth-apps
sg system oauth-apps --system-id hubspot

Flag	Description
--system-id <id>	Show apps that fit this system ID
--limit <n>	Max results (default: 25)
--offset <n>	Skip the first N results (default: 0)

sg system connection

Manage your connection for a system ID.

sg system connection get --system-id my_api
sg system connection set --system-id stripe --url https://api.stripe.com --credentials '{"api_key":"sk-..."}' --authentication '{"type":"api_key"}'
sg system connection set --system-id hubspot --oauth-app-id <appId>
sg system connection clear --system-id my_api

Subcommand	Description
get	Show the connection ID, secret names, whether each has a value, and placeholders
set	Create or update the connection
clear	Remove every stored secret from the connection, including OAuth tokens

get never returns secret values. Without --connection-id, commands target your default owned connection for the system ID, or your oldest owned one.

Flag	Applies to	Description
--system-id <id>	all	System ID — required
--connection-id <id>	all	Target a specific connection you can access under the system ID
--credentials <json>	set	Replace every stored secret, including OAuth tokens; omit to keep them
--url <url>	set	Base URL resolved by <<systemId_url>>. Pass "" to clear
--authentication <json>	set	Authentication config JSON. Required when creating a connection; use {"type":"none"} for public
--tunnel-id <id>	set	Secure Gateway tunnel ID. Pass "" to remove
--usage-instructions <text>	set	Guidance for using the connection. Pass "" to clear
--oauth-app-id <id>	set	Link an app from sg system oauth-apps. Pass "" to detach

sg system call

Make an authenticated call through a connection (HTTP API, database, or file server).

sg system call --url https://api.example.com/users --system-id my_api
sg system call --url https://api.example.com/users --method POST --body '{"name":"Jane"}' --system-id my_api
sg system call --url postgres://host/db --system-id my_db --body '{"query":"SELECT * FROM users LIMIT 5"}'

Flag	Description
--url <url>	Full URL including protocol — required
--system-id <id>	System ID whose connection resolves the placeholders
--connection-id <id>	Connection within --system-id; defaults to your default one
--method <method>	HTTP method (default: GET)
--headers <json>	HTTP headers JSON
--body <string>	Request body
--timeout <ms>	Per-request timeout; minimum 1000ms
--file <key=path>	File reference (repeatable)
--continue-on-error	Return a failed response envelope instead of exiting non-zero

sg system oauth

Authorize a connection via OAuth.

sg system oauth --system-id my_api --scopes "read write"
sg system oauth --system-id my_api --scopes "read" --grant-type client_credentials

Flag	Description
--system-id <id>	System ID — required
--connection-id <id>	Connection within --system-id; defaults to your own
--scopes <scopes>	Replace the saved scopes; "" requests none
--auth-url <url>	OAuth authorization URL (defaults to the connection’s value)
--token-url <url>	OAuth token URL (defaults to the connection’s value)
--grant-type <type>	authorization_code (default) or client_credentials

MCP commands

Manage named MCP servers that expose selected saved tools.

sg mcp list

List named MCP servers.

sg mcp list

Flag	Description
--limit <n>	Max results (default: 25)
--offset <n>	Skip the first N results (default: 0)

sg mcp find

Search MCP servers by query, name, or exact ID.

sg mcp find "sales"
sg mcp find --id server_abc123
sg mcp find --name sales-tools

Flag	Description
--id <exactId>	Exact MCP server ID lookup
--name <serverName>	Exact MCP server name lookup

sg mcp create

Create a named MCP server for selected saved tools.

sg mcp create --name sales-tools --tool get_customer --tool create_invoice
sg mcp create --name sales-tools --tools get_customer,create_invoice --auth-mode oauth
sg mcp create --config mcp-server.json

Flag	Description
--config <file-or-json>	MCP server config file or inline JSON
--name <name>	URL-safe server name
--display-name <name>	Human-readable display name
--description <text>	Description
--auth-mode <mode>	oauth (default) or creator_api_key
--tool <id>	Saved tool ID to expose (repeatable)
--tools <ids>	Comma-separated saved tool IDs to expose

sg mcp edit

Edit a named MCP server.

sg mcp edit --id server_abc123 --add-tool refund_invoice
sg mcp edit --id server_abc123 --remove-tool create_invoice
sg mcp edit --id server_abc123 --tools get_customer,create_invoice

Flag	Description
--id <id>	MCP server ID — required
--config <file-or-json>	Partial MCP server config file or inline JSON
--name <name>	New URL-safe server name
--display-name <name>	New human-readable display name
--clear-display-name	Clear the display name
--description <text>	New description
--clear-description	Clear the description
--auth-mode <mode>	oauth or creator_api_key
--tool <id>	Replacement saved tool ID (repeatable)
--tools <ids>	Replacement comma-separated saved tool IDs
--add-tool <id>	Add a saved tool ID (repeatable)
--remove-tool <id>	Remove a saved tool ID (repeatable)

Schedule commands

Manage cron schedules for saved tools.

sg schedule list

List tool schedules.

sg schedule list
sg schedule list --tool my-tool --status active

Flag	Description
--tool <id>	Filter by tool ID
--status <status>	Filter by status: active, inactive, or all (default: all)
--limit <n>	Max results (default: 25)
--offset <n>	Skip the first N results (default: 0)

sg schedule create

Create a schedule for a saved tool.

sg schedule create --tool my-tool --cron "0 9 * * *" --timezone Europe/Berlin
sg schedule create --tool my-tool --cron "0 * * * *" --timezone UTC --payload '{"limit":100}'

Flag	Description
--tool <id>	Saved tool ID to schedule — required
--cron <expression>	5-field cron expression — required
--timezone <name>	IANA timezone (e.g. UTC, Europe/Berlin); defaults to the local timezone
--disabled	Create the schedule disabled
--payload <json>	JSON object payload passed to each scheduled run
--payload-file <path>	JSON file payload passed to each scheduled run
--options <json-or-file>	Request options JSON object or file path
--options-file <path>	Request options JSON file
--webhook-url <url>	Webhook URL called after successful execution
--tool-chain <toolId>	Tool ID to run after successful execution
--retries <n>	Retry count, 0-3
--timeout <ms>	Request timeout in milliseconds

sg schedule edit

Edit, enable, or disable an existing schedule.

sg schedule edit --tool my-tool --id sched_abc123 --disabled
sg schedule edit --tool my-tool --id sched_abc123 --cron "0 12 * * *"

Flag	Description
--tool <id>	Saved tool ID that owns the schedule — required
--id <id>	Schedule ID — required
--cron <expression>	New 5-field cron expression
--timezone <name>	New IANA timezone
--enabled	Enable the schedule
--disabled	Disable the schedule
--payload <json>	Replacement JSON object payload
--payload-file <path>	Replacement JSON payload file
--options <json-or-file>	Replacement request options JSON object or file path
--options-file <path>	Replacement request options JSON file
--clear-options	Replace request options with an empty object
--webhook-url <url>	Set webhook URL called after successful execution
--tool-chain <toolId>	Set tool ID to run after successful execution
--clear-webhook	Remove webhook/tool-chain success action from options
--retries <n>	Set retry count, 0-3
--timeout <ms>	Set request timeout in milliseconds

Run commands

sg run list

List recent tool execution runs.

sg run list
sg run list --tool my-tool --status success --limit 20
sg run list --source cli,sdk --user user_123

Flag	Description
--tool <id>	Filter by tool ID
--status <statuses>	Comma-separated statuses: running, success, failed, aborted
--source <sources>	Comma-separated request sources
--user <userId>	Filter by user ID
--system-id <id>	Filter by system ID
--limit <n>	Max results (default: 10, max: 50)
--offset <n>	Skip the first N results (default: 0)

sg run get

Get details of a specific run.

sg run get run_abc123
sg run get run_abc123 --fetch-results

Takes a positional runId argument.

Flag	Description
--fetch-results	Include complete run data (alias for --full)

sg run download

Download file artifacts produced by a run.

sg run download run_abc123
sg run download run_abc123 report.csv --output-dir ./downloads

Takes a positional runId and an optional fileKey argument.

Flag	Description
--output-dir <path>	Target directory (default: .)

Project commands

List projects and manage their tasks and labels. Tasks are ordered per status column (not_started, in_progress, waiting, done). --position is the 0-based index in the column: 0 is the top, and values past the end place the task last.

sg project list

List projects.

sg project list
sg project list --include-archived

Flag	Description
--include-archived	Include archived projects
--limit <n>	Max results (default: 25, max: 100)
--offset <n>	Skip the first N results (default: 0)

sg project task list

List a project’s tasks in board order: by status column, then position. Descriptions appear only with --full.

sg project task list --project crm-migration
sg project task list --project crm-migration --status waiting --full

Flag	Description
--project <id>	Project ID — required
--status <status>	Filter by status: not_started, in_progress, waiting, done
--label <ids>	Comma-separated label IDs; returns tasks with any of them
--limit <n>	Max results (default: 100, max: 1000)
--offset <n>	Skip the first N results (default: 0)

sg project task create

Create a task. Without --position, the task goes to the end of its column.

sg project task create --project crm-migration --name "Map customer fields"
sg project task create --project crm-migration --name "Fix blockers" --status in_progress --position 0

Flag	Description
--project <id>	Project ID — required
--name <name>	Task name, 1–120 characters — required
--status <status>	not_started (default), in_progress, waiting, or done
--position <n>	0-based index in the status column
--description <text>	Task description
--description-file <path>	Read the task description from a file
--due-date <date>	Due date as YYYY-MM-DD
--assignee <userId>	Organization member user ID
--labels <ids>	Comma-separated project label IDs; replaces the task’s labels

sg project task edit

Update the given fields of a task. Omitted fields stay unchanged. A status change without --position moves the task to the end of the new column.

sg project task edit --project crm-migration --id map-customer-fields --position 0
sg project task edit --project crm-migration --id map-customer-fields --status done

Takes the same field flags as sg project task create, plus:

Flag	Description
--project <id>	Project ID — required
--id <taskId>	Task ID — required
--name <name>	New task name; the task ID stays unchanged
--clear-due-date	Remove the due date
--unassign	Remove the assignee
--clear-labels	Remove all labels

sg project label list

List a project’s task labels, sorted by name.

sg project label list --project crm-migration

sg project label create

Create a label. The label ID derives from the name. A project has at most 50 labels.

sg project label create --project crm-migration --name Blocked --color "#ef4444"

Flag	Description
--project <id>	Project ID — required
--name <name>	Label name, 1–40 characters, unique in the project — required
--color <hex>	Color as #rrggbb; omitted picks the first unused palette color

sg project label edit

Rename or recolor a label. The label ID and its task assignments stay unchanged.

sg project label edit --project crm-migration --id blocked --name "Blocked by client"

Flag	Description
--project <id>	Project ID — required
--id <labelId>	Label ID — required
--name <name>	New label name
--color <hex>	New color as #rrggbb

sg project label delete

Delete a label and remove it from every task. Requires the admin CLI preset.

sg project label delete --project crm-migration --id blocked