envelope

envelope는 현대적인 환경 변수 (Environment Variables) 관리자입니다.

A modern environment variables manager

Usage: envelope [COMMAND]
...

설치 (Installation)

Brew

homebrew-core를 통해 envelope를 설치할 수 있습니다:

$ brew install envelope

Binary

release에서 최신 envelope binary를 다운로드하여 $PATH에 포함된 폴더로 복사할 수 있습니다.

Cargo

cargo를 사용하여 envelope를 설치할 수 있습니다. ~/.cargo 폴더가 $PATH에 포함되어 있는지 확인하세요.

$ cargo install --git https://github.com/mattrighetti/envelope
$ envelope --version
envelope 0.3.11

Arch

binary를 패키징한 envelope-bin이라는 AUR 패키지가 있습니다:

yay -S envelope-bin

소스 코드 빌드 (Building from Source)

envelope는 Rust로 작성되었습니다. Rust 컴파일러가 필요합니다.

$ git clone https://github.com/mattrighetti/envelope
$ cd envelope
$ cargo build --release
...

사용법 (Usage)

초기화 (Init)

현재 디렉토리에 envelope를 초기화합니다. 이는 .envelope 데이터베이스 파일을 생성합니다.

$ envelope init

[!NOTE]
다른 명령어를 사용하기 전에 반드시 envelope init을 실행해야 합니다. 민감한 환경 변수가 커밋되는 것을 방지하기 위해 .envelope 파일은 .gitignore에 추가해야 합니다.

예쁘게 출력하기 (Pretty print)

.env 파일을 envelope로 파이프(Pipe)하여 파일의 내용을 보기 좋게 출력할 수 있습니다.

$ cat .env | envelope

+-------------------+----------------------------------------------+
...

가져오기 (Import)

.env 파일로부터 가져오기

$ envelope import dev .env
$ envelope list dev
API_KEY=your_api_key_here
...

표준 입력(stdin)으로부터 직접 가져오는 것도 가능합니다.

$ cat .env | envelope import prod

목록 보기 (List)

저장된 모든 환경을 나열합니다:

$ envelope list
dev
staging
...

특정 환경의 환경 변수 (Environment Variables) 목록을 나열합니다:

$ envelope list dev
API_KEY=your_api_key
DATABASE_URL=postgres://user:password@localhost:5432/mydb
...

테이블 형식으로 예쁘게 출력 (Pretty print) 합니다:

$ envelope list dev --pretty-print
+-------------+----------------------------------------------+-------+
| ENVIRONMENT | VARIABLE                                     | VALUE |
...

Pretty print 모드에서 긴 값을 생략 (Truncate) 합니다:

$ envelope list dev --pretty-print --truncate

정렬 옵션 (Sorting Options)

--sort 옵션을 사용하여 정렬 순서를 지정할 수 있습니다:

• key 또는 k: 키 (Key) 기준 오름차순 정렬
• value 또는 v: 값 (Value) 기준 오름차순 정렬
• date 또는 d: 생성 날짜 기준 오름차순 정렬
• kd: 키 (Key) 기준 내림차순 정렬
• vd: 값 (Value) 기준 내림차순 정렬
• dd: 생성 날짜 기준 내림차순 정렬 (기본값)

예시:

$ envelope list dev --sort kd
SMTP_HOST=smtp.example.com
SECRET_KEY=mysecretkey123
...

추가 (Add)

환경에 환경 변수를 추가합니다:

$ envelope add dev api_key sk_test_123456789
$ envelope list dev
API_KEY=sk_test_123456789

변수 이름은 자동으로 대문자로 변환됩니다:

$ envelope add dev database_url postgres://localhost/mydb
$ envelope list dev
DATABASE_URL=postgres://localhost/mydb

민감한 데이터의 경우 표준 입력 (stdin)으로부터 값을 읽어옵니다:

$ envelope add dev secret_token --stdin
Enter value for env secret_token:
my-super-secret-token

빈 값으로 변수를 추가합니다:

$ envelope add dev optional_var
$ envelope list dev
OPTIONAL_VAR=

삭제 (Delete)

환경에서 특정 변수를 삭제합니다 (Soft delete — 복구 가능):

$ envelope delete --env dev --key API_KEY
$ envelope list dev
# API_KEY가 더 이상 나타나지 않습니다

모든 환경에서 변수를 삭제합니다:

$ envelope delete --key DEBUG_MODE
# 존재하는 모든 환경에서 DEBUG_MODE를 제거합니다

전체 환경(environment)을 삭제합니다:

$ envelope delete --env dev
$ envelope list
# dev가 더 이상 나타나지 않습니다

[!NOTE]
Envelope은 항상 환경 변수(environment variables)를 소프트 삭제 (soft deletes) 합니다. 데이터베이스에서 실제로 제거되지 않으므로, 히스토리(history)를 확인하거나 변경 사항을 되돌릴(revert) 수 있습니다.
데이터를 영구적으로 제거하는 하드 삭제 (hard delete)를 원한다면 drop 명령어를 사용하세요.

Drop

