ObjectUI CLI

@object-ui/cli is a standalone command-line tool for scaffolding, developing, building, linting, testing, and validating ObjectUI applications driven by JSON or YAML schemas.

It is not an oclif plugin — it ships its own objectui binary just like vite, next, or astro.

Installation

npm install -g @object-ui/cli
# or run on demand
npx @object-ui/cli --help

The installed binary is named objectui.

Quick start

objectui init my-dashboard --template dashboard
cd my-dashboard
objectui dev app.json

Your app runs at http://localhost:3000.

Commands

The CLI exposes 15 commands. Run objectui <command> --help for the full flag list.

objectui init [name]

Scaffold a new ObjectUI project (creates app.json, package.json, vite.config.ts, tsconfig.json, index.html, and src/).

objectui init my-app
objectui init my-app --template form
objectui init . --template dashboard

objectui dev [schema]

Start the development server with hot reload. Opens the browser automatically.

objectui dev app.json
objectui dev pages/                    # file-system routing
objectui dev --port 8080 --no-open

objectui serve [schema]

Legacy alias of dev, kept for older scripts. Same positional argument and -p/-h flags as dev (no --no-open).

objectui build [schema]

Build the application for production with Vite.

objectui build app.json
objectui build --out-dir build --clean

objectui start

Serve a previously-built production bundle.

objectui start
objectui start --port 8080 --dir build

objectui lint

Lint the generated application code with ESLint.

objectui lint --fix

objectui test

Run the application's tests with Vitest.

objectui test --watch
objectui test --coverage
objectui test --ui

objectui generate <type> <name> (alias g)

Generate new resources.

objectui generate object User
objectui g page Dashboard
objectui generate plugin my-widget

objectui validate [schema]

Validate a schema file against the ObjectUI specification. Exits with code 0 on success and non-zero on failure — use it in CI pipelines.

objectui validate app.json
objectui validate ./schemas/dashboard.yaml

objectui check

Validate every schema file detected in the project. No flags.

objectui doctor

Diagnose common environment issues (Node version, deps, config sanity).

objectui add <component>

Add a new component renderer scaffold to your project.

objectui add Input

objectui studio

Launch the visual designer (@object-ui/plugin-designer) against the local project.

objectui create plugin <name>

Scaffold a new ObjectUI plugin via @object-ui/create-plugin.

objectui create plugin my-awesome-widget

objectui analyze

Analyze the built application.

Schema file format

dev, serve, build, and validate accept either JSON or YAML.

JSON

{
  "type": "div",
  "className": "min-h-screen flex items-center justify-center",
  "body": {
    "type": "card",
    "title": "Hello World",
    "body": { "type": "text", "content": "Welcome to Object UI!" }
  }
}

YAML

type: div
className: min-h-screen flex items-center justify-center
body:
  type: card
  title: Hello World
  body:
    type: text
    content: Welcome to Object UI!

File-system routing

If the project contains a pages/ directory, dev and build automatically switch to file-system routing — every .json/.yaml file under pages/ becomes a route based on its path.

my-app/
├── pages/
│   ├── index.json          → /
│   ├── about.json          → /about
│   └── users/
│       └── [id].json       → /users/:id

Programmatic API

import { serve, init } from '@object-ui/cli';

await serve('app.json', { port: '3000', host: 'localhost' });
await init('my-app', { template: 'dashboard' });

Only the long-running serve and project-creating init are exported as functions today; other commands are bin-only.

Troubleshooting

Port already in use

objectui dev --port 3001

Schema not found

objectui dev ./path/to/schema.json
# or, scaffold a fresh one
objectui init .

Run diagnostics

objectui doctor

Package information

Dependencies

The CLI is built on:

• Vite + @vitejs/plugin-react — bundling and dev server
• Express + express-rate-limit — preview / production server
• Commander — argument parsing
• chalk — terminal colors
• js-yaml — YAML parsing
• glob — file-system routing scan

Next steps

• Create Plugin — author your own plugins
• Schema Overview — learn the schema format
• Plugins — explore available plugins
• Examples — see example projects

Need help?

• GitHub Issues
• Documentation