Can I use Google Sheets as a CLI?

Yes. KosmoKrator exposes a Google Sheets CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Google Sheets through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Google Sheets tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Google Sheets credentials stored?

Google Sheets credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Google Sheets MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Google Sheets CLI for AI Agents

Use the Google Sheets CLI from KosmoKrator to call Google Sheets tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

20 functions 13 read 7 write OAuth browser flow auth

Submit Google Sheets feedback View package source

Google Sheets CLI Setup

Google Sheets can be configured headlessly with `kosmokrator integrations:configure google_sheets`.

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure google_sheets --set access_token="$GOOGLE_SHEETS_ACCESS_TOKEN" --enable --read allow --write ask --json
kosmokrator integrations:doctor google_sheets --json
kosmokrator integrations:status --json

Credentials

Authentication type: OAuth browser flow oauth2_authorization_code. Configure credentials once, then use the same stored profile from scripts, coding CLIs, Lua code mode, and the MCP gateway.

Key	Env var	Type	Required	Label
`access_token`	`GOOGLE_SHEETS_ACCESS_TOKEN`	OAuth token `oauth`	yes	Google Account

Call Google Sheets Headlessly

Use the generic call form when another coding CLI or script needs a stable universal interface.

kosmo integrations:call google_sheets.google_sheets_add_filter '{
  "spreadsheet_id": "example_spreadsheet_id",
  "range": "example_range"
}' --json

Use the provider shortcut form for shorter human-facing commands.

kosmo integrations:google_sheets google_sheets_add_filter '{
  "spreadsheet_id": "example_spreadsheet_id",
  "range": "example_range"
}' --json

Agent Discovery Commands

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

kosmo integrations:docs google_sheets --json
kosmo integrations:docs google_sheets.google_sheets_add_filter --json
kosmo integrations:schema google_sheets.google_sheets_add_filter --json
kosmo integrations:search "Google Sheets" --json
kosmo integrations:list --json

All CLI Functions

Every function below can be called headlessly. The generic form is stable across all integrations; the provider shortcut is shorter but specific to Google Sheets.

`google_sheets.google_sheets_add_filter`

Write write

Apply filter dropdowns to a range in a Google Sheets sheet/tab.

Parameters: spreadsheet_id, range

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_add_filter '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_add_filter '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range"}' --json

`google_sheets.google_sheets_add_sheet`

Write write

Add a new sheet/tab to a Google Spreadsheet.

Parameters: spreadsheet_id, title

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_add_sheet '{"spreadsheet_id":"example_spreadsheet_id","title":"example_title"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_add_sheet '{"spreadsheet_id":"example_spreadsheet_id","title":"example_title"}' --json

`google_sheets.google_sheets_append`

Read read

Append rows after the last data row in a Google Spreadsheet. Auto-detects the table boundary. Provide the range (e.g., "Sheet1" or "Sheet1!A:D") and a 2D array of rows to append.

Parameters: spreadsheet_id, range, values, input

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_append '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range","values":"example_values","input":"example_input"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_append '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range","values":"example_values","input":"example_input"}' --json

`google_sheets.google_sheets_batch_read`

Read read

Read multiple ranges from a Google Spreadsheet in one call. Provide an array of A1 notation ranges (e.g., ["Sheet1!A1:B5", "Sheet2!C1:D10"]). Returns results keyed by range.

Parameters: spreadsheet_id, ranges, render

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_batch_read '{"spreadsheet_id":"example_spreadsheet_id","ranges":"example_ranges","render":"example_render"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_batch_read '{"spreadsheet_id":"example_spreadsheet_id","ranges":"example_ranges","render":"example_render"}' --json

`google_sheets.google_sheets_batch_write`

Read read

Write to multiple ranges in a Google Spreadsheet in one call. Provide an array of {range, values} objects to update several areas at once.

Parameters: spreadsheet_id, data, input

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_batch_write '{"spreadsheet_id":"example_spreadsheet_id","data":"example_data","input":"example_input"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_batch_write '{"spreadsheet_id":"example_spreadsheet_id","data":"example_data","input":"example_input"}' --json

`google_sheets.google_sheets_clear`

Read read

