guild integration

Build and manage custom integrations. Each subcommand has its own section below, in alphabetical order. The version and operation groups list their subcommands in their own sections. Most commands take an integration identifier: an integration ID or a full name such as myorg~my-service. A typical flow for a new integration looks like this:

guild integration create my-service --base-url https://api.example.com --auth-scheme api-key   # Create it with a draft version
guild integration operation create myorg~my-service --openapi ./openapi.yaml                  # Add operations
guild integration version build myorg~my-service --version-number 1.0.0                       # Validate the draft
guild integration version test myorg~my-service --operation list_users --account my-account   # Try an operation
guild integration version publish myorg~my-service --version-number 1.0.0                     # Publish it

connect

Connect an API key credential to an integration.

guild integration connect myorg~my-service --owner <account>                  # Interactive prompt
guild integration connect myorg~my-service --owner <account> --token <value>  # Non-interactive

Option	Description
`--owner <id_or_name>`	Required. The account that owns the credential: a username, organization name, or account ID.
`--token <value>`	The API key value. Required in non-interactive mode. Without it, the CLI prompts for the key.

Argument	Description
`<id_or_name>`	Integration ID (UUID) or full name, such as `myorg~my-integration`.

connect works only for integrations that use API key authentication. Connect OAuth integrations in the Guild web app.

create

Create a new integration. guild integration create also registers an initial draft version and prints its ID, so you can define operations without running guild integration version create first.

# Create a new integration with API key auth
guild integration create my-service \
  --base-url https://api.example.com \
  --auth-scheme api-key \
  --description "Connect to the Acme API"

# Create with OAuth
guild integration create my-oauth-service \
  --base-url https://api.example.com \
  --auth-scheme oauth \
  --install-url https://example.com/oauth/authorize \
  --token-url https://example.com/oauth/token \
  --client-id <id> --client-secret <secret> \
  --scopes "read,write"

Option	Description
`--auth-scheme <scheme>`	Authentication scheme: `api-key` or `oauth`.
`--base-url <url>`	Base URL for all API requests.
`--client-id <id>`	OAuth client ID.
`--client-secret <secret>`	OAuth client secret.
`--description <text>`	What the integration does.
`--header-template <template>`	Header template for API key auth. Defaults to `X-API-Key: {token}`.
`--install-url <url>`	OAuth authorization endpoint.
`--owner <account>`	Owner account name or ID. Defaults to the current user.
`--public`	Make the integration visible to all users.
`--scopes <scopes>`	Comma-separated OAuth scopes.
`--token-url <url>`	OAuth token exchange endpoint.
`--webhook-events <events>`	Enable webhooks, with the events given as JSON.

Argument	Description
`<name>`	The integration name.

Guild validates the --base-url, --install-url, and --token-url values to prevent server-side request forgery (SSRF). Private network ranges, loopback addresses (such as localhost or 127.0.0.1), and internal DNS names are blocked. For local development, expose your service using a tunneling tool such as ngrok or Localtunnel and use the public URL.

get

Get an integration’s details.

guild integration get <id_or_name>   # Get integration details

Argument	Description
`<id_or_name>`	Integration ID or full name, such as `owner~name`.

list

List integrations. Without --owner, the command lists all integrations.

guild integration list                                          # List integrations
guild integration list --search "deploy"                        # Search by name or description
guild integration list --published                              # Only show published integrations
guild integration list --owner myorg --include-archived         # Include an owner's archived integrations

Option	Description
`--include-archived`	Include the owner’s archived integrations. Requires `--owner`.
`--limit <number>`	Number of results to return. Defaults to `20`.
`--offset <number>`	Offset for pagination. Defaults to `0`.
`--owner <account>`	Only list integrations owned by this account name or ID.
`--published`	Only show integrations with at least one published version.
`--search <query>`	Search integrations by name or description.
`--sort <field>`	Sort by `updated`, `newest`, or `name`. Defaults to `updated`.

operation

Manage the operations (endpoints) on an integration version. Both subcommands use the latest version unless you pass --version-number.

operation create

Add operations to an integration version, one at a time or imported from an OpenAPI spec.

# Add an operation manually
guild integration operation create myorg~my-service \
  --operation list_users \
  --method GET \
  --path /users \
  --summary "List all users"

# Import operations from an OpenAPI spec
guild integration operation create myorg~my-service --openapi ./openapi.yaml

Option	Description
`--input-body-schema <file>`	Path to a JSON file with the request body schema.
`--method <method>`	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
`--openapi <file>`	Path to an OpenAPI spec file, in YAML or JSON.
`--operation <name>`	Operation identifier, such as `list_users`.
`--output-body-schema <file>`	Path to a JSON file with the response body schema.
`--path <path>`	REST path, such as `/{owner}/{repo}/issues`.
`--summary <text>`	Short description of the operation.
`--tags <tags>`	Comma-separated tags, such as `users,admin`.
`--version-number <semver>`	The version to add operations to, such as `1.0.0`. Defaults to the latest version.

Argument	Description
`<id_or_name>`	Integration ID or full name, such as `owner~name`.

Without --openapi, you need --operation, --method, and --path. In an interactive terminal, the CLI prompts for any you leave out. With --openapi, Guild generates the operations asynchronously. Run guild integration operation list to check the results.

