gsheets
Read, write, format, and manage Google Sheets. Use when the user shares a sheets.google.com or docs.google.com/spreadsheets URL, asks to read or summarize spreadsheet data, wants cells written, format
SKILL.mdskills/gsheets/SKILL.md
GitHubGoogle Sheets
Work with a Google Sheet the user names or links to. Everything here assumes you
already have the spreadsheet ID — the segment between /d/ and /edit in a
https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit URL.
[!CAUTION]
mutate delete-sheet,mutate delete-rows,mutate delete-cols, andmutate clearpermanently remove data. Never run a destructive command the user did not explicitly ask for.
mutate deletepermanently deletes an entire spreadsheet document. Never use it unless the user asks explicitly; ask for confirmation and wait for the answer before executing. The command also requires--confirm.Never share a spreadsheet with a broad audience, a public link, or a whole organization. The user already has access to anything created on their behalf — let them handle sharing unless they explicitly instruct otherwise.
Setup and Authentication
gsheets auth status is the only way to tell whether you are logged in. Do not
run --help, search the filesystem or environment for tokens, check another
plugin's login, or run an operational command before logging in. Follow these
steps exactly.
1. Register and check. Run this skill's script with auth status. It
downloads the CLI, registers gsheets on the agent's PATH (not the user's
shell), and reports whether you are logged in:
<path/to/this/skill>/scripts/gsheets auth status
# Windows (PowerShell)
& "<path\to\this\skill>\scripts\gsheets.cmd" auth status
Every later call is just gsheets. Never ask the user to run it; they cannot.
If it reports Logged in, you are ready.
2. Log in for the user. Start this as a background command:
gsheets auth login
It prints an authorization URL and exits on its own once the user approves. Read
the URL from the task's log, open it in the user's browser or hand them the
link, then stop and wait. Confirm with gsheets auth status.
Usage
Do every Google Sheets operation — reading, writing, formatting, creating,
exporting — through gsheets. Commands are split into two namespaces:
readonly for anything that only reads, mutate for anything that changes the
spreadsheet. Run gsheets --help, or gsheets <namespace> <command> --help, to
confirm the exact flags of any command below.
Two rules the CLI's own help will not tell you:
- Never run a destructive command the user did not ask for. Deleting a spreadsheet, a sheet, or rows, and clearing a range, all discard data with no undo on the user's side. Ask first and wait for an answer.
- Write the narrowest range that does the job. Rewriting a whole sheet to change a few cells destroys formatting, formulas, and validation rules that were never yours to touch.
Recipes
Read data (readonly):
gsheets readonly read SPREADSHEET_ID 'Sheet1!A1:D10'
gsheets readonly read-all SPREADSHEET_ID
gsheets readonly read-links SPREADSHEET_ID 'Sheet1!A1:D10' # embedded hyperlinks, rich-text links, and smart chips
gsheets readonly info SPREADSHEET_ID
gsheets readonly list-sheets SPREADSHEET_ID
gsheets readonly list-named-ranges SPREADSHEET_ID
gsheets readonly list-filter-views SPREADSHEET_ID
gsheets readonly list "Quarterly Results" # search spreadsheets in Drive
gsheets readonly list-revisions SPREADSHEET_ID # revision history
gsheets readonly inspect-cell SPREADSHEET_ID 'Sheet1!B4' # deep cell and error diagnostics
gsheets readonly get-settings SPREADSHEET_ID # locale and timezone properties
gsheets readonly list-comments SPREADSHEET_ID # comment threads and replies
Write data (mutate):
gsheets mutate write SPREADSHEET_ID 'Sheet1!A1:B2' "Name,Age|Alice,30"
gsheets mutate write SPREADSHEET_ID 'Sheet1!A1:B2' $'Name,Age\nAlice,30'
gsheets mutate write SPREADSHEET_ID 'Sheet1!A1' "Value with\, a comma"
gsheets mutate append SPREADSHEET_ID 'Sheet1!A1' "Bob,25"
gsheets mutate clear SPREADSHEET_ID 'Sheet1!A1:D10'
gsheets mutate import-csv SPREADSHEET_ID /path/to/data.csv
gsheets mutate find-replace SPREADSHEET_ID --find "old" --replace "new"
gsheets mutate notes SPREADSHEET_ID 'Sheet1!A1' "This is a note"
gsheets mutate add-comment SPREADSHEET_ID "This is a comment" --range 'Sheet1!A1:A1'
gsheets mutate reply-comment SPREADSHEET_ID COMMENT_ID "This is a reply"
gsheets mutate resolve-comment SPREADSHEET_ID COMMENT_ID "Optional resolve message"
Create, delete, copy, and rename (mutate):
gsheets mutate create --title "New Spreadsheet"
gsheets mutate delete SPREADSHEET_ID --confirm # permanently deletes the document
gsheets mutate rename SPREADSHEET_ID "New File Name"
gsheets mutate copy-spreadsheet SPREADSHEET_ID "Copy Title"
gsheets mutate add-sheet SPREADSHEET_ID --title "Sheet2"
gsheets mutate delete-sheet SPREADSHEET_ID --sheet-id 1
gsheets mutate rename-sheet SPREADSHEET_ID --sheet-id 0 --title "Main"
gsheets mutate copy-sheet SPREADSHEET_ID --sheet-id 0 --dest OTHER_SPREADSHEET_ID
gsheets mutate create-from-template TEMPLATE_ID --title "New" --replacements "{{NAME}}=Alice"
Formatting (mutate):
gsheets mutate format SPREADSHEET_ID --sheet-id 0 --start-row 0 --end-row 1 --start-col 0 --end-col 5 --bold --align CENTER --bg-color "#00FF00" --fg-color "#FF0000" --wrap
gsheets mutate set-col-width SPREADSHEET_ID --sheet-id 0 --start-col 0 --end-col 1 --pixels 200
gsheets mutate autosize SPREADSHEET_ID --sheet-id 0 --start-col 0 --end-col 5
gsheets mutate merge SPREADSHEET_ID --sheet-id 0 --start-row 0 --end-row 1 --start-col 0 --end-col 3
gsheets mutate unmerge SPREADSHEET_ID --sheet-id 0 --start-row 0 --end-row 1 --start-col 0 --end-col 3
gsheets mutate freeze SPREADSHEET_ID --sheet-id 0 --rows 1 --cols 1
gsheets mutate borders SPREADSHEET_ID --sheet-id 0 --style SOLID --color "#000000"
gsheets mutate conditional-format SPREADSHEET_ID --sheet-id 0 --start-row 0 --end-row 100 --start-col 0 --end-col 1 --condition NUMBER_GREATER --value "90" --color "#00FF00"
Rows, columns, and data operations (mutate):
gsheets mutate sort SPREADSHEET_ID --sheet-id 0 --col 0 # --asc is default, omit for descending
gsheets mutate insert-rows SPREADSHEET_ID --range 'Sheet1!5:10' # human-readable ranges work
gsheets mutate delete-rows SPREADSHEET_ID --range 'Sheet1!5:10'
gsheets mutate insert-cols SPREADSHEET_ID --range 'Sheet1!C:D'
gsheets mutate insert-cols SPREADSHEET_ID --sheet-id 0 --start 2 --count 3 --inherit-from-before # append at the end (start may equal grid size)
gsheets mutate delete-cols SPREADSHEET_ID --range 'Sheet1!C:D'
gsheets mutate copy-paste SPREADSHEET_ID --sheet-id 0 --start-row 0 --end-row 5 --start-col 0 --end-col 2 --dest-row 0 --dest-col 3 --paste-type PASTE_VALUES
gsheets mutate auto-fill SPREADSHEET_ID --sheet-id 0 --start-row 0 --end-row 10 --start-col 0 --end-col 1 --source-end-row 3
gsheets mutate smart-fill SPREADSHEET_ID 'Sheet1!B2' # fills down the adjacent contiguous depth
gsheets mutate formula-fill SPREADSHEET_ID --range 'Sheet1!C1:C10' --formula "=B1+A1" # shifts relative references
gsheets mutate data-validation SPREADSHEET_ID 'Sheet1!B1:B10' --values "Yes,No,Maybe"
gsheets mutate protect SPREADSHEET_ID --range 'Sheet1!A1:D1' --editors "alice@example.com,bob@example.com"
gsheets mutate change-settings SPREADSHEET_ID --locale "de_DE" --timezone "Europe/Berlin"
gsheets mutate add-named-range SPREADSHEET_ID "MyRange" 'Sheet1!A1:D10'
gsheets mutate add-filter-view SPREADSHEET_ID "MyFilter" --sheet-id 0
gsheets mutate delete-filter-view SPREADSHEET_ID 12345
Charts, pivots, tables, sharing, and export:
gsheets mutate add-chart SPREADSHEET_ID --sheet-id 0 --chart-type BAR --start-row 0 --end-row 10 --start-col 0 --end-col 2 --title "Sales"
gsheets mutate add-chart SPREADSHEET_ID --sheet-id 0 --chart-type COLUMN --start-row 0 --end-row 10 --start-col 0 --end-col 2 --title "Pillars" --overlay --colors "#4285F4,#EA4335"
gsheets readonly export-chart SPREADSHEET_ID --chart-id 1 --output /tmp/chart.png
gsheets mutate pivot SPREADSHEET_ID --source 'Sheet1!A1:D100' --target-sheet-id 0
gsheets readonly export SPREADSHEET_ID /tmp/export.csv --format csv
gsheets readonly export SPREADSHEET_ID /tmp/export_tab.csv --format csv --sheet "Sheet2" # specific tab (CSV/TSV only)
gsheets readonly export SPREADSHEET_ID /tmp/page1.png --format png --page 1
gsheets mutate share SPREADSHEET_ID --email user@example.com --role writer
gsheets mutate add-table SPREADSHEET_ID "MyTable" 'Sheet1!A1:D10'
gsheets mutate update-table SPREADSHEET_ID "MyTable" 'Sheet1!A1:D20'
gsheets mutate delete-table SPREADSHEET_ID "MyTable"
gsheets mutate batch SPREADSHEET_ID -f requests.json
gsheets mutate raw-batch SPREADSHEET_ID -f raw_requests.json
Batch operations file (requests.json):
Each op is one of read, write, append, or clear. For write and
append, the data field is required and must be a 2D array of rows
([[...]]). Unknown JSON fields are rejected — typos surface immediately rather
than silently producing no-op writes.
[
{"op": "read", "range": "Sheet1!A1:B2"},
{"op": "write", "range": "Sheet1!A1", "data": [["Critical", "High"]]},
{"op": "append", "range": "Sheet1!A1", "data": [["new row"]]},
{"op": "clear", "range": "Sheet1!A1:B2"}
]
[!IMPORTANT]
The field is
data, notvalues. Writing"values": "X"fails withparsing batch JSON: json: unknown field "values". This is deliberate: the field name that used to be silently accepted was a silent-data-loss footgun.
Commands
| Namespace | Command | Description |
|---|---|---|
readonly |
read |
Read range |
readonly |
read-all |
Read all sheets |
readonly |
read-links |
Extract hyperlinks, rich text, |
| : : : and smart chips : | ||
readonly |
info |
Spreadsheet info |
readonly |
list |
List or search spreadsheets in |
| : : : Drive : | ||
readonly |
list-revisions |
List spreadsheet revision |
| : : : history : | ||
readonly |
list-sheets |
List sheets |
readonly |
list-named-ranges |
List named ranges |
readonly |
list-filter-views |
List filter views |
readonly |
list-comments |
List comment threads |
readonly |
get-settings |
View locale and timezone |
| : : : properties : | ||
readonly |
inspect-cell |
Detailed cell diagnostics |
| : : : (values, formulas, errors) : | ||
readonly |
export |
Export spreadsheet (csv, xlsx, |
| : : : pdf, ods, tsv, png) : | ||
readonly |
export-chart |
Export chart as image |
mutate |
write |
Write to range |
mutate |
append |
Append rows |
mutate |
clear |
Clear range |
mutate |
create |
Create spreadsheet |
mutate |
delete |
Permanently delete spreadsheet |
: : : document (--confirm) : |
||
mutate |
rename |
Rename spreadsheet document |
| : : : file : | ||
mutate |
copy-spreadsheet |
Copy entire spreadsheet |
mutate |
add-sheet |
Add sheet |
mutate |
delete-sheet |
Delete sheet |
mutate |
rename-sheet |
Rename sheet |
mutate |
copy-sheet |
Copy sheet to another |
| : : : spreadsheet : | ||
mutate |
format |
Format range (hex background |
| : : : and text colors) : | ||
mutate |
set-col-width |
Set column width |
mutate |
autosize |
Auto-resize columns |
mutate |
merge |
Merge cells |
mutate |
unmerge |
Unmerge cells |
mutate |
sort |
Sort range |
mutate |
freeze |
Freeze rows/cols |
mutate |
borders |
Set cell borders (hex color) |
mutate |
conditional-format |
Add conditional formatting |
mutate |
insert-rows |
Insert rows (range or manual |
| : : : offsets) : | ||
mutate |
delete-rows |
Delete rows (range or manual |
| : : : offsets) : | ||
mutate |
insert-cols |
Insert columns (range or manual |
| : : : offsets) : | ||
mutate |
delete-cols |
Delete columns (range or manual |
| : : : offsets) : | ||
mutate |
copy-paste |
Copy-paste range (supports |
| : : : paste-type) : | ||
mutate |
auto-fill |
Auto-fill range (manual |
| : : : coordinates) : | ||
mutate |
smart-fill |
Auto-fill down, detecting |
| : : : contiguous depth : | ||
mutate |
formula-fill |
Fill formula across range |
| : : : (shifts relative refs) : | ||
mutate |
find-replace |
Find and replace |
mutate |
notes |
Get/set cell notes |
mutate |
add-named-range |
Add a named range |
mutate |
import-csv |
Import CSV file |
mutate |
data-validation |
Add data validation |
mutate |
protect |
Protect range (range and |
| : : : restricted editors) : | ||
mutate |
change-settings |
Update locale and timezone |
| : : : properties : | ||
mutate |
add-chart |
Add a chart |
mutate |
add-filter-view |
Add a filter view |
mutate |
delete-filter-view |
Delete filter view by ID |
mutate |
pivot |
Create pivot table |
mutate |
share |
Share spreadsheet |
mutate |
create-from-template |
Create from template |
mutate |
add-table |
Add a structured table |
mutate |
update-table |
Update structured table range |
mutate |
delete-table |
Delete a structured table |
mutate |
batch |
Execute simplified batch |
| : : : operations : | ||
mutate |
raw-batch |
Execute raw |
: : : BatchUpdateSpreadsheetRequest : |
||
mutate |
add-comment |
Add a comment |
mutate |
reply-comment |
Reply to a comment |
mutate |
resolve-comment |
Resolve a comment |
Tips
- Creating Spreadsheets with Specific Tabs: When creating a new
spreadsheet with a specific tab/sheet name, note that
mutate creategenerates a default initial tab ("Sheet 1",--sheet-id 0). You can either repurpose "Sheet 1" by renaming it (mutate rename-sheet SPREADSHEET_ID --sheet-id 0 --title "Desired Tab Name") or add the new sheet and delete "Sheet 1" (mutate delete-sheet SPREADSHEET_ID --sheet-id 0). - CRITICAL: Never attempt to scrape Google Sheets URLs (e.g.,
docs.google.com/spreadsheets/...) using web reading tools. Always use the GSheets CLI commands (readonly read,readonly read-all) to access spreadsheet contents, as the URLs require authentication and will return permission errors. - LIMITATION: Due to Google Sheets API and Drive API limitations, any
comment created programmatically using
mutate add-commentwith a cell range anchor will appear as "Original Content Deleted" (unanchored) in the Google Sheets grid Web UI. However, the comment remains fully visible in the Sheets "Comment History" sidebar, and it is queryable/writable via the CLI'slist-comments,reply-comment, andresolve-commentcommands. - The
mutate formatcommand uses--sheet-id,--start-row/--end-row,--start-col/--end-col(not A1 range notation) - The
mutate notescommand takes range and note text as positional arguments (not --set flag) - Avoid spaces in sheet names when used in range notation; if unavoidable,
wrap in single quotes:
"'My Sheet'!A1:B5" - Chart types:
BAR,LINE,AREAwork reliably;PIEis listed but not supported by the API - Use
--jsonon read commands to get machine-parseable output - Use
--markdown-linksonreadonly read-allto extract rich-text hyperlinks and Smart Chips (Rich Links and People Chips) embedded in cells. Without this flag, the API returns only the display text, and hidden link targets or smart chip URIs are lost. With the flag, both standard links and smart chips (including People Chips asmailto:links) are rendered as[display text](URL). Can be combined with--jsonto output an array of rows containing the markdown-formatted strings. readonly read-links RANGEis the dedicated command (vs the--markdown-linksflag above, which is scoped toread-all) to pull embedded hyperlinks, rich-text links, and Smart Chips (Rich Links and People Chips asmailto:links) from a specific range, rendered as[display text](URL). Add--jsonfor an array of rows, or--debug-cellto dump the rawCellDataJSON for troubleshooting.- Use
--value-render-option FORMULAon thereadonly readcommand to retrieve the underlying cell formulas instead of the evaluated values. readonly exportsupportscsv,xlsx,pdf,ods,tsv, andpngformats. When exporting tocsvortsv, you can use the--sheet "TabName"flag to export a specific sheet tab by name (by default, Drive CSV export only downloads the first tab).- Both
|and\n(newline) work as row delimiters inmutate writeandmutate appendcommands. Use|for inline values and$'\n'for multi-row shell input - To include a comma inside a cell value, escape it with a backslash:
\, batchrequiresdata(notvalues) forwrite/appendops; unknown fields are rejected by the strict JSON decoder. See "Batch operations file" above.conditional-format --condition NUMBER_BETWEEN(andNUMBER_NOT_BETWEEN,DATE_BETWEEN,DATE_NOT_BETWEEN) accept a comma-separated--valuepair, e.g.--value "1,10". Other conditions still take a single--value. For bands of multiple ranges (e.g. 1-2, 3-5, 6+), add one rule per band.- Recommended workflow: Use
readonly export SPREADSHEET_ID page.png --format png --page Nto export a specific page as an image, review it visually, then iterate on edits
Global Flags
--json— output as JSON (works with all read commands)-v,--version— print the CLI build version--legacy-mode— how deprecated/renamed commands are handled:allowed|deprecated(default) |banned