Heroku add-on - ButterCMS Docs

The ButterCMS Heroku add-on lets you provision a ButterCMS account directly from Heroku. Your API token is automatically injected as a config var, and you can access the ButterCMS dashboard via Heroku SSO — no separate login required.

Provisioning

Provision the add-on using the Heroku CLI:

heroku addons:create butter

You can also provision it from the Heroku Elements Marketplace, or directly from the Resources tab of your app in the Heroku dashboard. For available plans and pricing, see the ButterCMS listing on the Heroku Elements Marketplace. To provision a specific plan:

heroku addons:create butter --app YOUR_APP_NAME

Regional availability

Runtime	Regions
Common Runtime	United States, Europe
Private Spaces	Dublin, Frankfurt, London, Montreal, Mumbai, Oregon, Singapore, Sydney, Tokyo, Virginia

Accessing your API token

After provisioning, a <APP_NAME>_BUTTER_TOKEN config var is automatically added to your Heroku app. Confirm it is set with:

heroku config:get <APP_NAME>_BUTTER_TOKEN

Local development

To use the token in your local environment, add it to a .env file:

heroku config:get <APP_NAME>_BUTTER_TOKEN -s >> .env

Make sure .env is listed in your .gitignore to avoid accidentally committing your API token to version control.

echo .env >> .gitignore

Using the token in your app

Reference <APP_NAME>_BUTTER_TOKEN as an environment variable in your application code rather than hardcoding it:

// Node.js
const butter = require('buttercms')(process.env.<APP_NAME>_BUTTER_TOKEN);

# Python
import buttercms
butter = buttercms.api_client.APIClient(os.environ.get('<APP_NAME>_BUTTER_TOKEN'))

# Ruby
butter = ButterCMS::API.new(ENV['<APP_NAME>_BUTTER_TOKEN'])

<APP_NAME>_BUTTER_TOKEN is a read API token. If you need write access, contact ButterCMS support to enable a write token.

Accessing the ButterCMS dashboard

Open the ButterCMS dashboard directly from the CLI using Heroku SSO:

heroku addons:open butter

You can also access it by clicking the ButterCMS icon in the Add-ons section of your app in the Heroku dashboard.

Supported languages & frameworks

JavaScript

Node.js, React, Vue.js, Angular

Python

Python, Django

Ruby

Ruby, Rails

PHP

PHP, Laravel

Go

JVM

Java, Scala, Clojure

Deprovisioning

To remove the ButterCMS add-on from your app:

heroku addons:destroy butter

Deprovisioning is permanent and will destroy all content and data associated with the add-on. This action cannot be undone.

Troubleshooting

<APP_NAME>_BUTTER_TOKEN is not set after provisioning

Run heroku config to list all config vars for your app. If <APP_NAME>_BUTTER_TOKEN is missing, try reprovisioning the add-on or contact ButterCMS support.

I can't open the dashboard with heroku addons:open butter

Ensure you are logged in to the Heroku CLI (heroku login) and that the add-on is provisioned for the correct app. Specify the app explicitly if needed: heroku addons:open butter --app YOUR_APP_NAME.

Who do I contact for support?

For Heroku-specific provisioning issues, use Heroku Support. For ButterCMS product questions, contact support@buttercms.com.

​Provisioning

​Regional availability

​Accessing your API token

​Local development

​Using the token in your app

​Accessing the ButterCMS dashboard

​Supported languages & frameworks

JavaScript

Python

Ruby

PHP

Go

JVM

​Deprovisioning

​Troubleshooting

Provisioning

Regional availability

Accessing your API token

Local development

Using the token in your app

Accessing the ButterCMS dashboard

Supported languages & frameworks

Deprovisioning

Troubleshooting