@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