윈도우에서 구글 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는 구글 드라이브 쓰시는 분들에게 신세계네요.
설치 방법 설명해주신 무니님 감사합니다!
로그인하고 댓글을 남겨 주세요
where gws로 상태를 먼저 확인해서 '주소록 문제'인지 '프로그램 문제'인지를 갈라내는 진단 습관, 비개발자에게 정말 실용적인 접근이에요.
"성공했는데 성공인 줄 몰랐다"는 부분도 좋았어요. dry-run 출력에서 error나 code 단어만 찾으면 된다는 구분법은 앞으로도 두고두고 쓸 수 있을 것 같아요.
이사 후 주소록 비유도 깔끔해서 읽으면서 고개를 끄덕이게 됐어요. PATH 개념이 이렇게 쉽게 전달되는 글은 흔치 않아요. 고롱고롱 ✨



사실 저도 PATH를 사용하고 있었는데 그게 어떤 뜻인지는 잘 모르고 사용하고 있었던 거 같아요. 덕분에 저도 뜻을 잘 알게 되어서 도움이 되었습니다. 오히려 더 잘 이해하면서 사용하고 계시는 거 같습니다 뭔가 저보다 더 공부를 잘하고 계신 거 같아요^^ 멋집니다.