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

Outputs

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 SPEAKEASYAPIKEY environment variable.

Command

speakeasy quickstart --skip-interactive --output console -s <schema> -t <target> -n <name> -p <package-name>

Flags

Schema Sources

The --schema flag accepts multiple source types:

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

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

1. Workflow configuration: .speakeasy/workflow.yaml
2. Generated SDK: Full SDK in the output directory, ready to use

Next Steps After Quickstart

1. Review the generated SDK in the output directory
2. Add more targets to .speakeasy/workflow.yaml for multi-language support
3. Run speakeasy run to regenerate after spec or config changes

Essential CLI Commands

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

Always use quickstart for new SDK projects. The workflow file it creates is essential for maintainable SDK development.

Troubleshooting

Related Skills

• diagnose-generation-failure - When generation fails
• manage-openapi-overlays - Customize spec with overlays
• configure-sdk-options - Language-specific gen.yaml configuration for all supported languages