Read and write files in the user’s Google Drive or OneDrive, and build reports as Sheets and Docs.
Google Drive: full CRUD over the files Hermoso created in th…
save_to_drive#
Save file(s) to Google Drive
Save a Hermoso render — or ANY file — into the user’s connected Google Drive. Pass a Hermoso render URL as url (or urls[] for several); for a local/external file, call upload_file first and pass the url it returns. Optional folder (created if new) + name. Returns the Drive file(s) with a webViewLink. Needs Google Drive connected (Settings ▸ Connectors ▸ Google Drive — one connection covers Drive, Sheets and Docs). NOTE: Hermoso uses the drive.file scope, so it reaches ONLY the files it created plus any the user explicitly handed over with the Google file picker in the app — never their whole Drive.
| Parameter | Type | Description |
|---|
url | string | a single Hermoso render URL to save |
urls | string[] | several render URLs (up to 20) to save in one call |
folder | string | Drive folder name to save into (created if new) |
name | string | file name (single save) |
list_drive_files#
List Google Drive files read-only
List the Google Drive files & folders Hermoso can reach — the ones it created, plus any the user handed over with the Google file picker in the app (the drive.file scope exposes nothing else, never their entire Drive). This is how you find the id of a file the user picked. Filter by query (name contains …), folderId (contents of a folder), or onlyFolders:true. Paginate with pageToken. Read-only.
| Parameter | Type | Description |
|---|
query | string | only files whose name contains this |
folderId | string | list the contents of this folder id |
onlyFolders | boolean | list folders only |
pageSize | number | rows per page (1–200, default 50) |
pageToken | string | cursor from a previous call |
includeTrashed | boolean | include trashed files (default false) |
get_drive_file#
Get a Drive file’s details read-only
Fetch one Drive file’s metadata — name, type, size, modified time, a webViewLink to open it and a webContentLink to download it. Pass fileId (from list_drive_files). Read-only.
| Parameter | Type | Description |
|---|
fileIdrequired | string | the Drive file id (from list_drive_files) |
update_drive_file#
Rename / move / trash a Drive file
Update a Drive file: rename (name), move it into a folder (moveToFolderId, optionally removeFromFolderId to move OUT of the old one), or trash / untrash it (trash:true|false). Pass fileId (from list_drive_files). To delete permanently, use delete_drive_file.
| Parameter | Type | Description |
|---|
fileIdrequired | string | the Drive file id |
name | string | new name |
moveToFolderId | string | folder id to move the file into (from create_drive_folder / list_drive_files) |
removeFromFolderId | string | the old parent folder id to remove (when moving) |
trash | boolean | true → move to Trash; false → restore from Trash |
delete_drive_file#
Delete a Drive file destructive
Delete a Drive file. By default it goes to Trash (recoverable); pass permanent:true to delete it forever. Pass fileId (from list_drive_files) + confirm:true. Irreversible when permanent — confirm with the user first.
| Parameter | Type | Description |
|---|
fileIdrequired | string | the Drive file id |
permanent | boolean | true = delete forever; default trashes (recoverable) |
confirm | boolean | REQUIRED true |
create_drive_folder#
Create a Drive folder
Create a folder in the user’s Google Drive (optionally nested under parentId) to organize saved files. Returns the folder id + webViewLink. Use that ID as update_drive_file’s moveToFolderId or as parentId for a nested folder. NOTE: save_to_drive’s `folder` is a NAME, not this id — it find-or-creates a folder by that name, so pass the folder NAME there (or omit and just save, then move with update_drive_file).
| Parameter | Type | Description |
|---|
namerequired | string | folder name |
parentId | string | parent folder id for a nested folder (default: Drive root) |
Google Sheets: export structured data to a spreadsheet the a…
create_sheet#
Create a Google Sheet
Create a new Google Spreadsheet in the user’s Drive and optionally fill it with rows — e.g. export a swipefile, ad list, or performance report. Pass rows as an array of row arrays (first row = headers). Returns the spreadsheet id + URL. Needs Google Drive connected (Settings ▸ Connectors ▸ Google Drive — one connection covers Drive, Sheets and Docs).
| Parameter | Type | Description |
|---|
title | string | spreadsheet title |
rows | string | number | boolean[][] | rows to write — array of row arrays; first row = headers |
append_to_sheet#
Append rows to a Google Sheet
Append rows to a Google Sheet Hermoso can reach — one it created (pass the spreadsheetId from create_sheet) or one the user handed over with the Google file picker in the app (find its id with list_drive_files). rows = array of row arrays.
| Parameter | Type | Description |
|---|
spreadsheetIdrequired | string | the spreadsheet id from create_sheet |
rowsrequired | string | number | boolean[][] | rows to append — array of row arrays |
range | string | range to append at (default A1 / first sheet) |
read_sheet#
Read a Google Sheet range read-only
Read cells from a Google Sheet Hermoso can reach — one it created, or one the user handed over with the Google file picker in the app (that is how an EXISTING spreadsheet becomes readable; find its id with list_drive_files). Pass the spreadsheetId (from create_sheet) OR paste a Google Sheets URL as sheetUrl. If Google answers that the file was not found, the user has not picked it yet — ask them to pick it in the app rather than retrying. Returns a 2-D array of values.
| Parameter | Type | Description |
|---|
spreadsheetId | string | the spreadsheet id (from create_sheet) |
sheetUrl | string | a Google Sheets URL to read — the spreadsheet id is extracted from it |
range | string | A1 range, e.g. "A1:D50" (default A1:Z1000) |
Google Docs: export copy / brief / report as a doc the app c…
create_doc#
Create a Google Doc
Create a new Google Doc in the user’s Drive with a title + optional body text — e.g. export ad copy, a creative brief, or a report. Returns the document id + URL. Needs Google Drive connected (Settings ▸ Connectors ▸ Google Drive — one connection covers Drive, Sheets and Docs).
| Parameter | Type | Description |
|---|
title | string | document title |
text | string | body text to insert |
append_to_doc#
Append text to a Google Doc
Append text to the end of a Google Doc Hermoso can reach — one it created (pass the documentId from create_doc) or one the user handed over with the Google file picker in the app (find its id with list_drive_files).
| Parameter | Type | Description |
|---|
documentIdrequired | string | the document id from create_doc |
textrequired | string | text to append at the end of the doc |
read_doc#
Read a Google Doc read-only
Read the text of a Google Doc Hermoso can reach — one it created, or one the user handed over with the Google file picker in the app (that is how an EXISTING doc becomes readable; find its id with list_drive_files). Pass documentId (from create_doc) OR paste a Google Docs URL as docUrl. Under the drive.file scope it reaches nothing else in the user’s Drive; if Google answers that the file was not found, the user has not picked it yet — ask them to pick it in the app rather than retrying. Returns the plain text. Read-only, free.
| Parameter | Type | Description |
|---|
documentId | string | the document id (from create_doc) |
docUrl | string | a Google Docs URL to read — the document id is extracted from it |
The Sheets / Docs WRITE surface
list_sheet_tabs#
List the tabs in a Google Sheet read-only
The tabs in a Google Spreadsheet, each with its name, numeric sheetId, row/column count and position. Call this BEFORE naming a tab in update_sheet / clear_sheet_range / manage_sheet_tabs / format_sheet, and before proposing to delete one — it is how you learn what the file actually contains instead of guessing at a name. Read-only, free.
| Parameter | Type | Description |
|---|
spreadsheetId | string | the spreadsheet id (from create_sheet, or list_drive_files for one the user picked) |
sheetUrl | string | a Google Sheets URL — the id is extracted from it |
update_sheet#
Write to a range in a Google Sheet destructive
CORRECT cells in a Google Sheet — write values to an exact range, overwriting whatever is there. This is the fix append_to_sheet cannot make: appending only ever adds rows at the bottom, so without this a wrong number stays wrong forever and the only "correction" is a second row contradicting the first. Pass `range` (e.g. "B2:C5", or "Q3 Report!B2" to name a tab — list_sheet_tabs gives the names) and `values` as an array of row arrays; an anchor cell like "B2" is fine and the block is written down and right from it. Writing into EMPTY cells goes straight through. Writing OVER cells that already hold values is REFUSED first, naming exactly how many filled cells would be overwritten — show the user that, get a yes, then call again with confirm:true. The result is READ BACK from the sheet, so what you report is what the sheet now holds rather than what Google accepted.
| Parameter | Type | Description |
|---|
spreadsheetId | string | |
sheetUrl | string | |
range | string | A1 range or anchor cell, e.g. "B2:C5", "B2", or "Q3 Report!B2" (default A1) |
values | string | number | boolean[][] | array of row arrays to write |
updates | object[] | write SEVERAL disjoint ranges in one call, instead of range+values |
valueInputOption | "USER_ENTERED" | "RAW" | USER_ENTERED (default) parses formulas, dates and numbers the way typing them would; RAW stores every value as literal text |
confirm | boolean | required only when the target range already holds values |
clear_sheet_range#
Clear a range in a Google Sheet destructive
Empty a range of cells in a Google Sheet, leaving the rows themselves in place. DESTRUCTIVE: call it WITHOUT confirm first and nothing is cleared — you get back the real number of filled cells in that exact range. Show the user that number, get an unambiguous yes, then call again with confirm:true AND confirmCells set to it. The echo is not ceremony: it is what catches naming A1:Z1000 when you meant A1:Z10, which is the mistake that actually happens. There is deliberately NO default range. The clear is read back and reported as confirmed only if the range really is empty afterwards. To remove a whole tab instead, use manage_sheet_tabs.
| Parameter | Type | Description |
|---|
spreadsheetId | string | |
sheetUrl | string | |
rangerequired | string | the range to clear, e.g. "A2:D50" or "Sheet1!A2:D50" |
confirm | boolean | |
confirmCells | number | echo back the filled-cell count the unconfirmed call reported |
manage_sheet_tabs#
Add, rename or delete a sheet tab destructive
Add, rename or delete a tab in a Google Spreadsheet. action:"add" + title · action:"rename" + tab + newTitle · action:"delete" + tab. Name the tab by its TITLE or its numeric sheetId (list_sheet_tabs gives both); an unknown tab is refused with the real list rather than a Google error nobody can map back. DELETING a tab destroys everything on it: call it without confirm first to get the filled-cell count, then confirm:true + confirmCells. Google does not allow removing the LAST remaining tab in a file, and that is refused by name with the way out (clear it, or delete the whole file with delete_drive_file). Every action is read back from the spreadsheet before it is reported as done.
| Parameter | Type | Description |
|---|
spreadsheetId | string | |
sheetUrl | string | |
actionrequired | "add" | "rename" | "delete" | |
tab | string | which tab — its title or numeric sheetId (rename / delete) |
title | string | the name for the new tab (action:"add") |
newTitle | string | what to rename the tab to (action:"rename") |
confirm | boolean | |
confirmCells | number | |
format_sheet#
Format a Google Sheet
Make an exported sheet readable: bold the header row, FREEZE it so it stays visible while scrolling, and auto-size the columns so nothing is cut off. Worth calling right after create_sheet — a raw export with unsized columns and a header that scrolls away is the difference between a spreadsheet someone reads and one they close. Changes no cell VALUE, so it is never gated. The defaults do all three on the first tab; pass `tab` to pick another, freezeRows:0 to skip freezing, boldHeader:false or autoResize:false to skip those.
| Parameter | Type | Description |
|---|
spreadsheetId | string | |
sheetUrl | string | |
tab | string | tab title or numeric sheetId (default: the first tab) |
boldHeader | boolean | |
freezeRows | number | how many top rows to freeze (default 1, 0 = none) |
autoResize | boolean | |
update_doc#
Edit a Google Doc in place destructive
EDIT a Google Doc — the correction append_to_doc cannot make, which until now meant a doc could only ever grow and a wrong line stayed in it forever. Two shapes: `replacements:[{find, replace}]` rewrites specific text wherever it appears (call read_doc first and match the text EXACTLY; matchCase:false ignores case), or `rewrite:"…"` replaces the ENTIRE body (rewrite:"" empties it). Find/replace runs immediately and REPORTS how many occurrences changed — zero matches is reported as a FAILURE to match, never as a quiet success, because a text edit that silently does nothing is worse than one that visibly fails. A whole-body rewrite is destructive: call it without confirm first to get the character count, then confirm:true + confirmCells. Both are index-free by design — an agent cannot reliably compute Google’s character offsets, and a wrong offset deletes the wrong sentence.
| Parameter | Type | Description |
|---|
documentId | string | the document id (from create_doc, or list_drive_files for one the user picked) |
docUrl | string | a Google Docs URL — the id is extracted from it |
replacements | object[] | find/replace pairs, applied in order |
rewrite | string | replace the WHOLE body with this text ("" empties the doc) |
confirm | boolean | |
confirmCells | number | echo back the character count the unconfirmed call reported (rewrite only) |
Microsoft OneDrive: full CRUD over the user's OneDrive
save_to_onedrive#
Save file(s) to OneDrive
Save a Hermoso render — or ANY file — into the user’s connected Microsoft OneDrive. Pass a Hermoso render URL as url (or urls[] for several); for a local/external file, call upload_file first and pass the url it returns. Optional folder (created if new) + name. Returns the OneDrive file(s) with a webViewLink. Needs OneDrive connected (Settings ▸ Connectors ▸ OneDrive).
| Parameter | Type | Description |
|---|
url | string | a single Hermoso render URL to save |
urls | string[] | several render URLs (up to 20) to save in one call |
folder | string | OneDrive folder name to save into (created if new) |
name | string | file name (single save) |
list_onedrive_files#
List OneDrive files read-only
List files & folders in the user’s OneDrive — the root by default, a folder’s contents (folderId), or a name search (query). onlyFolders:true lists folders only. Paginate with pageToken (the cursor from a previous call). Read-only.
| Parameter | Type | Description |
|---|
query | string | search — only items whose name matches this |
folderId | string | list the contents of this folder id |
onlyFolders | boolean | list folders only |
pageSize | number | rows per page (1–200, default 50) |
pageToken | string | cursor from a previous call |
get_onedrive_file#
Get a OneDrive file’s details read-only
Fetch one OneDrive item’s metadata — name, type, size, modified time, a webViewLink to open it and a webContentLink to download it. Pass fileId (from list_onedrive_files). Read-only.
| Parameter | Type | Description |
|---|
fileIdrequired | string | the OneDrive item id (from list_onedrive_files) |
update_onedrive_file#
Rename / move a OneDrive file
Update a OneDrive item: rename (name) and/or move it into a folder (moveToFolderId). Pass fileId (from list_onedrive_files). To remove an item, use delete_onedrive_file.
| Parameter | Type | Description |
|---|
fileIdrequired | string | the OneDrive item id |
name | string | new name |
moveToFolderId | string | folder id to move the item into (from create_onedrive_folder / list_onedrive_files) |
delete_onedrive_file#
Delete a OneDrive file destructive
Delete a OneDrive item — it moves to the OneDrive recycle bin (recoverable there). Pass fileId (from list_onedrive_files) + confirm:true. Confirm the exact file with the user first.
| Parameter | Type | Description |
|---|
fileIdrequired | string | the OneDrive item id |
confirm | boolean | REQUIRED true |
convert_onedrive_file#
Convert a OneDrive file to PDF or JPG read-only
Turn a file already in the user’s OneDrive into a PDF or a JPG — Microsoft does the conversion on its own servers, so nothing is re-encoded here and nothing is lost in a screenshot. It reads about 130 source formats, which is the point: PowerPoint and Word decks, Excel, Photoshop PSD, Illustrator AI, Sketch, 3D (fbx/glb/obj), video (mp4/mov/webm), HEIC from an iPhone, and the raw camera formats (CR2, NEF, ARW, DNG) that nothing else in this product can open. Use it to turn a client’s deck into images you can actually put in an ad, to get a usable JPG out of a designer’s PSD or a photographer’s raw file, or to hand someone a PDF of a spreadsheet. CONVERTING TO JPG REQUIRES BOTH width AND height — Microsoft refuses the call without them. The result is stored at a durable Hermoso URL you can pass straight to a render or a post; Microsoft’s own conversion link expires within minutes, so do not hand that one to anyone. Needs OneDrive connected — no new permission.
| Parameter | Type | Description |
|---|
fileIdrequired | string | the OneDrive item id, from list_onedrive_files |
format | "pdf" | "jpg" | default pdf |
width | number | REQUIRED for jpg — output width in pixels |
height | number | REQUIRED for jpg — output height in pixels |
create_onedrive_folder#
Create a OneDrive folder
Create a folder in the user’s OneDrive (optionally nested under parentId) to organize saved files. Returns the folder id + webViewLink. Use that id as update_onedrive_file’s moveToFolderId or as parentId for a nested folder. NOTE: save_to_onedrive’s `folder` is a NAME (find-or-created), not this id.
| Parameter | Type | Description |
|---|
namerequired | string | folder name |
parentId | string | parent folder id for a nested folder (default: OneDrive root) |