{"name":"airtable-cli","url":"https://skills.sh/airtable/skills/airtable-cli","install":"npx skills add airtable/skills --skill airtable-cli","sdk":"airtable","key":"airtable/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.","hasContent":true,"content":"---\nname: airtable-cli\ndescription: 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.\nlicense: MIT\nmetadata:\n version: '1.0.0'\n author: airtable\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 --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 --flagName value` |\n| Get tool help | `airtable-mcp --help` |\n| Pass args via stdin | `echo '{\"key\":\"val\"}' \\| airtable-mcp --input -` |\n| Bypass tool cache | `airtable-mcp --refresh` |\n| Suppress status msgs | `airtable-mcp -q` |\n| Raw text output | `airtable-mcp --output raw` |\n| Use a specific profile | `airtable-mcp --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 --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 --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 appEXAMPLEbase001 -q\n```\n\n**List records with specific fields:**\n\n```sh\nairtable-mcp list-records-for-table \\\n --baseId appEXAMPLEbase001 --tableId tblEXAMPLEtable01 \\\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 appEXAMPLEbase001 --tableId tblEXAMPLEtable01 \\\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 appEXAMPLEbase001 --table tblEXAMPLEtable01 \\\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\":\"appEXAMPLEbase001\",\"tableId\":\"tblEXAMPLEtable01\",\"records\":[{\"id\":\"recEXAMPLErecord1\",\"fields\":{\"fldEXAMPLEfield01\":\"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 (`fldEXAMPLEfield02`) — 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 ` --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","contentSource":"https://raw.githubusercontent.com/airtable/skills/main/plugins/airtable/skills/airtable-cli/SKILL.md","contentFetchedAt":"2026-07-27T09:02:29.314Z"}