Heroku Events CLI Plugin (Pilot)

Last updated December 11, 2024

This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.

Heroku Events is currently in pilot. The products offered as part of the pilot aren’t intended for production use and are considered as a Beta Service and are subject to the Beta Services terms at https://www.salesforce.com/company/legal/agreements.jsp.

The Heroku Events CLI plugin for the Heroku CLI allows you to manage, subscribe, and publish events with the Heroku Events add-on.

Install the Heroku CLI

You must have the Heroku CLI installed before adding the Heroku Events CLI plugin. See Heroku CLI for instructions.

Install the Heroku Events Plugin

To install the plugin, run the CLI command:

$ heroku plugins:install @heroku-cli/plugin-events

Provision the Heroku Events Add-on

You must provision the add-on before you can issue any commands from the plugin. If you run a command before provisioning the add-on on the app, you get the error:

$ heroku events:authorizations -a example-app
› Error: Heroku Events add-on isn’t present on ⬢ example-app.
› Install the add-on using heroku addons:create herokuevents -a example-app.

Heroku Events CLI Commands

This article includes the help texts for each of the plugin’s commands. You can see help text in your terminal with $ heroku events --help.

heroku events:authorizations

This command lists Heroku Events authorizations.

USAGE
  $ heroku events:authorizations -a <value> [-r <value>]

FLAGS
  -a, --app=<value>     (required) app to run command against
  -r, --remote=<value>  git remote of app to use

DESCRIPTION
  lists Heroku Events authorizations

EXAMPLE
$ heroku events:authorizations -a herokuevents-app

Example Output

$ heroku events:authorizations -a herokuevents-app
=== Heroku Events authorizations for app ⬢ herokuevents-app

Platform   Alias
────────── ───────────
Salesforce example-org

heroku events:authorizations:info

This command shows info for a Heroku Events authorization.

USAGE
  $ heroku events:authorizations:info [ALIAS] -a <value> [-r <value>]

ARGUMENTS
  ALIAS  Heroku Events authorization alias

FLAGS
  -a, --app=<value>     (required) app to run command against
  -r, --remote=<value>  git remote of app to use

DESCRIPTION
  shows info for a Heroku Events authorization

EXAMPLE
$ heroku events:authorizations:info example-org -a herokuevents-app

Example Output

$ heroku events:authorizations:info example-events -a herokuevents-app
Alias:    example-org
Id:       d255613d-67f5-457f-a78e-73482184f25b
Platform: Salesforce
Url:      https://dg0000000kvdomam.my.salesforce.com

heroku events:authorizations:salesforce:create

This command creates a Salesforce Platform authorization for Heroku Events.

USAGE
  $ heroku events:authorizations:salesforce:create [ALIAS] -a <value> [--browser <value>] [--sandbox | -l <value>] [-r <value>]

ARGUMENTS
  ALIAS  user chosen identifier for the org

FLAGS
  -a, --app=<value>        (required) app to run command against
  -l, --login-url=<value>  login URL to use for Salesforce login
  -r, --remote=<value>     git remote of app to use
  --browser=<value>        browser to open OAuth flow with (example: "firefox", "safari")
  --sandbox                use sandbox login URL

DESCRIPTION
  creates a Salesforce Platform authorization for Heroku Events

EXAMPLE
  $ heroku events:authorizations:salesforce:create example-org -a herokuevents-app

Example Output

$ heroku events:authorizations:salesforce:create example-org -a herokuevents-app
Opening browser to https://creds-virginia.events.heroku.com/salesforce/oauth/6c14f08c-df5d-49fe-af28-f77bfb9c5555
Press any key to open up the browser to authorize ⬢ herokuevents-app or q to exit:
Continue in your browser...

heroku events:authorizations:destroy

This command destroys a Heroku Events authorization.

USAGE
  $ heroku events:authorizations:destroy [ALIAS] -a <value> [-c <value>] [-r <value>]

ARGUMENTS
  ALIAS  Heroku Events authorization alias

FLAGS
  -a, --app=<value>      (required) app to run command against
  -c, --confirm=<value>
  -r, --remote=<value>   git remote of app to use

DESCRIPTION
  destroys a Heroku Events authorization

