Skip to content

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.

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

Terminal window
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)

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

Terminal window
sg logout

No flags.

Show the authenticated user and organization.

Terminal window
sg whoami

No flags.

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

Terminal window
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)

Update the CLI to the latest version.

Terminal window
sg update
sg update --check
Flag Description
--check Only check for updates without installing

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

Terminal window
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.

Execute a saved tool or a tool config.

Terminal window
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.

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.

Terminal window
sg tool save --config-file tool.json
sg 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.

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.

Terminal window
sg tool pull my-tool --out tool.json

Takes a positional toolId argument.

Flag Description
--out <path> File to write the tool config to — required

List all saved tools.

Terminal window
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)

Search tools by query or look up by exact ID.

Terminal window
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.

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

Terminal window
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.

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.

List system IDs derived from connections and tools.

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

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

Terminal window
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.

List reusable OAuth apps. Client secrets are never returned.

Terminal window
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)

Manage your connection for a system ID.

Terminal window
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
--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

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

Terminal window
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

Authorize a connection via OAuth.

Terminal window
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

Manage named MCP servers that expose selected saved tools.

List named MCP servers.

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

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

Terminal window
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

Create a named MCP server for selected saved tools.

Terminal window
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

Edit a named MCP server.

Terminal window
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)

Manage cron schedules for saved tools.

List tool schedules.

Terminal window
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)

Create a schedule for a saved tool.

Terminal window
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

Edit, enable, or disable an existing schedule.

Terminal window
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

List recent tool execution runs.

Terminal window
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)

Get details of a specific run.

Terminal window
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)

Download file artifacts produced by a run.

Terminal window
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: .)

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.

List projects.

Terminal window
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)

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

Terminal window
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)

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

Terminal window
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

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.

Terminal window
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

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

Terminal window
sg project label list --project crm-migration

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

Terminal window
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

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

Terminal window
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

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

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