Accorudo
CLI

Import

Generate an Accorudo contract set from an OpenAPI spec.

accorudo import reads an OpenAPI 3.x file and writes a full contract bundle. Each OpenAPI tag becomes a route file; shared schemas become model files.

Basic usage

accorudo import ./openapi/main.yaml --out ./contracts/main

Output:

contracts/main/
├── api.ts                 # Registry: one entry per operation
├── models/
│   ├── widget.ts          # Schemas referenced by widget routes
│   └── common.ts          # Shared response wrappers, pagination
├── routes/
│   ├── widget.ts          # Paths tagged "widget"
│   └── user.ts            # Paths tagged "user"
└── types/                 # Only when the spec has bundle-specific shapes
    └── index.ts

What gets generated

Route files follow the same structure as hand-written contracts:

// routes/widget.ts: generated, then editable

export type WidgetRouteFragment = RouteFragment<"/widget">;
export type IdentifyWidgetRouteFragment = RouteFragment<"/widget/:id", { id: string }>;

export type WidgetListQueryParams = PaginationOptions & {
  name?: string;
};

export type ListWidgetRoute = Route<
  "get",
  WidgetRouteFragment,
  WidgetListQueryParams,
  {},
  CollectionSuccess<WidgetEntity>
>;

Registry keys are derived from operationId when present, otherwise from method + path (listWidget, getWidgetById). Runtime calls still use literal path strings. Keys are for type aggregation only.

Models map OpenAPI $ref schemas to exported types. The generator inlines simple objects and creates named types for reused components.

Filtering by tag

Large specs can be split across bundles:

accorudo import ./openapi/main.yaml \
  --out ./contracts/admin \
  --only admin,moderation

Run separate imports for main, payments, etc., each with its own --out directory.

Preview changes

accorudo import ./openapi/main.yaml --out ./contracts/main --dry-run

Example output:

accorudo import: dry run

  create  contracts/main/api.ts
  create  contracts/main/routes/widget.ts
  create  contracts/main/routes/user.ts
  create  contracts/main/models/widget.ts
  update  contracts/main/models/common.ts   (pagination schema changed)

  4 create · 1 update · 0 skip

Re-importing updates existing files where the spec changed and leaves untouched routes alone when the spec is identical.

After import

  1. Scan generated route and model files for naming you want to adjust.
  2. Register is automatic. api.ts is rewritten each run.
  3. Replace generic response wrappers with project-specific types from ~/types/* where applicable.
  4. Commit the bundle; wire accorudo/client as usual.

Import is a scaffold. Hand-edited routes survive re-import when their OpenAPI operation unchanged. Generated types include @openapi.* comments; see OpenAPI annotations.

Scaffolding

Add models and routes to a contract bundle with the CLI.

Export

Generate an OpenAPI spec from Accorudo contracts.

Copyright © 2026