Terminal
Terminal/Skill
Generates a new SDK from an OpenAPI spec or registry source in languages like TypeScript, Python, Go, or Java, using the Speakeasy quickstart command.
By Speakeasy
Works with
npx skills add speakeasy-api/sdk-generation-skills --skill start-new-sdk-projectAlways use speakeasy quickstart to initialize a new SDK project. This is the ONLY correct command for new projects - it creates both the SDK and the essential .speakeasy/workflow.yaml configuration file.
⚠️ Never use
speakeasy generate sdkfor new projects - it does not create the workflow file needed for maintainable SDK development.
.speakeasy/workflow.yaml exists yet| Input | Required | Description |
|---|---|---|
| OpenAPI spec | Yes | Local file, URL, or registry source |
| Target language | Yes | typescript, python, go, java, csharp, php, ruby, kotlin, terraform |
| SDK name | Yes (non-interactive) | PascalCase name (e.g., AcmeSDK) |
| Package name | Yes (non-interactive) | Package identifier (e.g., acme-sdk) |
| Output | Location |
|---|---|
| Workflow config | .speakeasy/workflow.yaml |
| Generated SDK | Output directory (default: current dir) |
For non-interactive environments (CI/CD, automation), set:
export SPEAKEASY_API_KEY="<your-api-key>"
Run speakeasy auth login to authenticate interactively, or set the SPEAKEASY_API_KEY environment variable.
speakeasy quickstart --skip-interactive --output console -s <schema> -t <target> -n <name> -p <package-name>
| Flag | Short | Description |
|---|---|---|
--skip-interactive | Required for automation. Skips all prompts | |
--schema | -s | OpenAPI spec source (see Schema Sources below) |
--target | -t | Target language (see Supported Targets) |
--name | -n | SDK name in PascalCase (e.g., MyCompanySDK) |
--package-name | -p | Package name (language variants auto-inferred) |
--out-dir | -o | Output directory (default: current dir) |
--output | Output format: summary, console, mermaid. Use console for automation | |
--init-git | Initialize git repo (omit to skip in non-interactive mode) |
The --schema flag accepts multiple source types:
| Type | Format | Example |
|---|---|---|
| Local file | Path | ./api/openapi.yaml |
| URL | HTTP(S) | https://api.example.com/openapi.json |
| Registry source | source-name | my-api |
| Registry source (tagged) | source-name@tag | my-api@latest |
| Registry source (full) | org/workspace/source@tag | acme/prod/my-api@v2 |
Registry sources are OpenAPI specs you manage in your Speakeasy workspace. Use speakeasy pull --list --format json to see available sources. This lets you generate SDKs from specs managed in Speakeasy without needing local files.
| Language | Target Flag |
|---|---|
| TypeScript | typescript |
| Python | python |
| Go | go |
| Java | java |
| C# | csharp |
| PHP | php |
| Ruby | ruby |
| Kotlin | kotlin |
| Terraform | terraform |
# From local OpenAPI file
speakeasy quickstart --skip-interactive --output console \
-s ./api/openapi.yaml \
-t typescript \
-n "AcmeSDK" \
-p "acme-sdk"
# From URL
speakeasy quickstart --skip-interactive --output console \
-s "https://api.example.com/openapi.json" \
-t python \
-n "AcmeSDK" \
-p "acme-sdk"
# From registry source (managed in your Speakeasy workspace)
speakeasy quickstart --skip-interactive --output console \
-s "my-api@latest" \
-t go \
-n "AcmeSDK" \
-p "acme-sdk"
# With custom output directory and git init
speakeasy quickstart --skip-interactive --output console \
-s ./api/openapi.yaml \
-t python \
-n "AcmeSDK" \
-p "acme-sdk" \
-o ./sdks/python \
--init-git
.speakeasy/workflow.yaml.speakeasy/workflow.yaml for multi-language supportspeakeasy run to regenerate after spec or config changes| Command | Purpose |
|---|---|
speakeasy quickstart ... | Initialize new SDK project |
speakeasy run -y --output console | Regenerate SDK from workflow |
speakeasy lint openapi --non-interactive -s spec.yaml | Validate OpenAPI spec |
speakeasy auth login | Authenticate with Speakeasy |
speakeasy pull --list --format json | List registry sources |
Do NOT use speakeasy generate sdk for new projects. This low-level command generates code but does NOT create .speakeasy/workflow.yaml. Without a workflow file, you lose:
speakeasy runDo NOT skip --skip-interactive in automated environments. The command will hang waiting for user input.
Do NOT omit --output console in automated environments. You need structured output to verify success.
| Command | Creates workflow.yaml | Use case |
|---|---|---|
speakeasy quickstart | ✅ Yes | New projects - Always use this |
speakeasy generate sdk | ❌ No | One-off generation (rare, advanced use only) |
Always use quickstart for new SDK projects. The workflow file it creates is essential for maintainable SDK development.
| Error | Cause | Solution |
|---|---|---|
| Workflow already exists | .speakeasy/workflow.yaml already present | Run speakeasy run to regenerate the existing SDK instead |
| Unauthorized | Missing or invalid API key | Run speakeasy auth login or set SPEAKEASY_API_KEY |
| Schema not found | Invalid path, URL, or source name | Verify path exists or use speakeasy pull --list for sources |
diagnose-generation-failure - When generation failsmanage-openapi-overlays - Customize spec with overlaysconfigure-sdk-options - Language-specific gen.yaml configuration for all supported languages