# GenUI CLI

`@lynx-js/genui-cli` is the command line entry point for GenUI workflows. It is
structured by namespace so A2UI and OpenUI workflows can share one package and
binary.

## Usage

```bash
genui <namespace> <command> [options]
```

Available namespaces:

- `a2ui`: generate A2UI catalog artifacts and system prompts.
- `openui`: generate OpenUI system prompts.

The package also exposes `genui-cli` as an alias. `a2ui-cli` remains available as
a compatibility alias for existing A2UI-only scripts.

## A2UI Commands

Create a new A2UI project:

```bash
genui a2ui create my-a2ui-app
```

Generate a system prompt with the built-in A2UI basic catalog:

```bash
genui a2ui generate prompt --out dist/a2ui-system-prompt.txt
```

Generate catalog artifacts for a custom catalog:

```bash
genui a2ui generate catalog \
  --catalog-dir src/catalog \
  --source src/functions \
  --out-dir dist/catalog
```

Generate a system prompt for a custom catalog:

```bash
genui a2ui generate prompt \
  --catalog-dir dist/catalog \
  --catalog-id https://example.com/catalogs/custom/v1/catalog.json \
  --out dist/a2ui-system-prompt.txt
```

`generate prompt` uses the built-in A2UI basic catalog by default. Pass
`--catalog-dir` only when generating a prompt for custom generated catalog
artifacts. When `--catalog-dir` is provided, the directory must contain files
like `<Component>/catalog.json`.

## OpenUI Commands

Generate an OpenUI system prompt:

```bash
genui openui generate prompt --out dist/openui-system-prompt.txt
```

`generate prompt` uses the bundled OpenUI prompt library. Useful options:

- `--out <file>`: write the prompt to a file instead of stdout.
- `--appendix <text>`: append extra instructions to the generated prompt.

### `genui a2ui create`

Creates a new ReactLynx A2UI project from the bundled template.

```bash
genui a2ui create my-a2ui-app
cd my-a2ui-app
pnpm install
pnpm run dev
```

Useful options:

- `[project-name]`: target directory name. Defaults to `my-a2ui-app`.
- `--template <name>`: template to use. Defaults to `default`.

The target directory must be empty. The generated `package.json` replaces the
template workspace dependency placeholders with installable package versions
resolved from the parent `@lynx-js/genui` package metadata.

### `genui a2ui generate catalog`

Delegates catalog extraction to `@lynx-js/genui/a2ui-catalog-extractor`.

Useful options:

- `--catalog-dir <dir>`: directory to scan for TypeScript component catalog
  interfaces. Defaults to `src/catalog`.
- `--source <path>`: source file or directory to scan for catalog functions.
  Repeatable.
- `--typedoc-json <file>`: read an existing TypeDoc JSON project.
- `--out-dir <dir>`: output directory for generated catalog artifacts. Defaults
  to `dist/catalog`.

### `genui a2ui generate prompt`

Delegates prompt construction to `@lynx-js/genui/a2ui-prompt`.

Useful options:

- `--catalog-dir <dir>`: generated catalog artifact directory. Omit this option
  to use the built-in A2UI basic catalog.
- `--catalog-id <id>`: catalog id to require in `createSurface` messages.
  Defaults to the built-in A2UI basic catalog id.
- `--out <file>`: write the prompt to a file instead of stdout.
- `--appendix <text>`: append extra instructions to the generated prompt.

## Compatibility

Existing A2UI commands still work:

```bash
a2ui-cli generate catalog --catalog-dir src/catalog --out-dir dist/catalog
a2ui-cli generate prompt --out dist/a2ui-system-prompt.txt
```

New scripts should prefer `genui a2ui ...`.