heroku.env 0.6.1
CLI tool to manipulate environment variables on Heroku with local .env files
License: MIT license
Requires Python: >=3.7
Keywords: heroku.env heroku env herokuenv heroku_env environment variables load

==========
heroku.env
==========


.. image:: https://img.shields.io/pypi/v/heroku_env.svg
        :target: https://pypi.python.org/pypi/heroku.env

.. image:: https://pepy.tech/badge/heroku-env
        :target: https://pepy.tech/project/heroku-env
        :alt: Downloads


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.

Installation
------------
.. code-block:: bash

    pip install -U heroku.env


Requirements
------------

#. Python 3.7+
#. Your Heroku API key (found `here`_ or by running `this`_), for the Heroku API to run and authenticate you.
#. A valid Heroku app name is required to run against.
#. 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.


Features
--------

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

    Examples:

    .. code-block:: bash

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

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

    Examples:

    .. code-block:: yaml

        # 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:

    .. code-block:: yaml

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

    OR

    .. code-block:: yaml

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

    OR

    .. code-block:: yaml

        # 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:

    .. code-block:: yaml

        # 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:

    .. code-block:: yaml

        # 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:

    .. code-block:: bash

        $ 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:

    .. code-block:: bash

        $ 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.

    .. code-block:: bash

        $ 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:

    .. code-block:: bash

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


See all options with:

.. code-block:: bash

    $ heroku.env --help


Credits
-------

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

.. _sdkcodes: https://github.com/sdkcodes/heroku-config
.. _here: https://dashboard.heroku.com/account
.. _this: https://devcenter.heroku.com/articles/authentication#retrieving-the-api-token
.. _Click: https://click.palletsprojects.com
.. _heroku3: https://github.com/martyzz1/heroku3.py


=======
History
=======

0.6.1 (2023-01-11)
------------------

* Throw error if env file is empty

0.6.0 (2023-01-11)
------------------

* drop Python2 support, support 3.7+
* remove API key confirmation prompt
* update dependencies

0.5.5 (2019-02-13)
------------------

* bug fixes/improvements

0.5.4 (2019-02-12)
------------------

* fix --dump for absent files

0.5.3 (2019-02-12)
------------------

* allow dumping of env vars
* fixes for py2.x

0.5.2 (2019-01-27)
------------------

* allow skipping of env vars
* allow removal of env vars
* check for rate limit

0.5.1 (2019-01-08)
------------------

* fixes

0.5.0 (2019-01-06)
------------------

* Major revamp: Does not require Heroku CLI anymore. Uses Heroku API instead.
* Added --version/-v to check version
* Minor improvements

0.4.0 (2018-12-30)
------------------

* Detect Heroku installation and issues and launch appropriate URLs in browser to guide user
* Minor improvements

0.3.0 (2018-12-29)
------------------

* add feature to set alternate values during run
* cleanup and minor improvements

0.2.0 (2018-12-24)
------------------

* First release on PyPI.