---
title: Cli Extension
description: Cli Extension protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# 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** — The main CLI (`@objectstack/cli`) lists the plugin in its

`oclif.plugins` array, or users install it via `os plugins install <pkg>`.

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:

```json

// package.json of the plugin

\{

"name": "@acme/plugin-marketplace",

"oclif": \{

"commands": \{

"strategy": "pattern",

"target": "./dist/commands",

"glob": "**\/*.js"

\}

\}

\}

```

Commands are standard 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 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.

<Callout type="info">
**Source:** `packages/spec/src/kernel/cli-extension.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { CLICommandContribution, OclifPluginConfig } from '@objectstack/spec/kernel';
import type { CLICommandContribution, OclifPluginConfig } from '@objectstack/spec/kernel';

// Validate data
const result = CLICommandContribution.parse(data);
```

---

## CLICommandContribution

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | CLI command name |
| **description** | `string` | optional | Command description for help text |
| **module** | `string` | optional | Module path exporting oclif Command classes |


---

## OclifPluginConfig

oclif plugin configuration section

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **commands** | `Object` | optional | Command discovery configuration |
| **topicSeparator** | `string` | optional | Character separating topic and command names |


---

