Planning Center Add-ons CLI

This little app build and updates Planning Center Add-ons from the command line.

To install:

1. Install the package: npm install @planningcenter/add-ons-cli
2. Run the binary planningcenter-add-ons -h

The main commands are:

• create : creates a new skeleton add-on with sample code
• update : bundles and uploads add-on code to Planning Center
• watch : watch the files in the add-on directory and run update when they change
• promote : copies bundled JS code from testing to beta, or from beta to production environment

TypeScript Support & Dependencies

The CLI automatically provides @planningcenter/add-ons as a transitive dependency via npm hoisting. This means:

• No need to add it to your package.json - it's automatically available when you install the CLI
• TypeScript types work out of the box - import types and helper functions directly

Getting the Latest Version

The CLI includes @planningcenter/add-ons v6.x. To get the latest types and features:

# In your project directory
npm update @planningcenter/add-ons

When do you need to update?

• Fresh projects - Automatically get the latest v6.x when you run npm install
• Existing projects - Run npm update @planningcenter/add-ons to get new features/types

Example TypeScript Usage

// These imports work automatically - no need to install the package
import type { components } from "@planningcenter/add-ons"

const Heading = "Heading" as unknown as (typeof components)["Heading"]

See the generated template file for complete TypeScript setup instructions.

Request Flow for update / promote

ensure the add-on's oauth app has the right scopes

PATCH /api/v2/oauth_applications/:id
{ "data": { "attributes": { "add_on_scopes": "people" } }

get details about the oauth app's integrator add-on

there's an integrator_add_on record per add-on environment: testing, beta, and production.

GET /api/v2/oauth_applications/:id/integrator_add_ons

for each environment

up to 3 (testing, beta, production)

if there isn't an integrator add-on for the environment

POST /api/v2/oauth_applications/:id/integrator_add_ons
{ "data": { "attributes": {
  "environment": "",
  "oauth_authorize_url": "",
  "oauth_token_url": "",
  "oauth_identifier": "",
  "oauth_secret": "",
  "oauth_scopes": "",
  "oauth_redirect_uri": "",

  "target_organization_ids?": ""
} } }

if there is an integrator add-on for the environment

same as the post, but a patch to ensure it still matches the user's config this happens up to 3x (per environment)

PATCH /api/v2/oauth_applications/:id/integrator_add_ons/:id
{ "data": { "attributes": {
  "environment": "",
  "oauth_authorize_url": "",
  "oauth_token_url": "",
  "oauth_identifier": "",
  "oauth_secret": "",
  "oauth_scopes": "",
  "oauth_redirect_uri": "",

  "target_organization_ids?": ""
} } }

get details about the integrator add-ons's ui_extensions

GET /api/v2/oauth_applications/:id/integrator_add_ons/:id/ui_extensions

for each insertion point the user's creating a ui_extension for

up to 3 currently, but could be more: people.list.send_message, people.dashboards.background_checks.new, people./profile.background_checks.new

in test, we're uploading data.attribute.bundle that is the add-on's javascript code. in non-test, we're expecting to use a bundle_url that was set when the test ui extension was created or updated

if there isn't a ui extension already

POST /api/v2/oauth_applications/:id/integrator_add_ons/:id/ui_extensions
{ "data": { "attributes": {
  "component_version": "",
  "icon_url": "",
  "icon_dark_url": "",
  "insertion_point": "",
  "title": "",

  "bundle_url?": ""        if !env.test?
  "bundle?": "<js string>" if env.test?
} } }

if there is an existing ui extension

PATCH /api/v2/oauth_applications/:id/integrator_add_ons/:id/ui_extensions/:id
{ "data": { "attributes": {
  "component_version": "",
  "icon_url": "",
  "icon_dark_url": "",
  "insertion_point": "",
  "title": "",

  "bundle_url?": ""        if !env.test?
  "bundle?": "<js string>" if env.test?
} } }