Showcase: Built a CLI tool to batch-update Granola records from a spreadsheet.

Having spent the last quarter manually reconciling our team's Granola entries against our actual AWS Cost Explorer data, I identified a significant point of friction: the manual entry of recurring cost-saving actions. For example, each identified idle RDS instance or unattached EBS volume, once resolved, required a separate manual update in Granola to reflect the new monthly savings projection. With dozens of such actions per cloud account per month, this process was both error-prone and a poor use of engineering time.

Consequently, I developed a CLI tool to bridge this operational gap. The tool ingests a structured spreadsheet (typically exported from our internal tracking systems or a curated CSV) and performs batch updates via Granola's API. The primary use case is to programmatically update the `monthly_savings` field for multiple records at once, but it can also update statuses or add notes, ensuring our FinOps reporting remains synchronized with reality without manual overhead.

The core workflow of the tool is as follows:
* **Input:** A CSV file where the first column contains the Granola record IDs, and subsequent columns represent fields to update (e.g., `monthly_savings`, `status`).
* **Validation:** The tool performs a local validation pass, checking for numeric formatting in savings fields and the validity of status enumerations, before any API calls are made.
* **Execution:** It utilizes the Granola API to perform sequential PATCH requests for each record. It includes configurable throttling to respect API rate limits.
* **Output:** A detailed log file is generated, listing each record ID, the payload sent, the HTTP status code, and the response. This is crucial for auditability and reconciling any failures.

A critical consideration during development was handling the variety of states a record might be in. The tool must skip or flag records that have been marked as `invalid` or `completed` externally, as updating them might skew historical data. My implementation currently includes a pre-flight check that fetches the current state of each record ID and only proceeds with updates for records in a `pending` or `in_progress` state, though this can be configured.

From a cost perspective, automating this process has tangible benefits. It reduces the administrative labor required for Granola upkeep, which, when calculated at our blended engineering rate, represents a non-trivial saving. More importantly, it accelerates the feedback loop between identifying a savings opportunity, executing it, and reflecting its financial impact in Granola, thereby improving the accuracy of our forecasting and showback reports.

The tool is built in Python and uses only the standard library along with the `requests` module for simplicity and portability. I am considering adding support for direct integrations with cloud provider billing alerts or cost anomaly detection feeds to create records proactively, but that is a future phase. For teams managing a substantial volume of Granola records, I have found this batch update capability to be indispensable.

-- Liam