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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: speakeasy-api-skills-start-new-sdk-project3description: start-new-sdk-project4---56# start-new-sdk-project78**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.910> ⚠️ **Never use `speakeasy generate sdk` for new projects** - it does not create the workflow file needed for maintainable SDK development.1112## When to Use1314- Generating any SDK from an OpenAPI spec (TypeScript, Python, Go, Java, etc.)15- Starting a brand new SDK project16- No `.speakeasy/workflow.yaml` exists yet17- First-time Speakeasy setup18- User says: "generate SDK", "TypeScript SDK", "Python SDK", "Go SDK", "create SDK", "new SDK"1920## Inputs2122| Input | Required | Description |23|-------|----------|-------------|24| OpenAPI spec | Yes | Local file, URL, or registry source |25| Target language | Yes | typescript, python, go, java, csharp, php, ruby, kotlin, terraform |26| SDK name | Yes (non-interactive) | PascalCase name (e.g., `AcmeSDK`) |27| Package name | Yes (non-interactive) | Package identifier (e.g., `acme-sdk`) |2829## Outputs3031| Output | Location |32|--------|----------|33| Workflow config | `.speakeasy/workflow.yaml` |34| Generated SDK | Output directory (default: current dir) |3536## Prerequisites3738For non-interactive environments (CI/CD, automation), set:39```bash40export SPEAKEASY_API_KEY="<your-api-key>"41```42Run `speakeasy auth login` to authenticate interactively, or set the `SPEAKEASY_API_KEY` environment variable.4344## Command4546```bash47speakeasy quickstart --skip-interactive --output console -s <schema> -t <target> -n <name> -p <package-name>48```4950## Flags5152| Flag | Short | Description |53|------|-------|-------------|54| `--skip-interactive` | | **Required for automation.** Skips all prompts |55| `--schema` | `-s` | OpenAPI spec source (see Schema Sources below) |56| `--target` | `-t` | Target language (see Supported Targets) |57| `--name` | `-n` | SDK name in PascalCase (e.g., `MyCompanySDK`) |58| `--package-name` | `-p` | Package name (language variants auto-inferred) |59| `--out-dir` | `-o` | Output directory (default: current dir) |60| `--output` | | Output format: `summary`, `console`, `mermaid`. **Use `console` for automation** |61| `--init-git` | | Initialize git repo (omit to skip in non-interactive mode) |6263## Schema Sources6465The `--schema` flag accepts multiple source types:6667| Type | Format | Example |68|------|--------|---------|69| Local file | Path | `./api/openapi.yaml` |70| URL | HTTP(S) | `https://api.example.com/openapi.json` |71| Registry source | `source-name` | `my-api` |72| Registry source (tagged) | `source-name@tag` | `my-api@latest` |73| Registry source (full) | `org/workspace/source@tag` | `acme/prod/my-api@v2` |7475**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.7677## Supported Targets7879| Language | Target Flag |80|----------|-------------|81| TypeScript | `typescript` |82| Python | `python` |83| Go | `go` |84| Java | `java` |85| C# | `csharp` |86| PHP | `php` |87| Ruby | `ruby` |88| Kotlin | `kotlin` |89| Terraform | `terraform` |9091## Example9293```bash94# From local OpenAPI file95speakeasy quickstart --skip-interactive --output console \96 -s ./api/openapi.yaml \97 -t typescript \98 -n "AcmeSDK" \99 -p "acme-sdk"100101# From URL102speakeasy quickstart --skip-interactive --output console \103 -s "https://api.example.com/openapi.json" \104 -t python \105 -n "AcmeSDK" \106 -p "acme-sdk"107108# From registry source (managed in your Speakeasy workspace)109speakeasy quickstart --skip-interactive --output console \110 -s "my-api@latest" \111 -t go \112 -n "AcmeSDK" \113 -p "acme-sdk"114115# With custom output directory and git init116speakeasy quickstart --skip-interactive --output console \117 -s ./api/openapi.yaml \118 -t python \119 -n "AcmeSDK" \120 -p "acme-sdk" \121 -o ./sdks/python \122 --init-git123```124125## What It Creates1261271. **Workflow configuration**: `.speakeasy/workflow.yaml`1282. **Generated SDK**: Full SDK in the output directory, ready to use129130## Next Steps After Quickstart1311321. Review the generated SDK in the output directory1332. Add more targets to `.speakeasy/workflow.yaml` for multi-language support1343. Run `speakeasy run` to regenerate after spec or config changes135136## Essential CLI Commands137138| Command | Purpose |139|---------|---------|140| `speakeasy quickstart ...` | Initialize new SDK project |141| `speakeasy run -y --output console` | Regenerate SDK from workflow |142| `speakeasy lint openapi --non-interactive -s spec.yaml` | Validate OpenAPI spec |143| `speakeasy auth login` | Authenticate with Speakeasy |144| `speakeasy pull --list --format json` | List registry sources |145146## What NOT to Do147148- **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:149 - Reproducible builds via `speakeasy run`150 - Multi-target SDK generation151 - CI/CD integration152 - Version tracking and upgrade paths153154- **Do NOT skip `--skip-interactive`** in automated environments. The command will hang waiting for user input.155156- **Do NOT omit `--output console`** in automated environments. You need structured output to verify success.157158### quickstart vs generate sdk159160| Command | Creates workflow.yaml | Use case |161|---------|----------------------|----------|162| `speakeasy quickstart` | ✅ Yes | **New projects** - Always use this |163| `speakeasy generate sdk` | ❌ No | One-off generation (rare, advanced use only) |164165**Always use `quickstart` for new SDK projects.** The workflow file it creates is essential for maintainable SDK development.166167## Troubleshooting168169| Error | Cause | Solution |170|-------|-------|----------|171| Workflow already exists | `.speakeasy/workflow.yaml` already present | Run `speakeasy run` to regenerate the existing SDK instead |172| Unauthorized | Missing or invalid API key | Run `speakeasy auth login` or set `SPEAKEASY_API_KEY` |173| Schema not found | Invalid path, URL, or source name | Verify path exists or use `speakeasy pull --list` for sources |174175## Related Skills176177- `diagnose-generation-failure` - When generation fails178- `manage-openapi-overlays` - Customize spec with overlays179- `configure-sdk-options` - Language-specific gen.yaml configuration for all supported languages180181---182> Converted and distributed by [TomeVault](https://tomevault.io/claim/speakeasy-api) — claim your Tome and manage your conversions.183<!-- tomevault:4.0:skill_md:2026-04-12 -->
tomevault-io