clay-workbook-snapshot

---
name: clay-workbook-snapshot
description: "Create timestamped snapshots of Clay workbooks and compare them to track changes over time. Use this skill whenever the user wants to audit changes to specific Clay workbooks, maintain version history of workbook data, compare workbook snapshot versions (like git for Clay data), track daily changes, monitor data quality, create compliance audit trails, or investigate when a workbook's data changed. Perfect for daily snapshots, change tracking, debugging data issues, and building a historical record of how a Clay workbook evolved."
---

Clay Workbook Snapshot

Create and compare timestamped snapshots of any Clay workbook - like GitHub version control but for your Clay data!

> Terminology: this skill only ever snapshots the specific Clay workbook(s) you name — never everything in your Clay account. A named group of one or more tracked workbooks (plus a save location) is called a tracker throughout this doc. A tracker is not your Clay account's own "workspace" (the thing clay whoami reports on) — the two are unrelated. The scripts and config file below still use the word workspace internally, from before this doc's terminology was cleaned up; treat clay_workspace_*.py and ~/.clay_workspace_config.json as just their names, not a hint about scope.

When to Use This Skill

Use this skill when you need to:
- 📸 Take daily snapshots of specific Clay workbooks for audit trails
- 🔍 Track changes - see what rows were added, removed, or modified
- 📊 Compare versions - like git diff for your Clay data
- 🛡️ Compliance & auditing - maintain records of how a workbook evolved
- 🐛 Debug issues - find when and what data changed
- 📈 Monitor quality - track patterns over time
- 💾 Version history - keep a complete historical record

⚠️ Prerequisites

Before using this skill, you MUST have:
1. ✅ Clay CLI authenticated: clay whoami should return your Clay account/workspace info
2. ✅ Python 3.x installed
3. ✅ Read/write access to your save location

Not set up yet? Run:
``bash
clay login # Authenticate with Clay
clay whoami # Verify it works
`

---

What It Does

Create Snapshots

📂 Script location: All python3 commands below reference clay_workspace_setup.py, clay_workspace_export.py, and clay_compare_workspaces.py by name only. These scripts live in this skill's own directory (the same folder as this SKILL.md) — run them from an absolute path into that directory, e.g. python3 /path/to/this/skill/clay_workspace_setup.py.

🔧 First time only: Verify Clay CLI works
`bash
clay whoami # Should return your Clay account/workspace info
clay login # If needed, authenticate first
`

1. Set Up a New Tracker

`bash
python3 clay_workspace_setup.py
`
⚠️ This uses Clay CLI to fetch your workbooks from your authenticated Clay account

Interactive setup asks:
- Tracker name (e.g., "Project Name", "Client XYZ")
- Where to save snapshots (default: ~/Documents/{tracker_name}/)
- Which workbook(s) this tracker covers
- Export format (MD recommended)

2. Export Snapshots

`bash
python3 clay_workspace_export.py "Tracker Name"
`

Creates timestamped files: YYYY-MM-DD.md

3. Compare Snapshots

`bash
python3 clay_compare_workspaces.py "Tracker Name" 2026-08-06 2026-08-07
`

Generates: COMPARE_2026-08-06_to_2026-08-07.md

Full Workflow

First Time Setup

`bash


1. Run setup wizard

`bash


Every morning - create snapshot

`
~/Documents/Your Tracker Name/
├─ 2026-08-06.md (Daily snapshot)
├─ 2026-08-07.md (Daily snapshot)
├─ 2026-08-08.md (Daily snapshot)
└─ COMPARE_2026-08-06_to_2026-08-07.md (Comparison report)
`

Custom location example:

`
~/Projects/Client_XYZ/Clay_Snapshots/
├─ 2026-08-06.md
├─ 2026-08-07.md
└─ COMPARE_2026-08-06_to_2026-08-07.md
`

Tracker Management

List All Trackers

`bash
python3 clay_workspace_setup.py --list
`

Output:
`
📚 Configured Trackers:

Tracker 1
Location: ~/Documents/Tracker 1
Workbooks: 3
Format: md

Tracker 2
Location: ~/Projects/Client/Snapshots
Workbooks: 5
Format: md
`

Delete a Tracker

`bash
python3 clay_workspace_setup.py --delete "Tracker Name"
`

Snapshot Contents

Each daily MD file includes:

Header

`


Comparison Report: My Tracker

Comparing: 2026-08-06 → 2026-08-07

