윈도우에서 구글 CLI 설치하기 - PATH 설정 방법
2026.07.27

요약
7/27 무니님의 2주차 설치세션 - gws CLI 설치를 수강했습니다.
설치 과정에서 막혔던 부분을 정리해보았습니다.
구글 워크스페이스 CLI를 윈도우에 설치하면서 PATH 문제로 세 번 막혔고, 세 번 다 원인이 달랐습니다. 이 글은 그 세 가지를 순서대로 정리한 기록입니다.
이런 분께 도움이 됩니다
윈도우에서 명령어 도구를 처음 설치해보는 비개발자
분명히 설치했는데 “명령이 아닙니다”가 뜨는 분
PATH가 뭔지 대충만 알고 넘어갔던 분
진행 방법
PATH가 뭔가요?
이걸 모르면 뒤의 이야기가 안 풀립니다. 딱 한 줄로 정리하면 이렇습니다.
PATH는 컴퓨터가 프로그램을 찾을 때 뒤지는 폴더 주소록입니다.
gws라고 치면 컴퓨터는 그 이름의 프로그램이 어디 있는지 모릅니다. 그래서 주소록에 적힌 폴더들을 위에서부터 하나씩 열어보고, 거기서 gws.exe를 찾으면 실행합니다. 주소록에 없는 폴더에 프로그램이 있으면 컴퓨터는 영원히 못 찾습니다.
중요한 건 이겁니다. 주소록에는 주소만 적히고 내용물은 따라다니지 않습니다. 이사를 갔는데 주소록을 안 고치면 빈 집에 찾아가는 것과 같습니다.
1단계: 설치 파일 받아서 압축 풀기
가이드대로 윈도우용 압축파일을 받아서 풀면 파일 네 개가 나옵니다.
gws.exe
README.md
LICENSE
CHANGELOG.md여기서 압축을 푼 폴더를 어디에 둘지 먼저 정하세요. 이게 이 글의 핵심입니다.
나중에 옮길 거면 지금 옮기세요.
저는 이렇게 안정적인 위치에 뒀습니다.
C:\Users\사용자이름\AppData\Local\Programs\gws다운로드 폴더에 그대로 두는 것도 가능하지만, 다운로드 폴더는 나중에 지우기 쉬워서 추천하지 않습니다.
여기에 압축 푼 폴더의 파일 네 개가 보이는 화면 스크린샷을 넣으면 좋아요.
2단계: PATH에 등록하기
윈도우 키를 누르고 “환경 변수” 입력
“계정의 환경 변수 편집” 클릭
위쪽 사용자 변수에서 Path 선택 후 편집
새로 만들기를 누르고 1단계의 폴더 경로 붙여넣기
확인을 두 번 눌러서 창을 모두 닫기
여기에 환경 변수 편집 창 스크린샷을 넣으면 좋아요.
3단계: 반드시 새 명령 프롬프트를 열기
PATH 변경은 새로 여는 창부터 적용됩니다. 이미 열려 있던 창은 예전 주소록을 그대로 들고 있습니다.
시작 메뉴에서 cmd를 검색해 새로 열고 확인합니다.
gws --version버전 번호가 나오면 성공입니다.
오류 원인
위 3단계를 다 했는데도 저는 계속 이 화면을 봤습니다.
'gws'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는
배치 파일이 아닙니다.함정 1: 폴더를 옮겼다
가장 큰 원인이었습니다. 저는 다운로드받은 폴더를 D드라이브로 옮겼는데, 그게 화근이었습니다.
PATH에는 옮기기 전 주소가 남아 있었고, 컴퓨터는 없는 폴더를 계속 뒤지고 있었습니다. 빈 집에 찾아간 겁니다.
해결: 폴더를 고정된 위치 한 곳에 두고, 그 주소로 PATH를 다시 등록했습니다.
교훈: 처음 압축을 푼 폴더는 일단 옮기지 마세요. 옮길 거면 PATH를 반드시 다시 등록해야 하고, 그 과정에서 꼬입니다. 나중에 알았는데 가이드에도 이미 적혀 있었습니다.
이 폴더를 원래 위치에 두세요. 나중에 옮기면 PATH를 다시 등록해야 합니다.
급할 때 쓰는 우회로
PATH 등록이 자꾸 안 되면, 전체 주소로 바로 실행할 수 있습니다. PATH를 안 거치고 프로그램을 직접 지목하는 방식입니다.
"%LOCALAPPDATA%\Programs\gws\gws.exe" --version일단 이걸로 프로그램 자체는 멀쩡하다는 걸 확인하면 마음이 좀 놓입니다. 문제가 프로그램이 아니라 주소록에 있다는 게 확인되니까요.
설치 후에 또 걸린 것 두 개
PATH를 넘고 나서도 두 번 더 막혔습니다. 짧게 적어둡니다.
작은따옴표는 cmd에서 인용부호가 아니다
가이드 예시를 그대로 따라 쳤는데 계속 에러가 났습니다.
gws drive files list --params '{"pageSize": 5}' --format table돌아온 답은 이랬습니다.
error[validation]: error: unexpected argument '5}'' found원인은 cmd가 작은따옴표를 인용부호로 취급하지 않기 때문입니다. 그냥 글자로 봅니다. 그래서 공백에서 명령이 잘리고 5}'가 정체불명의 조각으로 넘어간 겁니다.
cmd에서는 큰따옴표로 감싸고, 안쪽 큰따옴표는 백슬래시로 표시해야 합니다.
gws drive files list --params "{\"pageSize\": 5}" --format table이렇게 바꾸니 바로 됐습니다.
성공인데 실패인 줄 알았다
되돌릴 수 없는 작업 전에 미리보기를 해주는 기능이 있습니다. 실제로 보내지 않고 어떤 요청이 갈지만 보여줍니다.
gws calendar +insert --summary "테스트 회의" --start "2026-07-28T10:00:00+09:00" --end "2026-07-28T11:00:00+09:00" --dry-run결과가 이렇게 나옵니다.
{
"body": {
"end": { "dateTime": "2026-07-28T11:00:00+09:00" },
"start": { "dateTime": "2026-07-28T10:00:00+09:00" },
"summary": "테스트 회의"
},
"dry_run": true,
"method": "POST",
"url": "https://www.googleapis.com/calendar/v3/calendars/primary/events"
}저는 이걸 보고 “또 막혔나” 했습니다. 캘린더에 아무것도 안 생겼거든요. 그런데 이게 성공 화면이었습니다. "dry_run": true가 실제로는 안 보냈다는 표시입니다.
에러였다면 이렇게 나왔을 겁니다.
error[validation]: ...
"code": 400구분법은 간단합니다. error나 code라는 단어가 있으면 실패, 없으면 성공입니다.
배운 점
1. 안 되는 이유가 매번 달랐다
같은 증상(“명령이 아닙니다”)인데 원인이 세 개였습니다. 처음엔 “아까 고쳤는데 왜 또 안 되지”라며 같은 걸 반복해서 시도했는데, 그게 시간을 제일 많이 잡아먹었습니다.
증상이 같다고 원인이 같은 게 아니라는 걸 배웠습니다. 안 되면 같은 방법을 반복하지 말고, 지금 상태를 먼저 확인해야 합니다. 아래 명령이 그 확인용입니다.
where gws주소가 나오면 컴퓨터가 프로그램을 찾은 것이고, 아무것도 안 나오면 주소록에 없는 겁니다. 이 한 줄로 “프로그램 문제인지 주소록 문제인지”가 갈립니다.
2. 성공 화면을 읽을 줄 알아야 한다
비개발자에게 진짜 어려운 건 에러가 아니라, 성공했는데 성공한 줄 모르는 상황이었습니다. 에러는 빨간 글씨로 명확한데, 성공은 낯선 형식으로 쭉 나오니까 그게 더 불안했습니다.
낯선 화면이 나오면 일단 error나 code 같은 단어부터 찾아보는 습관을 들이기로 했습니다.
3. 가이드를 꼼꼼히 읽자
폴더를 옮기지 말라는 경고가 가이드에 이미 있었습니다. 제가 안 읽고 넘어갔을 뿐입니다. 굵게 표시된 주의 문구는 대부분 누군가 이미 데였다는 뜻이더군요.
소감
다 설치하고 나서 최근 일주일 동안 제가 수정한 드라이브 파일 목록을 뽑아봤는데, 제가 어떤 일들을 하고 있었는지가 날짜별로 한눈에 정리돼서 나왔습니다. 평소에 구글 드라이브를 정말 많이 쓰는데 그게 AI와 연결된다는 게 감동이었습니다.
gws CLI는 구글 드라이브 쓰시는 분들에게 신세계네요.
설치 방법 설명해주신 무니님 감사합니다!
로그인하고 댓글을 남겨 주세요
사실 저도 PATH를 사용하고 있었는데 그게 어떤 뜻인지는 잘 모르고 사용하고 있었던 거 같아요. 덕분에 저도 뜻을 잘 알게 되어서 도움이 되었습니다. 오히려 더 잘 이해하면서 사용하고 계시는 거 같습니다 뭔가 저보다 더 공부를 잘하고 계신 거 같아요^^ 멋집니다.




where gws로 상태를 먼저 확인해서 '주소록 문제'인지 '프로그램 문제'인지를 갈라내는 진단 습관, 비개발자에게 정말 실용적인 접근이에요. "성공했는데 성공인 줄 몰랐다"는 부분도 좋았어요. dry-run 출력에서error나code단어만 찾으면 된다는 구분법은 앞으로도 두고두고 쓸 수 있을 것 같아요. 이사 후 주소록 비유도 깔끔해서 읽으면서 고개를 끄덕이게 됐어요. PATH 개념이 이렇게 쉽게 전달되는 글은 흔치 않아요. 고롱고롱 ✨