EXAMPLE
$ heroku events:authorizations:destroy example-org -a herokuevents-app

Example Output

$ heroku events:authorizations:destroy example-org -a herokuevents-app
 ›   Warning: Destructive Action.
 ›   This command will affect the app herokuevents-app.

To proceed, type herokuevents-app or re-run this command with --confirm herokuevents-app: herokuevents-app
Destroying authorization example-events on ⬢ herokuevents-app... !

heroku events:generate

This command creates an event generator. This can be useful to generate test events.

USAGE
  $ heroku events:generate [NAME] -a <value> -i <value> -m <value> [-r <value>] [-t <value>]

ARGUMENTS
  NAME  name for the event generator

FLAGS
  -a, --app=<value>        (required) app to run command against
  -i, --interval=<value>   (required) how often to trigger the event
  -m, --mapping=<value>    (required) the payload to be generated
  -r, --remote=<value>     git remote of app to use
  -t, --target=<value>...  name or id of the publication to link to

DESCRIPTION
  creates an event generator

EXAMPLES
  # Create an event generator named "my-generator" that triggers every minute

  $ heroku events:generate my-generator -i "1m" -m "root = {this}" -a herokuevents-app

Example Output

$ heroku events:generate my-generator -i "1m" -m "root = this" -a herokuevents-app
Creating event generator my-generator

heroku events:subscriptions

This command lists all Heroku Events subscriptions.

USAGE
  $ heroku events:subscriptions -a <value> [-j] [-r <value>]

FLAGS
  -a, --app=<value>     (required) app to run command against
  -j, --json            output in json format
  -r, --remote=<value>  git remote of app to use

DESCRIPTION
  lists Heroku Events subscriptions

EXAMPLE
$ heroku events:subscriptions -a herokuevents-app

Example Output

$ heroku events:subscriptions -a herokuevents-app
=== Heroku Events subscriptions for app ⬢ herokuevents-app

 Name               Platform   Alias
 ────────────────── ────────── ───────────
 AccountChangeEvent Salesforce example-org

heroku events:subscriptions:info

This command shows info for a Heroku Events subscription.

USAGE
  $ heroku events:subscriptions:info [SUB_NAME_OR_ID] -a <value> [-r <value>]

ARGUMENTS
  SUB_NAME_OR_ID  name or id of a Heroku Events subscription

FLAGS
  -a, --app=<value>     (required) app to run command against
  -r, --remote=<value>  git remote of app to use

DESCRIPTION
  shows info for a Heroku Events subscription

EXAMPLE
$ heroku events:subscriptions:info AccountChangeEvent -a herokuevents-app

Example Output

$ heroku events:subscriptions:info AccountChangeEvent -a herokuevents-app
Alias:    example-org
Id:       469fc380-dd0c-4ca4-b5f8-4fa4c9a91076
Name:     AccountChangeEvent
Platform: Salesforce
Topics:   ["/data/AccountChangeEvent"]

heroku events:subscriptions:salesforce:create

This command creates a Heroku Events subscription to receive Salesforce platform events or Change Data Capture events.

USAGE
  $ heroku events:subscriptions:salesforce:create [NAME] -a <value> -t <value> -A <value> [-f <value> -p <value>] [-r
  <value>]

ARGUMENTS
  NAME  name for the subscription created

FLAGS
  -A, --auth=<value>           (required) authorized Salesforce Org alias
  -a, --app=<value>            (required) app to run command against
  -f, --filter=<value>         filter to apply when linking to source
  -p, --publish-to=<value>...  existing publication name(s) or id(s) to link to
  -r, --remote=<value>         git remote of app to use
  -t, --topics=<value>...      (required) 1 or more topic(s) to subscribe to


DESCRIPTION
  creates a Heroku Events subscription to receive Salesforce platform events or Change Data Capture events

EXAMPLES
  # Create a Salesforce platform events or Change Data Capture subscription for AccountChangeEvent events from 'my-org'.

$ heroku events:subscriptions:salesforce:create accountChange -t "/data/AccountChangeEvent" -A my-org

Example Output

$ heroku events:subscriptions:salesforce:create AccountChangeEvent -a herokuevents-app -t "/data/AccountChange" -A example-org
Creating subscription AccountChangeEvent... done

