Gpc Plugin Development

gpc-plugin-development

Build and publish GPC plugins using the @gpc-cli/plugin-sdk.

When to use

• Building a new GPC plugin
• Adding custom hooks (notifications, logging, metrics)
• Registering custom CLI commands
• Understanding the plugin lifecycle and permission system
• Debugging plugin loading or hook execution
• Publishing a plugin to npm

Inputs required

• Node.js 20+ and TypeScript 5+
• @gpc-cli/plugin-sdk package (peer dependency)
• Plugin name — @gpc-cli/plugin-* (first-party) or gpc-plugin-* (third-party)

Procedure

0. Scaffold a new plugin

# Generate plugin boilerplate
gpc plugins init my-notifier --description "Send Slack notifications on release"

# This creates:
# gpc-plugin-my-notifier/
# ├── package.json
# ├── tsconfig.json
# ├── src/index.ts
# └── tests/plugin.test.ts

Or manually:

mkdir gpc-plugin-my-notifier && cd gpc-plugin-my-notifier
npm init -y
npm install --save-peer @gpc-cli/plugin-sdk
npm install --save-dev typescript vitest

1. Implement the plugin interface

Every plugin exports a GpcPlugin object:

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

export const plugin: GpcPlugin = {
  name: "gpc-plugin-my-notifier",
  version: "1.0.0",
  register(hooks: PluginHooks) {
    // Register your hooks here
    hooks.afterCommand(async (event, result) => {
      if (event.command === "releases upload" && result.success) {
        console.log(`✓ Upload complete in ${result.durationMs}ms`);
      }
    });
  },
};

export default plugin;

Read: references/hooks-reference.md for all 6 hook types with full type signatures.

2. Available lifecycle hooks

Register hooks inside the register() method:

register(hooks: PluginHooks) {
  // Before any command runs
  hooks.beforeCommand(async (event) => {
    console.log(`Running: gpc ${event.command}`);
  });

  // After successful command
  hooks.afterCommand(async (event, result) => {
    console.log(`Done: ${result.durationMs}ms, exit ${result.exitCode}`);
  });

  // On command failure
  hooks.onError(async (event, error) => {
    console.error(`Failed: ${error.code} — ${error.message}`);
  });

  // Before each API request
  hooks.beforeRequest(async (event) => {
    console.log(`API: ${event.method} ${event.path}`);
  });

  // After each API response
  hooks.afterResponse(async (event, response) => {
    console.log(`API: ${response.status} in ${response.durationMs}ms`);
  });

  // Register custom CLI commands
  hooks.registerCommands((registry) => {
    registry.add({
      name: "notify",
      description: "Send a test notification",
      action: async () => {
        console.log("Notification sent!");
      },
    });
  });
}

3. Declare permissions (third-party plugins)

Third-party plugins (gpc-plugin-*) must declare permissions:

{
  "gpc": {
    "permissions": [
      "hooks:afterCommand",
      "hooks:onError",
      "api:read"
    ]
  }
}

Read: references/permissions-system.md for the full permission list and trust model.

Available permissions:

