Build & Operate

CLI (surface + harness)

opt-cli is an operational CLI that combines Surface search, preview, copy, doctor, and update with harness contract validation.

reopt designUpdated Jun 26, 2026

1. Overview

opt-cli follows the shadcn/ui source-copy model, but extends it with pre-install discovery and operational checks. Core and Shells are imported from @reopt-ai/opt-ui, charts are imported from @reopt-ai/opt-charts, and only Surfaces are copied locally into your project for direct modification.

The current registry includes 38 Surfaces.
The CLI uses the bundled registry.json as the source of truth.
The binary is opt; Surface commands take the form opt surface <cmd>. Harness contract validation is provided separately as opt harness <cmd>.

2. Prerequisites

Surfaces import opt-ui Core/Shells and, when needed, opt-charts internally. Install @reopt-ai/opt-ui and the specialist packages you use in the project, and keep @reopt-ai/opt-cli as a dev dependency when you run the CLI repeatedly.

bash

bun add @reopt-ai/opt-ui
bun add -D @reopt-ai/opt-cli

# 설치 상태 / 프로젝트 정보 확인
npx @reopt-ai/opt-cli surface info

# 통합 상태 점검
npx @reopt-ai/opt-cli surface doctor

3. Discover and inspect

List, search, and inspect detailed metadata before installing. list and search share the same command surface.

bash

# 전체 목록
npx @reopt-ai/opt-cli surface list

# slug / 설명 / tags 검색
npx @reopt-ai/opt-cli surface search --query billing

# source package 기준 필터
npx @reopt-ai/opt-cli surface list --source opt-ui-surface

# 설치된 것만 보기
npx @reopt-ai/opt-cli surface list --installed

# JSON 출력
npx @reopt-ai/opt-cli surface search --query dashboard --json

# 개별 Surface 메타 조회
npx @reopt-ai/opt-cli surface view billing-page
npx @reopt-ai/opt-cli surface view billing-page --json

4. add: pre-install preview and actual copy

add handles both preview and the actual write. Preview variants never write files.

bash

# 기본 설치
npx @reopt-ai/opt-cli surface add billing-page

# 여러 개 한 번에 설치
npx @reopt-ai/opt-cli surface add billing-page analytics-dashboard

# 생성될 파일 내용만 보기
npx @reopt-ai/opt-cli surface add billing-page --view
npx @reopt-ai/opt-cli surface add billing-page --view billing-page.tsx

# 현재 로컬 파일과 registry diff 보기
npx @reopt-ai/opt-cli surface add billing-page --diff

# 실제 write 없이 설치 계획만 보기
npx @reopt-ai/opt-cli surface add billing-page --dry-run

# overwrite prompt 없이 덮어쓰기
npx @reopt-ai/opt-cli surface add billing-page --overwrite

# registry가 요구하는 외부 패키지도 같이 설치
npx @reopt-ai/opt-cli surface add data-explorer --install

5. opt-ui.json v2

On first install, opt-ui.json is created. The v2 schema records per-Surface file targets along with installed hashes so update and doctor can detect local modifications.

json

{
  "$schema": "https://opt-ui.dev/opt-ui.schema.json",
  "schemaVersion": 2,
  "surfacesDir": "components/surfaces",
  "importAlias": "@/components/surfaces",
  "surfaces": [
    {
      "slug": "billing-page",
      "version": "1.0.7",
      "contentHash": "e33ec0c3",
      "installedAt": "2026-03-11",
      "files": [
        {
          "target": "billing-page.tsx",
          "installedContentHash": "e33ec0c3"
        }
      ]
    }
  ]
}

surfacesDir: the root directory where Surfaces are copied
importAlias: the import prefix used in docs and CLI examples
surfaces[].files[]: each target file along with the content hash at the time of installation

6. info / doctor

Use info to inspect installation status, and doctor to check for actual issues.

bash

# package manager, framework, registry version, config 상태
npx @reopt-ai/opt-cli surface info
npx @reopt-ai/opt-cli surface info --json