Summary

Settings are stored in: ~/.clay_workspace_config.json

The filename and the JSON keys below (workspaces, workspace_name) are historical — they refer to a tracker, not your Clay account's workspace.

Example:
`json
{
"workspaces": {
"My Tracker": {
"workspace_name": "My Tracker",
"save_location": "~/Documents/My Tracker",
"workbooks": {
"wb_123": "Workbook 1",
"wb_456": "Workbook 2"
},
"export_format": "md",
"created": "2026-08-07T10:30:00"
}
}
}
`

excluded_tables (optional, not shown above) can be added by hand as an array of table IDs under a tracker entry — tables to skip even though they live in a tracked workbook. The setup wizard doesn't offer this yet, so it's a manual config edit for now.

Requirements

- Clay CLI authenticated (clay whoami works)
- Python 3.x installed
- Read/write access to save location
- Access to configured workbooks

Known Limitations

This skill (and the underlying clay CLI) cannot do the following — know these going in
so a gap doesn't read as a bug:

No edit history / no "who changed what."
Neither clay nor its API exposes any audit log, activity feed, or per-cell/per-row
edit history. workbooks get and tables get return a single owner field (the
creator) and createdAt — that's the entire attribution surface. There is no way to
snapshot or query who edited a table or when a specific change was made, only that
it differs from a prior snapshot. If your team needs that, it has to come from Clay's
own web UI (if it exposes one), not this skill.

Cross-workbook lineage is metadata-only, not a full pull.
When a table's action column references another table outside the tracked
workbook(s), the export resolves its name, owning workbook, and row count (for a
regular table) or its description/input/output schema (for a custom-Function table,
via clay functions get). It does not pull that external table's row data into the
snapshot — only its identity. Pulling full data cross-workbook was left out on purpose,
to keep a snapshot of workbook A from silently absorbing all of workbook B's rows too.

Permission-gated references show up as unresolved.
If a referenced table lives in a workbook the authenticated key/user can't read (or the
Clay workspace is on a plan without the public observability API), resolution fails with
auth_forbidden and the snapshot just records it as unresolvable — there's no way
around that from the CLI side.

Row data is capped, not exhaustive.
Each table pulls up to 1,000 rows via clay tables rows list --limit 1000, and the
snapshot only prints the first 500 of whatever came back. A table with more rows than
that will show a partial data section (row count is still accurate — only the row
listing is truncated).

Workflows aren't covered.
This skill only snapshots Tables/Workbooks (Clay's data-table product). Clay Workflows
— the separate automation/agent-node product — have their own run history in the Clay
app; nothing here tracks workflow node changes or run history.

Comparisons are between snapshots you already took, not live "since X" diffs.
clay_compare_workspaces.py diffs two markdown files that must already exist on disk.
It can't answer "what changed since last Tuesday" if you never exported on Tuesday —
there's no live time-travel query against Clay itself, only whatever you've snapshotted.

One Clay workspace per CLI session.
The clay CLI is pinned to whichever Clay account/workspace was picked at clay login.
Switching means running clay login again; this skill has no multi-workspace credential
switching of its own. (This is the one place "workspace" means your actual Clay account —
unrelated to the trackers this skill manages.)

Troubleshooting

"Tracker not found"
- Run clay_workspace_setup.py --list to see configured trackers
- Ensure the tracker name matches exactly (case-sensitive)

"Could not fetch tables"
- Verify Clay CLI is authenticated: clay whoami
- Check that your Clay account has access to the tracked workbook(s)

Large files
- Snapshots can be 50+ KB per tracker
- Archive old snapshots to save space
- Limit the number of workbooks per tracker if needed

Examples

Set Up Two Trackers

`bash


Set up Tracker 1

`bash


Monday morning

---

Built for Clay workbooks. Works with any configuration. Perfect for audit trails and change tracking.

📂 Script location: All python3 commands below reference clay_workspace_setup.py, clay_workspace_export.py, and clay_compare_workspaces.py by name only. These scripts live in this skill's own directory (the same folder as this SKILL.md) — run them from an absolute path into that directory, e.g. python3 /path/to/this/skill/clay_workspace_setup.py.

🔧 First time only: Verify Clay CLI works
``bash
clay whoami # Should return your Clay account/workspace info
clay login # If needed, authenticate first
``

- Clay CLI authenticated (clay whoami works)
- Python 3.x installed
- Read/write access to save location
- Access to configured workbooks