환경을 삭제(하드 삭제)하고 데이터베이스에서 해당 환경의 모든 변수를 영구적으로 제거합니다:

$ envelope drop dev
$ envelope list
# dev가 모든 히스토리를 포함하여 영구적으로 삭제되었습니다

[!WARNING]
delete와 달리, drop 명령어는 모든 데이터를 영구적으로 제거합니다.
이 작업은 되돌릴 수 없으며, 히스토리를 확인하거나 변경 사항을 되돌릴 수 없습니다.

Duplicate

기존 환경의 복사본을 생성합니다:

$ envelope add dev api_key sk_dev_12345
$ envelope add dev database_url postgres://localhost/devdb
$ envelope duplicate dev staging
...

다음과 같은 경우에 유용합니다:

• 기존 환경을 기반으로 새로운 환경 생성
• 테스트를 위해 운영(production) 설정을 스테이징(staging)으로 복사
• 변경 사항을 적용하기 전 백업 생성

예시 워크플로우:

# 실험을 수행하기 전 백업 생성
$ envelope duplicate prod prod-backup

...

Edit

$EDITOR를 열어 대화형으로 환경 변수를 편집합니다:

$ envelope edit dev

이 명령어를 실행하면 기본 에디터가 열리며 모든 변수가 다음과 같은 형식으로 표시됩니다:

API_KEY=your_api_key
DATABASE_URL=postgres://localhost/mydb
DEBUG_MODE=true

편집 팁:

• = 뒤의 텍스트를 변경하여 값을 수정합니다.
• 변수 앞에 #을 붙여 주석 처리하면 해당 변수가 삭제됩니다:

  #API_KEY=your_api_key
  

• 새로운 줄을 추가하여 새 변수를 추가합니다:

  NEW_VAR=new_value
  

에디터를 저장하고 닫으면, envelope은 다음 작업을 수행합니다:

• 수정된 모든 값을 업데이트합니다.
• 주석 처리된 모든 변수를 삭제합니다 (소프트 삭제).
• 모든 새 변수를 추가합니다.

Check

현재 쉘(shell)에 내보내기(exported) 되어 있는 환경(environment)을 확인합니다:

$ export $(envelope list dev)
$ envelope check
dev

check는 현재 쉘의 환경 변수(environment variables)를 저장된 모든 환경과 비교하여 작동합니다. 현재 내보내기 된 값과 변수들이 정확히 일치하는 모든 환경을 보여줍니다.

여러 환경이 동일한 변수를 공유하고 있다면 모두 일치할 수 있습니다:

$ envelope add shared-config api_key sk_12345
$ envelope duplicate shared-config also-shared
$ export $(envelope list shared-config)
...

완전히 일치하는 환경이 없다면 아무것도 반환되지 않습니다:

$ envelope check
# 출력이 없으면 활성화된 환경이 없음을 의미합니다

Lock

Envelope 데이터베이스를 암호화합니다. 비밀번호와 확인 절차를 요청하는 프롬프트가 나타납니다.

$ envelope lock
Password: ********
Confirm password: ********
...

[!NOTE]

데이터베이스가 잠긴(locked) 상태일 때, 필요할 때마다 잠금을 해제하라는 프롬프트가 나타납니다.
잠긴 Envelope 상태에서도 명령어를 실행할 수 있습니다.

Unlock

잠글 때 설정한 비밀번호를 사용하여 Envelope 데이터베이스를 복호화합니다.

$ envelope unlock
Password: ********
database unlocked successfully

Diff

두 환경을 비교하여 차이점을 확인합니다:

$ envelope add local db_connection http://localhost:3030
$ envelope add local dev true
$ envelope add prod db_connection https://proddb.com
...

출력 결과는 다음과 같습니다:

• 회색 # 라인: 두 환경 모두에 존재하지만 값이 다른 변수
  • 첫 번째 값은 소스 환경(local)의 값입니다.
  • 두 번째 값은 대상 환경(prod)의 값입니다.
• 빨간색 - 라인: 대상 환경(prod)에만 존재하는 변수
• 초록색 + 라인: 소스 환경(local)에만 존재하는 변수

사용 사례:

# 개발(development) 환경과 운영(production) 환경의 설정을 비교합니다
$ envelope diff dev prod

...

Revert (되돌리기)

변수를 이전 값으로 되돌립니다. revert를 호출할 때마다 히스토리(history) 상에서 한 단계씩 뒤로 이동합니다:

$ envelope add local db_connection http://localhost:3030
$ envelope add local db_connection http://localhost:2222
$ envelope add local db_connection http://localhost:3333
...

실제 예시:

# 실수로 잘못된 API 키를 설정함
$ envelope add prod api_key sk_wrong_key_12345
# 아차! 이전 값으로 되돌리기
...

[!NOTE]
revert가 작동하는 이유는 envelope가 모든 변경 사항의 전체 히스토리 (history)를 유지하기 때문입니다.
전체 히스토리를 거슬러 올라가기 위해 여러 번 되돌릴 수 있습니다.
되돌리기 전에 envelope history를 사용하여 모든 과거 값들을 확인할 수 있습니다.

