CLI Reference

The Typeweaver CLI reads a spec entrypoint, normalizes it, runs generation plugins, and writes the generated output directory.

Main command

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated

Global flags

Flag	Meaning
`--help`	Show available commands and options
`--version`	Print the installed CLI version

`generate`

Syntax

npx typeweaver generate [options]

Options

Option	Meaning
`-i, --input <inputPath>`	Path to the spec entrypoint file
`-o, --output <outputDir>`	Output directory for generated files
`-c, --config <configFile>`	Path to a config file: `.js`, `.mjs`, or `.cjs`
`-p, --plugins <plugins>`	Comma-separated plugin list, such as `clients,hono`
`--format` / `--no-format`	Enable or disable formatting of generated output
`--clean` / `--no-clean`	Clean the output directory before generation

Defaults:

format: true — uses oxfmt for formatting generated output
clean: true

Input behavior

--input points to a file, not a directory.

Typical example:

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated

The CLI bundles the entrypoint with rolldown into a single JavaScript file at <output>/spec/spec.js, then dynamically imports it. This means your spec file can use TypeScript and import from other local files — they are resolved at bundle time.

The bundled module accepts any of these export styles:

export const spec = defineSpec(...)
export default defineSpec(...)
module namespace that resolves directly to the spec object

Plugin behavior

The types plugin is always loaded automatically as the foundation for all generation. You do not need to specify it.

Plugin configuration in config files

In a config file, plugins can be plain strings or [name, options] tuples when a plugin accepts configuration:

export default {
  input: "./api/spec/index.ts",
  output: "./api/generated",
  plugins: ["clients", ["hono", { someOption: true }]],
};

CLI examples

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients,hono

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients,server,aws-cdk

Important notes:

the types plugin is always included as the foundation for generation
extra plugins are loaded by name
plugin dependencies control execution order

Config files

Use a JavaScript config file when you want a repeatable command.

// typeweaver.config.mjs
export default {
  input: "./api/spec/index.ts",
  output: "./api/generated",
  plugins: ["clients", "hono"],
  format: true,
  clean: true,
};

Then run:

npx typeweaver generate --config ./typeweaver.config.mjs

Supported config export styles

Choose one:

export default { ... }
export const config = { ... }

Do not export both from the same file.

Supported config file types

Supported:

.js
.mjs
.cjs

Not supported:

.ts
.mts
.cts

If you previously used a TypeScript config file, convert it to JavaScript before passing it to --config.

CLI overrides config

When you provide both a config file and CLI flags, the CLI flags win.

For example:

npx typeweaver generate --config ./typeweaver.config.mjs --output ./api/generated-ci --no-format

In that run:

output becomes ./api/generated-ci
format becomes false
other values still come from the config file unless overridden

Common commands

Generate clients for local development

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients

Generate server integration and clients together

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients,server

Generate from config in CI

npx typeweaver generate --config ./typeweaver.config.mjs

Keep the output directory between runs

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --no-clean

About `init`

The CLI exposes an init command name, but it is currently not implemented as a real project scaffolder. Do not plan around it yet.