operation list

List the operations on an integration version.

guild integration operation list <id_or_name>                          # Operations on the latest version
guild integration operation list <id_or_name> --version-number 1.0.0   # Operations on a specific version

Option	Description
`--limit <number>`	Number of results to return. Defaults to `100`.
`--offset <number>`	Offset for pagination. Defaults to `0`.
`--version-number <semver>`	The version to list, such as `1.0.0`. Defaults to the latest version.

Argument	Description
`<id_or_name>`	Integration ID or full name, such as `owner~name`.

search

Search integrations.

guild integration search <query>                          # Search integrations
guild integration search <query> --sort newest            # Sort by: updated, newest, name
guild integration search <query> --published              # Only show published integrations
guild integration search <query> --limit 10 --offset 20   # Paginate results

Option	Description
`--limit <number>`	Number of results to return. Defaults to `20`.
`--offset <number>`	Offset for pagination. Defaults to `0`.
`--published`	Only show integrations with at least one published version.
`--sort <field>`	Sort by `updated`, `newest`, or `name`. Defaults to `updated`.

Argument	Description
`<query>`	The search query.

unarchive

Restore an archived integration.

guild integration unarchive myorg~my-service   # Unarchive an integration

Argument	Description
`<id_or_name>`	Integration ID or full name, such as `owner~integration-name`.

update

Update an integration’s settings.

guild integration update myorg~my-service --description "Updated description"   # Update the description
guild integration update myorg~my-service --no-public                           # Make the integration private

Option	Description
`--client-secret <secret>`	Update the OAuth client secret.
`--description <text>`	Update the description.
`--header-template <template>`	Update the API key header template.
`--install-url <url>`	Update the OAuth authorization URL.
`--no-public`	Make the integration private.
`--public`	Make the integration public.
`--token-url <url>`	Update the OAuth token URL.
`--webhook-events <events>`	Update the webhook events, given as JSON.

Argument	Description
`<id_or_name>`	Integration ID or full name.

The same SSRF validation described under create applies to --install-url and --token-url.

Publishing freezes the endpoint URL, and the OAuth authorization and token URLs with it. Until the integration’s first version is published, the owner can still change them — nothing is installed against the integration yet. Once a version is published, users install credentials against those URLs, so Guild refuses to let the owner repoint them at another server. The whole update is rejected with a 403, not just the URL field, so a request that changes a URL alongside other settings saves none of them. To serve a different endpoint, create a new integration.

version

Manage integration versions. Unless noted, subcommands that accept --version-number use the latest version when you leave it out.

version build

Build (validate) a draft version and assign it a semantic version number.

guild integration version build <id_or_name> --version-number 1.0.0   # Validate the latest draft

Option	Description
`--version-number <semver>`	Required. The semantic version number to assign, such as `1.0.0`.

Argument	Description
`<id_or_name>`	Integration full name (`owner~name`), which uses the latest draft, or a version UUID.

version create

Create a new draft version.

guild integration version create <id_or_name>   # Create a draft version

Argument	Description
`<id_or_name>`	Integration ID or full name.

version get

Get a version’s details.

guild integration version get <id_or_name>                          # Latest version details
guild integration version get <id_or_name> --version-number 1.0.0   # A specific version

Option	Description
`--version-number <semver>`	The version to get, such as `1.0.0`. Defaults to the latest version.

Argument	Description
`<id_or_name>`	Integration ID or full name, such as `owner~name`.

version list

List an integration’s versions.

guild integration version list <id_or_name>   # List versions

Option	Description
`--limit <number>`	Number of results to return. Defaults to `20`.
`--offset <number>`	Offset for pagination. Defaults to `0`.

Argument	Description
`<id_or_name>`	Integration ID or full name.

version publish

Publish a built version. The command waits until the version is published.

guild integration version publish <id_or_name> --version-number 1.0.0   # Publish a built version

Option	Description
`--version-number <semver>`	The version to publish, such as `1.0.0`. Defaults to the latest version.

Argument	Description
`<id_or_name>`	Integration ID or full name, such as `owner~name`.

Publishing freezes the integration’s endpoint and OAuth URLs. See update.

version test

Test an operation on an integration version. The command prints the request URL and the response status.

guild integration version test myorg~my-service \
  --operation list_users \
  --account my-account \
  --input-query '{"limit": 10}'

Option	Description
`--account <name>`	The account name to resolve the credential from.
`--input-body <json>`	JSON object for the request body.
`--input-path <json>`	JSON object of path parameters.
`--input-query <json>`	JSON object of query parameters.
`--operation <name>`	Required. The operation to test, such as `list_users`.
`--version-number <semver>`	The version to test, such as `1.0.0`. Defaults to the latest version.

Argument	Description
`<id_or_name>`	Integration ID or full name, such as `owner~name`.

​archive

​connect

​create

​get

​list

​operation

​operation create

​operation list

​search

​unarchive

​update

​version

​version build

​version create

​version get

​version list

​version publish

​version test

archive

connect

create

get

list

operation

operation create

operation list

search

unarchive

update

version

version build

version create

version get

version list

version publish

version test