# 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.

### Install a PR preview

Use the same commit for GenUI and its React peer. Replace `<commit>` with the
commit shown in the PR's pkg.pr.new comment:

```bash
pnpm add --config.blockExoticSubdeps=false \
  https://pkg.pr.new/lynx-family/lynx-stack/@lynx-js/genui@<commit> \
  https://pkg.pr.new/lynx-family/lynx-stack/@lynx-js/react@<commit> \
  @lynx-js/lynx-ui
```

pnpm 11 blocks URL dependencies within packages by default. The flag allows
them for this command without changing your global configuration. Install both
preview URLs explicitly so pnpm does not look for the React preview on npm.
Lynx UI may report a React peer-range warning because preview packages use
`0.0.0-preview-<commit>` versions.

When you create a project with a preview CLI, the generated manifest keeps
pkg.pr.new URLs. Follow the printed install command, which includes the same
flag. Stable releases use npm versions and the normal install command.

### `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 ...`.