heroku events:subscriptions:destroy

This command unlinks and destroys a Heroku Events subscription.

USAGE
  $ heroku events:subscriptions:destroy SUB_NAME_OR_ID -a <value> [-c <value>]

ARGUMENTS
  SUB_NAME_OR_ID  name or id of a Heroku Events subscription

FLAGS
  -a, --app=<value>      (required) app to run command against
  -c, --confirm=<value>
  -r, --remote=<value>   git remote of app to use

DESCRIPTION
  unlinks and destroys a Heroku Events subscription

EXAMPLES
  $ heroku events:subscriptions:destroy AccountChangeEvent -a herokuevents-app

Example Output

$ heroku events:subscriptions:destroy AccountChangeEvent -a herokuevents-app
Destroying subscription AccountChangeEvent on herokuevents-app

heroku events:publications

This command lists Heroku Events publications.

USAGE
  $ heroku events:publications -a <value> [-j] [-r <value>]

FLAGS
  -a, --app=<value>     (required) app to run command against
  -j, --json            output in json format
  -r, --remote=<value>  git remote of app to use

DESCRIPTION
  lists Heroku Events publications

EXAMPLE
$ heroku events:publications -a herokuevents-app

Example Output

$ heroku events:publications -a herokuevents-app
=== Heroku Events publications for app ⬢ herokuevents-app

 Name         Platform   Alias
 ──────────── ────────── ───────────
 systemStatus Salesforce example-org

heroku events:publications:info

This command shows info for a Heroku Events publication.

USAGE
  $ heroku events:publications:info [PUB_NAME_OR_ID] -a <value> [-r <value>]

ARGUMENTS
  PUB_NAME_OR_ID  name or id of the Heroku Events publication

FLAGS
  -a, --app=<value>     (required) app to run command against
  -r, --remote=<value>  git remote of app to use

DESCRIPTION
  shows info for a Heroku Events publication

EXAMPLE
  $ heroku events:publications:info systemStatus -a herokuevents-app

Example Output

$ heroku events:publications:info systemStatus -a herokuevents-app
Alias:    example-org
Filter:
Id:       af3d1a0d-ad29-4e3f-ad06-31195b99bae8
Name:     systemStatus
Platform: Salesforce
Topic:    /event/System_Status__e

heroku events:publications:salesforce:create

This command creates a Heroku Events publication to publish Salesforce platform events or Change Data Capture events.

USAGE
  $ heroku events:publications:salesforce:create [NAME] -a <value> -t <value> -A <value> [-f <value> -s <value>] [-r
  <value>]

ARGUMENTS
  NAME  name to assign to the publication created

FLAGS
  -A, --auth=<value>             (required) authorized Salesforce Org alias
  -a, --app=<value>              (required) app to run command against
  -f, --filter=<value>           filter to apply when linking to source
  -r, --remote=<value>           git remote of app to use
  -s, --subscribe-to=<value>...  existing subscription name(s) or id(s) to link to
  -t, --topic=<value>            (required) topic to publish to

DESCRIPTION
  creates a Heroku Events publication to publish Salesforce platform events or Change Data Capture events

EXAMPLES
  # Create a Heroku Event publication to publish a 'System_Status' platform event

    $ heroku events:publications:salesforce:create systemStatus -t "/event/System_Status__e" -A my-org

Example Output

$ heroku events:publications:salesforce:create systemStatus -t "/event/System_Status__e" -A example-org -a herokuevents-app
Creating publication systemStatus... done

heroku events:publications:datacloud:create

This command creates a Data Cloud publication.

USAGE
  $ heroku events:publications:datacloud:create [NAME] -a <value> -c <value> --object <value> -A <value> [-f <value> -s <value>] [-r
    <value>]

ARGUMENTS
  NAME  name for the publication created

FLAGS
  -A, --auth=<value>       (required) authorized Salesforce Org alias
  -a, --app=<value>        (required) app to run command against
  -c, --connector=<value>  (required) ingest API Data Connector name
  -f, --filter=<value>     filter to apply when linking to source
  -r, --remote=<value>     git remote of app to use
  -s, --source=<value>...  name or id of the subscription to link to
  --object=<value>         (required) object to publish to

DESCRIPTION
  creates a Data Cloud publication