# blocking issue + warning 검사
npx @reopt-ai/opt-cli surface doctor

# legacy opt-ui.json migration을 저장
npx @reopt-ai/opt-cli surface doctor --fix

Key items doctor checks

Presence of the @reopt-ai/opt-ui dependency
Whether opt-ui.json parses and its schema migration status
Whether installed Surface files are missing or locally modified
Whether @reopt-ai/opt-ui/tailwind.css is imported

7. update workflow

update only overwrites automatically when the last installed hash matches the current local file. If you've made local edits, it stops by default and points you to the diff.

bash

# 전체 installed Surface 업데이트
npx @reopt-ai/opt-cli surface update

# 특정 slug만 업데이트
npx @reopt-ai/opt-cli surface update billing-page

# 로컬 수정본까지 강제로 덮어쓰기
npx @reopt-ai/opt-cli surface update billing-page --force

# 단일 Surface diff 확인
npx @reopt-ai/opt-cli surface add billing-page --diff

# 설치된 Surface 전체 drift 확인
npx @reopt-ai/opt-cli surface diff
npx @reopt-ai/opt-cli surface diff --json --format summary
npx @reopt-ai/opt-cli surface diff --exit-code

8. Harness contract validation

opt harness checks the authored contract that opt-shell runtime screens follow. Static analysis is check, browser fixture validation is test, and environment/version diagnostics are doctor.

bash

# Tier 1: 정적 contract/lint 검사
npx @reopt-ai/opt-cli harness check
npx @reopt-ai/opt-cli harness check --json
npx @reopt-ai/opt-cli harness check --fix
npx @reopt-ai/opt-cli harness check --rule harness/workspace-first

# Tier 2: fixture 기반 런타임 검증
npx @reopt-ai/opt-cli harness test
npx @reopt-ai/opt-cli harness test --fixture ./harness.fixtures.ts

# 환경/버전/contract 진단
npx @reopt-ai/opt-cli harness doctor
npx @reopt-ai/opt-cli harness doctor --fix

9. Post-install structure

text

my-app/
├── components/
│   └── surfaces/
│       └── billing-page.tsx
├── opt-ui.json
└── package.json

Build & Operate

CLI (surface + harness)

opt-cli is an operational CLI that combines Surface search, preview, copy, doctor, and update with harness contract validation.

reopt designUpdated Jun 26, 2026

1. Overview

The current registry includes 38 Surfaces.
The CLI uses the bundled registry.json as the source of truth.
The binary is opt; Surface commands take the form opt surface <cmd>. Harness contract validation is provided separately as opt harness <cmd>.

2. Prerequisites

bash

bun add @reopt-ai/opt-ui
bun add -D @reopt-ai/opt-cli

# 설치 상태 / 프로젝트 정보 확인
npx @reopt-ai/opt-cli surface info

# 통합 상태 점검
npx @reopt-ai/opt-cli surface doctor

3. Discover and inspect

List, search, and inspect detailed metadata before installing. list and search share the same command surface.

bash

# 전체 목록
npx @reopt-ai/opt-cli surface list

# slug / 설명 / tags 검색
npx @reopt-ai/opt-cli surface search --query billing

# source package 기준 필터
npx @reopt-ai/opt-cli surface list --source opt-ui-surface

# 설치된 것만 보기
npx @reopt-ai/opt-cli surface list --installed

# JSON 출력
npx @reopt-ai/opt-cli surface search --query dashboard --json

# 개별 Surface 메타 조회
npx @reopt-ai/opt-cli surface view billing-page
npx @reopt-ai/opt-cli surface view billing-page --json

4. add: pre-install preview and actual copy

add handles both preview and the actual write. Preview variants never write files.

bash

# 기본 설치
npx @reopt-ai/opt-cli surface add billing-page

# 여러 개 한 번에 설치
npx @reopt-ai/opt-cli surface add billing-page analytics-dashboard

