envmap - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #llm #deep-learning #linux #macos #nodejs #cli #vue #awesome-list #security #ios #openai

envmap

(★ 130)

ENV management tool, consolidate and manage local .env and env variables.

파일 탐색기

최종 버전 다운로드 (.zip)

- - go.yml
  - release.yml
- aws_secretsmanager.go
- aws_ssm.go
- config.go
- crypto_test.go
- doppler.go
- gcp.go
- local.go
- local_test.go
- mapping.go
- mapping_test.go
- metadata.go
- onepassword.go
- provider.go
- provider_test.go
- vault.go
config.go
config_test.go
env.go
envfile.go
envfile_test.go
go.mod
go.sum
init_interactive.go
LICENSE
logo.svg
main.go
prompt.go
README.md
spawn.go
spawn_test.go
sync.go

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/BinSquare/envmap

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd envmap

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Go go install 명령어를 쓰려면 Go가 필요합니다.

go install github.com/binsquare/envmap@latest

지정된 버전을 바로 다운로드해서 설치합니다. 레포를 직접 클론할 필요가 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Go

보통

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Go Go 언어 컴파일러 및 도구 모음입니다.

go install github.com/binsquare/envmap@latest

지정된 버전을 바로 다운로드해서 설치합니다. 레포를 직접 클론할 필요가 없습니다.

✅ 빌드가 에러 없이 끝나면 성공입니다. go run . 을 썼다면 터미널 출력을 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <img src="./logo.svg" alt="envmap logo" width="280">
</p>

<p align="center">
  <a href="https://github.com/binsquare/envmap/stargazers">
    <img src="https://img.shields.io/github/stars/binsquare/envmap?style=social" alt="GitHub stars">
  </a>
  <a href="https://github.com/binsquare/envmap/actions/workflows/release.yml">
    <img src="https://img.shields.io/github/actions/workflow/status/binsquare/envmap/release.yml?branch=main&event=push&label=release" alt="Release workflow status">
  </a>
  <a href="https://pkg.go.dev/github.com/binsquare/envmap">
    <img src="https://pkg.go.dev/badge/github.com/binsquare/envmap" alt="Go pkg Reference">
  </a>
  <a href="https://goreportcard.com/report/github.com/binsquare/envmap">
    <img src="https://goreportcard.com/badge/github.com/binsquare/envmap" alt="Go Report Card">
  </a>
  <a href="https://github.com/binsquare/envmap/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/binsquare/envmap" alt="License: Apache-2.0">
  </a>
</p>

# envmap

`envmap` is a local env manager that helps you:

1.  Keep local environment variables in sync with the remote secret stores, per project.
2.  Makes the `.env` file an ephemeral artifact, to keep secrets providers the source of truth. i.e. "envmap --sync" to produce a newly updated `.env` file.
3.  Comes with metadata on each key stored to inform when those keys were last changed/created for sake of doing routine rotations.
4.  Potentially better security since you're not locked to storing secrets in a plaintext `.env` file.
5.  Runs completely local + opensource for audits.

### Who is this for?

- Engineers working with multiple `.env` variants like `.env.prod, .env.dev, .env.staging`. This will help you consolidate and switch environments with a single command. Here's an example of that workflow:

```
(base) binsquare@mac.lan:~/Documents/envMap (main*) $ ./envmap sync --env prod
Wrote .env (1 secrets)
(base) binsquare@mac.lan:~/Documents/envMap (main*) $ cat .env
# generated by envmap sync 2025-12-01T07:49:20Z
testkey=apishofih123
(base) binsquare@mac.lan:~/Documents/envMap (main*) $ ./envmap sync --env dev
Wrote .env (1 secrets)
(base) binsquare@mac.lan:~/Documents/envMap (main*) $ cat .env
# generated by envmap sync 2025-12-01T07:50:07Z
testkey=test123
```

- Engineers working a long list of env variables just wants a thin that helps you manage that increases dev velocity by making sure you have metadata
- Engineers working across multiple projects and wants to consolidate and track ENV variables globally.

## Installation

### Option 1: Go toolchain

```sh
go install github.com/binsquare/envmap@latest
```

### Option 2: Prebuilt binary (bash)

```sh
# install into /usr/local/bin (requires sudo)
curl -sSfL "https://github.com/binsquare/envmap/releases/latest/download/envmap_$(uname -s)_$(uname -m).tar.gz" \
  | sudo tar -xz -C /usr/local/bin envmap

# or install into ~/.local/bin (no sudo; ensure it's on PATH)
mkdir -p ~/.local/bin
curl -sSfL "https://github.com/binsquare/envmap/releases/latest/download/envmap_$(uname -s)_$(uname -m).tar.gz" \
  | tar -xz -C ~/.local/bin envmap

# (optional) verify checksum (adjust path if using ~/.local/bin)
curl -sSfL "https://github.com/binsquare/envmap/releases/latest/download/envmap_$(uname -s)_$(uname -m).tar.gz.sha256" \
  | sha256sum --check -
```

