대상 사용자: 프로그래머. Go로 작성된 Mike Farah yq 4.54.1을 사용해 YAML 설정에서 필요한 값을 뽑고 조건을 검사하는 Windows x64 실습입니다. 같은 이름의 Python 프로그램과 구분하세요. 공식 릴리스와 공식 문서를 2026-10-11에 확인했습니다.
다운로드·설치
첨부 yq-4.54.1-windows-x64-ko.zip에는 수정하지 않은 공식 Windows amd64 ZIP, 라이선스·고지문, 한국어 설명서, YAML 실습이 포함됩니다. Windows ARM64와 32비트 사용자는 공식 릴리스에서 자신의 아키텍처에 맞는 파일을 선택하세요. 이 첨부의 실행 파일은 Windows x64용입니다.
- 첨부를 전용 폴더에 모두 압축 해제합니다.
- 그 폴더에서 PowerShell을 엽니다. 설명서에 적힌 명령은 모두 압축을 푼 최상위 폴더 기준입니다.
- 다음 명령으로 내부 공식 ZIP을
bin폴더에 풉니다. 처음 실습할 때 기존bin폴더가 없는 새 폴더를 사용하세요.
Expand-Archive -LiteralPath .\official\yq_windows_amd64.zip -DestinationPath .\bin
& .\bin\yq_windows_amd64.exe --version
예상 버전은 yq (https://github.com/mikefarah/yq/) version v4.54.1입니다. PATH 등록이나 관리자 권한은 필요하지 않습니다. &는 PowerShell에서 지정한 실행 파일을 호출하는 연산자입니다. 공식 사용 안내에도 별도 런타임 없이 실행하는 배포 방식이 설명되어 있습니다.
공식 ZIP의 SHA-256은 아래 값이며, 공식 GitHub 릴리스의 자산 digest와 실제 다운로드 파일이 일치하는지 확인했습니다. 이 값은 안쪽 공식 ZIP에 대한 값입니다.
c2fb1234e58a3b80e358a0a8baeaf7ec51bfa698bbe40e2fcab0ed37d590c107
YAML 값 읽기와 필터링
practice/config.yaml에는 게이트웨이 이름과 활성·비활성 센서 3개가 들어 있습니다. 실제 주소나 인증 정보는 포함하지 않았습니다.
& .\bin\yq_windows_amd64.exe -r '.gateway.name' .\practice\config.yaml
& .\bin\yq_windows_amd64.exe -r '.sensors[] | select(.enabled == true) | .name' .\practice\config.yaml
& .\bin\yq_windows_amd64.exe -o=json '.' .\practice\config.yaml
첫 명령은 lab-gateway, 두 번째 명령은 temperature와 humidity를 줄 단위로 출력합니다. 세 번째는 전체 내용을 JSON으로 출력합니다. 표현식은 PowerShell 작은따옴표로 감싸고, 파일 경로는 별도 인자로 전달합니다. 활성 센서 선택은 공식 select 연산자 문서를 참고할 수 있습니다.
조건을 종료 코드로 검사하기
& .\bin\yq_windows_amd64.exe -e '.gateway.retry_count > 0' .\practice\config.yaml
$LASTEXITCODE
& .\bin\yq_windows_amd64.exe -e '.gateway.retry_count > 10' .\practice\config.yaml
$LASTEXITCODE
예제의 재시도 수는 3입니다. 첫 조건은 true와 종료 코드 0, 두 번째는 false와 종료 코드 1이 예상됩니다. -e는 결과가 없거나 null·false일 때 실패 종료 상태를 내는 옵션입니다. 종료 코드는 바로 확인하세요. -e는 YAML 문서가 임의의 스키마 전체를 만족하는지 검사하는 기능이 아닙니다.
이 글의 조회 명령은 파일을 수정하지 않습니다. -i를 넣은 명령은 원본 YAML을 덮어쓰는 방식이므로 수정 실습은 복사본에서 별도로 진행하세요. 출력 문자열이 다르게 보이면 먼저 --version으로 Go 버전 yq를 사용 중인지 확인합니다.
첨부 실습과 문제 해결
practice/EXPECTED-KO.txt에 예상 값과 종료 코드를 정리했습니다. 공식 실행 파일로 위 조회·필터·JSON 변환·조건 검사를 실행해 확인했으며, 실습 전후 YAML 파일의 바이트도 동일했습니다.
| 증상 | 해결 방법 |
|---|---|
| 실행 파일을 찾지 못함 | 안쪽 공식 ZIP을 bin에 풀었는지, 현재 폴더가 첨부 최상위 폴더인지 확인합니다. |
| 현재 PC에서 실행할 수 없다고 표시 | 운영체제와 CPU 아키텍처를 확인하고 공식 릴리스의 맞는 배포본을 사용합니다. |
.gateway 조회가 예상과 다름 |
들여쓰기, 키 철자, 실제 파일 인자, 다른 이름의 yq가 실행됐는지 확인합니다. |
| 조건 결과가 false인데 작업이 성공으로 처리됨 | -e를 추가하고 $LASTEXITCODE를 즉시 확인합니다. |
| 한글이 깨져 보임 | YAML을 UTF-8로 저장하고 터미널의 UTF-8 표시 설정을 확인합니다. |
원본·라이선스·소스
공식 원본은 official/yq_windows_amd64.zip에 보존했습니다. yq의 MIT 라이선스와 실행 파일에 포함된 의존성 27개의 원문 라이선스·고지문은 licenses 폴더에 있습니다. 소스 제공이 필요한 MPL 구성요소인 HCL의 해당 버전 전체 소스 ZIP도 함께 넣었습니다. 출처·버전은 licenses/THIRD-PARTY-SOURCES.json과 licenses/BUILD-INFO.txt에 적었습니다. 라이선스 파일은 실행 파일을 다시 배포할 때도 보존하세요.
공식 yq 소스: v4.54.1 소스 저장소. 본 설명서와 직접 만든 실습 데이터는 CC0-1.0이며, 실행 파일·각 구성요소는 각각의 원본 라이선스를 따릅니다.