# 생성될 파일 내용만 보기
npx @reopt-ai/opt-cli surface add billing-page --view
npx @reopt-ai/opt-cli surface add billing-page --view billing-page.tsx

# 현재 로컬 파일과 registry diff 보기
npx @reopt-ai/opt-cli surface add billing-page --diff

# 실제 write 없이 설치 계획만 보기
npx @reopt-ai/opt-cli surface add billing-page --dry-run

# overwrite prompt 없이 덮어쓰기
npx @reopt-ai/opt-cli surface add billing-page --overwrite

# registry가 요구하는 외부 패키지도 같이 설치
npx @reopt-ai/opt-cli surface add data-explorer --install

5. opt-ui.json v2

On first install, opt-ui.json is created. The v2 schema records per-Surface file targets along with installed hashes so update and doctor can detect local modifications.

json

{
  "$schema": "https://opt-ui.dev/opt-ui.schema.json",
  "schemaVersion": 2,
  "surfacesDir": "components/surfaces",
  "importAlias": "@/components/surfaces",
  "surfaces": [
    {
      "slug": "billing-page",
      "version": "1.0.7",
      "contentHash": "e33ec0c3",
      "installedAt": "2026-03-11",
      "files": [
        {
          "target": "billing-page.tsx",
          "installedContentHash": "e33ec0c3"
        }
      ]
    }
  ]
}

surfacesDir: the root directory where Surfaces are copied
importAlias: the import prefix used in docs and CLI examples
surfaces[].files[]: each target file along with the content hash at the time of installation

6. info / doctor

Use info to inspect installation status, and doctor to check for actual issues.

bash

# package manager, framework, registry version, config 상태
npx @reopt-ai/opt-cli surface info
npx @reopt-ai/opt-cli surface info --json

# blocking issue + warning 검사
npx @reopt-ai/opt-cli surface doctor

# legacy opt-ui.json migration을 저장
npx @reopt-ai/opt-cli surface doctor --fix

Key items doctor checks

Presence of the @reopt-ai/opt-ui dependency
Whether opt-ui.json parses and its schema migration status
Whether installed Surface files are missing or locally modified
Whether @reopt-ai/opt-ui/tailwind.css is imported

7. update workflow

update only overwrites automatically when the last installed hash matches the current local file. If you've made local edits, it stops by default and points you to the diff.

bash

# 전체 installed Surface 업데이트
npx @reopt-ai/opt-cli surface update

# 특정 slug만 업데이트
npx @reopt-ai/opt-cli surface update billing-page

# 로컬 수정본까지 강제로 덮어쓰기
npx @reopt-ai/opt-cli surface update billing-page --force

# 단일 Surface diff 확인
npx @reopt-ai/opt-cli surface add billing-page --diff

# 설치된 Surface 전체 drift 확인
npx @reopt-ai/opt-cli surface diff
npx @reopt-ai/opt-cli surface diff --json --format summary
npx @reopt-ai/opt-cli surface diff --exit-code

8. Harness contract validation

opt harness checks the authored contract that opt-shell runtime screens follow. Static analysis is check, browser fixture validation is test, and environment/version diagnostics are doctor.

bash

# Tier 1: 정적 contract/lint 검사
npx @reopt-ai/opt-cli harness check
npx @reopt-ai/opt-cli harness check --json
npx @reopt-ai/opt-cli harness check --fix
npx @reopt-ai/opt-cli harness check --rule harness/workspace-first

# Tier 2: fixture 기반 런타임 검증
npx @reopt-ai/opt-cli harness test
npx @reopt-ai/opt-cli harness test --fixture ./harness.fixtures.ts

# 환경/버전/contract 진단
npx @reopt-ai/opt-cli harness doctor
npx @reopt-ai/opt-cli harness doctor --fix

9. Post-install structure

text

my-app/
├── components/
│   └── surfaces/
│       └── billing-page.tsx
├── opt-ui.json
└── package.json