Clear all values from a Google Sheets range (keeps formatting intact). Specify the range in A1 notation.

Parameters: spreadsheet_id, range

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_clear '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_clear '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range"}' --json

`google_sheets.google_sheets_create`

Read read

Create a new empty Google Spreadsheet with a given title. Returns the new spreadsheet ID and URL.

Parameters: title

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_create '{"title":"example_title"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_create '{"title":"example_title"}' --json

`google_sheets.google_sheets_delete_columns`

Write write

Delete columns from a Google Sheets sheet/tab. Uses 0-based indexing.

Parameters: spreadsheet_id, sheet, start_index, count

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_delete_columns '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","start_index":1,"count":1}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_delete_columns '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","start_index":1,"count":1}' --json

`google_sheets.google_sheets_delete_rows`

Write write

Delete rows from a Google Sheets sheet/tab. Uses 0-based indexing.

Parameters: spreadsheet_id, sheet, start_index, count

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_delete_rows '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","start_index":1,"count":1}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_delete_rows '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","start_index":1,"count":1}' --json

`google_sheets.google_sheets_delete_sheet`

Write write

Delete a sheet/tab from a Google Spreadsheet.

Parameters: spreadsheet_id, sheet

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_delete_sheet '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_delete_sheet '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet"}' --json

`google_sheets.google_sheets_duplicate_sheet`

Write write

Copy a sheet/tab within the same Google Spreadsheet.

Parameters: spreadsheet_id, sheet, title

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_duplicate_sheet '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","title":"example_title"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_duplicate_sheet '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","title":"example_title"}' --json

`google_sheets.google_sheets_find`

Read read

Search for text within a Google Spreadsheet. Searches all sheets by default, or specify a sheet name to narrow the search. Returns match count and number of sheets containing matches.

Parameters: spreadsheet_id, query, sheet, match_case, match_entire_cell

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_find '{"spreadsheet_id":"example_spreadsheet_id","query":"example_query","sheet":"example_sheet","match_case":true,"match_entire_cell":true}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_find '{"spreadsheet_id":"example_spreadsheet_id","query":"example_query","sheet":"example_sheet","match_case":true,"match_entire_cell":true}' --json

`google_sheets.google_sheets_get_metadata`

Read read

Get spreadsheet title and list of sheets/tabs with their names, IDs, and dimensions. Use this first to discover sheet names and structure before reading or writing data.

Parameters: spreadsheet_id

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_get_metadata '{"spreadsheet_id":"example_spreadsheet_id"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_get_metadata '{"spreadsheet_id":"example_spreadsheet_id"}' --json

`google_sheets.google_sheets_insert_columns`

Read read

Insert blank columns into a Google Sheets sheet/tab. Uses 0-based indexing.

Parameters: spreadsheet_id, sheet, start_index, count

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_insert_columns '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","start_index":1,"count":1}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_insert_columns '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","start_index":1,"count":1}' --json

`google_sheets.google_sheets_insert_rows`

Read read

Insert blank rows into a Google Sheets sheet/tab. Uses 0-based indexing.

Parameters: spreadsheet_id, sheet, start_index, count

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_insert_rows '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","start_index":1,"count":1}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_insert_rows '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","start_index":1,"count":1}' --json

`google_sheets.google_sheets_read_range`

Read read

Read cell values from a Google Sheets range using A1 notation. A1 notation examples: `Sheet1!A1:D10` (range), `Sheet1!A:A` (whole column), `Sheet1` (entire sheet). Sheet names with spaces need quotes: `'My Sheet'!A1:B2`.

Parameters: spreadsheet_id, range, render

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_read_range '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range","render":"example_render"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_read_range '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range","render":"example_render"}' --json

`google_sheets.google_sheets_remove_filter`

Write write

Remove the filter from a Google Sheets sheet/tab.

Parameters: spreadsheet_id, sheet

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_remove_filter '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_remove_filter '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet"}' --json

`google_sheets.google_sheets_rename_sheet`

Read read

Rename a sheet/tab in a Google Spreadsheet.

Parameters: spreadsheet_id, sheet, title

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_rename_sheet '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","title":"example_title"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_rename_sheet '{"spreadsheet_id":"example_spreadsheet_id","sheet":"example_sheet","title":"example_title"}' --json

