{"id":18450829,"url":"https://github.com/patrixr/kankyo","last_synced_at":"2025-04-19T15:57:10.405Z","repository":{"id":143882176,"uuid":"341800432","full_name":"patrixr/kankyo","owner":"patrixr","description":":wrench: A nicer environment-aware alternative to .env","archived":false,"fork":false,"pushed_at":"2021-03-09T03:24:11.000Z","size":1079,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-18T06:49:47.382Z","etag":null,"topics":["cli","config","dotenv","environment","node","toml"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/patrixr.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-24T06:21:38.000Z","updated_at":"2021-10-28T04:23:36.000Z","dependencies_parsed_at":"2023-07-21T09:00:07.316Z","dependency_job_id":null,"html_url":"https://github.com/patrixr/kankyo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrixr%2Fkankyo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrixr%2Fkankyo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrixr%2Fkankyo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrixr%2Fkankyo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrixr","download_url":"https://codeload.github.com/patrixr/kankyo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249342330,"owners_count":21254272,"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":["cli","config","dotenv","environment","node","toml"],"created_at":"2024-11-06T07:26:40.364Z","updated_at":"2025-04-17T12:50:43.906Z","avatar_url":"https://github.com/patrixr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kankyō\n\n環境, かんきょう\n\nAn configurable and environment aware .env alternative.\n\n[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://forthebadge.com)\n[![forthebadge](https://forthebadge.com/images/badges/made-with-typescript.svg)](https://forthebadge.com)\n\n![](./resources/kankyo.png)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Getting started](#getting-started)\n    - [Adding to your project](#adding-to-your-project)\n    - [Installed globally](#installed-globally)\n    - [With npx](#with-npx)\n- [Usage](#usage)\n  - [From the command line](#from-the-command-line)\n  - [Programatically](#programatically)\n  - [Fron NPM scripts](#fron-npm-scripts)\n- [Environment file](#environment-file)\n- [Generating the file](#generating-the-file)\n  - [Default Variables](#default-variables)\n  - [Configurable Environments](#configurable-environments)\n  - [Options](#options)\n    - [Required fields](#required-fields)\n      - [CI/CD](#cicd)\n- [String interpolation](#string-interpolation)\n- [Full file example](#full-file-example)\n- [Cross-platform](#cross-platform)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Getting started\n\n#### Adding to your project\n\n`npm install --save kankyo`\n\n#### Installed globally\n\n`npm install -g kankyo`\n\n#### With npx\n\n`npx kankyo exec -- node app.js`\n\n## Usage\n\n### From the command line\n\n```bash\n$\u003e npx kankyo --help\n\nUsage: cli [options] [command]\n\nOptions:\n  -q --quiet          Quiet mode\n  -e, --env \u003cenv\u003e     Specify the environment manually\n  -f --force          If set, will ignore schema/required fields mismatch\n  -i, --input \u003cfile\u003e  Specify the environment file\n  -V, --version       output the version number\n  -h, --help          display help for command\n\nCommands:\n  init\n  exec\n  help [command]      display help for command\n```\n\nBy using the cli's `exec` command, followed by your own shell command, Kankyō will load the environment and run the specified command with it.\n\ne.g\n\n`npx kankyo exec -- command arg1 arg2 arg3`\n\n### Programatically\n\nAt the earliest stage possible, you can require Kankyō and call its `inject` method to load up the environment file into the current environment. As you would traditional `.env` files\n\ne.g\n\n```javascript\nrequire('kankyo').inject();\n\nconsole.log(process.env);\n```\n\n### Fron NPM scripts\n\nConfigure your scripts to run anything with Kankyo\n\n```javascript\n{\n  // ...\n  \"scripts\": {\n    \"start\": \"kankyo exec -- node app.js\"\n  }\n}\n```\n\n## Environment file\n\nKankyo is configured using a custom [TOML](https://toml.io) file\n\nThe default file name is `.kankyo.toml`\n\nHowever it also supports the following names as alternatives:\n\n- `.kankyo.toml`\n- `.environment.toml`\n- `.env.toml`\n- `kankyo.toml`\n- `environment.toml`\n- `env.toml`\n\n## Generating the file\n\nA file can be generated inside your project using the following command:\n\n`npx kankyo init`\n\n### Default Variables\n\nStart by setting the default variables of your environment\n\n```toml\n[defaults]\n\nhostname      = \"hello\"\ndatabase_name = \"my_db\"\n```\n\n### Configurable Environments\n\nYou can set any number of custom environments, here's an example of us setting a `staging` environment\n\n```toml\n[defaults]\n\n# ...\n\n[env.staging]\n\ndatabase_name = \"my_staging_db\"\n```\n\nWhen run in staging mode, the default `database_name` will be overridden by the value set under the staging block\n\n### Options\n\n* `env_var` - Set the variable name that defines which environment is used. Defaults to `NODE_ENV`\n* `uppercase` - If set, will uppercase all environment variable names. Defaults to `true`\n* `required` - An array of variable names which must be provided\n\n#### Required fields\n\nUnder the `[options]` block, you can add a list of required variables\n\ne.g\n\n```toml\n[options]\n\nrequired = [\"API_KEY]\n```\n\nAn exception will be raised if that variable is missing during runtime\n\n```bash\n\u003e kankyo exec -- \u003cyour app\u003e\n\n  kankyo:info Kankyo environment file detected: .kankyo.toml +0ms\n  kankyo:info Loading environment +1ms\n  kankyo:error Missing environment variables: API_KEY +0ms\n```\n\nThis forces users to either :\n\n- Add the value to the file (either in defaults or in the environment)\n- Add it to the shell environment\n\n```bash\n\u003e API_KEY=123 kankyo exec -- \u003cyour app\u003e\n\n  hello world !\n```\n\n##### CI/CD\n\nThis feature is particularly useful when dealing with critical variables such as passwords, api keys.\n\nYour CI/CD platform can fill in those keys during deployment, and the error message keeps developers aware when working locally.\n\n## String interpolation\n\nVariables defined in the Kankyō file support string interpolation using the `\"${...}\"` format.\n\nExample:\n\n```toml\n[defaults]\n\nword_a    = \"foo\"\nword_b    = \"bar\"\nsentence  = \"${word_a} ${word_b}\"\n```\n## Full file example\n\n```toml\n[options]\n\nenv_key     = \"NODE_ENV\"\nuppercase   = true\n\n[defaults]\n\nword_a    = \"foo\"\nword_b    = \"bar\"\nsentence  = \"${word_a} ${word_b}\"\n\n[env.production]\n\nword_a = \"hello\"\nword_b = \"world\"\n```\n\n## Cross-platform\n\nKankyō is not limited to nodejs projects. The `kankyo exec` command can run any type of project\n\nExample with Ruby:\n\nSet the `env_key` option to desired key\n\n```toml\n[options]\n\nenv_key     = \"RUBY_ENV\"\n\n# ...\n```\n\nand run your ruby project\n\n`RUBY_ENV=development kankyo exec -- ruby program.rb`\n\n## License\n\nMIT License\n\nCopyright (c) 2021 Patrick R\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrixr%2Fkankyo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrixr%2Fkankyo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrixr%2Fkankyo/lists"}