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. Checked against the source repository, which is the authority where it and this page disagree.
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.
The ideas you need to hold to use it, and the ones that cost time when nobody told you.
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.
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.
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.
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.
Commands and API calls are as the component's own documentation gives them. Every example marked with a source is copied from that public repository, so it can be checked rather than trusted.
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.
# 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 testTargets and features can also be named at scaffold time with -t ts,py,go and -f test, which collapses steps 1 and 2.
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.
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)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.
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, versionBoth 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.
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 packageThe lookup tables. The first-party documentation below goes deeper on every row.
| Name | What it is |
|---|---|
.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. |
| Name | What it is |
|---|---|
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. |
This page summarises at the altitude a decision needs. These go all the way down, and they are the authority.
The toolchain is MIT and open, and the catalog holds 600+ generated SDKs readable without installing anything.