Run (실행)

특정 환경 (environment)의 환경 변수 (environment variables)가 자동으로 주입된 상태로 명령어를 실행합니다. 이를 통해 셸 (shell)에 변수를 수동으로 export 할 필요가 없습니다.

$ envelope run dev -- cargo run

어떠한 명령어와 인자 (arguments)도 실행할 수 있습니다. -- 구분자는 선택 사항이지만, 실행하려는 명령어 자체에 플래그 (flags)가 포함되어 있는 경우에는 사용을 권장합니다.

부모 프로세스로부터 상속된 환경 변수들을 제거하고 싶다면, --isolated 플래그를 사용할 수 있습니다. 이 플래그를 사용하면 선택된 환경 변수들만 서브프로세스 (subprocess)에 주입되도록 보장합니다.

$ envelope add prod ENVIRONMENT=prod
$ envelope run prod env
PATH=...
...

사용 사례 (Use cases):

• 현재 셸 (shell) 환경을 오염시키지 않고 스크립트 실행
• 동일한 명령어에 대해 서로 다른 환경을 빠르게 테스트
• CI/CD 파이프라인에서 실행 단계를 래핑 (wrap) 하여 사용

History (히스토리)

삭제된 값을 포함하여 변수의 전체 히스토리를 확인합니다:

$ envelope add local db_connection http://localhost:3030
$ envelope add local db_connection http://localhost:2222
$ envelope add local db_connection http://localhost:3333
...

삭제된 변수 확인:

$ envelope add dev api_key sk_old_key
$ envelope add dev api_key sk_new_key
$ envelope delete --env dev --key api_key
...

사용 사례 (Use cases):

• 변수가 언제, 어떻게 변경되었는지 감사 (Audit)
• 실수하기 전의 이전 값 찾기
• 시간에 따른 구성 (Configuration) 변경 사항 추적
• 마지막 값을 확인하여 삭제된 변수 복구

일반적인 워크플로우 (Common Workflows)

새로운 프로젝트 시작하기

# 프로젝트에서 envelope 초기화
$ cd my-project
$ envelope init
...

일상적인 개발

# 환경 (Environments) 간 전환
$ export $(envelope list dev)
$ npm start
...

비밀값 (Secrets)의 안전한 관리

# 셸 히스토리 (Shell history)에 노출하지 않고 민감한 값 추가
$ envelope add prod database_password --stdin
Enter value for env database_password:
...

새로운 환경 설정하기

# 운영 (Production) 환경을 기반으로 스테이징 (Staging) 생성
$ envelope duplicate prod staging

...

구성 업데이트

# 운영 환경을 업데이트하기 전
$ envelope duplicate prod prod-backup

...

팀 협업

# 팀원과 환경 구조(값은 제외) 공유
$ envelope list dev --pretty-print > env-structure.txt

...

환경 문제 디버깅

# 특정 환경이 활성화되어 있는지 확인
$ envelope check

...

팁과 요령 (Tips and Tricks)

셸 별칭 (Shell Aliases)

더 빠른 워크플로우를 위해 .bashrc 또는 .zshrc에 다음을 추가하세요:

# 빠른 환경 전환
alias envdev='export $(envelope list dev)'
alias envprod='export $(envelope list prod)'
...

Docker와 함께 사용하기

# docker run으로 직접 내보내기
$ docker run --env-file <(envelope list prod) myapp

...

Docker Compose와 함께 사용하기

# docker-compose.yml
services:
  app:
...

CI/CD 통합

# CI/CD 파이프라인에서 CI 환경으로부터 비밀값을 가져올 수 있습니다
$ envelope init
$ envelope add ci DATABASE_URL "$DATABASE_URL"
...

일괄 작업 (Bulk Operations)

# 여러 환경을 빠르게 복사
$ for env in dev1 dev2 dev3; do
    envelope duplicate prod $env
...

.env 파일에서 마이그레이션하기

# 모든 .env.* 파일을 가져오기
$ for file in .env.*; do
    env_name=${file#.env.}
...

.env 파일로 다시 내보내기

# 환경(environment)을 .env 파일로 내보내기
$ envelope list prod > .env.production

...

보안 모범 사례 (Security Best Practices)

환경 변수 보호하기

항상 .gitignore에 .envelope를 추가하세요:

$ echo ".envelope" >> .gitignore

.envelope 파일은 모든 환경 변수를 포함하는 SQLite 데이터베이스입니다.
이 파일에는 다음과 같은 민감한 데이터가 포함되어 있으므로 절대로 버전 관리 시스템 (Version Control)에 커밋해서는 안 됩니다:

• API 키 및 토큰 (API keys and tokens)
• 데이터베이스 비밀번호 (Database passwords)
• 비밀 키 (Secret keys)
• OAuth 자격 증명 (OAuth credentials)

민감한 프로젝트에는 암호화를 사용하세요:

# 활발하게 개발 중이지 않을 때 데이터베이스를 잠그기
$ envelope lock
Password: ********
...