guild integration

Build and manage custom integrations.

Discovery and management

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 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
guild integration get <id_or_name>            # Get integration details

Creating and updating

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"

# Update an existing integration
guild integration update myorg~my-service --description "Updated description"

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.

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.

Connecting credentials

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

versions

guild integration version list <id_or_name>                 # List versions
guild integration version create <id_or_name>               # Create a draft version
guild integration version get <id_or_name>                  # Get latest version details
guild integration version get <id_or_name> --version-number 1.0.0

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

Operations (endpoints)

# List operations on a version
guild integration operation list <id_or_name>
guild integration operation list <id_or_name> --version-number 1.0.0

# Add operations 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

Testing

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

​Discovery and management

​Creating and updating

​Connecting credentials

​versions

​Operations (endpoints)

​Testing

Discovery and management

Creating and updating

Connecting credentials

versions

Operations (endpoints)

Testing