start-new-sdk-project
Always 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 sdk for new projects - it does not create the workflow file needed for maintainable SDK development.
When to Use
- Generating any SDK from an OpenAPI spec (TypeScript, Python, Go, Java, etc.)
- Starting a brand new SDK project
- No
.speakeasy/workflow.yaml exists yet - First-time Speakeasy setup
- User says: "generate SDK", "TypeScript SDK", "Python SDK", "Go SDK", "create SDK", "new SDK"
Inputs
| 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) |
Outputs
| Output | Location |
|---|
| Workflow config | .speakeasy/workflow.yaml |
| Generated SDK | Output directory (default: current dir) |
Prerequisites
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.
Command
speakeasy quickstart --skip-interactive --output console -s <schema> -t <target> -n <name> -p <package-name>
Flags
| 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) |
Schema Sources
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.
Supported Targets
| Language | Target Flag |
|---|
| TypeScript | typescript |
| Python | python |
| Go | go |
| Java | java |
| C# | csharp |
| PHP | php |
| Ruby | ruby |
| Kotlin | kotlin |
| Terraform | terraform |
Example
# 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
What It Creates
- Workflow configuration:
.speakeasy/workflow.yaml - Generated SDK: Full SDK in the output directory, ready to use
Next Steps After Quickstart
- Review the generated SDK in the output directory
- Add more targets to
.speakeasy/workflow.yaml for multi-language support - Run
speakeasy run to regenerate after spec or config changes
Essential CLI Commands
| 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 |
What NOT to Do
- 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:
- Reproducible builds via speakeasy run - Multi-target SDK generation - CI/CD integration - Version tracking and upgrade paths
- Do 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.
quickstart vs generate sdk
| 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.
Troubleshooting
| 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 |
Related Skills
diagnose-generation-failure - When generation failsmanage-openapi-overlays - Customize spec with overlaysconfigure-sdk-options - Language-specific gen.yaml configuration for all supported languages
