cli.md

CLI reference

Install @openmirai/typeforge from npmjs. Add a script so the binary resolves from node_modules/.bin:

{
  "scripts": {
    "generate:types": "typeforge generate --all"
  }
}

Install

Package manager	Command
npm	npm install --save-dev @openmirai/typeforge
pnpm	pnpm add -D @openmirai/typeforge
yarn	yarn add -D @openmirai/typeforge
bun	bun add -d @openmirai/typeforge

Commands × package managers

Replace <args> with the flags for that subcommand (see below).

Subcommand	npm	pnpm	yarn	bun
init <args>	npx typeforge init <args>	pnpm exec typeforge init <args>	yarn typeforge init <args>	bunx typeforge init <args>
generate <args>	npx typeforge generate <args>	pnpm exec typeforge generate <args>	yarn typeforge generate <args>	bunx typeforge generate <args>
check <args>	npx typeforge check <args>	pnpm exec typeforge check <args>	yarn typeforge check <args>	bunx typeforge check <args>
accept-base <args>	npx typeforge accept-base <args>	pnpm exec typeforge accept-base <args>	yarn typeforge accept-base <args>	bunx typeforge accept-base <args>

Recommended day-to-day: npm run generate:types (or the equivalent for your package manager).

Subcommands

init

typeforge init --source <key> --client axios|fetch|custom [--layout monolith|packages]

Creates http.ts, known-types.ts, source.ts, and generated/ under apiRoot.

generate

typeforge generate --source <key> [--source <key2> ...] [--spec <path>] [--check] [--accept-base]
typeforge generate --all [--check] [--accept-base]

--all walks every directory under apiRoot that contains source.ts.

check

Shorthand for generate --check. Exits with code 1 when generated files would change.

accept-base

Updates generated/base.ts and patches models.ts BaseResponse to match the spec envelope.

Common flags

Flag	Applies to	Meaning
--source <key>	init, generate, check, accept-base	Source directory name under apiRoot
--all	generate	Generate every source
--spec <path>	generate, check, accept-base	Override spec path for this run
--check	generate	Drift check only; do not write files
--accept-base	generate	Accept envelope base type drift
--client axios|fetch|custom	init	HTTP adapter template
--layout monolith|packages	init	Default apiRoot layout

--check and --accept-base cannot be used together.

Spec resolution order

1. --spec <path>
2. Environment variable OPENAPI_SPEC_<KEY> (key uppercased, - → _)
3. spec field in <apiRoot>/<key>/source.ts
4. typeforge.local.json (gitignored)
5. <apiRoot>/<key>/spec.json snapshot

Type-safe source.ts

import { defineSourceConfig } from "@openmirai/typeforge";

export default defineSourceConfig({
  spec: "./specs/acme.json",
  pathPrefix: "/api/acme/v3",
  generationMode: "authoritative",
  naming: "path",
});

The CLI reads source.ts at generate time (including defineSourceConfig(...) wrappers). Use synthetic paths like /api/acme/v3 in examples and tests.