kenv

kenv는 CLI 환경에서 환경 변수를 관리하기 위해 env 명령어를 확장한 유틸리티입니다.

# .env.yaml - Powerful environment variable management
DB_USER: "admin"
DB_HOST: "localhost"

DB_PASSWORD:
  file: "/path/to/db_secret"  # Load from file

API_KEY:
  file: "/path/to/api_key"

DATABASE_URL:
  value: "postgresql://{{ .DB_USER }}:{{ .DB_PASSWORD }}@{{ .DB_HOST }}/mydb"
  refs:
    - DB_USER
    - DB_PASSWORD
    - DB_HOST  # Build from variables
  profile:
    dev: "sqlite://local.db"  # Override with profile

CONFIG_DATA:
  command:
    - curl
    - -H
    - "Authorization: Bearer {{ .API_KEY }}"
    - https://api.example.com/config
  refs:
    - API_KEY  # Fetch data from API

다양한 소스에서 환경 변수를 로드

• .env 파일 (정적 값, 파일 내용 참조, 명령 실행 결과 지원)
• YAML 설정 파일 (고급 구성 지원)
• 인라인 환경 변수 (KEY=value)
• 시스템 환경 변수
• 로드된 환경 변수를 사용해 CLI 인자를 동적으로 치환

변수 우선순위 System < .env < YAML < Inline → 뒤에 정의된 값이 이전 값을 override

설치

# Install v2 (the /v2 suffix is required)
go install github.com/gaebalai/kenv/v2@latest

# Note: github.com/gaebalai/kenv@latest will install v1 even after v2 release

명령줄 라인

kenv [OPTIONS] [ENVIRONMENT_VARIABLES] [COMMAND] [ARGS...]

옵션

• -e, --env FILE: .env 파일에서 환경 변수를 로드합니다. (여러 개 지정 가능)
• -c, --config FILE: YAML 설정 파일에서 환경 변수를 로드합니다. (여러 개 지정 가능)
• -p, --profile NAME: YAML 설정 파일에서 사용할 프로파일을 선택합니다.

기본 사용법

CLI 인자로 설정

env 명령어와 동일한 방식으로 환경 변수를 설정할 수 있습니다.

$ kenv POSTGRES_DB=your_local_dev_db psql

.env 파일에서 로드

현재 디렉터리에 있는 .env 파일을 자동으로 로드합니다. 또한 -e 옵션을 사용해 원하는 .env 파일을 직접 지정할 수도 있습니다.

$ cat .env
POSTGRES_DB=your_local_db
POSTGRES_USER=test_user
PGDATA=/var/lib/db

$ kenv psql -h localhost -p 15432
# connecting to your_local_db on localhost:15432 as test_user

# Or specify custom .env file
$ kenv -e production.env psql

Load from YAML configuration files

Both .env.yaml and .env.yml file extensions are supported. If both files exist, they will be automatically merged.

$ cat .env.yaml
DATABASE_URL: "postgresql://localhost/mydb"
PORT: "3000"

$ kenv -c .env.yaml myapp
# myapp runs with DATABASE_URL and PORT set from .env.yaml (or .env.yml)

여러 파일과 우선순위

여러 소스에서 환경 변수를 로드할 수 있습니다. 환경 변수는 다음 순서로 적용되며, 뒤에 로드된 값이 이전 값을 override 합니다.

1. 시스템 환경 변수
2. .env 파일 (지정된 순서)
3. YAML 파일 (지정된 순서)
4. 인라인 변수 (KEY=value)

# Load from multiple sources
$ kenv -e base.env -e override.env -c config.yaml DATABASE_URL=sqlite://local.db myapp

환경 변수 목록 확인

명령어 없이 실행하면 로드된 모든 환경 변수를 확인할 수 있습니다.

$ kenv
DATABASE_URL=postgresql://localhost/mydb [.yaml]
PORT=3000 [.yaml]
API_SECRET=secret_from_file [.yaml]
CURRENT_BRANCH=main [.yaml]
PATH=/usr/bin:/bin [system]
...

# List with specific configuration
$ kenv -e production.env -c config.yaml

YAML 설정 형식

기본 사용법

YAML 파일에서는 표준 key-value 형식을 사용해 환경 변수를 정의합니다.

DATABASE_URL: "postgresql://localhost/mydb"
API_KEY: "secret-key-123"
PORT: "3000"
DEBUG: "true"

고급 기능

단순 문자열 이상의 기능이 필요할 경우 **객체 형식(object format)**을 사용할 수 있습니다.

