CLI tool to manipulate environment variables on Heroku with local .env files, through the Heroku API.

Mentioned in the popular PyCoder's Weekly: https://pycoders.com/issues/357

This library was a quick personal project because we used to use Heroku a lot at work and I find it really annoying when you have to add env vars manually from your local environment every time.

pip install -U heroku.env

1. Python 3.7+
2. Your Heroku API key (found here or by running this), for the Heroku API to run and authenticate you.
3. A valid Heroku app name is required to run against.
4. The absolute/relative path to the .env file is also needed, but if not provided, .env will be used as the default file name, which expects a file named .env to be present in the current working directory.

• Auto-setting of all env vars from a .env file.

  Examples:

  $ heroku.env --app swimming-briskly-123 --env-file dot.env

• Lines starting with # are considered comments in the env file and ignored.

  Examples:

  # Django settings module
  DJANGO_SETTINGS_MODULE=portfolio.settings

• Allow setting of alternate values or removal/skipping of an env var by specifying alt_value in the comments of the env file AND with the option --set-alt.

  For example, if you want to load the env vars from the .env file into a Heroku app running in production, you might want to use different values for some variables, than the ones in the .env file.

  Examples of allowed usages:

  I use a portfolio.env for my portfolio app running in Docker for local development. If I want the Heroku app to use a different value for DJANGO_SETTINGS_MODULE, I would do something like this:

  # Django settings module alt_value=portfolio.prod_settings
  DJANGO_SETTINGS_MODULE=portfolio.settings

  OR

  # Django settings module
  # alt_value=portfolio.prod_settings
  DJANGO_SETTINGS_MODULE=portfolio.settings

  OR

  # alt_value=portfolio.prod_settings
  # Django settings module
  DJANGO_SETTINGS_MODULE=portfolio.settings

  NOTE: The alt_value needs to be on the line right before the actual env var you want to change. Also note that anything (except for trailing whitespace) specified after alt_value= is used as the alternate value, so be careful.

  If you want to skip an environment variable, simply don't set alt_value to anything (use alt_value=) and it won't be set on the app. Note that this will not remove if its added already, but only skips it.

  For example, this variable will be skipped:

  # Django settings module
  # alt_value=
  DJANGO_SETTINGS_MODULE=portfolio.settings

  If you want to remove an existing environment variable, set alt_value to - (use alt_value=-) and it will be removed from the Heroku app.

  In this example, this variable will be removed:

  # Django settings module
  # alt_value=-
  DJANGO_SETTINGS_MODULE=portfolio.settings

  Any of these methods above will force the tool to replace/skip/remove DJANGO_SETTINGS_MODULE but only if you run with the option --set-alt like this:

  $ heroku.env --app swimming-briskly-123 --env-file portfolio.env --set-alt

• Secure, does not store your API key anywhere.

  There are 3 ways of passing your API key:

  • setting it as an environment variable (recommended: set as HEROKU_API_KEY before running the tool)
  • entering it in a password prompt.
  • passing with --api-key or -k

  If the API key is set as an environment variable, it will be automatically read first. All other ways of setting it will be ignored.

  If it is not set in any way, you will be given a password-type prompt to enter it.

  It is recommended for security purposes that you set it as an environment variable before running the tool, like this:

  $ export HEROKU_API_KEY=a1b12c24-ab1d-123f-5678-1234b12a0a1b

  OR you can wait for the prompt.

  This is not recommended, but is still available as an option.

  $ heroku.env --app swimming-briskly-123 --env-file dot.env --api-key a1b12c24-ab1d-123f-5678-1234b12a0a1b

• Dumping of all env vars from upstream Heroku for a specified app into a specified .env file.

  Warning: Existing .env files in the same path with the same name will be replaced. As usual, absolute/relative path to the .env file is needed, but if not provided, .env will be used as the default file name.

  Examples:

  $ heroku.env --dump --app swimming-briskly-123 --env-file dot.env

See all options with:

$ heroku.env --help

• This is inspired by a script by sdkcodes.
• martyzz1, for the heroku3 API wrapper.
• Click, for making writing CLI tools a complete pleasure.