gmickel/sheets-cli

인간과 에이전트를 위한 조합 가능한 Google Sheets 프리미티브 (primitives)

설치 (Installation) • 빠른 시작 (Quick Start) • 명령어 (Commands) • 에이전트용 (For Agents)

📢 새로운 프로젝트: GNO를 확인해 보세요 — 여러분의 문서(Markdown, PDF, Word, Excel)를 위한 로컬 하이브리드 검색 도구입니다. BM25와 벡터 검색 (vector search)을 MCP 통합을 통해 AI 에이전트에 결합했습니다. sheets-cli의 훌륭한 동반자로서, 로컬 문서를 검색하고 클라우드 시트에 질의할 수 있습니다.

Google Sheets를 위한 빠르고 결정론적인 (deterministic) CLI입니다. 테이블 읽기, 행 추가, 키(key) 또는 인덱스(index)를 통한 셀 업데이트, 배치 작업 (batch operations) 등을 지원하며, 프로그램에서 소비할 수 있도록 모든 결과가 JSON 형식으로 출력됩니다.

# 구조화된 데이터로 시트 읽기
sheets-cli read table --sheet "Projects" --limit 10
# 키 컬럼을 사용하여 업데이트 (취약한 행 인덱스 미사용)
...

🆕 에이전트 기술 (Agent Skills) — Claude Code, OpenAI Codex 또는 VS Code (Insiders preview; chat.useAgentSkills 활성화 필요)를 위한 기술로 설치하세요. 에이전트는 스프레드시트를 언급할 때 sheets-cli를 자동으로 발견합니다. '에이전트용' 섹션을 참조하세요.

사전 요구 사항 (Prerequisites): Bun 런타임 (runtime)

git clone https://github.com/gmickel/sheets-cli.git
cd sheets-cli
bun install
...

PATH에 추가

# 심볼릭 링크 (Symlink)
ln -s "$(pwd)/dist/sheets-cli" /usr/local/bin/sheets-cli
# 또는 셸 설정에 추가
...

• Google Cloud Console → APIs로 이동

• Google Sheets API 활성화

• Google Drive API 활성화 (sheets find 명령에 필요)

• Google Cloud Console → Credentials로 이동

• OAuth 2.0 Client ID 생성 → 데스크톱 앱 (Desktop app) 선택 - JSON 파일 다운로드

데스크톱 앱은 localhost 리다이렉트를 자동으로 허용합니다. CLI는 http://localhost:3847을 통해 OAuth 코드를 캡처합니다.

sheets-cli auth login --credentials ./client_secret.json

브라우저가 열리면 → 승인 → 완료.

# 매번 --spreadsheet를 전달하는 것을 방지하기 위해 환경 변수 설정
export SHEETS_CLI_DEFAULT_SPREADSHEET_ID="your-spreadsheet-id"

시트 URL에서 ID를 가져오세요: docs.google.com/spreadsheets/d/<ID>/edit

시트 URL에서 ID를 가져오세요: docs.google.com/spreadsheets/d/<ID>/edit

sheets-cli sheets list --spreadsheet <id>
sheets-cli read table --spreadsheet <id> --sheet "Sheet1" --limit 5
sheets-cli append --spreadsheet <id> --sheet "Sheet1" --values '{"Name":"New Item","Status":"Active""}'

sheets-cli auth login --credentials <file> [--token-store <path>]
sheets-cli auth status
sheets-cli auth logout

sheets-cli sheets list [--spreadsheet <id>]
sheets-cli sheets find --name "<query>" [--limit 10] # 이름으로 검색
sheets-cli sheet info --sheet "<name>" [--spreadsheet <id>]
...

sheets-cli read table --sheet "<name>" [--limit 500] [--range "A1:Z500"] [--raw]
sheets-cli read range --range "<sheet>!A1:Z50"

sheets-cli append --sheet "<name>" --values '<json>' [--value-input USER_ENTERED|RAW] [--dry-run]
sheets-cli update row --sheet "<name>" --row 12 --set '<json>' [--dry-run]
sheets-cli update key --sheet "<name>" --key-col "Col" --key "Val" --set '<json>' [--dry-run] [--allow-multi]
...

