# create-sdkgen

> Scaffolds a project. The way in. One command turns an OpenAPI spec into a project with the model already built, the targets you asked for already added, and a generate script wired up. Start here unless you are working on the toolchain itself. Part of the Voxgig SDK toolchain. Checked 8 September 2026.

## What it is

create-sdkgen is a scaffolder. It runs apidef over your spec to build the model, creates the project layout around it, adds the targets and features you name, and installs dependencies. What you get is a project you own, not a service you call.

It is the right entry point for building an SDK for your own API. The sdkgen and apidef pages are about the machinery; this one is about using it.

After the scaffold you are in a loop, and it is worth being explicit about which parts of the tree are yours: you edit the model under `.sdk/model/`, run generate, and run the target's tests. Everything under the language directories is output.

## Facts

- Package: @voxgig/create-sdkgen (https://www.npmjs.com/package/@voxgig/create-sdkgen)
- Source: voxgig/create-sdkgen (https://github.com/voxgig/create-sdkgen)
- Licence: MIT
- Runs: apidef, then sdkgen scaffolding
- Needs: an OpenAPI 3 spec, as .yaml or .json

## Concepts

### Commit before you regenerate

Generation three-way merges into an existing generated file by default, and a project can switch to plain overwrite with one line of config, which is what both demo repositories do. Either way an uncommitted experiment in a target directory is at risk, and `voxgig-sdkgen doctor` exists to tell you what a resync would revert. Commit first, and fix bugs in the model, a template or a component rather than in the output.

### The model is where you shape the SDK

Entities, operations and fields all live in `.sdk/model/`. Renaming an entity, dropping an operation you do not want to expose, tightening a type: those are model edits. `.sdk/model/project.aon` is created once and never overwritten, so project-level decisions belong there. The model files beside it are toolchain-derived and refreshed, and apidef merges into your edits rather than clobbering them.

### Your documented examples are tested

Every generated target carries a `readme_examples` test that extracts each code block from that language's `README.md` and `REFERENCE.md`, compiles it, and runs the runnable ones in offline test mode. A documented example that does not work fails that target's build. This is why the examples on this page were copied out of real generated READMEs rather than written by hand.

### Publishing is yours to do

The toolchain generates packages; it does not publish them. When the tests are green, each language package is published the way its ecosystem expects: npm, PyPI, Packagist, RubyGems, LuaRocks, or a Go module tag.

## Examples

### From a spec to a tested SDK

Four steps. The first scaffolds, the second adds targets and offline test mode, the third generates, the fourth proves it. This is the shape both worked examples on this site were built with.

`shell, the four steps`

```bash
# 1. Scaffold a project from your OpenAPI 3 spec
npx @voxgig/create-sdkgen my-api -d ./openapi.yaml -o ./my-api-sdk

# 2. Add the languages you want, plus offline test mode
cd my-api-sdk/.sdk
npx voxgig-sdkgen target add ts py go
npx voxgig-sdkgen feature add test

# 3. Generate (builds the .sdk sources, then runs the generator)
npm run generate

# 4. Verify
cd ../ts && npm install && npm run build && npm test
```

Targets and features can also be named at scaffold time with `-t ts,py,go` and `-f test`, which collapses steps 1 and 2.

### The loop you stay in

After the scaffold, every change follows the same three moves. Nothing here is a one-off: adding an entity, correcting a classification apidef got wrong, and turning on a feature all go through the same loop.

`shell, the regenerate loop`

```bash
git commit -am 'before regenerate'          # generation rewrites ts/, py/, go/

$EDITOR .sdk/model/entity/planet.aon        # shape the SDK here
(cd .sdk && npm run generate)               # regenerate every target

(cd ts && npm test)                         # offline: no server, no credentials
(cd py && python -m pytest)
```

### Options

The scaffolder takes a name, a spec and an output directory, plus the targets and features to add on the way. `--no-install` is the one to reach for in CI or when you want to inspect before anything is fetched.

`shell, the scaffolder options`

```bash
create-sdkgen <name> [options]

  <name>                 SDK name in kebab-case, the package base name
  -d, --def <spec>       OpenAPI 3 spec file (.yaml or .json)
  -o, --folder <dir>     output directory (default: <name>-sdk)
  -t, --target <langs>   targets to add during scaffold, e.g. ts,py,go
  -f, --feature <feats>  features to add, e.g. test
      --no-install       skip npm install
  -h, -v                 help, version
```

### What the two worked examples were built from

Both public demo SDKs on this site came out of this scaffold. solardemo took every target the toolchain has; elementdemo took six and then added a feature of its own. Reading either repository is the fastest way to see what your own project will look like a few steps in.

`shell, reading the worked examples`

```bash
git clone https://github.com/voxgig-sdk/voxgig-solardemo-sdk
git clone https://github.com/voxgig-sdk/voxgig-elementdemo-sdk

# The model is the interesting part; the language directories are output.
ls voxgig-solardemo-sdk/.sdk/model/entity     # moon.aon  planet.aon
ls voxgig-elementdemo-sdk/.sdk/model/feature  # elementcard.aon and four more
ls voxgig-elementdemo-sdk/ext                 # the project's own sdkgen package
```

## Reference

### What the scaffold produces

| | |
| --- | --- |
| `.sdk/` | The project: the model, the generator components and templates, and the generate script. |
| `.sdk/model/project.aon` | Yours. Created once, never overwritten. |
| `.sdk/model/entity/` | One file per entity, from apidef. |
| `<target>/` | One directory per target, all generated output. |
| `README.md` | The top-level README, generated, listing every target. |
| `AGENTS.md` | The guide an agent reads to work on the project. |

### The three moves

| | |
| --- | --- |
| `Edit` | `.sdk/model/` only. The language directories are output. |
| `Generate` | `(cd .sdk && npm run generate)`. |
| `Verify` | Each target's own test command, offline by default. |

## First-party documentation

- [create-sdkgen on GitHub](https://github.com/voxgig/create-sdkgen)
- [AGENTS.md: the complete build guide, spec to publish](https://github.com/voxgig/create-sdkgen/blob/main/AGENTS.md)
- [sdkgen tutorial: generate your first SDK](https://github.com/voxgig/sdkgen/blob/main/docs/tutorial.md)
- [solardemo, the breadth example](https://github.com/voxgig-sdk/voxgig-solardemo-sdk)
- [elementdemo, the depth example](https://github.com/voxgig-sdk/voxgig-elementdemo-sdk)

## The rest of the toolchain

- [The toolchain documentation index](https://voxgig.com/sdk/docs): the pipeline, the components, and the two worked examples.
- [sdkgen](https://voxgig.com/sdk/docs/sdkgen): Turns the model into SDKs.
- [apidef](https://voxgig.com/sdk/docs/apidef): Turns a spec into a model.
- [docgen](https://voxgig.com/sdk/docs/docgen): Generates documentation targets.
- apigen: Not yet published.
- [Voxgig SDK Generator](https://voxgig.com/sdk)