`google_sheets.google_sheets_sort_range`

Read read

Sort data by column(s) in a Google Sheets range.

Parameters: spreadsheet_id, range, sort_column, ascending

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_sort_range '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range","sort_column":1,"ascending":true}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_sort_range '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range","sort_column":1,"ascending":true}' --json

`google_sheets.google_sheets_write_range`

Read read

Write values to a Google Sheets range. Values format: `[["Name", "Age"], ["Alice", 30]]` — each inner array is one row. Formulas work with user_entered input mode (default): `[["=SUM(A1:A10)"]]`.

Parameters: spreadsheet_id, range, values, input

Generic CLI call

kosmo integrations:call google_sheets.google_sheets_write_range '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range","values":"example_values","input":"example_input"}' --json

Provider shortcut

kosmo integrations:google_sheets google_sheets_write_range '{"spreadsheet_id":"example_spreadsheet_id","range":"example_range","values":"example_values","input":"example_input"}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

`google_sheets.google_sheets_add_filter`

Apply filter dropdowns to a range in a Google Sheets sheet/tab.

Operation: Write write
Schema command: kosmo integrations:schema google_sheets.google_sheets_add_filter --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`range`	string	yes	A1 notation range including header row (e.g., "Sheet1!A1:D10").

`google_sheets.google_sheets_add_sheet`

Add a new sheet/tab to a Google Spreadsheet.

Operation: Write write
Schema command: kosmo integrations:schema google_sheets.google_sheets_add_sheet --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`title`	string	yes	Name for the new sheet/tab.

`google_sheets.google_sheets_append`

Append rows after the last data row in a Google Spreadsheet. Auto-detects the table boundary. Provide the range (e.g., "Sheet1" or "Sheet1!A:D") and a 2D array of rows to append.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_append --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`range`	string	yes	A1 notation range (e.g., "Sheet1" or "Sheet1!A:D").
`values`	array	yes	2D array of rows to append (e.g., [["Alice", 30], ["Bob", 25]]).
`input`	string	no	Input mode: "user_entered" (default, parses formulas/dates) or "raw" (literal strings).

`google_sheets.google_sheets_batch_read`

Read multiple ranges from a Google Spreadsheet in one call. Provide an array of A1 notation ranges (e.g., ["Sheet1!A1:B5", "Sheet2!C1:D10"]). Returns results keyed by range.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_batch_read --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`ranges`	array	yes	Array of A1 notation ranges (e.g., ["Sheet1!A1:B5", "Sheet2!C1:D10"]).
`render`	string	no	Value rendering: "formatted" (default, as displayed), "unformatted" (raw numbers), or "formula" (shows formulas).

`google_sheets.google_sheets_batch_write`

Write to multiple ranges in a Google Spreadsheet in one call. Provide an array of {range, values} objects to update several areas at once.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_batch_write --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`data`	array	yes	Array of {range, values} objects (e.g., [{"range": "Sheet1!A1:B2", "values": [["a", "b"]]}]).
`input`	string	no	Input mode: "user_entered" (default, parses formulas/dates) or "raw" (literal strings).

`google_sheets.google_sheets_clear`

Clear all values from a Google Sheets range (keeps formatting intact). Specify the range in A1 notation.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_clear --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`range`	string	yes	A1 notation range to clear (e.g., "Sheet1!A1:D10").

`google_sheets.google_sheets_create`

Create a new empty Google Spreadsheet with a given title. Returns the new spreadsheet ID and URL.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_create --json

Parameter	Type	Required	Description
`title`	string	yes	Title for the new spreadsheet.

`google_sheets.google_sheets_delete_columns`

Delete columns from a Google Sheets sheet/tab. Uses 0-based indexing.

Operation: Write write
Schema command: kosmo integrations:schema google_sheets.google_sheets_delete_columns --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`sheet`	string	yes	Sheet/tab name.
`start_index`	integer	yes	0-based column index to start deleting from.
`count`	integer	no	Number of columns to delete (default 1).

`google_sheets.google_sheets_delete_rows`

Delete rows from a Google Sheets sheet/tab. Uses 0-based indexing.

