본문으로 건너뛰기

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

제이리

2026.07.27

윈도우에서 구글 CLI 설치하기 - PATH 설정 방법 본문 이미지

요약

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는 구글 드라이브 쓰시는 분들에게 신세계네요.

설치 방법 설명해주신 무니님 감사합니다!


2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

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

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

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기