npm package: @objectstack/cli
Description: Command Line Interface for ObjectStack Protocol
Author: Steedos
Latest version: 4.0.2

# @objectstack/cli

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

Built on [oclif](https://oclif.io/) — commands are auto-discovered, and plugins can extend the CLI without modifying the main package.

## Installation

```bash
pnpm add -D @objectstack/cli
```

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

## Quick Start

```bash
# 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:

```typescript
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`:**

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

**2. Create oclif Command classes:**

```typescript
// 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:**

```bash
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