챕터 14 · L2
Google Workspace CLI 기본 사용법
Drive·Docs·Sheets·Gmail 명령과 파이프·AI 연동 패턴
gws로 Drive·Docs·Sheets를 자주 쓰는 패턴으로 다루고, AI 도구와 파이프 연동을 할 수 있어요.
참고 문서
공개 문서
14. Google Workspace CLI 기본 사용법
아래는 content/courses/14-google-workspace-cli-basics.mdx 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# Google Workspace CLI 기본 사용법
> **이 챕터를 마치면** gws로 Drive·Docs·Sheets를 자주 쓰는 패턴으로 다루고, AI 도구와 파이프 연동을 할 수 있어요.
gws는 Google Discovery API 기반이라 **Drive, Docs, Sheets, Gmail, Calendar** 등 다양한 서비스를 같은 CLI로 사용할 수 있어요.
---
## Drive 자주 쓰는 명령
```bash
# 내 파일 목록 (최근순)
gws drive files list --order-by "modifiedTime desc"
# 특정 MIME 타입만 (예: 스프레드시트)
gws drive files list --mime-type "application/vnd.google-apps.spreadsheet"
# 파일 검색 (이름 포함)
gws drive files list --query "name contains '기획서'"
# 파일 다운로드 (바이너리)
gws drive files get <file-id> --output ./downloaded.pdf
```
---
## Docs 실전 패턴
### 기획서·문서를 코드 작업 맥락으로 넘기기
```bash
# Docs 내용 전체를 Claude Code에 전달
gws docs get <doc-id> | claude "이 기획서를 바탕으로 Next.js 앱의 라우트 구조를 제안해줘"
# 문서를 Gemini에 넘겨 요약·체크리스트 생성
gws docs get <doc-id> | gemini "이 문서에서 해야 할 일을 체크리스트로 정리해줘"
```
### 여러 문서를 한 번에
```bash
# 문서 ID 목록이 있으면 루프로 처리
for id in doc-id-1 doc-id-2; do
gws docs get $id >> combined.md
done
cat combined.md | gemini "이 문서들을 통합 요약해줘"
```
---
## Sheets 실전 패턴
### 스프레드시트 데이터를 개발 맥락에 활용
```bash
# 시트 전체 시리즈 데이터 가져오기
gws sheets get <sheet-id> --range "데이터!A:Z" | claude "이 CSV를 JSON 배열로 바꿔줘. 키는 첫 행이야."
# 특정 범위만
gws sheets get <sheet-id> --range "Sheet1!A1:E20" | gemini "이 표에서 결측치와 이상치를 찾아줘"
```
### 환경 변수·설정값 관리
팀에서 설정값을 Sheets로 관리할 때:
```bash
gws sheets get <config-sheet-id> --range "prod!A1:B50" > .env.generated
# 필요 시 .env와 병합 후 사용
```
---
## Gmail·Calendar (선택)
gws는 Gmail·Calendar API도 지원해요. 사용 전 해당 API가 Google Cloud 프로젝트에서 활성화되어 있어야 해요.
```bash
# 최근 메일 목록
gws gmail messages list --max-results 10
# 캘린더 이벤트 목록
gws calendar events list --calendar-id primary
```
---
## AI 에이전트 스킬과의 연동
Google Workspace CLI는 **AI 에이전트용 스킬**로도 사용돼요. 에이전트가 "Drive에서 파일 찾기", "Docs 내용 가져오기" 같은 작업을 스킬로 호출할 수 있어요. 공식 문서에서 스킬 등록 방법을 확인할 수 있어요.
---
## 핵심 슬래시·옵션 정리
| 영역 | 자주 쓰는 옵션 |
|------|----------------|
| Drive | `--folder-id`, `--mime-type`, `--query`, `--order-by` |
| Docs | `get <doc-id>` |
| Sheets | `get <sheet-id> --range "시트명!A1:D10"` |
| 공통 | `--help`로 서브커맨드·옵션 확인 |
---
## 다음 단계
gws로 문서·데이터를 가져오는 방법을 익혔다면 **네 도구(Cursor, Claude Code, Gemini CLI, gws)를 한 번에 조합하는 통합 워크플로우**를 배워봅시다.
---
## 9장 보강 프로세스 적용: 기본 사용 루틴 표준화
기본 명령을 많이 아는 것보다, 반복 가능한 루틴을 가지는 것이 중요합니다.
### 권장 루틴 (문서/시트 공통)
1. 대상 식별(ID/범위)
2. 조회 명령 실행
3. 결과 정제(필요 구간만 추출)
4. AI 도구로 전달
5. 요약/체크리스트 저장
### 14챕터 실패 패턴 TOP 5
1. **시트 범위 지정 오류**
- 대응: `"시트명!A1:D10"` 형식으로 명시
2. **문서 전체를 무조건 전달**
- 대응: 필요한 섹션만 추출 후 전달
3. **파이프 결과의 목적 불명확**
- 대응: "무엇을 만들지"를 프롬프트에 먼저 선언
4. **조회 성공 후 기록 미흡**
- 대응: 명령/결과 요약을 템플릿으로 남기기
5. **권한 부족 에러 반복**
- 대응: 계정/프로젝트/API 활성화를 먼저 점검
### 14챕터 체크리스트 (DoD)
- [ ] Drive/Docs/Sheets 각 1회 이상 명령 실행 완료
- [ ] Docs 또는 Sheets 결과를 AI 파이프에 전달 완료
- [ ] 범위 지정 템플릿(시트/문서) 확보 완료
- [ ] 명령-결과 요약 로그 1개 이상 작성 완료
- [ ] 다음 통합 챕터용 입력값 정리 완료
> **다음 챕터 입력값:** gws 출력 표준 포맷, claude/gemini 전달 프롬프트, 데이터 정제 규칙공개 문서 변환 코드 (HTML)
<h1>Google Workspace CLI 기본 사용법</h1>
<blockquote>
<p><strong>이 챕터를 마치면</strong> gws로 Drive·Docs·Sheets를 자주 쓰는 패턴으로 다루고, AI 도구와 파이프 연동을 할 수 있어요.</p>
</blockquote>
<p>gws는 Google Discovery API 기반이라 <strong>Drive, Docs, Sheets, Gmail, Calendar</strong> 등 다양한 서비스를 같은 CLI로 사용할 수 있어요.</p>
<hr>
<h2>Drive 자주 쓰는 명령</h2>
<pre><code class="language-bash"># 내 파일 목록 (최근순)
gws drive files list --order-by "modifiedTime desc"
# 특정 MIME 타입만 (예: 스프레드시트)
gws drive files list --mime-type "application/vnd.google-apps.spreadsheet"
# 파일 검색 (이름 포함)
gws drive files list --query "name contains '기획서'"
# 파일 다운로드 (바이너리)
gws drive files get <file-id> --output ./downloaded.pdf
</code></pre>
<hr>
<h2>Docs 실전 패턴</h2>
<h3>기획서·문서를 코드 작업 맥락으로 넘기기</h3>
<pre><code class="language-bash"># Docs 내용 전체를 Claude Code에 전달
gws docs get <doc-id> | claude "이 기획서를 바탕으로 Next.js 앱의 라우트 구조를 제안해줘"
# 문서를 Gemini에 넘겨 요약·체크리스트 생성
gws docs get <doc-id> | gemini "이 문서에서 해야 할 일을 체크리스트로 정리해줘"
</code></pre>
<h3>여러 문서를 한 번에</h3>
<pre><code class="language-bash"># 문서 ID 목록이 있으면 루프로 처리
for id in doc-id-1 doc-id-2; do
gws docs get $id >> combined.md
done
cat combined.md | gemini "이 문서들을 통합 요약해줘"
</code></pre>
<hr>
<h2>Sheets 실전 패턴</h2>
<h3>스프레드시트 데이터를 개발 맥락에 활용</h3>
<pre><code class="language-bash"># 시트 전체 시리즈 데이터 가져오기
gws sheets get <sheet-id> --range "데이터!A:Z" | claude "이 CSV를 JSON 배열로 바꿔줘. 키는 첫 행이야."
# 특정 범위만
gws sheets get <sheet-id> --range "Sheet1!A1:E20" | gemini "이 표에서 결측치와 이상치를 찾아줘"
</code></pre>
<h3>환경 변수·설정값 관리</h3>
<p>팀에서 설정값을 Sheets로 관리할 때:</p>
<pre><code class="language-bash">gws sheets get <config-sheet-id> --range "prod!A1:B50" > .env.generated
# 필요 시 .env와 병합 후 사용
</code></pre>
<hr>
<h2>Gmail·Calendar (선택)</h2>
<p>gws는 Gmail·Calendar API도 지원해요. 사용 전 해당 API가 Google Cloud 프로젝트에서 활성화되어 있어야 해요.</p>
<pre><code class="language-bash"># 최근 메일 목록
gws gmail messages list --max-results 10
# 캘린더 이벤트 목록
gws calendar events list --calendar-id primary
</code></pre>
<hr>
<h2>AI 에이전트 스킬과의 연동</h2>
<p>Google Workspace CLI는 <strong>AI 에이전트용 스킬</strong>로도 사용돼요. 에이전트가 "Drive에서 파일 찾기", "Docs 내용 가져오기" 같은 작업을 스킬로 호출할 수 있어요. 공식 문서에서 스킬 등록 방법을 확인할 수 있어요.</p>
<hr>
<h2>핵심 슬래시·옵션 정리</h2>
<table>
<thead>
<tr>
<th>영역</th>
<th>자주 쓰는 옵션</th>
</tr>
</thead>
<tbody><tr>
<td>Drive</td>
<td><code>--folder-id</code>, <code>--mime-type</code>, <code>--query</code>, <code>--order-by</code></td>
</tr>
<tr>
<td>Docs</td>
<td><code>get <doc-id></code></td>
</tr>
<tr>
<td>Sheets</td>
<td><code>get <sheet-id> --range "시트명!A1:D10"</code></td>
</tr>
<tr>
<td>공통</td>
<td><code>--help</code>로 서브커맨드·옵션 확인</td>
</tr>
</tbody></table>
<hr>
<h2>다음 단계</h2>
<p>gws로 문서·데이터를 가져오는 방법을 익혔다면 <strong>네 도구(Cursor, Claude Code, Gemini CLI, gws)를 한 번에 조합하는 통합 워크플로우</strong>를 배워봅시다.</p>
<hr>
<h2>9장 보강 프로세스 적용: 기본 사용 루틴 표준화</h2>
<p>기본 명령을 많이 아는 것보다, 반복 가능한 루틴을 가지는 것이 중요합니다.</p>
<h3>권장 루틴 (문서/시트 공통)</h3>
<ol>
<li>대상 식별(ID/범위)</li>
<li>조회 명령 실행</li>
<li>결과 정제(필요 구간만 추출)</li>
<li>AI 도구로 전달</li>
<li>요약/체크리스트 저장</li>
</ol>
<h3>14챕터 실패 패턴 TOP 5</h3>
<ol>
<li><p><strong>시트 범위 지정 오류</strong></p>
<ul>
<li>대응: <code>"시트명!A1:D10"</code> 형식으로 명시</li>
</ul>
</li>
<li><p><strong>문서 전체를 무조건 전달</strong></p>
<ul>
<li>대응: 필요한 섹션만 추출 후 전달</li>
</ul>
</li>
<li><p><strong>파이프 결과의 목적 불명확</strong></p>
<ul>
<li>대응: "무엇을 만들지"를 프롬프트에 먼저 선언</li>
</ul>
</li>
<li><p><strong>조회 성공 후 기록 미흡</strong></p>
<ul>
<li>대응: 명령/결과 요약을 템플릿으로 남기기</li>
</ul>
</li>
<li><p><strong>권한 부족 에러 반복</strong></p>
<ul>
<li>대응: 계정/프로젝트/API 활성화를 먼저 점검</li>
</ul>
</li>
</ol>
<h3>14챕터 체크리스트 (DoD)</h3>
<ul>
<li><input disabled="" type="checkbox"> Drive/Docs/Sheets 각 1회 이상 명령 실행 완료</li>
<li><input disabled="" type="checkbox"> Docs 또는 Sheets 결과를 AI 파이프에 전달 완료</li>
<li><input disabled="" type="checkbox"> 범위 지정 템플릿(시트/문서) 확보 완료</li>
<li><input disabled="" type="checkbox"> 명령-결과 요약 로그 1개 이상 작성 완료</li>
<li><input disabled="" type="checkbox"> 다음 통합 챕터용 입력값 정리 완료</li>
</ul>
<blockquote>
<p><strong>다음 챕터 입력값:</strong> gws 출력 표준 포맷, claude/gemini 전달 프롬프트, 데이터 정제 규칙</p>
</blockquote>