{"id":"d481ceed-8173-42f8-a64f-d3e4e5f4b79f","shortId":"QDFHJR","kind":"skill","title":"sheets-cli","tagline":"Read, write, and update Google Sheets data via CLI. Use when the user asks to read spreadsheet data, update cells, append rows, or work with Google Sheets. Triggers on mentions of spreadsheets, sheets, Google Sheets, tabular data in the cloud, or specific sheet names like \"Projec","description":"# sheets-cli\n\nCLI for Google Sheets primitives. Read tables, append rows, update cells by key or index, batch operations.\n\n> **Installation:** `sheets-cli` is already installed and available in the user's PATH. Run commands directly—no installation needed.\n\n## Quick Reference\n\n```bash\n# Find spreadsheet by name\nsheets-cli sheets find --name \"Projects\"\n\n# List sheets/tabs\nsheets-cli sheets list --spreadsheet <id-or-url>\n\n# Read table data\nsheets-cli read table --spreadsheet <id> --sheet \"Sheet1\" --limit 100\n\n# Update by key column (preferred - rows can shift)\nsheets-cli update key --spreadsheet <id> --sheet \"Projects\" \\\n  --key-col \"Name\" --key \"Acme\" --set '{\"Status\":\"Done\"}'\n\n# Append row\nsheets-cli append --spreadsheet <id> --sheet \"Projects\" \\\n  --values '{\"Name\":\"NewCo\",\"Status\":\"Active\"}'\n```\n\n## Workflow Pattern\n\nAlways follow **read → decide → dry-run → apply**:\n\n```bash\n# 1. Understand current state\nsheets-cli read table --sheet \"Tasks\" --limit 100\n\n# 2. Dry-run first\nsheets-cli update key --sheet \"Tasks\" --key-col \"ID\" --key \"TASK-42\" \\\n  --set '{\"Status\":\"Complete\"}' --dry-run\n\n# 3. Apply if dry-run looks correct\nsheets-cli update key --sheet \"Tasks\" --key-col \"ID\" --key \"TASK-42\" \\\n  --set '{\"Status\":\"Complete\"}'\n```\n\n## Commands\n\n### Auth (Setup)\n```bash\nsheets-cli auth login --credentials <oauth-client.json>\nsheets-cli auth status\nsheets-cli auth logout\n```\n\n### Find Spreadsheet by Name\n```bash\nsheets-cli sheets find --name \"<query>\" [--limit 10]\n```\nSearches Google Drive for spreadsheets matching the name. Returns ID, name, URL.\n\n> Requires Google Drive API enabled in the project.\n\n### List Sheets/Tabs\n```bash\nsheets-cli sheets list --spreadsheet <id>\n```\n\n### Sheet Info\n```bash\nsheets-cli sheet info --spreadsheet <id> --sheet \"<name>\"\nsheets-cli sheet info --spreadsheet <id> --gid <gid>\n```\nGet sheet metadata by name or GID.\n\n### Get Header Row\n```bash\nsheets-cli header --spreadsheet <id> --sheet \"<name>\" [--header-row N]\n```\nReturns column headers. Auto-detects header row if not specified.\n\n### Read Table Data\n```bash\nsheets-cli read table --spreadsheet <id> --sheet \"<name>\" [--limit N] [--raw]\n```\nReturns `{ headers: [\"_row\", ...], rows: [{_row: N, ...}, ...], headerRow: N }`.\n\nEach row includes `_row` - the absolute sheet row number for use with `update row`.\n\n### Read Raw Range\n```bash\nsheets-cli read range --spreadsheet <id> --range \"Sheet1!A1:B10\"\n```\n\n### Append Row\n```bash\nsheets-cli append --spreadsheet <id> --sheet \"<name>\" \\\n  --values '<json>' [--dry-run]\n```\nJSON object with column names as keys. Column matching is case-insensitive with normalized whitespace.\n\n### Update by Key (Preferred)\n```bash\nsheets-cli update key --spreadsheet <id> --sheet \"<name>\" \\\n  --key-col \"<column>\" --key \"<value>\" --set '<json>' \\\n  [--allow-multi] [--dry-run]\n```\nFinds rows where `key-col` equals `key`, updates columns from `--set`. Throws if multiple matches unless `--allow-multi`.\n\n### Update by Row Index\n```bash\nsheets-cli update row --spreadsheet <id> --sheet \"<name>\" \\\n  --row <n> --set '<json>' [--dry-run]\n```\nUpdates specific row by 1-indexed row number. Use `_row` from `read table` output directly.\n\n## Row Numbering\n\n- `read table` returns `headerRow` and rows with `_row` field\n- `_row` is the absolute sheet row number - use directly with `update row --row`\n- Example: `headerRow: 2` means headers on row 2, first data row is `_row: 3`\n- **Never calculate row numbers manually** - always use `_row` from read output\n\n### Set Range\n```bash\nsheets-cli set range --spreadsheet <id> --range \"Sheet1!A1:B2\" \\\n  --values '<2d-json-array>' [--dry-run]\n```\n\n### Batch Operations\n```bash\nsheets-cli batch --spreadsheet <id> --ops '<json-array>' [--dry-run]\n```\nOperations: `append`, `updateRow`, `updateKey`, `setRange`.\n\n## Global Options\n\n| Option | Description |\n|--------|-------------|\n| `--spreadsheet <id>` | Spreadsheet ID or full URL |\n| `--dry-run` | Preview without applying |\n| `--header-row <n>` | Header row (auto-detects if omitted) |\n| `--value-input <mode>` | `USER_ENTERED` (default) or `RAW` |\n\n## Output Format\n\nAll commands return JSON:\n\n```json\n{\n  \"ok\": true,\n  \"cmd\": \"update key\",\n  \"spreadsheetId\": \"...\",\n  \"sheet\": \"Projects\",\n  \"result\": { \"matchedRows\": 1, \"updatedCells\": 2 }\n}\n```\n\nErrors:\n```json\n{\n  \"ok\": false,\n  \"cmd\": \"update key\",\n  \"error\": { \"code\": \"VALIDATION_ERROR\", \"message\": \"...\" }\n}\n```\n\n## Best Practices\n\n1. **Use `sheets find`** to get spreadsheet ID from name\n2. **`--spreadsheet` accepts URLs** - paste full Google Sheets URL directly\n3. **Prefer key-based updates** over row indices - rows shift on insert/delete\n4. **Always dry-run** before writes\n5. **Check `ok` field** in response before proceeding\n6. **Batch related operations** for atomicity\n7. **Column names match case-insensitively** with normalized whitespace\n8. **Header row auto-detects** - skips empty rows to find first data row\n9. **Headerless sheets:** `read table` returns columns as `A`, `B`, ...; use column letters for `--set` / `--key-col`\n11. **Column letter vs header:** When a key like `ID` or `URL` matches both a header name and a column letter pattern, the header match wins. Column letter addressing (`A`, `B`, `AA`) is only used as fallback when no header matches\n10. **Empty sheets:** `append` can bootstrap by writing a header row from JSON keys\n11. **`read table --range`** accepts `A1:Z` (auto-prefixed with the sheet)\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 10 | Validation error |\n| 20 | Auth error |\n| 30 | Permission error |\n| 40 | API/transient error |","tags":["sheets","cli","gmickel","agent-skills","automation","bun","claude-code","google-sheets","openai-codex","spreadsheet","typescript"],"capabilities":["skill","source-gmickel","skill-sheets-cli","topic-agent-skills","topic-automation","topic-bun","topic-claude-code","topic-cli","topic-google-sheets","topic-openai-codex","topic-spreadsheet","topic-typescript"],"categories":["sheets-cli"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/gmickel/sheets-cli","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add gmickel/sheets-cli","source_repo":"https://github.com/gmickel/sheets-cli","install_from":"skills.sh"}},"qualityScore":"0.479","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 58 github stars · SKILL.md body (5,596 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T18:57:33.658Z","embedding":null,"createdAt":"2026-04-18T23:53:58.261Z","updatedAt":"2026-04-22T18:57:33.658Z","lastSeenAt":"2026-04-22T18:57:33.658Z","tsv":"'-42':206,234 '0':826 '1':175,492,641,658 '10':270,795,828 '100':124,187 '11':754,809 '2':188,529,534,643,668 '20':831 '2d':567 '2d-json-array':566 '3':213,540,678 '30':834 '4':691 '40':837 '5':698 '6':706 '7':712 '8':722 '9':736 'a1':397,563,814 'aa':785 'absolut':376,517 'accept':670,813 'acm':146 'activ':163 'address':782 'allow':446,469 'allow-multi':445,468 'alreadi':75 'alway':166,546,692 'api':286 'api/transient':838 'append':24,60,150,155,399,405,586,798 'appli':173,214,605 'array':569 'ask':17 'atom':711 'auth':239,245,251,256,832 'auto':342,612,726,817 'auto-detect':341,611,725 'auto-prefix':816 'avail':78 'b':745,784 'b10':398 'b2':564 'base':682 'bash':92,174,241,262,293,302,327,352,388,401,432,475,554,575 'batch':68,573,579,707 'best':656 'bootstrap':800 'calcul':542 'case':423,717 'case-insensit':422,716 'cell':23,63 'check':699 'cli':3,12,52,53,73,99,108,117,135,154,181,195,223,244,250,255,265,296,305,312,330,355,391,404,435,478,557,578 'cloud':43 'cmd':633,648 'code':652,823,824 'col':143,202,230,442,456,753 'column':128,339,415,419,460,713,742,747,755,773,780 'command':85,238,627 'complet':209,237 'correct':220 'credenti':247 'current':177 'data':10,21,40,114,351,536,734 'decid':169 'default':621 'descript':593 'detect':343,613,727 'direct':86,502,522,677 'done':149 'dri':171,190,211,217,410,449,486,571,583,601,694 'drive':273,285 'dry-run':170,189,210,216,409,448,485,570,582,600,693 'empti':729,796 'enabl':287 'enter':620 'equal':457 'error':644,651,654,830,833,836,839 'exampl':527 'exit':822 'fallback':790 'fals':647 'field':513,701 'find':93,101,258,267,451,661,732 'first':192,535,733 'follow':167 'format':625 'full':598,673 'get':317,324,663 'gid':316,323 'global':590 'googl':8,29,37,55,272,284,674 'header':325,331,335,340,344,364,531,607,609,723,758,769,777,793,804 'header-row':334,606 'headerless':737 'headerrow':369,508,528 'id':203,231,280,596,665,763 'includ':373 'index':67,474,493 'indic':686 'info':301,307,314 'input':618 'insensit':424,718 'insert/delete':690 'instal':70,76,88 'json':412,568,629,630,645,807 'key':65,127,137,142,145,197,201,204,225,229,232,418,430,437,441,443,455,458,635,650,681,752,761,808 'key-bas':680 'key-col':141,200,228,440,454,751 'letter':748,756,774,781 'like':48,762 'limit':123,186,269,360 'list':104,110,291,298 'login':246 'logout':257 'look':219 'manual':545 'match':276,420,466,715,766,778,794 'matchedrow':640 'mean':530,825 'mention':33 'messag':655 'metadata':319 'multi':447,470 'multipl':465 'n':337,361,368,370 'name':47,96,102,144,160,261,268,278,281,321,416,667,714,770 'need':89 'never':541 'newco':161 'normal':426,720 'number':379,495,504,520,544 'object':413 'ok':631,646,700 'omit':615 'op':581 'oper':69,574,585,709 'option':591,592 'output':501,551,624 'past':672 'path':83 'pattern':165,775 'permiss':835 'practic':657 'prefer':129,431,679 'prefix':818 'preview':603 'primit':57 'proceed':705 'projec':49 'project':103,140,158,290,638 'quick':90 'rang':387,393,395,553,559,561,812 'raw':362,386,623 'read':4,19,58,112,118,168,182,349,356,385,392,499,505,550,739,810 'refer':91 'relat':708 'requir':283 'respons':703 'result':639 'return':279,338,363,507,628,741 'row':25,61,130,151,326,336,345,365,366,367,372,374,378,384,400,452,473,480,483,490,494,497,503,510,512,514,519,525,526,533,537,539,543,548,608,610,685,687,724,730,735,805 'run':84,172,191,212,218,411,450,487,572,584,602,695 'search':271 'set':147,207,235,444,462,484,552,558,750 'setrang':589 'setup':240 'sheet':2,9,30,36,38,46,51,56,72,98,100,107,109,116,121,134,139,153,157,180,184,194,198,222,226,243,249,254,264,266,295,297,300,304,306,309,311,313,318,329,333,354,359,377,390,403,407,434,439,477,482,518,556,577,637,660,675,738,797,821 'sheet1':122,396,562 'sheets-c':1,50,71,97,106,115,133,152,179,193,221,242,248,253,263,294,303,310,328,353,389,402,433,476,555,576 'sheets/tabs':105,292 'shift':132,688 'skill' 'skill-sheets-cli' 'skip':728 'source-gmickel' 'specif':45,489 'specifi':348 'spreadsheet':20,35,94,111,120,138,156,259,275,299,308,315,332,358,394,406,438,481,560,580,594,595,664,669 'spreadsheetid':636 'state':178 'status':148,162,208,236,252 'success':827 'tabl':59,113,119,183,350,357,500,506,740,811 'tabular':39 'task':185,199,205,227,233 'throw':463 'topic-agent-skills' 'topic-automation' 'topic-bun' 'topic-claude-code' 'topic-cli' 'topic-google-sheets' 'topic-openai-codex' 'topic-spreadsheet' 'topic-typescript' 'trigger':31 'true':632 'understand':176 'unless':467 'updat':7,22,62,125,136,196,224,383,428,436,459,471,479,488,524,634,649,683 'updatedcel':642 'updatekey':588 'updaterow':587 'url':282,599,671,676,765 'use':13,381,496,521,547,659,746,788 'user':16,81,619 'valid':653,829 'valu':159,408,565,617 'value-input':616 'via':11 'vs':757 'whitespac':427,721 'win':779 'without':604 'work':27 'workflow':164 'write':5,697,802 'z':815","prices":[{"id":"911d9a7e-abb7-4d92-9003-d104f2588415","listingId":"d481ceed-8173-42f8-a64f-d3e4e5f4b79f","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"gmickel","category":"sheets-cli","install_from":"skills.sh"},"createdAt":"2026-04-18T23:53:58.261Z"}],"sources":[{"listingId":"d481ceed-8173-42f8-a64f-d3e4e5f4b79f","source":"github","sourceId":"gmickel/sheets-cli","sourceUrl":"https://github.com/gmickel/sheets-cli","isPrimary":false,"firstSeenAt":"2026-04-18T23:53:58.261Z","lastSeenAt":"2026-04-22T18:57:33.658Z"}],"details":{"listingId":"d481ceed-8173-42f8-a64f-d3e4e5f4b79f","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"gmickel","slug":"sheets-cli","github":{"repo":"gmickel/sheets-cli","stars":58,"topics":["agent-skills","automation","bun","claude-code","cli","google-sheets","openai-codex","spreadsheet","typescript"],"license":null,"html_url":"https://github.com/gmickel/sheets-cli","pushed_at":"2026-02-11T11:07:49Z","description":"Composable Google Sheets CLI for humans and agents. Read, write, update cells by key—with Agent Skills for Claude Code and OpenAI Codex.","skill_md_sha":"d0a023af6479ae3efba9e8c199321004eeb99cef","skill_md_path":"SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/gmickel/sheets-cli"},"layout":"root","source":"github","category":"sheets-cli","frontmatter":{"name":"sheets-cli","description":"Read, write, and update Google Sheets data via CLI. Use when the user asks to read spreadsheet data, update cells, append rows, or work with Google Sheets. Triggers on mentions of spreadsheets, sheets, Google Sheets, tabular data in the cloud, or specific sheet names like \"Projects\" or \"Tasks\"."},"skills_sh_url":"https://skills.sh/gmickel/sheets-cli"},"updatedAt":"2026-04-22T18:57:33.658Z"}}