> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superglue.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> Complete reference for all CLI commands and flags

## sg init

Interactive setup wizard. Prompts for API key, endpoint, output mode, and config location.

```bash theme={null}
sg init
```

No flags — fully interactive.

***

## sg update

Update the CLI to the latest version.

```bash theme={null}
sg update
sg update --check
```

| Flag      | Description                               |
| --------- | ----------------------------------------- |
| `--check` | Only check for updates without installing |

***

## Tool Commands

### sg tool build

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

```bash theme={null}
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.

```bash theme={null}
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 |

Exactly one of `--tool`, `--draft`, `--config`, or `--config-file` is required.

### sg tool edit

Edit a tool or draft using JSON Patch operations ([RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902)).

```bash theme={null}
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.

### sg tool save

Persist a draft to the server.

```bash theme={null}
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.

```bash theme={null}
sg tool list
```

No flags.

### sg tool find

Search tools by query or look up by exact ID.

```bash theme={null}
sg tool find "user data"
sg tool find --id my-tool
sg tool find
```

| Flag             | Description          |
| ---------------- | -------------------- |
| `--id <exactId>` | Exact tool ID lookup |

When called with no arguments or `*`, lists all tools. Otherwise performs a semantic search.

***

## System Commands

### sg system create

Create a new system.

```bash theme={null}
sg system create --config system.json
sg system create --name "My API" --url https://api.example.com --credentials '{"apiVersion":"v2"}'
sg system create --name "My API" --id my_api --url https://api.example.com --credential-ownership user
```

| Flag                                 | Description                                                                |
| ------------------------------------ | -------------------------------------------------------------------------- |
| `--config <file>`                    | JSON config file                                                           |
| `--id <id>`                          | System ID (derived from `--name` if omitted)                               |
| `--name <name>`                      | Human-readable name — **required** unless using `--config` or `--template` |
| `--url <url>`                        | API URL — **required** unless using `--config` or `--template`             |
| `--template <id>`                    | Template ID (merges template defaults)                                     |
| `--instructions <text>`              | Specific instructions                                                      |
| `--credentials <json>`               | Runtime credentials JSON, including secret values when needed              |
| `--authentication <json>`            | Authentication config JSON                                                 |
| `--credential-ownership <ownership>` | `organization` or `user`                                                   |
| `--docs-url <url>`                   | Documentation URL to scrape after creation                                 |
| `--openapi-url <url>`                | OpenAPI spec URL to fetch after creation                                   |
| `--env <environment>`                | `dev` or `prod`                                                            |

`--name` and `--url` must be present in the system definition — provide them as flags, include them in `--config`, or let `--template` auto-fill both. `--id` is derived from `--name` if omitted.

### sg system edit

Edit an existing system.

```bash theme={null}
sg system edit --id my-api --url https://api-v2.example.com
sg system edit --id my-api --credentials '{"api_key":"new-key"}'
sg system edit --id my-api --scrape-url https://docs.example.com --scrape-keywords "auth endpoints"
```

| Flag                                 | Description                       |
| ------------------------------------ | --------------------------------- |
| `--id <id>`                          | System ID — **required**          |
| `--name <name>`                      | New name                          |
| `--url <url>`                        | New URL                           |
| `--instructions <text>`              | New instructions                  |
| `--credentials <json>`               | Runtime credentials JSON to merge |
| `--authentication <json>`            | Authentication config JSON        |
| `--credential-ownership <ownership>` | `organization` or `user`          |
| `--scrape-url <url>`                 | Documentation URL to scrape       |
| `--scrape-keywords <keywords>`       | Space-separated scrape keywords   |
| `--env <environment>`                | `dev` or `prod`                   |

### sg system list

List all systems.

```bash theme={null}
sg system list
sg system list --mode dev
```

| Flag            | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| `--mode <mode>` | Filter by environment: `dev`, `prod`, or `all` (default: `all`) |

### sg system find

Search systems by query or look up by exact ID.

```bash theme={null}
sg system find "payment"
sg system find --id my-api
sg system find --id my-api --env prod
```

| Flag                  | Description            |
| --------------------- | ---------------------- |
| `--id <exactId>`      | Exact system ID lookup |
| `--env <environment>` | `dev` or `prod`        |

### sg system call

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

```bash theme={null}
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 "SELECT * FROM users LIMIT 5"
```

| Flag                  | Description                                                   |
| --------------------- | ------------------------------------------------------------- |
| `--url <url>`         | Full URL including protocol — **required**                    |
| `--system-id <id>`    | System ID for credential injection                            |
| `--method <method>`   | HTTP method (default: `GET`)                                  |
| `--headers <json>`    | HTTP headers JSON                                             |
| `--body <string>`     | Request body                                                  |
| `--file <key=path>`   | File reference (repeatable)                                   |
| `--env <environment>` | `dev` or `prod`                                               |
| `--continue-on-error` | Return a failed response envelope instead of exiting non-zero |

### sg system credentials

Manage the current user's credentials for systems configured with `credentialOwnership: "user"`.

```bash theme={null}
sg system credentials get --system-id my-api
sg system credentials set --system-id my-api --credentials '{"api_key":"sk-..."}'
sg system credentials clear --system-id my-api
```

| Subcommand | Description                                                                                           |
| ---------- | ----------------------------------------------------------------------------------------------------- |
| `get`      | Get current user's credentials for a user-owned system. Values are masked unless `--reveal` is passed |
| `set`      | Set current user's credentials from `--credentials <json>`                                            |
| `clear`    | Delete current user's credentials                                                                     |

Common flags:

| Flag                  | Description              |
| --------------------- | ------------------------ |
| `--system-id <id>`    | System ID — **required** |
| `--env <environment>` | `dev` or `prod`          |

### sg system search-docs

Search a system's scraped documentation.

```bash theme={null}
sg system search-docs --system-id my-api --keywords "authentication oauth"
```

| Flag                        | Description                    |
| --------------------------- | ------------------------------ |
| `--system-id <id>`          | System ID — **required**       |
| `-k, --keywords <keywords>` | Search keywords — **required** |

### sg system oauth

Authenticate a system via OAuth.

```bash theme={null}
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**                                        |
| `--scopes <scopes>`   | Space-separated OAuth scopes; defaults to system/template value |
| `--auth-url <url>`    | OAuth authorization URL (defaults to system/template value)     |
| `--token-url <url>`   | OAuth token URL (defaults to system/template value)             |
| `--grant-type <type>` | `authorization_code` (default) or `client_credentials`          |
| `--env <environment>` | `dev` or `prod`                                                 |

***

## Run Commands

### sg run list

List recent tool execution runs.

```bash theme={null}
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 <status>`  | Filter by status: `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>`       | Offset for pagination — converted to a page number as `ceil((offset+1)/limit)` (default: `0`) |

### sg run get

Get details of a specific run.

```bash theme={null}
sg run get run_abc123
```

Takes a positional `runId` argument. No additional flags.