Operation: Write write
Schema command: kosmo integrations:schema google_sheets.google_sheets_delete_rows --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`sheet`	string	yes	Sheet/tab name.
`start_index`	integer	yes	0-based row index to start deleting from.
`count`	integer	no	Number of rows to delete (default 1).

`google_sheets.google_sheets_delete_sheet`

Delete a sheet/tab from a Google Spreadsheet.

Operation: Write write
Schema command: kosmo integrations:schema google_sheets.google_sheets_delete_sheet --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`sheet`	string	yes	Sheet/tab name to delete.

`google_sheets.google_sheets_duplicate_sheet`

Copy a sheet/tab within the same Google Spreadsheet.

Operation: Write write
Schema command: kosmo integrations:schema google_sheets.google_sheets_duplicate_sheet --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`sheet`	string	yes	Source sheet/tab name to duplicate.
`title`	string	no	Name for the copy (defaults to "Copy of {name}").

`google_sheets.google_sheets_find`

Search for text within a Google Spreadsheet. Searches all sheets by default, or specify a sheet name to narrow the search. Returns match count and number of sheets containing matches.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_find --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`query`	string	yes	Text to search for.
`sheet`	string	no	Sheet name to search in. Omit to search all sheets.
`match_case`	boolean	no	Case-sensitive search. Default false.
`match_entire_cell`	boolean	no	Match entire cell content only. Default false.

`google_sheets.google_sheets_get_metadata`

Get spreadsheet title and list of sheets/tabs with their names, IDs, and dimensions. Use this first to discover sheet names and structure before reading or writing data.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_get_metadata --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).

`google_sheets.google_sheets_insert_columns`

Insert blank columns into a Google Sheets sheet/tab. Uses 0-based indexing.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_insert_columns --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`sheet`	string	yes	Sheet/tab name.
`start_index`	integer	yes	0-based column index to insert at.
`count`	integer	no	Number of columns to insert (default 1).

`google_sheets.google_sheets_insert_rows`

Insert blank rows into a Google Sheets sheet/tab. Uses 0-based indexing.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_insert_rows --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`sheet`	string	yes	Sheet/tab name.
`start_index`	integer	yes	0-based row index to insert at.
`count`	integer	no	Number of rows to insert (default 1).

`google_sheets.google_sheets_read_range`

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_read_range --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`range`	string	yes	A1 notation range (e.g., "Sheet1!A1:D10", "Sheet1!A:A", "Sheet1").
`render`	string	no	Value rendering: "formatted" (default, as displayed), "unformatted" (raw numbers), or "formula" (shows formulas).

`google_sheets.google_sheets_remove_filter`

Remove the filter from a Google Sheets sheet/tab.

Operation: Write write
Schema command: kosmo integrations:schema google_sheets.google_sheets_remove_filter --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`sheet`	string	yes	Sheet/tab name to remove the filter from.

`google_sheets.google_sheets_rename_sheet`

Rename a sheet/tab in a Google Spreadsheet.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_rename_sheet --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`sheet`	string	yes	Current sheet/tab name.
`title`	string	yes	New name for the sheet/tab.

`google_sheets.google_sheets_sort_range`

Sort data by column(s) in a Google Sheets range.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_sort_range --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`range`	string	yes	A1 notation range to sort (e.g., "Sheet1!A1:D10").
`sort_column`	integer	yes	0-based column index within the range to sort by.
`ascending`	boolean	no	Sort ascending (true, default) or descending (false).

`google_sheets.google_sheets_write_range`

Write values to a Google Sheets range. Values format: `[["Name", "Age"], ["Alice", 30]]` — each inner array is one row. Formulas work with user_entered input mode (default): `[["=SUM(A1:A10)"]]`.

Operation: Read read
Schema command: kosmo integrations:schema google_sheets.google_sheets_write_range --json

Parameter	Type	Required	Description
`spreadsheet_id`	string	yes	Spreadsheet ID (from the URL).
`range`	string	yes	A1 notation range (e.g., "Sheet1!A1:D10").
`values`	array	yes	2D array of values. Each inner array is a row (e.g., [["Name", "Age"], ["Alice", 30]]).
`input`	string	no	Input mode: "user_entered" (default, parses formulas/dates) or "raw" (literal strings).

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.