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 my-app/pages              # ...from anywhere, not just inside my-app
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

Reading a failure

A document is checked against a union of every component type, so a failure is reported first at the document root and then narrowed to the arm your type selected. Each numbered issue carries a path and a code; the 1.1-style entries beneath it are that arm's own diagnosis, with the real path to the node that failed:

1. Invalid input
   Path: (root)
   Code: invalid_union
   1.1 RETIRED (objectui#6523) — dividers are `{ separator: true }`; …
       Path: items → 0 → type
       Code: invalid_type

Only the selected arm is shown. When your type matches no component at all, the report says so and offers the nearest few of the accepted values instead:

1. Invalid input
   Path: (root)
   Code: invalid_union
   No arm accepts type "dropdwn-menu".
   Nearest of the 108 accepted types: dropdown-menu, context-menu, component, drawer, breadcrumb

A document with no type at all is reported the same way, without a candidate list — there is nothing for the suggestions to be near.

objectui check

Scan the project for ObjectUI schema files and report on the ones it recognises. No flags.

A JSON file with a root type is recognised when its root carries an ObjectUI structural key (children, body, className, …) or when the whole document validates as an ObjectUI component schema. Recognised files have their type checked against the component types this build registers.

Files that are recognised by neither arm fall into one of two reports, and the distinction matters:

• Reported by name when the root type does name a registered component. That is ObjectUI content the validator could not accept — either the document is off-spec, or its component type is not modelled by @object-ui/types. Run objectui validate <file> for the reason.
• Counted as skipped otherwise. A root type heads several unrelated JSON vocabularies — package.json's "type": "module" most of all — and those are not ObjectUI files.

Only unreadable JSON makes objectui check exit non-zero; everything above is a report. Use objectui validate when you want a failing exit code.

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, serve and build automatically switch to file-system routing — every .json/.yaml file under pages/ becomes a route based on its path.

my-app/
├── app.json                → app config (title, layout)
├── pages/
│   ├── index.json          → /
│   ├── about.json          → /about
│   └── users/
│       └── [id].json       → /users/:id

Which directory is "the project" is decided by the schema argument, so the three commands answer one invocation the same way from anywhere:

1. The directory the schema argument points into — objectui build my-app/app.json run from above my-app/ routes from my-app/pages/, with my-app/app.json as the app config. A directory argument counts here too: it may be the pages/ directory itself (objectui dev my-app/pages) or the project directory holding it (objectui dev my-app), and both answer exactly as naming the app config beside them does — from any working directory.
2. Otherwise the current working directory — cd my-app && objectui dev routes from ./pages/, with ./app.json as the app config when present.
3. Otherwise the named file is rendered on its own (single-schema mode), which is what a lone .json/.yaml schema with no pages/ beside it does. A directory that reaches this step is no project, and is refused by name — it is neither a pages/ directory nor does it contain one.

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