oclif-tsgen.mdc

---
description: OCLIF tsgen command, flags, and delegation to @contentstack/types-generator
alwaysApply: false
globs:
  - src/commands/**
  - src/lib/**
---

# OCLIF `tsgen` command

Scope: **CLI only**. Type generation internals live in the **`@contentstack/types-generator`** package ([npm](https://www.npmjs.com/package/@contentstack/types-generator), [repository](https://github.com/contentstack/types-generator))—do not invent library APIs here.

## Command shape

- Extends **`Command`** from **`@contentstack/cli-command`** ([`src/commands/tsgen.ts`](src/commands/tsgen.ts)).
- **Flags:** e.g. **`token-alias`** (`-a`, required), **`output`** (`-o`), **`prefix`**, **`doc`**, **`branch`**, **`include-system-fields`**, **`include-editable-tags`**, **`include-referenced-entry`**, **`api-type`** (`rest` \| `graphql`), **`namespace`** (GraphQL).
- Use **`this.parse`**, **`this.error`**, **`this.log`** / **`cliux`** / **`log`** from **`@contentstack/cli-utilities`** per existing patterns.

## Auth and stack config

- Resolve token via **`this.getToken(flags["token-alias"])`**. Warn if **`token.type !== "delivery"`** (management token may break Delivery/GraphQL flows).
- Build **`StackConnectionConfig`**: **`apiKey`**, **`token`**, **`region`**, **`environment`**, **`branch`**, **`host`** (CDA host from command context).

## Generation paths

- **`api-type === "graphql"`** → **`graphqlTS(...)`** with delivery token required; pass **`logger: log`** where applicable.
- **REST (default)** → **`generateTS({ ...config, tokenType: "delivery", ... })`**.
- Write result with **`fs.writeFileSync`** to the resolved output path.

## Errors

- Use **`printFormattedError`** from [`src/lib/helper.ts`](src/lib/helper.ts) for consistent CLI messaging; **`process.exit(1)`** on failure paths as in the command today.
- **Terminology:** **Delivery** and **GraphQL** as documented in flags—not **CMA** as the primary path.