@reopt-ai/opt-cli

Unified opt CLI for reopt design packages. The CLI verifies authored harness contracts, vendors copy-paste Block templates, exposes component metadata, and inspects generated data-opt-id registries.

Skill support

There is no dedicated opt-cli-install skill. The opt-ui-install skill installs and uses opt-cli for doctor and Block/Surface workflows:

npx skills add reopt-ai/reopt-skills/opt-ui-install

Use the manual commands below when adopting opt-cli by itself.

Install

bun add -d @reopt-ai/opt-cli

@reopt-ai/opt-shell is an optional peer — install it alongside the CLI only when you use the opt harness ... commands (they audit the shell contract):

bun add -d @reopt-ai/opt-cli @reopt-ai/opt-shell

The package publishes the opt binary:

bunx opt --help

Commands

Harness Contracts

opt harness check [--fix] [--rule <id>] [--json] [--verbose] [-c opt.config.ts]
opt harness test [--headed] [--fixture <path>] [-c opt.config.ts]
opt harness doctor [-c opt.config.ts]

harness check exits 1 on errors (warnings pass); --json emits findings and a summary to stdout. harness doctor combines environment checks, static analysis, and the runtime fixture tier, and exits 1 when any tier fails or cannot run.

harness means the authored product contract that is audited before a runtime shell renders it. Runtime APIs live in @reopt-ai/opt-shell; the CLI keeps the harness vocabulary for contract governance.

Block Registry

opt block list [--json] [--installed] [--query <q>] [--source <pkg>] [--limit <n>]
opt block view sql-workspace [--json]
opt block add sql-workspace [-y] [-n] [--view [file]] [--diff [file]] [--overwrite] [--install] [--json]
opt block update [slugs...] [--force] [--json]
opt block remove <slugs...> [--force] [--keep-files]
opt block diff [slugs...] [--json] [--format summary|full] [--exit-code]
opt block info [--json]
opt block doctor [--fix]

• add previews with --dry-run/--view/--diff and never writes outside the configured surfaces directory. Non-interactive sessions must pass slugs and --yes/--overwrite explicitly.
• update re-vendors installed surfaces from the registry; files you modified or deleted locally are only overwritten/restored with --force.
• remove deletes a surface's recorded files and its opt-ui.json entry; locally modified files require --force, and --keep-files drops only the record.
• diff is the bulk drift detector for CI; add --diff is the interactive single-surface inspection.
• doctor inspects opt-ui.json integration health; --fix persists the config migration when needed.
• --json on add/update emits per-surface machine-readable results and never prompts.

opt surface ... remains as a deprecated alias for opt block ....

Project Sync (Builder ↔ local repo)

opt project link <projectId> [--origin <url>] [--pages-dir <dir>]
opt project pull [slugs...] [--force] [-n] [--json]
opt project status [--json]
opt project push [slugs...] [--json]

Ties a Builder project to this repo through opt-project.json. The sync artifact is the page node document (<slug>.nodes.json); the <slug>.generated.tsx next to it is regenerated server-side from that document — treat it as build output.

• pull vendors every Builder page as generated TSX plus its nodes sidecar, along with project-level files (theme.css, a credential-free data-sources.json summary), recording content hashes for drift detection (local edits require --force). Node types the codegen cannot express (e.g. app-synthetic block refs) are omitted from the TSX and reported as warnings — the nodes sidecar always keeps the full document.
• push uploads locally edited nodes sidecars under an optimistic lock; on success the server returns freshly generated files so TSX and ledger update in the same step. A 409 means the canvas moved on — pull first.
• status reports the three-way state per page (up-to-date, remote-updated, local-modified, conflict, not-pulled, remote-missing).

Auth: localhost dev servers accept requests as-is. For remote origins set OPT_PROJECT_COOKIE to a Better Auth session cookie (OPT_PROJECT_ORIGIN overrides the default origin). There is no token auth yet — a first-class opt login flow is the planned replacement.

Component Metadata

opt component --list
opt component button --props
opt component data-table --examples --json
opt component --query chart --json

Component metadata is bundled as component-catalog.json, so consumers can query @reopt-ai/opt-ui and @reopt-ai/opt-charts contracts without importing runtime UI code.

ID Registry

opt ids list --json
opt ids show 42177 --json
opt ids stats --json

Registry Scope

registry.json is generated with OPT_REGISTRY_SCOPE:

| Scope | Contents | | ------------------ | -------------------------------------------- | | public (default) | Public-safe opt-ui blocks only | | internal | Web registry blocks plus private Brandapp UI |

Published npm artifacts always use the default public scope. Internal builds must opt in with OPT_REGISTRY_SCOPE=internal and must not be committed.

At runtime, block commands fetch the signed public manifest from https://design.reopt.ai/api/r. The CLI verifies its Ed25519 signature and SHA-256 payload hash, rejects manifests older than the bundled registry version (replay/downgrade protection), and falls back to the bundled public registry — with a stderr warning — when the network or validation fails. Responses are revalidated with ETag/If-None-Match against an on-disk cache (~/.cache/opt-cli), so unchanged manifests are not re-downloaded.

| Variable | Behavior | | -------------------------- | ------------------------------------------------------- | | OPT_REGISTRY_URL | Override the remote manifest URL | | OPT_REGISTRY_OFFLINE=1 | Skip remote access and use the bundle | | OPT_REGISTRY_STRICT=1 | Fail instead of falling back | | OPT_REGISTRY_PUBLIC_KEYS | JSON public-key map for development/key rollout testing | | OPT_CLI_CACHE_DIR | Override the ETag cache directory |

@reopt-ai/opt-cli/registry exports the registry Zod schemas, canonical hash, and Ed25519 signing/verification helpers for registry hosts.

Development

bun run --filter @reopt-ai/opt-cli build
bun run --filter @reopt-ai/opt-cli smoke:cli
bun run --filter @reopt-ai/opt-cli smoke:cli -- --dist
bun run --filter @reopt-ai/opt-cli validate:registry