GWS CLI 구글드라이브
드라이브 작업은 거의 다 네 가지입니다. 찾기, 내려받기, 올리기, 공유하기. 기본 명령과 함정만 알면 사람이 브라우저를 열 일이 없어집니다.
기본기와 인증은 GWS CLI에 있습니다. 여기는 드라이브 레시피만 모았습니다.
1. 찾기
폴더 ID는 공유 링크 주소의 /folders/<ID> 부분, 파일 ID는 /d/<ID> 부분입니다.
폴더 안 목록
gws drive files list --params '{
"q":"'<폴더ID>' in parents and trashed=false",
"fields":"files(id,name,mimeType,size,modifiedTime)",
"pageSize":100
}' --format tableq는 --q 같은 개별 옵션이 아니라 --params JSON 안에 들어갑니다. 서비스 이름도 빠뜨리지 마십시오 — gws files list는 Unknown service 'files'로 떨어집니다.
이름으로 찾기
이름을 정확히 모를 때는 부분 매칭으로 후보를 뽑고 부모를 거슬러 올라가 위치를 특정합니다.
# 1) 후보
gws drive files list --params '{"q":"name contains \"보고서\" and trashed=false","fields":"files(id,name,parents,mimeType)"}'
# 2) 그 부모가 어디인지
gws drive files get --params '{"fileId":"<부모ID>","fields":"id,name,parents"}'사람이 말하는 폴더 이름과 실제 이름이 다를 수 있습니다. “AS 폴더”라고 들었는데 드라이브에는 Alternative Society로 들어 있는 식입니다. 못 찾았다고 “자료가 없다”고 선언하기 전에 부분 매칭을 돌려보십시오.
결과가 많을 때
gws drive files list --params '{"q":"...","pageSize":100}' --page-all --page-limit 20페이지마다 JSON 한 줄(NDJSON)로 나옵니다.
2. 내려받기
업로드된 파일 (PDF·docx·xlsx·이미지 등)
cd <파일을 둘 디렉토리>
gws drive files get --params '{"fileId":"<ID>","alt":"media"}' --output <파일명>🔴 --output은 현재 디렉토리 밖 경로를 거부합니다. 파일을 둘 디렉토리로 cd 한 뒤 파일명만 넘기십시오.
🔴 files download 서브커맨드는 쓰지 마십시오. 500으로 죽습니다. get + alt:media가 표준입니다.
내용이 JSON·텍스트인 파일
gws drive files get --params '{"fileId":"<ID>","alt":"media"}' 2>/dev/null > out.json--output으로 받으면 0바이트로 떨어지고 종료 코드는 0입니다. CLI가 JSON 본문을 자기 응답으로 파싱해버리기 때문입니다. 섞인 폴더를 받을 때는 바이너리와 JSON을 갈라 두 번 돌리십시오. 자세한 경위는 GWS CLI 함정 ②.
구글 네이티브 문서 (Docs·Sheets·Slides)
네이티브 문서는 원본 바이트가 없으니 alt=media가 아니라 export로 변환해 받습니다.
gws drive files export --params '{"fileId":"<ID>","mimeType":"text/plain"}' --output doc.txt
gws drive files export --params '{"fileId":"<ID>","mimeType":"application/pdf"}' --output doc.pdf자주 쓰는 변환 대상: text/plain text/markdown application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document(docx) text/csv(시트 단일 탭) application/vnd.openxmlformats-officedocument.spreadsheetml.sheet(xlsx).
제약이 하나 있습니다. export 결과는 10MB까지입니다(API 문서 명시). 큰 문서는 부분으로 끊어 받거나 다른 경로를 찾아야 합니다.
받은 뒤 검증
종료 코드 0은 받았다는 증거가 아닙니다. 메타데이터의 size와 로컬 크기를 맞춰보십시오.
gws drive files get --params '{"fileId":"<ID>","fields":"name,size,md5Checksum"}'3. 올리기
가장 쉬운 길 — +upload 헬퍼
gws drive +upload ./보고서.pdf --parent <폴더ID> --name '2026 보고서.pdf'MIME 타입을 자동으로 잡습니다. 그리고 이 헬퍼는 절대경로를 받습니다 — files create --upload가 거부하는 현재 디렉토리 밖 경로도 통과합니다(2026-10-09 실측).
원시 API — 변환이 필요할 때
cd <파일이 있는 디렉토리>
gws drive files create \
--upload 파일.pdf \
--json '{"name":"문서명","parents":["<폴더ID>"]}' \
--params '{"fields":"id,name,webViewLink"}'🔴 --upload는 현재 디렉토리 밖을 거부합니다. 파일이 있는 디렉토리에서 파일명만 넘기십시오.
마크다운을 구글독스로 자동 변환해 올리기
본문 mimeType을 구글 문서로 지정하고 올리는 파일의 MIME을 따로 알려주면 드라이브가 변환해줍니다.
gws drive files create \
--json '{"name":"문서명","parents":["<폴더ID>"],"mimeType":"application/vnd.google-apps.document"}' \
--upload 초안.md \
--upload-content-type text/markdowntext/html·text/plain도 같은 방식으로 변환됩니다. 로컬에서 마크다운으로 쓰고 구글독스로 올려 사람들이 웹에서 고치게 하는 흐름이 여기서 나옵니다.
덮어쓰기 — 링크를 살린 채 내용만 교체
gws drive files update --params '{"fileId":"<ID>"}' --upload 수정본.md --upload-content-type text/markdown문서 ID가 그대로라 이미 뿌린 링크와 권한을 다시 만들 필요가 없습니다. 문서를 고쳐 다시 배포할 때는 새로 만들지 말고 이걸 쓰십시오.
4. 공유
# 링크를 아는 누구나 보기
gws drive permissions create --params '{"fileId":"<ID>"}' --json '{"role":"reader","type":"anyone"}'
# 특정 사람에게 보기 권한
gws drive permissions create --params '{"fileId":"<ID>"}' \
--json '{"role":"reader","type":"user","emailAddress":"[email protected]"}'
# 현재 권한 확인
gws drive permissions list --params '{"fileId":"<ID>","fields":"permissions(id,type,role,emailAddress)"}'role은 reader commenter writer owner. 공유는 외부로 나가는 행동입니다 — 명단을 사람이 한 번 확인한 뒤 실행하십시오.
5. 그 밖에
# 저장용량
gws drive about get --params '{"fields":"storageQuota,user(emailAddress)"}'
# 휴지통 비우기 (휴지통도 용량에 포함됩니다)
gws drive files emptyTrash
# 폴더 만들기
gws drive files create --json '{"name":"새폴더","mimeType":"application/vnd.google-apps.folder","parents":["<부모ID>"]}'
# 버전 이력
gws drive revisions list --params '{"fileId":"<ID>"}'용량을 비울 때 흔한 오해 하나. 휴지통에 넣은 것도 한도에 들어갑니다. 지웠는데 용량이 안 줄면 휴지통을 보십시오. 그리고 구글 계정 용량은 드라이브·지메일·포토가 함께 쓰니 드라이브만 비워선 안심할 수 없습니다.
6. 함께 읽기
- GWS CLI — 명령 구조·인증·함정 전체
- 구글 업무를 AI와 함께 하는 법 — 역할 분담과 검증
- GWS CLI 지메일 · GWS CLI 캘린더