CLI (block + harness + project)
opt-cli is an operational CLI that combines Surface search, preview, copy, doctor, and update with harness contract validation.
reopt designUpdated
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 31 Surfaces.
- The CLI uses the bundled
registry.jsonas the source of truth. - The binary is
opt; Block commands areopt block <cmd>(the oldopt surfaceremains a deprecated alias). Harness contract validation lives underopt harness <cmd>, and Builder project sync underopt project <cmd>.
2. Prerequisites
Optional: shared foundation skill
There is no dedicated opt-cli skill. opt-ui-install wires opt-cli for Surface and doctor workflows. Use the manual install below when adopting the CLI by itself.
From the consumer project root, install the skill into your agent runtime. Skip this command if it is already installed.
npx skills add reopt-ai/reopt-skills/opt-ui-installThen ask your agent to apply it. The skill detects whether this is a new install or an upgrade.
Use the opt-ui-install skill to set up and verify the opt-ui and opt-cli doctor and Surface workflow.The skill idempotently updates a reopt marker block in AGENTS.md (or CLAUDE.md), reads the docs shipped by the installed package version, and runs module-appropriate checks such as typecheck or doctor.
The package commands below are the manual fallback when a skill is unavailable or you need to control every setup step. Review the skill source and current support.
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.
bun add @reopt-ai/opt-ui
bun add -D @reopt-ai/opt-cli
# 설치 상태 / 프로젝트 정보 확인
npx @reopt-ai/opt-cli block info
# 통합 상태 점검
npx @reopt-ai/opt-cli block doctor3. Discover and inspect
List, search, and inspect detailed metadata before installing. list and search share the same command surface.
# 전체 목록
npx @reopt-ai/opt-cli block list
# slug / 설명 / tags 검색
npx @reopt-ai/opt-cli block search --query billing
# source package 기준 필터
npx @reopt-ai/opt-cli block list --source opt-ui
# 설치된 것만 보기
npx @reopt-ai/opt-cli block list --installed
# JSON 출력
npx @reopt-ai/opt-cli block search --query dashboard --json
# 개별 Surface 메타 조회
npx @reopt-ai/opt-cli block view billing-page
npx @reopt-ai/opt-cli block view billing-page --json4. add: pre-install preview and actual copy
add handles both preview and the actual write. Preview variants never write files.
# 기본 설치
npx @reopt-ai/opt-cli block add billing-page
# 여러 개 한 번에 설치
npx @reopt-ai/opt-cli block add billing-page analytics-dashboard
# 생성될 파일 내용만 보기
npx @reopt-ai/opt-cli block add billing-page --view
npx @reopt-ai/opt-cli block add billing-page --view billing-page.tsx
# 현재 로컬 파일과 registry diff 보기
npx @reopt-ai/opt-cli block add billing-page --diff
# 실제 write 없이 설치 계획만 보기
npx @reopt-ai/opt-cli block add billing-page --dry-run
# overwrite prompt 없이 덮어쓰기
npx @reopt-ai/opt-cli block add billing-page --overwrite
# registry가 요구하는 외부 패키지도 같이 설치
npx @reopt-ai/opt-cli block add data-explorer --install
# CI/에이전트용 JSON 출력 (항상 비대화형)
npx @reopt-ai/opt-cli block add billing-page --yes --json5. 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.
{
"$schema": "https://opt-ui.dev/opt-ui.schema.json",
"schemaVersion": 2,
"surfacesDir": "components/surfaces",
"importAlias": "@/components/surfaces",
"blocks": [
{
"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 copiedimportAlias: the import prefix used in docs and CLI examplessurfaces[].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.
# package manager, framework, registry version, config 상태
npx @reopt-ai/opt-cli block info
npx @reopt-ai/opt-cli block info --json
# blocking issue + warning 검사
npx @reopt-ai/opt-cli block doctor
# legacy opt-ui.json migration을 저장
npx @reopt-ai/opt-cli block doctor --fixKey items doctor checks
- Presence of the
@reopt-ai/opt-uidependency - Whether
opt-ui.jsonparses and its schema migration status - Whether installed Surface files are missing or locally modified
- Whether
@reopt-ai/opt-ui/tailwind.cssis 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.
# 전체 installed Surface 업데이트
npx @reopt-ai/opt-cli block update
# 특정 slug만 업데이트
npx @reopt-ai/opt-cli block update billing-page
# 로컬 수정본까지 강제로 덮어쓰기
npx @reopt-ai/opt-cli block update billing-page --force
# 단일 Surface diff 확인
npx @reopt-ai/opt-cli block add billing-page --diff
# 설치된 Surface 전체 drift 확인
npx @reopt-ai/opt-cli block diff
npx @reopt-ai/opt-cli block diff --json --format summary
npx @reopt-ai/opt-cli block diff --exit-code
# 설치 해제 — 수정된 파일은 --force, 기록만 지우려면 --keep-files
npx @reopt-ai/opt-cli block remove billing-page
npx @reopt-ai/opt-cli block remove billing-page --keep-files8. 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.
# 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 진단 (error만 차단, warning은 통과)
npx @reopt-ai/opt-cli harness doctor9. project: Builder sync
opt project syncs a Builder project with your local repo in both directions. The sync contract is the page node document (*.nodes.json); *.generated.tsx is a server-generated artifact. Edit the node document locally, then push — the canvas updates and freshly generated TSX comes back in the same step.
# Builder 프로젝트와 링크 (opt-project.json 생성)
npx @reopt-ai/opt-cli project link demo-sync-example
npx @reopt-ai/opt-cli project link demo-sync-example --origin https://design.reopt.ai
# 캔버스 → 로컬: 생성 TSX + 노드 사이드카 + theme.css
npx @reopt-ai/opt-cli project pull
npx @reopt-ai/opt-cli project pull orders --force
# 3자 상태 리포트 (마지막 pull vs 로컬 vs Builder)
npx @reopt-ai/opt-cli project status
# 로컬 → 캔버스: 수정한 *.nodes.json 업로드 (낙관적 잠금)
npx @reopt-ai/opt-cli project push10. Post-install structure
my-app/
├── components/
│ └── surfaces/
│ └── billing-page.tsx
├── opt-ui.json
└── package.json