Skip to main content
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

RuntimeRegions
Common RuntimeUnited States, Europe
Private SpacesDublin, 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

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

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.
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.
For Heroku-specific provisioning issues, use Heroku Support. For ButterCMS product questions, contact support@buttercms.com.