파일 내용 읽기

파일의 내용을 읽어 환경 변수 값으로 사용할 수 있습니다.

SECRET_KEY:
  file: "/path/to/secret/file"

SSL_CERT:
  file: "/etc/ssl/certs/app.pem"

명령어 실행

명령어를 실행하고, 그 출력 결과를 환경 변수 값으로 사용할 수 있습니다.

GIT_COMMIT:
  command:
    - git
    - rev-parse
    - HEAD

BUILD_TIME:
  command:
    - date
    - "+%Y-%m-%d"

변수 참조 (Alias)

다른 변수나 시스템 환경 변수를 참조할 수 있습니다.

APP_HOME:
  alias: "HOME"  # References system environment variable

PRIMARY_DB: "postgresql://primary.example.com/maindb"

DATABASE_URL:
  alias: "PRIMARY_DB"  # References another YAML variable

템플릿 (변수 치환)

refs를 추가하면 Go의 text/template 문법을 사용해 여러 변수를 조합할 수 있습니다.

DB_USER: "admin"

DB_HOST: "localhost"

DB_NAME: "myapp"

# Simple interpolation
DATABASE_URL:
  value: "postgresql://{{ .DB_USER }}@{{ .DB_HOST }}/{{ .DB_NAME }}"
  refs:
    - DB_USER
    - DB_HOST
    - DB_NAME

# Conditional logic
USE_STAGING: "true"

API_ENDPOINT:
  value: "{{ if eq .USE_STAGING \"true\" }}https://staging.api.example.com{{ else }}https://api.example.com{{ end }}"
  refs:
    - USE_STAGING

T템플릿 기능:

• {{ .VAR_NAME }} 형식으로 변수를 참조할 수 있습니다.
• 조건문 지원: {{ if }} / {{ else }} / {{ end }}
• 시스템 환경 변수, .env 변수, YAML 변수를 모두 참조할 수 있습니다.
• value와 command 모두 refs와 함께 템플릿을 사용할 수 있습니다.

프로파일 지원

환경별 설정을 관리할 수 있습니다. (예: dev, staging, prod 등)

# Basic profile usage
API_URL: "https://api.example.com"

DATABASE_HOST: "prod-db.example.com"

# Unset variable in specific profile (null value)
DEBUG_MODE: "false"

# Profile with different value types
SSL_CERT:
  file: "/etc/ssl/prod.pem"

profiles:
  dev:
    API_URL: "http://localhost:8080"
    DATABASE_HOST: "localhost"
    DEBUG_MODE: "true"
    SSL_CERT: "-----BEGIN CERTIFICATE-----\ndev-cert\n-----END CERTIFICATE-----"

  staging:
    API_URL: "https://staging-api.example.com"
    DATABASE_HOST: "staging-db.example.com"
    SSL_CERT:
      file: "/etc/ssl/staging.pem"

  prod:
    DEBUG_MODE: null  # Unset DEBUG_MODE in prod

특정 프로파일을 사용하려면 다음과 같이 실행합니다:

# Use dev profile
kenv -c config.yaml -p dev myapp

# Use staging profile
kenv -c config.yaml --profile staging deploy

시크릿 값 마스킹

secret: true를 추가하면 해당 변수의 값이 마스킹 처리됩니다. 변수 목록에서는 값이 *로 표시되며, 명령어의 stdout/stderr 출력에서는 *****로 대체됩니다.

DB_PASSWORD:
  file: "/path/to/db_secret"
  secret: true

Profile values inherit secret: true from their base configuration.

설정 규칙

값 타입 (Value Types) (각 변수에는 다음 중 하나만 지정할 수 있습니다.):

• value: 직접 문자열 값을 지정 (refs와 함께 사용하면 템플릿으로 동작)
• file: 지정한 파일 경로의 내용을 읽어 값으로 사용
• command: 명령어를 실행하고 출력 결과를 값으로 사용
• alias: 다른 변수를 참조

추가 옵션:

• refs: 템플릿에서 참조할 변수 목록 (value 또는 command와 함께 사용)
• profiles: 환경별 설정 오버라이드 (dev, staging, prod 등)

참고 사항:

• 순환 참조(예: A → B → A)가 발생하면 오류가 발생합니다.
• -p/--profile 옵션으로 프로파일을 선택하면 해당 값이 기본 설정을 덮어씁니다.
• 프로파일 값이 null이면 해당 환경에서 변수가 unset(삭제) 됩니다.

License

Apache License 2.0