Orchestrate Multi-Target SDKs Skill

Orchestrate Multi-Target SDKs

Generate SDKs for multiple languages or variants from a single repository using CLI commands.

When to Use

Generating SDKs for multiple languages from the same API spec
Creating SDK variants (Azure, GCP, regional) from different specs
Setting up an SDK monorepo
User says: "generate SDKs for multiple languages", "SDK for each language", "multi-target"

Quick Start: Multiple Languages

Always use CLI commands. Never create .speakeasy directories manually.

# Step 1: Initialize first target (creates .speakeasy/workflow.yaml)
speakeasy quickstart --skip-interactive --output console \
  -s openapi.yaml -t typescript -n "MySDK" -p "my-sdk"

# Step 2: Add more language targets using configure
speakeasy configure targets \
  --target-type python \
  --source my-source \
  --output ./sdks/python

speakeasy configure targets \
  --target-type go \
  --source my-source \
  --output ./sdks/go

# Step 3: Generate all SDKs
speakeasy run --output console

CLI Reference

`speakeasy configure sources`

Add a new OpenAPI source to an existing workflow:

speakeasy configure sources \
  --location ./openapi.yaml \
  --source-name my-api

# With authentication header
speakeasy configure sources \
  --location https://api.example.com/openapi.yaml \
  --source-name my-api \
  --auth-header "Authorization"

| Flag | Short | Description | |------|-------|-------------| | --location | -l | OpenAPI document location (file or URL) | | --source-name | -s | Name for the source | | --auth-header | | Authentication header name (optional) | | --output | -o | Output path for compiled source (optional) | | --non-interactive | | Force non-interactive mode |

`speakeasy configure targets`

Add a new SDK target to an existing workflow:

speakeasy configure targets \
  --target-type typescript \
  --source my-api \
  --output ./sdks/typescript

# With all options
speakeasy configure targets \
  --target-type go \
  --source my-api \
  --target-name my-go-sdk \
  --sdk-class-name MyAPI \
  --package-name github.com/myorg/myapi-go \
  --output ./sdks/go

| Flag | Short | Description | |------|-------|-------------| | --target-type | -t | Language: typescript, python, go, java, csharp, php, ruby, terraform | | --source | -s | Name of source to generate from | | --target-name | | Name for the target (defaults to target-type) | | --sdk-class-name | | SDK class name (optional) | | --package-name | | Package name (optional) | | --base-server-url | | Base server URL (optional) | | --output | -o | Output directory (optional) | | --non-interactive | | Force non-interactive mode |

Example: Multi-Language SDKs

Single OpenAPI spec → TypeScript, Python, Go SDKs:

# Initialize with first target
speakeasy quickstart --skip-interactive --output console \
  -s ./openapi.yaml -t typescript -n "MySDK" -p "my-sdk" -o ./sdks/typescript

# Add Python
speakeasy configure targets \
  --target-type python \
  --source my-source \
  --sdk-class-name MySDK \
  --package-name my-sdk \
  --output ./sdks/python

# Add Go
speakeasy configure targets \
  --target-type go \
  --source my-source \
  --sdk-class-name MySDK \
  --package-name github.com/myorg/my-sdk-go \
  --output ./sdks/go

# Generate all
speakeasy run --output console

Example: SDK Variants (Multiple Sources)

Different OpenAPI specs → variant SDKs:

# Initialize with main API
speakeasy quickstart --skip-interactive --output console \
  -s ./openapi.yaml -t typescript -n "MySDK" -p "my-sdk"

# Add Azure variant source
speakeasy configure sources \
  --location ./openapi-azure.yaml \
  --source-name azure-api

# Add Azure target
speakeasy configure targets \
  --target-type typescript \
  --source azure-api \
  --target-name typescript-azure \
  --sdk-class-name MySDKAzure \
  --package-name "@myorg/my-sdk-azure" \
  --output ./packages/azure

# Generate all
speakeasy run --output console

Repository Structure

my-api-sdks/
├── openapi.yaml              # Source spec
├── .speakeasy/
│   └── workflow.yaml         # Multi-target config (created by CLI)
├── sdks/
│   ├── typescript/
│   │   ├── .speakeasy/
│   │   │   └── gen.yaml      # Created by configure
│   │   └── src/
│   ├── python/
│   │   ├── .speakeasy/
│   │   │   └── gen.yaml
│   │   └── src/
│   └── go/
│       ├── .speakeasy/
│       │   └── gen.yaml
│       └── go.mod
└── .github/workflows/
    └── sdk_generation.yaml

Running Generation

# Generate all targets
speakeasy run --output console

# Generate specific target only
speakeasy run -t typescript --output console
speakeasy run -t python --output console

CI Workflow

# .github/workflows/sdk_generation.yaml
name: Generate SDKs
on:
  push:
    branches: [main]
    paths: ['openapi.yaml']
  workflow_dispatch:

jobs:
  generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
    with:
      mode: pr
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}
      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}

What NOT to Do

Do NOT create .speakeasy/ directories manually - Use speakeasy quickstart and speakeasy configure
Do NOT write workflow.yaml or gen.yaml files directly - Use CLI commands
Do NOT copy .speakeasy/ directories between projects - Each needs its own config

Incorrect

# WRONG: Do not do this
mkdir -p .speakeasy
cat > .speakeasy/workflow.yaml << 'EOF'
...
EOF

Correct

# RIGHT: Use CLI commands
speakeasy quickstart --skip-interactive --output console \
  -s openapi.yaml -t typescript -n "MySDK" -p "my-sdk"

speakeasy configure targets --target-type python --source my-source

Troubleshooting

| Issue | Solution | |-------|----------| | Wrong target generated | Specify -t target-name in speakeasy run | | Source not found | Run speakeasy configure sources to add it | | Target not found | Run speakeasy configure targets to add it | | Config out of sync | Run speakeasy run to regenerate |

After Making Changes

After adding sources or targets, regenerate:

speakeasy run --output console

After Making Changes

After modifying workflow.yaml or per-target gen.yaml, prompt the user to regenerate the SDK(s):

Configuration complete. Would you like to regenerate the SDK(s) now with speakeasy run?

If the user confirms, run:

# Generate all targets
speakeasy run --output console

# Or generate a specific target
speakeasy run -t <target-name> --output console

Changes to workflow.yaml and gen.yaml only take effect after regeneration.

Related Skills

start-new-sdk-project - Initial SDK setup for single target
configure-sdk-options - Language-specific gen.yaml options
manage-openapi-overlays - Spec customization with overlays
orchestrate-multi-repo-sdks - Separate repository per language

Agent Skills: Orchestrate Multi-Target SDKs

Install this agent skill to your local

Skill Files