@gpc-cli/plugin-sdk

Plugin interface for extending GPC with custom commands, lifecycle hooks, and integrations.

Install

npm install @gpc-cli/plugin-sdk

Create a Plugin

import { definePlugin } from "@gpc-cli/plugin-sdk";
import type { GpcPlugin } from "@gpc-cli/plugin-sdk";

export const myPlugin: GpcPlugin = definePlugin({
  name: "gpc-plugin-slack",
  version: "1.0.0",

  hooks: {
    afterCommand({ command, result }) {
      // Notify Slack after every command
      if (result.success) {
        postToSlack(`${command} completed successfully`);
      }
    },

    onError({ error }) {
      postToSlack(`GPC error: ${error.message}`);
    },

    registerCommands(registry) {
      registry.addCommand({
        name: "slack:notify",
        description: "Send a Slack notification",
        options: [{ flags: "--channel <channel>", description: "Slack channel" }],
        action: async (opts) => {
          await postToSlack(opts.channel, "Manual notification from GPC");
        },
      });
    },
  },
});

Lifecycle Hooks

| Hook | When | Use Case | | ------------------ | ----------------------- | ---------------------------------- | | beforeCommand | Before any CLI command | Logging, validation, feature flags | | afterCommand | After command completes | Notifications, metrics, summaries | | onError | When a command fails | Error reporting, alerting | | beforeRequest | Before each API call | Request logging, headers | | afterResponse | After each API response | Response logging, metrics | | registerCommands | Plugin initialization | Add custom commands to the CLI |

Permissions

Plugins declare required permissions in their manifest:

const plugin: GpcPlugin = {
  name: "my-plugin",
  version: "1.0.0",
  manifest: {
    permissions: ["api:read", "hooks:afterCommand"],
  },
  hooks: { ... },
};

| Permission | Grants | | ------------------- | --------------------------- | | read:config | Read GPC configuration | | write:config | Modify GPC configuration | | read:auth | Access auth credentials | | api:read | Read-only API access | | api:write | Write API access | | commands:register | Register custom commands | | hooks:* | Subscribe to specific hooks |

Third-party plugins require user approval before loading:

gpc plugins approve gpc-plugin-slack

Scaffold a Plugin

gpc plugins init my-plugin

Generates a complete plugin project with TypeScript config, tests, and example hooks.

Part of the GPC Monorepo

See the Plugin Development Guide for full documentation.

License

MIT