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
1---2name: start-new-sdk-project3description: Use when generating a new SDK from an OpenAPI spec. This is the PRIMARY skill for SDK generation. Triggers on "create SDK", "generate SDK", "new SDK", "quickstart", "TypeScript SDK", "Python SDK", "Go SDK", "Java SDK", "generate TypeScript", "generate Python", "generate Go", "make SDK", "build SDK", "SDK from OpenAPI", "SDK from spec", "initialize SDK project".4license: Apache-2.05---67# start-new-sdk-project89**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.1011> ⚠️ **Never use `speakeasy generate sdk` for new projects** - it does not create the workflow file needed for maintainable SDK development.1213## When to Use1415- Generating any SDK from an OpenAPI spec (TypeScript, Python, Go, Java, etc.)16- Starting a brand new SDK project17- No `.speakeasy/workflow.yaml` exists yet18- First-time Speakeasy setup19- User says: "generate SDK", "TypeScript SDK", "Python SDK", "Go SDK", "create SDK", "new SDK"2021## Inputs2223| Input | Required | Description |24|-------|----------|-------------|25| OpenAPI spec | Yes | Local file, URL, or registry source |26| Target language | Yes | typescript, python, go, java, csharp, php, ruby, kotlin, terraform |27| SDK name | Yes (non-interactive) | PascalCase name (e.g., `AcmeSDK`) |28| Package name | Yes (non-interactive) | Package identifier (e.g., `acme-sdk`) |2930## Outputs3132| Output | Location |33|--------|----------|34| Workflow config | `.speakeasy/workflow.yaml` |35| Generated SDK | Output directory (default: current dir) |3637## Prerequisites3839For non-interactive environments (CI/CD, automation), set:40```bash41export SPEAKEASY_API_KEY="<your-api-key>"42```43Run `speakeasy auth login` to authenticate interactively, or set the `SPEAKEASY_API_KEY` environment variable.4445## Command4647```bash48speakeasy quickstart --skip-interactive --output console -s <schema> -t <target> -n <name> -p <package-name>49```5051## Flags5253| Flag | Short | Description |54|------|-------|-------------|55| `--skip-interactive` | | **Required for automation.** Skips all prompts |56| `--schema` | `-s` | OpenAPI spec source (see Schema Sources below) |57| `--target` | `-t` | Target language (see Supported Targets) |58| `--name` | `-n` | SDK name in PascalCase (e.g., `MyCompanySDK`) |59| `--package-name` | `-p` | Package name (language variants auto-inferred) |60| `--out-dir` | `-o` | Output directory (default: current dir) |61| `--output` | | Output format: `summary`, `console`, `mermaid`. **Use `console` for automation** |62| `--init-git` | | Initialize git repo (omit to skip in non-interactive mode) |6364## Schema Sources6566The `--schema` flag accepts multiple source types:6768| Type | Format | Example |69|------|--------|---------|70| Local file | Path | `./api/openapi.yaml` |71| URL | HTTP(S) | `https://api.example.com/openapi.json` |72| Registry source | `source-name` | `my-api` |73| Registry source (tagged) | `source-name@tag` | `my-api@latest` |74| Registry source (full) | `org/workspace/source@tag` | `acme/prod/my-api@v2` |7576**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.7778## Supported Targets7980| Language | Target Flag |81|----------|-------------|82| TypeScript | `typescript` |83| Python | `python` |84| Go | `go` |85| Java | `java` |86| C# | `csharp` |87| PHP | `php` |88| Ruby | `ruby` |89| Kotlin | `kotlin` |90| Terraform | `terraform` |9192## Example9394```bash95# From local OpenAPI file96speakeasy quickstart --skip-interactive --output console \97 -s ./api/openapi.yaml \98 -t typescript \99 -n "AcmeSDK" \100 -p "acme-sdk"101102# From URL103speakeasy quickstart --skip-interactive --output console \104 -s "https://api.example.com/openapi.json" \105 -t python \106 -n "AcmeSDK" \107 -p "acme-sdk"108109# From registry source (managed in your Speakeasy workspace)110speakeasy quickstart --skip-interactive --output console \111 -s "my-api@latest" \112 -t go \113 -n "AcmeSDK" \114 -p "acme-sdk"115116# With custom output directory and git init117speakeasy quickstart --skip-interactive --output console \118 -s ./api/openapi.yaml \119 -t python \120 -n "AcmeSDK" \121 -p "acme-sdk" \122 -o ./sdks/python \123 --init-git124```125126## What It Creates1271281. **Workflow configuration**: `.speakeasy/workflow.yaml`1292. **Generated SDK**: Full SDK in the output directory, ready to use130131## Next Steps After Quickstart1321331. Review the generated SDK in the output directory1342. Add more targets to `.speakeasy/workflow.yaml` for multi-language support1353. Run `speakeasy run` to regenerate after spec or config changes136137## Essential CLI Commands138139| Command | Purpose |140|---------|---------|141| `speakeasy quickstart ...` | Initialize new SDK project |142| `speakeasy run -y --output console` | Regenerate SDK from workflow |143| `speakeasy lint openapi --non-interactive -s spec.yaml` | Validate OpenAPI spec |144| `speakeasy auth login` | Authenticate with Speakeasy |145| `speakeasy pull --list --format json` | List registry sources |146147## What NOT to Do148149- **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:150 - Reproducible builds via `speakeasy run`151 - Multi-target SDK generation152 - CI/CD integration153 - Version tracking and upgrade paths154155- **Do NOT skip `--skip-interactive`** in automated environments. The command will hang waiting for user input.156157- **Do NOT omit `--output console`** in automated environments. You need structured output to verify success.158159### quickstart vs generate sdk160161| Command | Creates workflow.yaml | Use case |162|---------|----------------------|----------|163| `speakeasy quickstart` | ✅ Yes | **New projects** - Always use this |164| `speakeasy generate sdk` | ❌ No | One-off generation (rare, advanced use only) |165166**Always use `quickstart` for new SDK projects.** The workflow file it creates is essential for maintainable SDK development.167168## Troubleshooting169170| Error | Cause | Solution |171|-------|-------|----------|172| Workflow already exists | `.speakeasy/workflow.yaml` already present | Run `speakeasy run` to regenerate the existing SDK instead |173| Unauthorized | Missing or invalid API key | Run `speakeasy auth login` or set `SPEAKEASY_API_KEY` |174| Schema not found | Invalid path, URL, or source name | Verify path exists or use `speakeasy pull --list` for sources |175176## Related Skills177178- `diagnose-generation-failure` - When generation fails179- `manage-openapi-overlays` - Customize spec with overlays180- `configure-sdk-options` - Language-specific gen.yaml configuration for all supported languages
speakeasy-api