cli

@objectstack/cli

Command Line Interface for building metadata-driven applications with the ObjectStack Protocol.

Built on oclif — commands are auto-discovered, and plugins can extend the CLI without modifying the main package.

Installation

pnpm add -D @objectstack/cli

The CLI is available as objectstack or the shorter alias os.

Quick Start

# Initialize a new project
os init my-app

# Generate metadata
os generate object task
os generate view task
os generate flow task

# Validate configuration
os validate

# Start development server
os dev

# Compile for production
os compile

Commands

Development

Command	Description
os init [name]	Initialize a new ObjectStack project in the current directory
os dev [package]	Start development mode with hot reload
os serve [config]	Start the ObjectStack server with plugin auto-detection
os studio [config]	Launch Studio UI with development server

Build & Validate

Command	Description
os compile [config]	Compile configuration to a JSON artifact (dist/objectstack.json)
os validate [config]	Validate configuration against the ObjectStack Protocol schema
os info [config]	Display metadata summary (objects, fields, apps, agents, etc.)

Scaffolding

Command	Description
os generate <type> <name>	Generate metadata files (alias: os g)
os create <type> [name]	Create a new package/plugin/example from template

Available generate types: object, view, action, flow, agent, dashboard, app

Plugin Management

Command	Description
os plugin list [config]	List plugins defined in configuration (alias: os plugin ls)
os plugin info <name> [config]	Show detailed plugin information
os plugin add <package>	Add a plugin import and entry to config
os plugin remove <name>	Remove a plugin from config (alias: os plugin rm)

Quality

Command	Description
os test [files]	Run Quality Protocol test scenarios against a running server
os doctor	Check development environment health
os lint [config]	Check configuration for style and convention issues
os diff [before] [after]	Compare two configurations and detect breaking changes

Reference

Command	Description
os explain [schema]	Display human-readable explanation of an ObjectStack schema

Code Transforms

Command	Description
os codemod v2-to-v3	Migrate ObjectStack v2 config to v3 format

Configuration

The CLI looks for objectstack.config.ts (or .js, .mjs) in the current directory:

import { defineStack } from '@objectstack/spec';
import * as objects from './src/objects';

export default defineStack({
  manifest: {
    id: 'com.example.my-app',
    namespace: 'my_app',
    version: '1.0.0',
    type: 'app',
    name: 'My App',
  },
  objects: Object.values(objects),
});

CLI Options

Global

• -v, --version — Show version number
• -h, --help — Show help

os init

• -t, --template <template> — Template: app (default), plugin, empty
• --no-install — Skip dependency installation

os compile

• -o, --output <path> — Output path (default: dist/objectstack.json)
• --json — Output compile result as JSON (for CI pipelines)

os validate

• --strict — Treat warnings as errors
• --json — Output result as JSON

os serve

• -p, --port <port> — Server port (default: 3000)
• --dev — Run in development mode (load devPlugins, pretty logging)
• --ui — Enable Studio UI
• --no-server — Skip starting HTTP server plugin

os generate

• -d, --dir <directory> — Override target directory

os plugin list

• --json — Output as JSON

os plugin add

• -d, --dev — Add as a dev-only plugin
• -c, --config <path> — Configuration file path

os plugin remove

• -c, --config <path> — Configuration file path

os info

• --json — Output as JSON

os doctor

• -v, --verbose — Show fix suggestions for warnings
• --scan-deprecations — Scan for deprecated patterns

oclif Plugin System

The CLI uses oclif's built-in plugin system for extensibility. Third-party plugins (e.g., cloud commands, marketplace tools) can extend the CLI without modifying the main package.

How Plugin Extension Works

1. Create an oclif plugin package with its own oclif config in package.json
2. Export oclif Command classes from the plugin's src/commands/ directory
3. Install the plugin via os plugins install <package> or declare it in the main CLI's oclif.plugins

Creating a CLI Plugin

1. Configure the plugin's package.json:

{
  "name": "@acme/plugin-marketplace",
  "oclif": {
    "commands": {
      "strategy": "pattern",
      "target": "./dist/commands",
      "glob": "**/*.js"
    }
  }
}

2. Create oclif Command classes:

// src/commands/marketplace/search.ts
import { Args, Command, Flags } from '@oclif/core';

export default class MarketplaceSearch extends Command {
  static override description = 'Search marketplace applications';

  static override args = {
    query: Args.string({ description: 'Search query', required: true }),
  };

  async run() {
    const { args } = await this.parse(MarketplaceSearch);
    // Implementation...
  }
}

3. Install and use:

os plugins install @acme/plugin-marketplace
os marketplace search "crm"

Key Differences from Previous Plugin Model

Before (Commander.js)	After (oclif)
Plugins declared in objectstack.config.ts	Plugins installed via os plugins install or oclif.plugins
Custom loadPluginCommands mechanism	oclif's built-in plugin discovery
contributes.commands in manifest	oclif.commands in package.json
Commander.js new Command(...) exports	oclif class extends Command exports
Project config determines CLI commands	CLI commands available without project init

Typical Workflow

os init                          # 1. Create project
os generate object customer      # 2. Add a Customer object
os generate object order         # 3. Add an Order object  
os generate view customer        # 4. Add a list view
os plugin add @objectstack/plugin-auth  # 5. Add auth plugin
os validate                      # 6. Validate everything
os dev                           # 7. Start dev server
os compile                       # 8. Build for production

Architecture

@objectstack/cli (oclif)
├── bin/run.js                  # Entry point (os / objectstack)
├── src/commands/               # Auto-discovered command classes
│   ├── init.ts                 # os init
│   ├── dev.ts                  # os dev
│   ├── serve.ts                # os serve
│   ├── compile.ts              # os compile
│   ├── validate.ts             # os validate
│   ├── generate.ts             # os generate (alias: g)
│   ├── plugin/                 # os plugin <subcommand>
│   │   ├── list.ts
│   │   ├── info.ts
│   │   ├── add.ts
│   │   └── remove.ts
│   ├── codemod/                # os codemod <subcommand>
│   │   └── v2-to-v3.ts
│   └── ...
├── src/utils/                  # Shared utilities
└── package.json                # oclif config under "oclif" key

License

Apache-2.0