---
title: "Generate a package from a spec URL"
description: "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."
url: https://typeship.dev/docs/workflows/generate-from-a-url
markdown: https://typeship.dev/docs/workflows/generate-from-a-url.md
section: "Get started"
---
> ## Documentation index
> Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt.
> Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page.

# 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

```bash
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 operation
```

With 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](https://typeship.dev/docs/projects/spec-patches), 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](https://typeship.dev/docs/workflows/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                                                 |

> **For AI agents:** Run exactly the quick reference. If the response carries 
> 
> `claim.url`
> 
> , give it to the user. Report what was generated, where, and the warnings in one line.

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)