Update to Airtable

{
  "name": "airtable-cli",
  "description": "Lists bases, reads and writes records, manages tables and fields, filters and searches data in Airtable via the `airtable-mcp` CLI. Use when the task involves Airtable data or the user mentions airtable-mcp, bases, tables, records, or fields.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 243
    }
  ],
  "skill_md_contents": "---\nname: airtable-cli\ndescription: >-\n    Lists bases, reads and writes records, manages tables and fields, filters and\n    searches data in Airtable via the `airtable-mcp` CLI. Use when the task\n    involves Airtable data or the user mentions airtable-mcp, bases, tables,\n    records, or fields.\n---\n\n# airtable-mcp\n\n## Self-discovery\n\nTools are fetched from the MCP server at runtime, so the CLI never has a hardcoded command list. Discover what's available:\n\n```sh\nairtable-mcp tools            # human-readable list\nairtable-mcp tools --json     # machine-parseable list\nairtable-mcp <tool> --help    # show flags and descriptions for a tool\n```\n\nRun `airtable-mcp tools` before assuming a tool exists. Tool names, arguments, and output shapes can change between server releases without a CLI update.\n\n## Install\n\n```sh\nnpm install -g @airtable/mcp-cli\n```\n\n## Auth\n\nThe CLI needs an Airtable personal access token (PAT). Two paths:\n\n**Environment variable (preferred for scripts/agents):**\n\n```sh\nexport AIRTABLE_TOKEN=pat_xxx\n```\n\n**Interactive configure (stores token in `~/.airtable/cli.json` with 0600 permissions):**\n\n```sh\nairtable-mcp configure\n```\n\nCreate tokens at https://airtable.com/create/tokens. Ensure the token has the scopes required by the tools being called.\n\n`AIRTABLE_TOKEN` takes precedence over saved profiles when no `--profile` flag is set. Never log or echo tokens.\n\n## Quick reference\n\n| Task                   | Command                                                 |\n| ---------------------- | ------------------------------------------------------- |\n| Set up credentials     | `airtable-mcp configure`                                |\n| Add a named profile    | `airtable-mcp configure --profile work`                 |\n| Check auth status      | `airtable-mcp whoami`                                   |\n| Remove credentials     | `airtable-mcp logout`                                   |\n| Remove all profiles    | `airtable-mcp logout --all`                             |\n| List available tools   | `airtable-mcp tools`                                    |\n| Run a tool             | `airtable-mcp <tool> --flagName value`                  |\n| Get tool help          | `airtable-mcp <tool> --help`                            |\n| Pass args via stdin    | `echo '{\"key\":\"val\"}' \\| airtable-mcp <tool> --input -` |\n| Bypass tool cache      | `airtable-mcp <tool> --refresh`                         |\n| Suppress status msgs   | `airtable-mcp <tool> -q`                                |\n| Raw text output        | `airtable-mcp <tool> --output raw`                      |\n| Use a specific profile | `airtable-mcp <tool> --profile work`                    |\n\nTool names use hyphens on the CLI (`list-records`) but underscores in MCP (`list_records`). The CLI translates automatically.\n\n## Workflow\n\n1. **Auth** — set `AIRTABLE_TOKEN` or run `airtable-mcp configure`\n2. **Discover** — run `airtable-mcp tools` to see available tools\n3. **Inspect** — run `airtable-mcp <tool> --help` for flags and descriptions\n4. **Check access** — in `tools --json` output, check the `access` field: `read-only`, `write`, or `destructive`. Confirm with the user before running `destructive` tools.\n5. **Execute** — run `airtable-mcp <tool> --flagName value`\n\n## Output & automation\n\n-   Default output is formatted JSON to stdout. Status messages go to stderr.\n-   `--json` on `tools` gives a JSON array of `{name, title, access}`.\n-   `-q` / `--quiet` suppresses stderr status messages (cache warnings, etc).\n-   `--output raw` returns the raw server response text instead of parsed JSON.\n-   `--input -` reads tool arguments as a JSON object from stdin, bypassing flag parsing.\n-   Exit codes: `0` success, `1` error (auth, tool failure, not found), `2` usage error (bad flags, bad input).\n\n## Common tasks\n\n**Find a base and list its tables:**\n\n```sh\nairtable-mcp search-bases --searchQuery \"Project Tracker\" -q\nairtable-mcp list-tables-for-base --baseId appK9MtBqFw3o5jGN -q\n```\n\n**List records with specific fields:**\n\n```sh\nairtable-mcp list-records-for-table \\\n  --baseId appK9MtBqFw3o5jGN --tableId tblL4GpTfEz8byRsW \\\n  --fieldIds '[\"Name\",\"Status\"]' --pageSize 10 -q\n```\n\n**Filter records** — filters use structured JSON, not formula strings. Wrap conditions in an `operands` array; the top-level `operator` defaults to `and` if omitted:\n\n```sh\nairtable-mcp list-records-for-table \\\n  --baseId appK9MtBqFw3o5jGN --tableId tblL4GpTfEz8byRsW \\\n  --filters '{\"operator\":\"and\",\"operands\":[{\"operator\":\"=\",\"operands\":[\"Status\",\"Done\"]}]}' -q\n```\n\nFor select fields, filter by choice ID (from `get-table-schema`), not the display name. The `airtable-filters` skill covers compound filters, date filters, and operator-by-field-type details.\n\n**Search records** — use `search-records` for free-text/fuzzy queries on large tables. Use `list-records-for-table` with `--filters` when filtering by exact field values:\n\n```sh\nairtable-mcp search-records \\\n  --baseId appK9MtBqFw3o5jGN --table tblL4GpTfEz8byRsW \\\n  --query \"acme\" --fields '[\"Name\",\"Notes\"]' -q\n```\n\nPass `--fields ALL_SEARCHABLE_FIELDS` to search across every indexed field. Date, rating, checkbox, and button fields are not searchable.\n\n**Update records** — complex args are easier via `--input -`:\n\n```sh\necho '{\"baseId\":\"appK9MtBqFw3o5jGN\",\"tableId\":\"tblL4GpTfEz8byRsW\",\"records\":[{\"id\":\"recVnR3xPq8sD2yLk\",\"fields\":{\"fld8WsrpLHHevsnW8\":\"Done\"}}]}' \\\n  | airtable-mcp update-records-for-table --input - -q\n```\n\nSelect field values are returned as objects (`{\"id\":\"sel...\",\"name\":\"Done\"}`) but must be written as plain strings (`\"Done\"`). Record field keys in create/update currently require field IDs (`fldXXX`) — use `get-table-schema` to resolve names to IDs before writing. Note that `fieldIds`, `sort`, and `filters` accept both names and IDs.\n\n## Gotchas\n\n| Problem                                      | Cause                                                              | Fix                                                                      |\n| -------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------ |\n| `Unknown tool: X`                            | Tool name doesn't exist on the server or cache is stale            | Run `airtable-mcp tools --refresh` to refresh, then retry                |\n| `Authentication failed`                      | Token expired, revoked, or wrong                                   | Run `airtable-mcp configure` or check `AIRTABLE_TOKEN`                   |\n| `Access denied`                              | Token missing required scopes                                      | Add scopes at https://airtable.com/create/tokens                         |\n| `Connection timed out`                       | Server unreachable (10s timeout)                                   | Check network; CLI falls back to stale cache if available                |\n| Boolean flags take no value                  | `--dryRun true` passes `\"true\"` as next arg                        | Use `--dryRun` alone (booleans are presence-based)                       |\n| Array/object args fail                       | Value isn't valid JSON                                             | Pass as JSON string: `--fieldMappings '{\"a\":\"b\"}'`                       |\n| Filter rejected at top level                 | Single condition passed without `operands` wrapper                 | Wrap in `{\"operands\":[...]}` (`operator` defaults to `and`)              |\n| Sort key is `fieldId` not `field`            | `--sort '[{\"field\":\"Name\"}]'` silently ignored                     | Use `{\"fieldId\":\"Name\",\"direction\":\"asc\"}` — accepts field IDs or names  |\n| Select filter returns no matches             | Filtering by display name instead of choice ID                     | Run `get-table-schema` first to get `sel...` choice IDs                  |\n| `INVALID_RECORDS` on batch write             | Batch limit is 10 records per request (default; varies by account) | Split into chunks of ≤10 and check `<tool> --help` for the current limit |\n| Permission error on `list-records-for-table` | User has interface-only access to the base                         | Use `list-records-for-page` / `get-record-for-page` instead              |\n| Endpoints restricted                         | CLI only allows HTTPS on `*.airtable.com`                          | Cannot point at arbitrary servers (security constraint)                  |\n"
}