SKILL.md
start-new-sdk-project
Use speakeasy quickstart to initialize a new SDK project with workflow configuration and generate the SDK.
When to Use
- Starting a brand new SDK project
- No
.speakeasy/workflow.yaml exists yet
- First-time Speakeasy setup
- User says: "create SDK", "new SDK", "quickstart", "get started with Speakeasy"
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, AI agents), set:
export SPEAKEASY_API_KEY="<your-api-key>"
Run speakeasy auth login to authenticate interactively, or set the SPEAKEASYAPIKEY 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 AI agents. 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 AI agents |
--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
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 SPEAKEASYAPIKEY |
| Schema not found |
Invalid path, URL, or source name |
Verify path exists or use speakeasy pull --list for sources |
