--- name: pp-airtable description: "Airtable REST API CLI with offline cross-base search, CSV merge-upserts, field-level diffs before bulk writes, and schema drift detection. Trigger phrases: `query my Airtable base`, `sync this CSV into Airtable`, `search across my Airtable bases`, `check Airtable schema changes`, `upsert records into Airtable`, `use airtable-cli`, `run airtable-pp-cli`." author: "Elizabeth Stone" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - airtable-pp-cli install: - kind: go bins: [airtable-pp-cli] module: github.com/mvanhorn/printing-press-library/library/productivity/airtable/cmd/airtable-pp-cli --- # Airtable — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `airtable-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install airtable --cli-only ``` 2. Verify: `airtable-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.9 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/productivity/airtable/cmd/airtable-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. Airtable's wrappers are libraries, and its official MCP is an online-only tool surface without delete, comments, webhooks, attachments, or a local store. This CLI mirrors your bases into local SQLite for full-text search across every base at once, runs CSV-to-merge-upserts, shows field-level diffs before bulk writes, and serves the whole API to agents over stdio or HTTP MCP. ## When to Use This CLI Use this CLI for scripted or agent-driven Airtable workflows: bulk record sync from CSV/external systems, cross-base reporting and search, schema change monitoring across many bases, and any automation that outgrew a no-code tool's per-task limits. ## Anti-triggers Do not use this CLI for: - Do not use this CLI to build or edit Airtable's visual interface layer (Interface Designer) — that requires the Interface Extensions SDK. - Do not use this CLI for real-time collaborative editing inside the Airtable UI — writes here are one-shot API calls, not live cursor-synced edits. - Do not use this CLI for record revision/activity history — that endpoint is Enterprise-only and not exposed here. - Do not use this CLI to write Airtable automations/scripting-block code — that's the separate Scripting API surface. ## Unique Capabilities ### Bulk data sync - **`records upsert-csv`** — Take a raw CSV export and merge-upsert it straight into an Airtable table, matched on the field you choose. _Reach for this whenever the input is a CSV export from another system and existing rows should be updated instead of duplicated._ ```bash airtable-pp-cli records upsert-csv --base appLkNDICXNqxSDhG --table Leads --file leads.csv --merge-on Email ``` - **`records diff`** — See exactly which fields on which existing records would change before a bulk update or upsert actually runs. _Use before any agent-authored bulk update to confirm what will actually change, not just how many rows will be touched._ ```bash airtable-pp-cli records diff --base appLkNDICXNqxSDhG --table Shipments --stdin < changes.json ``` ### Local state that compounds - **`search`** — Search text across every synced base and table at once from one local index. _Reach for this instead of iterating records list per table when the query might match any base or table already synced locally._ ```bash airtable-pp-cli search "union square" --type records --agent --limit 10 ``` - **`bases schema-diff`** — Show exactly what changed in a base's schema since the last time this command ran for that base. _Run before deploying pipeline changes that depend on a base's field names or types staying stable._ ```bash airtable-pp-cli bases schema-diff appLkNDICXNqxSDhG ``` ## Command Reference **attachments** — Direct attachment upload to a cell - `airtable-pp-cli attachments ` — Upload a file (up to 5MB) directly to an attachment cell **bases** — Base-level metadata: list bases, get schema, collaborators, create bases - `airtable-pp-cli bases create` — Create a base with tables and return its schema - `airtable-pp-cli bases get-collaborators` — Get basic base info: name, permission level, and outstanding invites - `airtable-pp-cli bases get-schema` — Return the schema (tables, fields, views) for a base - `airtable-pp-cli bases list` — List bases the token can access **comments** — Threaded comments on records - `airtable-pp-cli comments create` — Create a comment on a record - `airtable-pp-cli comments delete` — Delete a comment you created (Enterprise Admins can delete any) - `airtable-pp-cli comments list` — List comments on a record, newest first - `airtable-pp-cli comments update` — Update a comment you created **fields** — Field (column) schema management within a table - `airtable-pp-cli fields create` — Create a field in a table - `airtable-pp-cli fields update` — Update a field's name, description, or options **records** — Record CRUD in a table (records have no fixed schema — fields are user-defined per base) - `airtable-pp-cli records create` — Create one or more records - `airtable-pp-cli records delete` — Delete a single record - `airtable-pp-cli records delete-multiple` — Delete multiple records by ID - `airtable-pp-cli records get` — Retrieve a single record - `airtable-pp-cli records list` — List records in a table, with formula filtering, sorting, view scoping, and pagination - `airtable-pp-cli records replace` — Destructively replace a single record; unspecified cell values are cleared - `airtable-pp-cli records replace-multiple` — Destructively replace multiple records in one request (or upsert, clearing unspecified fields) - `airtable-pp-cli records update` — Update a single record; only the fields you specify are changed (partial update) - `airtable-pp-cli records update-multiple` — Update or upsert multiple records in one request (partial update per record) **tables** — Table schema management within a base - `airtable-pp-cli tables create` — Create a table in a base - `airtable-pp-cli tables update` — Update a table's name, description, or date-dependency settings **user** — Authenticated user identity and token scopes - `airtable-pp-cli user` — Get the authenticated user's ID, and token scopes/email if the token has those scopes **views** — View metadata within a base - `airtable-pp-cli views delete` — Delete a view - `airtable-pp-cli views get` — Get metadata for a view - `airtable-pp-cli views list` — List views in a base **webhooks** — Webhook subscriptions for base change notifications - `airtable-pp-cli webhooks create` — Create a webhook on a base (max 10 per base) - `airtable-pp-cli webhooks delete` — Delete a webhook - `airtable-pp-cli webhooks list` — List webhooks registered on a base - `airtable-pp-cli webhooks list-payloads` — Retrieve queued change payloads for a webhook (call after receiving a ping) - `airtable-pp-cli webhooks refresh` — Extend a webhook's expiration by 7 days - `airtable-pp-cli webhooks set-notifications` — Enable or disable notification pings for a webhook **bases** - `airtable-pp-cli bases schema-diff` — Show exactly what changed in a base's schema since the last time this command ran for that base. **records** - `airtable-pp-cli records upsert-csv` — Take a raw CSV export and merge-upsert it straight into an Airtable table, matched on the field you choose. - `airtable-pp-cli records diff` — See exactly which fields on which existing records would change before a bulk update or upsert actually runs. ## Freshness Contract This printed CLI owns bounded freshness only for registered store-backed read command paths. In `--data-source auto` mode, those paths check `sync_state` and may run a bounded refresh before reading local data. `--data-source local` never refreshes. `--data-source live` reads the API and does not mutate the local store. Set `AIRTABLE_NO_AUTO_REFRESH=1` to skip the freshness hook without changing source selection. Covered paths: - `airtable-pp-cli bases` - `airtable-pp-cli bases get` - `airtable-pp-cli bases list` - `airtable-pp-cli bases search` When JSON output uses the generated provenance envelope, freshness metadata appears at `meta.freshness`. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash airtable-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Find delayed shipments and summarize by carrier ```bash airtable-pp-cli records list --base appLkNDICXNqxSDhG --table Shipments --filter-formula "{Status}='Delayed'" --expand-links --agent --select fields.Carrier,fields.Status,fields.Address ``` Pulls only delayed shipments, resolves linked carrier IDs to names from the local mirror (run records sync-table on the linked Carriers table first), and trims the response to the fields a report needs. ### Bulk-sync a CRM export into Airtable ```bash airtable-pp-cli records upsert-csv --base appLkNDICXNqxSDhG --table Leads --file leads.csv --merge-on Email --dry-run ``` Preview a merge-upsert from a CSV export before committing the write, matched on the Email field. ### Search every synced base for a customer name ```bash airtable-pp-cli search "Acme Corp" --type records --json ``` One query across every base/table already synced locally, instead of repeating records list per table. ### Check what changed in a base's schema ```bash airtable-pp-cli bases schema-diff appLkNDICXNqxSDhG ``` Flags added, removed, or retyped fields since the last time schema-diff ran for this base. ## Auth Setup Create a Personal Access Token at airtable.com/create/tokens with the scopes you need (for example data.records:read, data.records:write, schema.bases:read) and the specific bases or workspaces it should reach. Set it as AIRTABLE_API_KEY, or store it with the auth commands. This CLI authenticates with personal access tokens only. Run `airtable-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array). `--csv` prefixes `'` on a cell or header key that starts with `=`, `+`, `-`, `@`, tab, CR, or LF (fullwidth `＝＋－＠` too) so a spreadsheet does not run it as a formula; a plain signed number such as `-5` or `+2.5e3` is unchanged. - `--quiet` — one identity value per row, no envelope - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash airtable-pp-cli bases list --agent ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit confirmation** — `--agent` does not imply `--yes`; pass `--yes` separately only after the target, arguments, and side effects are clear - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success, and use `--ignore-missing` only when a missing delete target should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `AIRTABLE_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `AIRTABLE_CONFIG_DIR`, `AIRTABLE_DATA_DIR`, `AIRTABLE_STATE_DIR`, `AIRTABLE_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `AIRTABLE_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `airtable-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "airtable": { "command": "airtable-pp-mcp", "env": { "AIRTABLE_HOME": "/srv/airtable" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `AIRTABLE_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `AIRTABLE_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, pass the question as an argv or MCP tool argument to `recall --agent`. Do not interpolate user-controlled text into a shell command line. Quoted `recall ""` breaks on an apostrophe, which is ordinary English. A quoted heredoc breaks when a body line equals the delimiter, and that delimiter is published in these docs. Write the question with a non-shell file-writing tool, then read it back as data: ```bash # Write the question verbatim with your file-writing tool (no shell involved). # Command substitution on a file only ever yields data — the shell never # parses the file's bytes as syntax. QUERY=$(cat /path/to/question.txt) airtable-pp-cli recall "$QUERY" --agent ``` Prefer MCP: pass the question as the tool's query argument. `"$QUERY"` after a file read is argv-safe; putting the question itself in the command text is not. The response envelope: ```json { "query": "...", "normalized": "", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ], "warnings": [ /* top-level */ ], "candidates": [ { "id": 12, "class": "flag_alias | playbook_candidate", "summary": "...", "sightings": 3, "last_seen": "...", "rationale": "...", "next_action": ["", "airtable-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "", "canonical": "" } }, "notes": "" }, "notes": "" } ``` Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and `learnings list` and `learnings candidates` are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught. ### Step 2: decision tree Read `candidates`, `playbook`, `notes`, `results[0]`, and warnings in that order: ``` if Candidates present (warnings include "candidates_present"): -> candidates are try-then-confirm, never facts. Follow each candidate's two-step next_action verbatim: run the trial command first, then run `learnings confirm ` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject `. -> NEVER re-teach something recall surfaced as a candidate; confirm or reject that candidate instead of teaching a duplicate. -> candidates ride alongside playbooks and resource hits, not instead of them; continue with the branches below after acting on them. if Playbook present: -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose) -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries for the entity slot tokens. If a step's slot is unresolved, fall back to discovery for that step only. -> the Playbook's expected_tool_calls is a budget; if you find yourself running materially more, record the divergence via `airtable-pp-cli playbook amend` at end-of-session. elif Notes present (no Playbook): -> read Notes