Generate a package from a spec URL
From a public OpenAPI or GraphQL URL to a typed package in a directory, with or without an account. The commands, then why each one.
Quick reference
npm install -g typeship-ax # or npx -y typeship-ax@latest ...
typeship generate run --spec '{"url":"https://api.acme.example.com/openapi.json"}' \
--language typescript --platforms '["sdk","cli"]' --out sdk/acme # no key needed
cd sdk/acme && npm install && npm test # TypeScript: build + one smoke test per operationWith a key in TYPESHIP_TOKEN, the same command generates the whole spec instead of the first 25 operations.
Why these commands
generate run is stateless. It runs the generator on the spec and returns the package. Nothing is stored, so it is the right call for a one-off, an evaluation, or a script that commits the output itself. --out writes the files where you point it and prints a summary (meta, warnings, limits, claim) instead of the file contents; without --out the whole package comes back as JSON.
Anonymous is fine to start. Without a key the first 25 operations generate, 20 calls a minute per address. The response's limits object says how many operations were left out; claim.url is a link that turns this run into a linked project once you sign in, so nothing is lost by starting without an account.
Pick the language first, then platforms. --language is typescript, python, or go. The CLI and MCP server are TypeScript artifacts, so --platforms with cli or mcp only applies there; Python and Go produce the SDK alone.
Read the warnings once. They name what the spec left out or what was approximated (a relative server URL, a security scheme that did not map, an operation without an id). Most are fixed in the spec or with a spec patch, not by hand in the output.
Verify before you depend on it. A TypeScript package builds and ships one smoke test per operation (npm test against the spec's shapes, no network); Python compiles (python -m compileall); Go builds (go build ./...). The package's own AGENTS.md and api.md are the reference for what you generated.
What can go wrong
| You see | It means | Do |
|---|---|---|
fetch_error | typeship could not fetch the URL (auth, 404, timeout) | Make the spec public, or paste it: --spec "{\"inline\":$(jq -Rs . < openapi.yaml)}" |
spec_error / SPEC_INVALID | the document is not a usable spec | Debug a spec |
limits.omitted_operations > 0 | the anonymous or free cap | Sign in; a key generates the whole spec |
RATE_LIMITED | more than 20 anonymous calls a minute | Wait the seconds named; or send a key |
claim.url, give it to the user. Report what was generated, where, and the warnings in one line.Generate from GraphQL
A GraphQL schema generates the same package as an OpenAPI spec, on the same runtime: queries on client.query, mutations on client.mutation, typed selections, connections that auto-paginate.
Add typeship to an existing API repository
The repository already has the API and its spec. Put the generated package beside it, wire a linked project, and let pull requests keep it current.