Plugins

Plugins let you package commands and extensions into reusable, distributable npm packages. They're the primary mechanism for sharing functionality across CLI projects.

Defining a Plugin

seedcli-plugin-docker/src/index.ts

import { definePlugin, command, flag } from '@seedcli/core'

export default definePlugin({
  name: 'docker',
  description: 'Docker integration for Seed CLI',
  version: '1.0.0',
  seedcli: '>=1.0.0',  // Required Seed CLI version

  commands: [
    command({
      name: 'docker-build',
      description: 'Build a Docker image',
      flags: {
        tag: flag({ type: 'string', alias: 't', description: 'Image tag' }),
        push: flag({ type: 'boolean', description: 'Push after build' }),
      },
      run: async ({ flags, system, print }) => {
        const tag = flags.tag ?? 'latest'
        await system.exec(`docker build -t ${tag} .`)
        if (flags.push) {
          await system.exec(`docker push ${tag}`)
        }
        print.success(`Built image: ${tag}`)
      },
    }),
  ],

  extensions: [
    {
      name: 'docker-check',
      setup: async (seed) => {
        await seed.system.whichOrThrow('docker')
      },
    },
  ],

})

Plugin Options

Option	Type	Description
`name`	`string`	Plugin identifier (required)
`description`	`string`	Human-readable description
`version`	`string`	Plugin version (required)
`seedcli`	`string`	Required Seed CLI semver range
`peerPlugins`	`Record<string, string>`	Required peer plugin versions
`commands`	`Command[]`	Commands to register
`extensions`	`ExtensionConfig[]`	Extensions to register
`templates`	`string`	Path to templates directory
`defaults`	`Record<string, unknown>`	Default configuration values

Loading Plugins

By Name

const runtime = build('my-cli')
  .plugin('seedcli-plugin-docker')
  .create()

Resolves from node_modules. The package must export a plugin as its default export.

Multiple Plugins

build('my-cli')
  .plugin(['seedcli-plugin-docker', 'seedcli-plugin-aws'])

From Directory

build('my-cli')
  .plugins('./plugins')

Scans the directory for subdirectories (including symlinks from npm link) and imports each as a plugin module.

Peer Plugin Dependencies

Plugins can declare dependencies on other plugins:

definePlugin({
  name: 'deploy',
  version: '1.0.0',
  peerPlugins: {
    docker: '>=1.0.0',
    aws: '>=2.0.0',
  },
  // ...
})

If a required peer plugin is missing or the version doesn't match, a PluginValidationError is thrown at startup.

Version Constraints

The seedcli field constrains which versions of Seed CLI the plugin supports:

definePlugin({
  name: 'my-plugin',
  version: '1.0.0',
  seedcli: '>=1.0.0 <2.0.0',
  // ...
})

Publishing a Plugin

Plugins are standard npm packages. Follow these conventions:

Name your package seedcli-plugin-<name>
Export the plugin as the default export
Specify seedcli version range
Include "seedcli-plugin" keyword in package.json

package.json

{
  "name": "seedcli-plugin-docker",
  "version": "1.0.0",
  "keywords": ["seedcli-plugin"],
  "main": "dist/index.js",
  "peerDependencies": {
    "@seedcli/core": ">=1.0.0"
  }
}

Declare @seedcli/core as a peer dependency, not a regular dependency, to avoid version conflicts.

Plugins

On this page