{"id":18369234,"url":"https://github.com/envkey/envkey-source","last_synced_at":"2025-04-06T17:32:01.164Z","repository":{"id":57491366,"uuid":"102988488","full_name":"envkey/envkey-source","owner":"envkey","description":"Set OS-level shell environment variables with EnvKey. Allows EnvKey to be used with any language. Pairs well with Docker.","archived":false,"fork":false,"pushed_at":"2022-03-10T21:29:19.000Z","size":696271,"stargazers_count":63,"open_issues_count":1,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-22T04:03:25.034Z","etag":null,"topics":["bash","configuration","configuration-management","developer-tools","devops","devops-tools","docker","encryption","environment-variables","envkey","golang","openpgp","secret-management","secret-sharing","secret-storage","secrets","security","security-tools","shell","web-of-trust"],"latest_commit_sha":null,"homepage":"https://www.envkey.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/envkey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-09T22:23:53.000Z","updated_at":"2024-02-21T14:49:27.000Z","dependencies_parsed_at":"2022-08-29T20:31:26.341Z","dependency_job_id":null,"html_url":"https://github.com/envkey/envkey-source","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envkey%2Fenvkey-source","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envkey%2Fenvkey-source/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envkey%2Fenvkey-source/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envkey%2Fenvkey-source/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/envkey","download_url":"https://codeload.github.com/envkey/envkey-source/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247522473,"owners_count":20952557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","configuration","configuration-management","developer-tools","devops","devops-tools","docker","encryption","environment-variables","envkey","golang","openpgp","secret-management","secret-sharing","secret-storage","secrets","security","security-tools","shell","web-of-trust"],"created_at":"2024-11-05T23:28:49.758Z","updated_at":"2025-04-06T17:32:00.474Z","avatar_url":"https://github.com/envkey.png","language":"Go","readme":"# envkey-source\n\nIntegrate [EnvKey](https://www.envkey.com) with any language, either in development or on a server, by making your configuration available through the shell as environment variables.\n\n# v2\n\nNow that [EnvKey v2](https://v2.envkey.com) has been released, you can find version 2 of envkey-source in [a subdirectory of the EnvKey v2 monorepo](https://github.com/envkey/envkey/tree/main/public/sdks/envkey-source). Using v2 requires an EnvKey v2 organization (it won't work with ENVKEYs generated in a v1 org).\n\n[Here's a guide on migrating from v1 to v2.](https://docs-v2.envkey.com/docs/migrating-from-v1)\n\n## Installation\n\nenvkey-source compiles into a simple static binary with no dependencies, which makes installation a simple matter of fetching the right binary for your platform and putting it in your `PATH`. An `install.sh` script is available to simplify this, as well as a [homebrew tap](https://github.com/envkey/homebrew-envkey).\n\n**Install via bash:**\n\n```bash\ncurl -s https://raw.githubusercontent.com/envkey/envkey-source/master/install.sh | bash\n```\n\n***Note:** the install.sh script writes, then deletes a couple temporary files to the current directory during installation, so make sure you have write permissions for whatever directory you run this command in. In locked down environments, you may want to run it in `$HOME` to be safe.*\n\n***Another Note:** the install.sh script downloads the appropriate envkey-source binary from Github Releases by default, but Github has a fairly low rate limit for unauthenticated requests. For added redundancy, it will fail over to envkey-source-releases.s3.amazonaws.com (an S3 bucket controlled by EnvKey) and download the binary from there if the request to Github Releases fails.*\n\n**Install manually:**\n\nFind the [release](https://github.com/envkey/envkey-source/releases) for your platform and architecture, and stick the appropriate binary somewhere in your `PATH` (or wherever you like really).\n\n## Usage\n\nFirst, generate an `ENVKEY` in the [EnvKey App](https://github.com/envkey/envkey-app).\n\nThen with a `.env` file in the current directory that includes `ENVKEY=...` (in development) / an `ENVKEY` environment variable set (on a server):\n\n```bash\neval $(envkey-source)\n```\n\nNow you can access your app's environment variables in this shell, or in any process (in any language) launched from this shell.\n\nYou can also pass an `ENVKEY` directly. This isn't recommended for a real workflow, but can be useful for trying things out.\n\n```bash\neval $(envkey-source ENVKEY)\n```\n\n### Multi-Line Values\n\nIf your EnvKey config includes multi-line values, you need to load it with slightly different syntax to preserve formatting. Instead of:\n\n```bash\neval $(envkey-source)\necho $SOME_VAR\n```\n\nUse this (note the additional **double quotes**):\n\n```bash\neval \"$(envkey-source)\"\necho \"$SOME_VAR\"\n```\n\n### Flags\n\n```text\n    --cache                cache encrypted config as a local backup (default is true when .env file exists, false otherwise)\n    --no-cache             do NOT cache encrypted config as a local backup even when .env file exists\n    --cache-dir string     cache directory (default is $HOME/.envkey/cache)\n    --dot-env-compatible   change output to .env format\n    --env-file string      ENVKEY-containing env file name (default \".env\")\n    --pam-compatible       change output format to be compatible with /etc/environment on Linux\n-f, --force                overwrite existing environment variables and/or other entries in .env file\n-h, --help                 help for envkey-source\n-v, --version              prints the version\n    --verbose              print verbose output (default is false)\n    --timeout float        timeout in seconds for http requests (default 10)\n    --retries uint8        number of times to retry requests on failure (default 3)\n    --retryBackoff float   retry backoff factor: {retryBackoff} * (2 ^ {retries - 1}) (default 1)\n```\n\n### Errors\n\nIf you get an error, envkey-source will echo the error string to stdout and return false instead of setting environment variables. For example:\n\n```bash\n$ eval $(envkey-source notvalidenvkey) \u0026\u0026 ./env-dependent-script.sh\nerror: ENVKEY invalid\n```\n\n### Security - Preventing Shell Injection\n\nWhenever you use `eval`, you need to worry about shell injection. We did the worrying for you--envkey-source wraps all EnvKey variables in single quotes and safely escapes any single quotes the variables might contain. This removes any potential for shell injection.\n\n### Overriding Vars\n\nBy default, envkey-source will not overwrite existing environment variables or additional variables set in a `.env` file. This can be convenient for customizing environments that otherwise share the same configuration. But if you do want EnvKey vars to take precedence, use the `--force` / `-f` flag. You can also use [sub-environments](https://blog.envkey.com/development-staging-production-and-beyond-85f26f65edd6) in the EnvKey App for this purpose.\n\n### Working Offline\n\nenvkey-source caches your encrypted config in development so that you can still use it while offline. Your config will still be available (though possibly not up-to-date) the next time you lose your internet connection. If you do have a connection available, envkey-source will always load the latest config.\n\nBy default, caching is enabled when a `.env` file is present in the directory, and disabled otherwise. You can also enable it with the `--cache` flag or disable it with the `--no-cache` flag.\n\n### Examples\n\nAssume you have `GITHUB_TOKEN` set to `cf4b78a2b8356059f340a7df735d0f63` for the `development` environment in the EnvKey App. You generate a local development `ENVKEY`.\n\nIn your project's `.env` file (ignored from source control):\n\n```bash\n# .env\nENVKEY=GsL8zC74DWchdpvssa9z-nk7humd7hJmAqNoA\n```\n\nRun envkey-source:\n\n```bash\n$ eval $(envkey-source)\n```\n\nNow `GITHUB_TOKEN` is available in the shell:\n\n```bash\n$ echo $GITHUB_TOKEN\ncf4b78a2b8356059f340a7df735d0f63\n```\n\nOr in any process you launch from this shell:\n\n```bash\n$ python\n```\n\n```python\n\u003e\u003e\u003e import os\n\u003e\u003e\u003e os.environ[\"GITHUB_TOKEN\"]\n'cf4b78a2b8356059f340a7df735d0f63'\n```\n\nYou can do exactly the same on a **server**, except instead of putting your `ENVKEY` in a `.env` file, you'll set it as an environment variable (in whatever way you set environment variables for your host/server management platform).\n\nSo you set an environment variable on your server:\n\n```bash\nENVKEY=HSyahYDL2jBpyMnkV6gF-2rBFUNAHcQSJTiLA\n```\n\nThen you run envkey-source as part of your server start and restart commands, whatever those may be.\n\n```bash\n$ eval $(envkey-source) \u0026\u0026 server-start\n```\n\n```bash\n$ eval $(envkey-source) \u0026\u0026 server-restart\n```\n\nIf you're using envkey-source on a **CI server**, the process is much the same. Set the `ENVKEY` environment variable in your CI interface, then run `eval $(envkey-source)` before running tests.\n\n### Docker\n\nHere's a simple example using Python:\n\n```docker\nFROM python:3\n\n# install envkey-source\nRUN curl -s https://raw.githubusercontent.com/envkey/envkey-source/master/install.sh | bash\n\nRUN mkdir /code\nWORKDIR /code\nADD . /code/\n\n# set EnvKey environment variables before running the process\nCMD eval $(envkey-source) \u0026\u0026 python3 example.py\n```\n\nTo supply the `ENVKEY` in development with docker-compose, you can add it to a `.env` file, then use the `env_file` key in `docker-compose.yml`.\n\n```yml\nservices:\n  example:\n    build: .\n    env_file: .env\n```\n\nOn a server, you just need to pass the ENVKEY environment variable through to your docker container. Where to set this depends on your host, but it shouldn't be difficult.\n\nAnd now you can access EnvKey variables the same way you'd read normal environment variables.\n\n```python\n# example.py\n\nimport os\n\nprint(os.environ[\"GITHUB_TOKEN\"])\n```\n\n### envkey-source within scripts\n\nNote that if you run envkey-source inside a script, your environment variables will only be visible to commands run within that script unless you run the script with `source`, in which case they will be set in the current shell.\n\n### direnv\n\nenvkey-source works well with [direnv](https://direnv.net). Just add the following to your `.envrc` file:\n\n```bash\nexport ENVKEY=HSyahYDL2jBpyMnkV6gF-2rBFUNAHcQSJTiLA\n\nif has envkey-source; then\n  eval $(envkey-source --cache)\nfi\n```\n\nand rerun `direnv allow`.\n\n## x509 error / ca-certificates\n\nOn a stripped down OS like Alpine Linux, you may get an `x509: certificate signed by unknown authority` error when `envkey-source` attempts to load your config. [envkey-fetch](https://github.com/envkey/envkey-fetch) (which `envkey-source` wraps) tries to handle this by including its own set of trusted CAs via [gocertifi](https://github.com/certifi/gocertifi), but if you're getting this error anyway, you can fix it by ensuring that the `ca-certificates` dependency is installed. On Alpine you'll want to run:\n```\napk add --no-cache ca-certificates\n```\n\n## Other EnvKey Libraries\n\n[envkey-fetch](https://github.com/envkey/envkey-fetch) - lower level command line tool that simply accepts an `ENVKEY` and spits out decrypted config as json. Handles core fetching, decryption, verification, web of trust, redundancy, and caching logic. Does most of the work behind the scenes for this library.\n\n[envkey-ruby](https://github.com/envkey/envkey-fetch) - EnvKey Client Library for Ruby and Rails.\n\n[envkey-node](https://github.com/envkey/envkey-node) - EnvKey Client Library for Node.js.\n\n[envkeygo](https://github.com/envkey/envkeygo) - EnvKey Client Library for Go.\n\n## Further Reading\n\nFor more on EnvKey in general:\n\nRead the [docs](https://docs.envkey.com).\n\nRead the [integration quickstart](https://docs.envkey.com/integration-quickstart.html).\n\nRead the [security and cryptography overview](https://security.envkey.com).\n\n## Need help? Have questions, feedback, or ideas?\n\nPost an [issue](https://github.com/envkey/envkey-source/issues) or email us: [support@envkey.com](mailto:support@envkey.com).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvkey%2Fenvkey-source","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenvkey%2Fenvkey-source","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvkey%2Fenvkey-source/lists"}