모든 플래그 (All flags)

플래그	설명	기본값
--spreadsheet <id>	스프레드시트 ID 또는 전체 URL	환경 변수 또는 필수
--dry-run	적용하지 않고 미리보기	false
--value-input <mode>	USER_ENTERED 또는 RAW	USER_ENTERED
--header-row <n>	헤더 행 번호	자동 감지
--limit <n>	반환할 최대 행 수	무제한
--raw	서식이 적용되지 않은 값 반환	false
--allow-multi	일치하는 여러 행 업데이트 허용	false

{"Name": "Acme Corp", "Status": "Active", "Start Date": "2025-01-15"}

헤더가 없는 시트 (열 문자):

{"A": "Acme Corp", "C": "Active"}

`[[

코드	의미
0	성공 (Success)
10	유효성 검사 오류 (Validation error)
20	인증 오류 (Auth error)
30	권한 오류 (Permission error)
40	API/일시적 오류 (API/transient error)

# Claude Code
sheets-cli install-skill # 프로젝트: ./.claude/skills/sheets-cli/SKILL.md
sheets-cli install-skill --global # 개인: ~/.claude/skills/sheets-cli/SKILL.md
...

에이전트에게 sheets-cli 사용법을 가르치는 에이전트 스킬 (Agent Skill)을 설치합니다. 설치 후에는 스프레드시트 (spreadsheets), Google Sheets, 또는 시트 이름을 언급하면 에이전트가 자동으로 sheets-cli를 탐색합니다.

Codex: ~/.codex/config.toml 파일의 [features] 섹션에 skills = true 설정이 필요합니다.

VS Code: 에이전트 스킬 (Agent Skills) 지원은 프리뷰 (preview) 단계이며 VS Code Insiders에서만 사용할 수 있습니다. 에이전트 스킬을 사용하려면 chat.useAgentSkills를 활성화하세요.

스킬을 설치한 후에는 에이전트를 재시작하여 스킬을 로드해야 합니다.

읽기(read) → 결정(decide) → 드라이 런(dry-run) → 적용(apply) 순서를 따르세요:

# 1. 현재 상태 파악
sheets-cli read table --sheet "Tasks" --limit 100
# 2. 드라이 런 (Dry-run)
...

이름으로부터 스프레드시트 ID를 가져오려면 sheets find를 사용하세요.

• 행 인덱스 (row indices)보다 키 기반 업데이트 (key-based updates)를 선호하세요 — 삽입/삭제 시 행이 밀릴 수 있습니다.
• 쓰기 작업을 수행하기 전에는 항상 드라이 런 (dry-run)을 수행하세요.
• 진행하기 전에 ok로 확인하세요.
• 원자성 (atomicity)을 위해 관련 작업은 일괄 처리 (Batch related operations) 하세요.
• 열 이름 (Column names)은 대소문자를 구분하지 않으며, 정규화된 공백 (normalized whitespace)과 함께 일치해야 합니다.
• 헤더 행 (Header row)은 자동 감지됩니다 — 데이터가 있는 첫 번째 행을 찾기 위해 빈 행은 건너뜁니다.
• 헤더가 없는 시트: read table은 열을 A, B, ...로 반환합니다; --set / --key-col에는 열 문자를 사용하세요.
• 빈 시트: append는 JSON 키로부터 헤더 행을 작성하여 초기화 (bootstrap) 할 수 있습니다.
• --spreadsheet는 read table --range의 A1:Z 형식을 수락합니다 (시트 이름이 자동으로 접두사로 붙음) — Google Sheets 전체 URL을 직접 붙여넣어도 됩니다.
• URL을 수락합니다.

bun run dev # 핫 리로드 (Hot-reload)
bun run build # 바이너리 컴파일 (Compile binary)
bun run typecheck # 타입 체크 (Type check)
...

MIT

Bun으로 제작됨 • 기계와 인간 모두를 위해 스타일링됨