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
Section titled “Authentication”sg login
Section titled “sg login”Authenticate the CLI through the browser. Stores an OAuth session in ~/.superglue/auth.json.
sg loginsg login --no-browsersg 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
Section titled “sg logout”Remove the stored OAuth session from ~/.superglue/auth.json.
sg logoutNo flags.
sg whoami
Section titled “sg whoami”Show the authenticated user and organization.
sg whoamiNo flags.
sg init
Section titled “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
Section titled “sg update”Update the CLI to the latest version.
sg updatesg update --check| Flag | Description |
|---|---|
--check |
Only check for updates without installing |
sg skill
Section titled “sg skill”Print the skill reference (SKILL.md) for AI agents, or a specific topic reference.
sg skillsg skill postgressg skill integrationTakes 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
Section titled “Tool commands”sg tool run
Section titled “sg tool run”Execute a saved tool or a tool config.
sg tool run --tool my-tool --payload '{"userId": "123"}'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 |
--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, --config, or --config-file is required. When a saved tool with the config’s id exists, the run is recorded as a draft run with the tool ID <id>_draft. Otherwise the run is recorded under the config’s id. A state fixture does not change the tool’s saved state; use sg tool state for that.
sg tool save
Section titled “sg tool save”Save a tool config to the server. The command creates the tool, or replaces the config of the saved tool that has the same ID. The saved tool then has the same steps, outputTransform, inputSchema, and outputSchema as the file. A field that the file does not have is removed.
sg tool save --config-file tool.jsonsg tool save --config-file tool.json --id custom-tool-id| Flag | Description |
|---|---|
--config-file <path> |
Tool config JSON file |
--config <json> |
Inline tool config JSON |
--id <customId> |
Tool ID to save under (defaults to the id in the config) |
Exactly one of --config-file or --config is required.
sg tool pull
Section titled “sg tool pull”Write a saved tool’s config to a local JSON file. Edit the file, test it with sg tool run --config-file, and save it with sg tool save --config-file.
sg tool pull my-tool --out tool.jsonTakes a positional toolId argument.
| Flag | Description |
|---|---|
--out <path> |
File to write the tool config to — required |
sg tool list
Section titled “sg tool list”List all saved tools.
sg tool listsg 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
Section titled “sg tool find”Search tools by query or look up by exact ID.
sg tool find "user data"sg tool find --id my-toolsg tool find --id my-tool --fields instruction,inputSchemasg 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
Section titled “sg tool state”Inspect, replace, or reset a saved tool’s persistent state.
sg tool state get my-toolsg tool state set my-tool --state '{"cursor":"2026-09-01T00:00:00Z"}'sg tool state set my-tool --state-file state.jsonsg 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
Section titled “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
Section titled “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
Section titled “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
Section titled “sg system oauth-apps”List reusable OAuth apps. Client secrets are never returned.
sg system oauth-appssg 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
Section titled “sg system connection”Manage your connection for a system ID.
sg system connection get --system-id my_apisg 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 |
--allowed-hosts <hosts> |
set |
Comma-separated extra hosts (host or host:port) that may receive the secrets. Pass "" to clear |
--oauth-app-id <id> |
set |
Link an app from sg system oauth-apps. Pass "" to detach |
sg system call
Section titled “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_apisg system call --url https://api.example.com/users --method POST --body '{"name":"Jane"}' --system-id my_apisg 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
Section titled “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
Section titled “MCP commands”Manage named MCP servers that expose selected saved tools.
sg mcp list
Section titled “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
Section titled “sg mcp find”Search MCP servers by query, name, or exact ID.
sg mcp find "sales"sg mcp find --id server_abc123sg mcp find --name sales-tools| Flag | Description |
|---|---|
--id <exactId> |
Exact MCP server ID lookup |
--name <serverName> |
Exact MCP server name lookup |
sg mcp create
Section titled “sg mcp create”Create a named MCP server for selected saved tools.
sg mcp create --name sales-tools --tool get_customer --tool create_invoicesg mcp create --name sales-tools --tools get_customer,create_invoice --auth-mode oauthsg 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
Section titled “sg mcp edit”Edit a named MCP server.
sg mcp edit --id server_abc123 --add-tool refund_invoicesg mcp edit --id server_abc123 --remove-tool create_invoicesg 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
Section titled “Schedule commands”Manage cron schedules for saved tools.
sg schedule list
Section titled “sg schedule list”List tool schedules.
sg schedule listsg 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
Section titled “sg schedule create”Create a schedule for a saved tool.
sg schedule create --tool my-tool --cron "0 9 * * *" --timezone Europe/Berlinsg 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
Section titled “sg schedule edit”Edit, enable, or disable an existing schedule.
sg schedule edit --tool my-tool --id sched_abc123 --disabledsg 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
Section titled “Run commands”sg run list
Section titled “sg run list”List recent tool execution runs.
sg run listsg run list --tool my-tool --status success --limit 20sg 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
Section titled “sg run get”Get details of a specific run.
sg run get run_abc123sg run get run_abc123 --fetch-resultsTakes a positional runId argument.
| Flag | Description |
|---|---|
--fetch-results |
Include complete run data (alias for --full) |
sg run download
Section titled “sg run download”Download file artifacts produced by a run.
sg run download run_abc123sg run download run_abc123 report.csv --output-dir ./downloadsTakes a positional runId and an optional fileKey argument.
| Flag | Description |
|---|---|
--output-dir <path> |
Target directory (default: .) |
Project commands
Section titled “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
Section titled “sg project list”List projects.
sg project listsg 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
Section titled “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-migrationsg 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
Section titled “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
Section titled “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 0sg project task edit --project crm-migration --id map-customer-fields --status doneTakes 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
Section titled “sg project label list”List a project’s task labels, sorted by name.
sg project label list --project crm-migrationsg project label create
Section titled “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
Section titled “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
Section titled “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