@gpc-cli/plugin-sdk

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

Add Slack notifications, custom release gates, internal dashboards, or any workflow GPC doesn't cover out of the box — without forking the CLI.

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.

Licensing

Free to use. Source code is on GitHub at yasserstudio/gpc.