> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Heroku add-on

> Provision and configure ButterCMS as a Heroku add-on to manage your API token and access the ButterCMS dashboard directly from Heroku.

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:

```bash theme={null}
heroku addons:create butter
```

You can also provision it from the [Heroku Elements Marketplace](https://elements.heroku.com/addons/butter), 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](https://elements.heroku.com/addons/butter#pricing).

To provision a specific plan:

```bash theme={null}
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:

```bash theme={null}
heroku config:get <APP_NAME>_BUTTER_TOKEN
```

### Local development

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

```bash theme={null}
heroku config:get <APP_NAME>_BUTTER_TOKEN -s >> .env
```

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

  ```bash theme={null}
  echo .env >> .gitignore
  ```
</Warning>

### Using the token in your app

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

```javascript theme={null}
// Node.js
const butter = require('buttercms')(process.env.<APP_NAME>_BUTTER_TOKEN);
```

```python theme={null}
# Python
import buttercms
butter = buttercms.api_client.APIClient(os.environ.get('<APP_NAME>_BUTTER_TOKEN'))
```

```ruby theme={null}
# Ruby
butter = ButterCMS::API.new(ENV['<APP_NAME>_BUTTER_TOKEN'])
```

<Info>
  `<APP_NAME>_BUTTER_TOKEN` is a read API token. If you need write access, contact [ButterCMS support](mailto:support@buttercms.com) to enable a write token.
</Info>

## Accessing the ButterCMS dashboard

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

```bash theme={null}
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

<CardGroup cols={3}>
  <Card title="JavaScript" icon="js">
    Node.js, React, Vue.js, Angular
  </Card>

  <Card title="Python" icon="python">
    Python, Django
  </Card>

  <Card title="Ruby" icon="gem">
    Ruby, Rails
  </Card>

  <Card title="PHP" icon="php">
    PHP, Laravel
  </Card>

  <Card title="Go" icon="golang">
    Go
  </Card>

  <Card title="JVM" icon="java">
    Java, Scala, Clojure
  </Card>
</CardGroup>

## Deprovisioning

To remove the ButterCMS add-on from your app:

```bash theme={null}
heroku addons:destroy butter
```

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="<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](mailto:support@buttercms.com).
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="Who do I contact for support?">
    For Heroku-specific provisioning issues, use [Heroku Support](https://help.heroku.com). For ButterCMS product questions, contact [support@buttercms.com](mailto:support@buttercms.com).
  </Accordion>
</AccordionGroup>