First-party plugins (@gpc-cli/*) are auto-trusted — no permissions needed.

Trust check order (v0.9.74+): discoverPlugins() calls isPluginTrusted() before calling import() on any plugin specifier. Untrusted plugins are silently skipped without their module code ever running. Previously, GPC imported first and checked approval afterward, which allowed top-level module side-effects to execute before the trust decision was made.

Permission enforcement (v0.9.80+): Permissions are now enforced at hook registration time, not just validated. A third-party plugin without hooks:beforeRequest permission that calls hooks.beforeRequest() will see a warning instead of the hook being silently registered. If register() throws, the error is caught and the plugin is skipped with a warning -- it cannot crash the CLI. Project .gpcrc.json can no longer set approvedPlugins -- only user config (~/.config/gpc/config.json) is trusted for plugin approval.

4. Test your plugin

// tests/plugin.test.ts
import { describe, it, expect, vi } from "vitest";
import { plugin } from "../src/index.js";

describe("my-notifier plugin", () => {
  it("has required fields", () => {
    expect(plugin.name).toBe("gpc-plugin-my-notifier");
    expect(plugin.version).toBeDefined();
    expect(typeof plugin.register).toBe("function");
  });

  it("registers afterCommand hook", () => {
    const hooks = {
      beforeCommand: vi.fn(),
      afterCommand: vi.fn(),
      onError: vi.fn(),
      beforeRequest: vi.fn(),
      afterResponse: vi.fn(),
      registerCommands: vi.fn(),
    };
    plugin.register(hooks);
    expect(hooks.afterCommand).toHaveBeenCalled();
  });
});

npx vitest run

5. Install and configure

# Install locally
npm install ./gpc-plugin-my-notifier

# Or from npm
npm install -g @gpc-cli/cli-plugin-my-notifier

Add to .gpcrc.json:

{
  "plugins": ["gpc-plugin-my-notifier"],
  "approvedPlugins": ["gpc-plugin-my-notifier"]
}

Third-party plugins must be listed in approvedPlugins to load.

6. Publish to npm

# Build
npx tsc

# Test
npx vitest run

# Publish
npm publish

Naming convention:

• First-party: @gpc-cli/plugin-<name> (reserved for official plugins)
• Third-party: gpc-plugin-<name>

Verification

• gpc plugins list shows your plugin as loaded
• Hooks fire at the expected lifecycle points
• npx vitest run passes all tests
• Third-party permission errors show clear messages
• Plugin loads without blocking GPC startup

Failure modes / debugging

Related skills

• gpc-ci-integration — uses @gpc-cli/plugin-ci as an example of a first-party plugin
• gpc-setup — configuration file where plugins are registered
• gpc-troubleshooting — debugging plugin loading issues

Plugin Hooks Reference

Complete type signatures and behavior for all 6 GPC plugin hooks.

Hook execution order

Command invoked
  │
  ├─ beforeCommand(event)
  │
  ├─ For each API call:
  │   ├─ beforeRequest(requestEvent)
  │   ├─ [HTTP request]
  │   └─ afterResponse(requestEvent, responseEvent)
  │
  ├─ On success: afterCommand(event, result)
  │  On failure: onError(event, error)
  │
  └─ Done

Hooks run sequentially in registration order across plugins.

1. beforeCommand

Runs before any GPC command executes.

hooks.beforeCommand(async (event: CommandEvent) => {
  // event.command — "releases upload", "vitals crashes", etc.
  // event.args — resolved arguments { track: "beta", app: "com.example.app" }
  // event.app — package name (if available)
  // event.startedAt — Date when command started
});

Behavior: Errors in this hook propagate and can prevent the command from running.

Use cases: Validation, prerequisite checks, command logging.

2. afterCommand

Runs after a command completes successfully.

hooks.afterCommand(async (event: CommandEvent, result: CommandResult) => {
  // result.success — always true in this hook
  // result.data — command output data (varies by command)
  // result.durationMs — execution time in milliseconds
  // result.exitCode — 0 for success
});

Behavior: Errors in this hook are logged but don't change the command's exit code.

Use cases: Notifications (Slack, email), metrics, audit logging, CI step summaries.

3. onError

Runs when a command fails.

hooks.onError(async (event: CommandEvent, error: PluginError) => {
  // error.code — "API_FORBIDDEN", "AUTH_FAILED", etc.
  // error.message — human-readable error description
  // error.exitCode — 1-10 (see exit code reference)
  // error.cause — original Error object (if available)
});

Behavior: Errors in this handler are swallowed to prevent cascading failures.

Use cases: Error reporting, alerting, logging failures to external systems.

4. beforeRequest

Runs before each HTTP request to the Google Play API.

hooks.beforeRequest(async (event: RequestEvent) => {
  // event.method — "GET", "POST", "PUT", "PATCH", "DELETE"
  // event.path — API path (relative to base URL)
  // event.startedAt — Date
});

Behavior: Errors are swallowed — never blocks API calls.

Use cases: Request tracing, custom headers, API call logging.

5. afterResponse

Runs after each HTTP response from the Google Play API.

hooks.afterResponse(async (event: RequestEvent, response: ResponseEvent) => {
  // response.status — HTTP status code (200, 403, 404, etc.)
  // response.durationMs — request duration
  // response.ok — true if 2xx status
});

Behavior: Errors are swallowed.

Use cases: Performance monitoring, rate-limit tracking, API metrics.

6. registerCommands

Register custom CLI commands from your plugin.

hooks.registerCommands((registry: CommandRegistry) => {
  registry.add({
    name: "my-command",
    description: "Does something custom",
    options: [
      { flags: "--format <type>", description: "Output format" },
    ],
    action: async (args) => {
      console.log("Running custom command with:", args);
    },
  });
});

Behavior: Commands are registered synchronously during plugin load.

Use cases: Domain-specific tools, workflow shortcuts, report generators.

Error handling summary

Example: Slack notification plugin

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

export const plugin: GpcPlugin = {
  name: "gpc-plugin-slack",
  version: "1.0.0",
  register(hooks) {
    hooks.afterCommand(async (event, result) => {
      if (event.command.startsWith("releases")) {
        await fetch(process.env.SLACK_WEBHOOK!, {
          method: "POST",
          body: JSON.stringify({
            text: `✓ gpc ${event.command} completed in ${result.durationMs}ms`,
          }),
        });
      }
    });

    hooks.onError(async (event, error) => {
      await fetch(process.env.SLACK_WEBHOOK!, {
        method: "POST",
        body: JSON.stringify({
          text: `✗ gpc ${event.command} failed: ${error.code} — ${error.message}`,
        }),
      });
    });
  },
};

Plugin Permission System

How GPC manages plugin trust and permissions.

Trust model

First-party plugins (@gpc-cli/*)

• Auto-trusted — no permission validation
• Loaded automatically if installed
• Full access to all hooks and APIs
• Example: @gpc-cli/plugin-ci

Third-party plugins (gpc-plugin-*)

• Must declare permissions in package.json
• Must be listed in approvedPlugins config
• Permission violations throw PLUGIN_INVALID_PERMISSION (exit code 10)
• Users must explicitly approve each plugin

Declaring permissions

In your plugin's package.json:

{
  "name": "gpc-plugin-slack-notifier",
  "version": "1.0.0",
  "gpc": {
    "permissions": [
      "hooks:afterCommand",
      "hooks:onError"
    ]
  }
}

All permissions

Approving third-party plugins

In .gpcrc.json:

{
  "plugins": [
    "@gpc-cli/plugin-ci",
    "gpc-plugin-slack-notifier"
  ],
  "approvedPlugins": [
    "gpc-plugin-slack-notifier"
  ]
}

• plugins — list of plugins to load
• approvedPlugins — third-party plugins the user has explicitly approved
• First-party plugins don't need to be in approvedPlugins

Permission validation flow

The trust check runs before import() is called on any plugin specifier. This prevents untrusted top-level module code from executing during discovery.

discoverPlugins() resolves specifier
  │
  ├─ Is @gpc-cli/* prefix?
  │   └─ Yes → isPluginTrusted() = true → import() → Auto-trusted, skip permission validation
  │
  ├─ Is in approvedPlugins?
  │   └─ No → isPluginTrusted() = false → Skip (silent, no import())
  │
  └─ Yes → isPluginTrusted() = true → import()
        │
        ├─ Has gpc.permissions in package.json?
        │   └─ No → Reject with PLUGIN_INVALID_PERMISSION
        │
        ├─ All permissions recognized?
        │   └─ No → Reject with PLUGIN_INVALID_PERMISSION
        │
        └─ Enforce permissions

Security note: Prior to v0.9.74, GPC imported the plugin module first and checked approval afterward. This allowed untrusted top-level module code (side effects on import()) to run during discovery -- an RCE risk. The new model gates import() behind isPluginTrusted(), so unapproved plugins never execute any code.

Common permission patterns

Notification plugin (read-only)

{
  "gpc": {
    "permissions": ["hooks:afterCommand", "hooks:onError"]
  }
}

Metrics plugin (observability)

{
  "gpc": {
    "permissions": [
      "hooks:beforeCommand",
      "hooks:afterCommand",
      "hooks:onError",
      "hooks:beforeRequest",
      "hooks:afterResponse"
    ]
  }
}

Custom command plugin

{
  "gpc": {
    "permissions": [
      "commands:register",
      "api:read",
      "read:config"
    ]
  }
}

Full-access plugin

{
  "gpc": {
    "permissions": [
      "read:config", "write:config",
      "read:auth",
      "api:read", "api:write",
      "commands:register",
      "hooks:beforeCommand", "hooks:afterCommand", "hooks:onError",
      "hooks:beforeRequest", "hooks:afterResponse"
    ]
  }
}

Standalone binary

Plugins are disabled when running GPC as a standalone binary (__GPC_BINARY=1). Use the npm-installed version for plugin support.