If you use the `~/.local/bin` option, make sure your shell loads it (most modern shells already do; otherwise append `export PATH="$HOME/.local/bin:$PATH"` to your profile).

Restart the shell (or reload the profile) and run `envmap --help` to verify.

## Quick start (local provider)

```sh
# 1. Generate encryption key (writes to ~/.envmap/key)
envmap keygen

# 2. Configure global provider (wizard; runs keygen if needed)
envmap init --global

# 3. Create project config (wizard)
envmap init

# 4. Add secrets
envmap set --env dev DATABASE_URL --prompt
envmap set --env dev STRIPE_KEY --prompt

# 5. Inspect/export/run
envmap get --env dev --all
eval $(envmap export --env dev)
envmap run --env dev -- npm start
```

Prefer the wizards, but manual config is supported. Use absolute paths (Go does not expand `~` or `${HOME}`).

<details>
<summary>Manual configuration reference</summary>

### Global config (`~/.envmap/config.yaml`)

```yaml
providers:
  local-dev:
    type: local-file
    path: /Users/<you>/.envmap/secrets.db
    encryption:
      key_file: /Users/<you>/.envmap/key
```

### Project config (`.envmap.yaml`)

```yaml
project: demo
default_env: dev
envs:
  dev:
    provider: local-dev
    prefix: demo/dev/
```

</details>

## Usage

- `envmap run [--env <name>] -- <command>` – fetch secrets and run the command with them injected as env vars (disk never sees them).
- `envmap export [--env <name>] [--format plain|json]` – output suitable for `eval`, direnv, or tooling.
- `envmap get --env <name> KEY [--raw]` – read individual secrets.
- `envmap get --env <name> --all [--raw] [--global]` – list all secrets (masked by default); `--global` iterates all envs.
- `envmap set --env <name> KEY (--prompt | --file PATH)` – write/update secrets without shell history.
- `envmap import PATH --env <name> [--delete]` – ingest existing `.env` files.
- `envmap sync --env <name> [--out .env] [--merge] [--keep-local] [--force] [--backup=false]` – write a .env file from provider secrets. Provider wins by default; merge keeps extra local-only keys; keep-local preserves local values on conflict; backup writes .bak first.
- `envmap sync --env <name> --check` – report drift between provider and .env without writing.
- `envmap keygen [-o PATH]` – create a 256-bit key for the local provider.
- `envmap validate` – confirm `.envmap.yaml` and global config reference defined providers.
- `envmap init` / `envmap init --global` – interactive project/global configuration.

### Use with direnv

```sh
# .envrc
eval "$(envmap export --env dev)"
```

Then run `direnv allow`. Every time you enter the directory, direnv will re-run `envmap export` and populate the shell with fresh secrets without touching disk.

## Configuration

### Global config (`~/.envmap/config.yaml`)

```yaml
providers:
  aws-dev:
    type: aws-ssm
    region: us-west-2
    profile: dev # optional, uses default credential chain

vault-prod:
    type: vault
    address: https://vault.internal:8200
    mount: secret # default: secret

local:
    type: local-file
    path: ~/.envmap/secrets.db
    encryption:
      key_file: ~/.envmap/key # must be chmod 600
      # or: key_env: ENVMAP_KEY
```

### Project config (`.envmap.yaml`)

```yaml
project: myapp
default_env: dev

envs:
  dev:
    provider: aws-dev
    path_prefix: /myapp/dev/

staging:
    provider: aws-dev
    path_prefix: /myapp/staging/

local:
    provider: local
    prefix: myapp/
```

## Built-in providers (WIP)

| Type                 | Auth                       | Notes                                                   |
| -------------------- | -------------------------- | ------------------------------------------------------- |
| `aws-ssm`            | IAM (profile/env/instance) | Requires `path_prefix`. Uses SecureString.              |
| `aws-secretsmanager` | IAM                        | Full secret names. JSON secrets expanded to `name/key`. |
| `gcp-secretmanager`  | ADC or service account     | Reads latest version. Adds version on write.            |
| `vault`              | Token (env/config)         | KV v2. Configurable mount path and namespace.           |
| `onepassword`        | Connect server             | Requires `connect_host`. Items matched by title.        |
| `doppler`            | Service token              | Read-only; writes require Doppler CLI.                  |
| `local-file`         | AES-256-GCM                | Key from file (0600) or env var. For local dev.         |

## Security Model

- Secrets never touch disk during normal operation. (unless you choose to use localstore to store all your env variables)
- We only have`set --prompt` and `set --file` avoid saving secrets to shell history.
- Values are masked by default in `env` and `get` output

## Contributions

Contributions and bug reports are welcome—open an issue or submit a PR if you find a bug.

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) for details.