CLI (block + harness + project)
opt-cli는 Surface 검색·미리보기·복사·점검·업데이트와 harness 계약 검증을 통합한 운영형 CLI입니다.
reopt design업데이트
1. 개요
opt-cli는 shadcn/ui식 source copy 모델을 따르되, 설치 전 조회와 운영 점검까지 포함합니다. Core/Shells는 @reopt-ai/opt-ui, 차트는 @reopt-ai/opt-charts 패키지로 import 하고, Surface만 프로젝트 로컬로 복사해서 직접 수정합니다.
- 현재 registry에는 31개 Surface가 포함됩니다.
- CLI는 bundled
registry.json을 source of truth로 사용합니다. - binary는
opt이며, Block 명령은opt block <cmd>형태입니다(구opt surface는 deprecated alias). harness 계약 검증은opt harness <cmd>, Builder 프로젝트 동기화는opt project <cmd>입니다.
2. 사전 요구사항
선택 설정: 공통 기반 스킬
opt-cli 전용 스킬은 없습니다. opt-ui-install이 Surface 설치와 doctor 과정에서 opt-cli를 함께 연결합니다. CLI만 단독 도입할 때는 아래 수동 설치를 사용합니다.
소비자 프로젝트 루트에서 스킬을 에이전트 런타임에 설치합니다. 이미 설치했다면 이 명령은 생략할 수 있습니다.
npx skills add reopt-ai/reopt-skills/opt-ui-install설치 후 에이전트에게 아래처럼 요청하세요. 스킬은 현재 설치 상태를 확인해 신규 설치와 업그레이드를 구분합니다.
opt-ui-install 스킬로 opt-ui와 opt-cli의 doctor·Surface workflow를 설정하고 검증해줘.스킬은 소비자 프로젝트의 AGENTS.md(없으면 CLAUDE.md)에 reopt marker 블록을 멱등하게 갱신하고, 설치된 패키지 버전의 문서를 읽은 뒤 typecheck·doctor 등 해당 모듈의 검증을 실행합니다.
아래 패키지 설치 명령은 스킬을 사용할 수 없거나 설정 과정을 직접 통제해야 할 때의 수동 대안입니다. 스킬 소스와 최신 지원 범위 확인.
Surface는 내부에서 opt-ui Core/Shells와 필요 시 opt-charts를 import 합니다. 프로젝트에는 @reopt-ai/opt-ui와 필요한 전문 패키지를 설치하고, 반복 실행할 CLI는 @reopt-ai/opt-cli를 dev dependency로 둘 수 있습니다.
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. 검색과 조회
설치 전에 목록, 검색, 상세 메타를 확인할 수 있습니다. list와 search는 같은 명령 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: 설치 전 preview와 실제 복사
add는 preview와 실제 write를 모두 담당합니다. preview 계열은 파일을 쓰지 않습니다.
# 기본 설치
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
첫 설치 시 opt-ui.json이 생성됩니다. v2 스키마는 Surface별 파일 target과 installed hash를 같이 기록해서 update/doctor가 로컬 수정을 판별합니다.
{
"$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: Surface가 복사되는 루트 디렉토리importAlias: docs와 CLI 예시에 쓰는 import prefixsurfaces[].files[]: 각 target 파일과 마지막 설치 시점의 content hash
6. info / doctor
설치 상태를 보기만 할 때는 info, 실제 이상 여부를 검사할 때는 doctor를 사용합니다.
# 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 --fixdoctor가 보는 핵심 항목
@reopt-ai/opt-uidependency 존재 여부opt-ui.json파싱 가능 여부와 schema migration 상태- 설치된 Surface 파일 누락 / 로컬 수정 여부
@reopt-ai/opt-ui/tailwind.cssimport 여부
7. update workflow
update는 마지막 설치 hash와 현재 로컬 파일이 같을 때만 자동으로 덮어씁니다. 로컬 수정이 있으면 기본적으로 중단하고 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 계약 검증
opt harness 명령은 opt-shell runtime이 따르는 authored contract를 검사합니다. 정적 분석은 check, 브라우저 fixture 검증은 test, 환경/버전 진단은 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 동기화
opt project는 Builder 프로젝트와 로컬 레포를 양방향으로 동기화합니다. 동기화 계약은 페이지 노드 문서(*.nodes.json)이고, *.generated.tsx는 서버가 다시 만들어 주는 생성물입니다. 로컬에서는 노드 문서를 수정한 뒤 push하세요 — 캔버스가 갱신되고 재생성된 TSX가 함께 돌아옵니다.
# 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. 설치 후 구조
my-app/
├── components/
│ └── surfaces/
│ └── billing-page.tsx
├── opt-ui.json
└── package.json