Cli Extension — Kernel Protocol reference

CLI Extension Protocol

Defines the contract for plugins that extend the ObjectStack CLI with custom commands. This enables third-party packages (e.g., marketplace, cloud deployment tools) to register new CLI commands via oclif's built-in plugin system.

How It Works (oclif Plugin Model)

1. Declare — Plugin's package.json includes an oclif config section declaring its commands directory and any topics.
2. Discover — oclif loads a plugin that the CLI's own package.json lists in both oclif.plugins and dependencies. @objectstack/cli lists none and ships no plugin manager, so os plugins is not a command. To add a plugin's commands to os, build an os distribution: a package whose own package.json lists the plugin in both places.
3. Load — oclif automatically discovers and registers all Command classes exported from the plugin's commands directory.

Plugin Package Contract

The plugin must be a valid oclif plugin:

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

Commands are standard 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 apps';
  static override args = {
    query: Args.string({ description: 'Search query', required: true }),
  };
  async run() {
    const { args } = await this.parse(MarketplaceSearch);
    // ...
  }
}

Migration from Commander.js

The previous plugin model required contributes.commands in the manifest and exported Commander.js Command instances. The new model uses oclif's native plugin system for automatic command discovery and registration. The objectstack.config.ts plugins array no longer determines CLI commands.

TypeScript Usage

import { OclifPluginConfigSchema } from '@objectstack/spec/kernel';
import type { OclifPluginConfig } from '@objectstack/spec/kernel';

// Validate data
const result = OclifPluginConfigSchema.parse(data);

OclifPluginConfig

oclif plugin configuration section

Properties

Nested Shape: OclifPluginConfig.commands