EXAMPLES
  # Create a Data Cloud target ingesting

   $ heroku events:publications:datacloud:create ordersDataTarget -a herokuevents-app -c "SalesConnector" --object "Orders" -A example-org

Example Output

$ heroku events:publications:datacloud:create ordersDataTarget -a herokuevents-app -c "SalesConnector" --object "Orders" -A example-org
Creating publication ordersDataTarget... done

heroku events:publications:webhook:create

This command creates a webhook publication.

USAGE
  $ heroku events:publications:webhook:create [NAME] -a <value> -u <value> [-f <value> -s <value>] [-r <value>] [-t
  <value>] [-H <value>]

ARGUMENTS
  NAME  name for the publication created

FLAGS
  -H, --header=<value>     [default: Authorization] header field to use for access token
  -a, --app=<value>        (required) app to run command against
  -f, --filter=<value>     filter to apply when linking to source
  -r, --remote=<value>     git remote of app to use
  -s, --source=<value>...  name or id of the subscription to link to
  -t, --token=<value>      access token
  -u, --url=<value>        (required) webhook URL

DESCRIPTION
  creates a webhook publication

EXAMPLES
  # Create a Webhook URL target

    $ heroku events:publications:webhook:create opportunityChanged -u "https://herokuevents-app.herokuapp.com/webhooks" -a herokuevents-app

Example Output

$ heroku events:publications:webhook:create opportunityChanged -u "https://herokuevents-app.herokuapp.com/webhooks" -a herokuevents-app
Creating publication opportunityChanged... done

heroku events:publications:destroy

This command unlinks and destroys a Heroku Events publication.

USAGE
  $ heroku events:publications:destroy PUB_NAME_OR_ID -a <value> [-c <value>]

ARGUMENTS
  PUB_NAME_OR_ID  name or id of the Heroku Events publication

FLAGS
  -a, --app=<value>      (required) app to run command against
  -c, --confirm=<value>
  -r, --remote=<value>   git remote of app to use

DESCRIPTION
  unlinks and destroys a Heroku Events publication

EXAMPLE
  $ heroku events:publications:destroy systemStatus -a herokuevents-app

Example Output

$ heroku events:publications:destroy systemStatus -a herokuevents-app
Destroying publication systemStatus on herokuevents-app

heroku events:streams

This command lists Heroku Events streams.

USAGE
  $ heroku events:streams -a <value> [-j] [-r <value>]

FLAGS
  -a, --app=<value>     (required) app to run command against
  -j, --json            output in json format
  -r, --remote=<value>  git remote of app to use

DESCRIPTION
  lists Heroku Events streams

EXAMPLE
$ heroku events:streams -a herokuevents-app

heroku events:streams:create

This command links a publication to a subscription.

USAGE
  $ heroku events:streams:create [SOURCE] [TARGET] -a <value> [-f <value> ] [-r <value>]

ARGUMENTS
  SOURCE  name or id of an existing subscription
  TARGET  name or id of an existing publication

FLAGS
  -a, --app=<value>     (required) app to run command against
  -f, --filter=<value>  filter to apply
  -r, --remote=<value>  git remote of app to use

DESCRIPTION
  links a publication to a subscirption

EXAMPLES
  $ heroku events:streams:create subAccountChange pubAccountChange -a herokuevents-app

Example Output

$ heroku events:streams:create subAccountChange pubAccountChange -a herokuevents-app
Linking subAccountChange to pubAccountChange... done

heroku events:streams:destroy

This command unlinks a publication from a subscription.

USAGE
  $ heroku events:streams:destroy [SOURCE] [TARGET] -a <value> [-r <value>]

ARGUMENTS
  SOURCE  name or id of an existing subscription
  TARGET  name or id of an existing publication

FLAGS
  -a, --app=<value>     (required) app to run command against
  -r, --remote=<value>  git remote of app to use

DESCRIPTION
  unlinks a publication from a subscription

EXAMPLES
  $ heroku events:streams:destroy subAccountChange pubAccountChange -a herokuevents-app

Example Output

$ heroku events:streams:destroy subAccountChange pubAccountChange -a herokuevents-app
Unlinking subAccountChange to pubAccountChange... done

Feedback

Log in to submit feedback.