CLI Plugin API v2.4.0

Extend the Aevum Zenth CLI with custom commands, hooks, and integrations using our stable, type-safe plugin interface.

ℹ️

Note: The Plugin API is stable as of v2.0.0. Breaking changes will only occur in major versions. Always check the compatibility matrix for your CLI version.

Overview

The Aevum Zenth CLI Plugin API provides a standardized way to extend the core command-line interface. Plugins can register commands, intercept lifecycle events, modify configuration, and integrate with external services. All plugins follow a consistent structure and are loaded asynchronously at startup.

Quick Start

Initialize a new plugin project using the official scaffolding tool:

# Scaffold a new plugin
$ aevum init plugin my-custom-plugin
# Navigate and install dependencies
$ cd my-custom-plugin
$ npm install
            

Plugin Structure

Every plugin must export a default configuration object that implements the PluginDefinition interface:

import { PluginDefinition } from '@aevum-zenth/cli-sdk';

const plugin: PluginDefinition = {
  name: 'my-custom-plugin',
  version: '1.0.0',
  description: 'Extends CLI with deployment workflows',
  commands: [ // ... registered commands ],
  hooks: {
    preInit: async (ctx) => { /* ... */ },
    postBuild: async (ctx) => { /* ... */ }
  },
  configSchema: { /* ... */ }
};

export default plugin;
            

Core Interfaces

Interface	Description	Usage
PluginDefinition	Root plugin configuration object	Required export for all plugins
PluginContext	Runtime environment & utilities	Passed to hooks and command handlers
CommandHandler	Function signature for CLI commands	(args, options, ctx) => void
HookCallback	Async function for lifecycle events	(ctx) => Promise<void>

Available Lifecycle Hooks

Plugins can attach to specific points in the CLI execution pipeline. Hooks run sequentially unless marked as parallelizable.

preInit - Executed before CLI environment setup
postInit - Run after core services are initialized
preBuild - Triggered before the build/compile phase
postBuild - Runs after successful compilation
preDeploy - Executed before deployment pipelines start
postDeploy - Runs after deployment completes or fails
teardown - Cleanup hook run on CLI exit

// Example: Hook registration
const plugin: PluginDefinition = {
  // ...
  hooks: {
    postBuild: async (ctx) => {
      ctx.log.info('[my-plugin] Optimizing assets...');
      await ctx.utils.compressAssets('./dist');
    }
  }
};
            

Command Registration

Define custom commands that appear in aevum --help. Each command requires a name, description, argument parser, and handler function.

import { defineCommand } from '@aevum-zenth/cli-sdk';

const deployCmd = defineCommand({
  name: 'deploy',
  description: 'Deploy current workspace to target environment',
  usage: 'aevum deploy [env] [options]',
  args: [
    { name: 'env', required: true, type: 'string', default: 'staging' }
  ],
  options: {
    dryRun: { alias: 'd', type: 'boolean', description: 'Simulate deployment' }
  },
  handler: async (args, opts, ctx) => {
    ctx.log.info(`Deploying to ${args.env}`);
    // deployment logic...
  }
});
            

Configuration & Environment

Plugins can read and modify the CLI configuration schema. Use ctx.config for runtime access and configSchema for static validation.

⚠️

Security Notice: Never hardcode credentials in plugin configuration. Use the built-in secret manager via ctx.secrets.get() for sensitive data.

Best Practices

Asynchronous by Default: All hooks and handlers should be async. Synchronous blocking will degrade CLI performance.
Graceful Error Handling: Use ctx.error() for non-fatal issues and throw PluginError for fatal failures.
Telemetry Opt-Out: Respect ctx.telemetry.disabled and never send data when telemetry is off.
Version Constraints: Specify CLI compatibility in package.json using "aevum-cli": "^2.0.0".

Testing & Debugging

Run your plugin in debug mode to inspect hook execution and command routing:

$ DEBUG=aevum:plugin aevum deploy production --dry-run

Plugins are loaded from ~/.aevum/plugins/ and node_modules directories. Use aevum plugins list to verify active installations.