airtable-cli 0.1.0__tar.gz

airtable_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:airtable.com)",
+      "WebFetch(domain:developer.airtable.com)",
+      "WebSearch",
+      "WebFetch(domain:support.airtable.com)",
+      "Bash(pip3:*)",
+      "Bash(python3:*)",
+      "Bash(pip install:*)",
+      "Bash(/Users/xavier/Library/Python/3.12/bin/airtable:*)",
+      "Bash(/Users/xavier/Library/Python/3.12/bin/pytest:*)",
+      "Bash(AIRTABLE_PAT=pat1kF01sMFQAPbKK.a59d4400c7223470936868e3abb0f4d096c7fe819e0f7d64081a4aa7fc358cac /Users/xavier/Library/Python/3.12/bin/airtable:*)",
+      "Bash(curl:*)"
+    ]
+  }
+}

airtable_cli-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.log
+.pytest_cache/
+.coverage
+htmlcov/

airtable_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xavier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

airtable_cli-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: airtable-cli
+Version: 0.1.0
+Summary: A CLI tool to interact with the full Airtable Web API
+Project-URL: Homepage, https://github.com/professor-eggs/airtable-cli
+Project-URL: Repository, https://github.com/professor-eggs/airtable-cli
+Project-URL: Bug Tracker, https://github.com/professor-eggs/airtable-cli/issues
+Author-email: professor-eggs <0xavier0@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Xavier
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: airtable,api,cli,database,no-code
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: inquirerpy>=0.3.4
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# airtable-cli
+
+A command-line tool for interacting with the [Airtable Web API](https://airtable.com/developers/web/api/introduction). Manage bases, tables, fields, records, comments, and webhooks from your terminal — with interactive fuzzy-search prompts or fully non-interactive scripting mode.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+**via pip** (simplest):
+```bash
+pip install airtable-cli
+```
+
+**via pipx** (recommended — isolates the tool from your system Python):
+```bash
+pipx install airtable-cli
+```
+
+**via Homebrew** (macOS/Linux):
+```bash
+brew tap professor-eggs/airtable-cli
+brew install airtable-cli
+```
+
+**from source** (development):
+```bash
+git clone https://github.com/professor-eggs/airtable-cli
+cd airtable-cli
+pip install -e ".[dev]"
+```
+
+## Authentication
+
+Get a Personal Access Token from [airtable.com/create/tokens](https://airtable.com/create/tokens), then configure the CLI:
+
+```bash
+airtable auth configure --token patXXXXXXXXXXXXXX
+```
+
+You can also set the token via environment variable (takes precedence over the config file):
+
+```bash
+export AIRTABLE_PAT=patXXXXXXXXXXXXXX
+```
+
+The config file is stored at `~/.config/airtable-cli/config.toml`.
+
+## Usage
+
+```
+airtable [--base TEXT] [--output table|json|yaml] [--no-interactive] [--version]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--base` | Override the default base ID for this invocation (env: `AIRTABLE_BASE_ID`) |
+| `--output`, `-o` | Output format: `table` (default), `json`, or `yaml` |
+| `--no-interactive` | Disable all prompts — required args must be passed as flags |
+| `--version` | Print version and exit |
+
+## Command Reference
+
+### `auth`
+
+```bash
+airtable auth configure [--token TEXT] [--default-base TEXT]
+airtable auth show
+airtable auth revoke
+```
+
+### `bases`
+
+```bash
+airtable bases list
+airtable bases schema [--base TEXT]
+```
+
+### `tables`
+
+```bash
+airtable tables list   [--base TEXT]
+airtable tables get    [--base TEXT] [--table TEXT]
+airtable tables create [--base TEXT] [--name TEXT] [--description TEXT] [--fields JSON]
+```
+
+### `fields`
+
+```bash
+airtable fields list   [--base TEXT] [--table TEXT]
+airtable fields create [--base TEXT] [--table TEXT] [--name TEXT] [--type TEXT] [--options JSON]
+airtable fields update [--base TEXT] [--table TEXT] [--field TEXT] [--name TEXT] [--options JSON]
+```
+
+### `records`
+
+```bash
+airtable records list   [--base TEXT] [--table TEXT] [--view TEXT] [--filter TEXT]
+                        [--sort FIELD:asc|desc]... [--max-records INT]
+                        [--fields TEXT]... [--all-pages] [--cell-format json|string]
+airtable records get    [--base TEXT] [--table TEXT] [--record TEXT]
+airtable records create [--base TEXT] [--table TEXT] [--fields JSON] [--fields-file PATH] [--typecast]
+airtable records update [--base TEXT] [--table TEXT] [--record TEXT]...
+                        [--fields JSON] [--fields-file PATH] [--mode patch|put] [--typecast]
+airtable records delete [--base TEXT] [--table TEXT] [--record TEXT]... [--confirm/--no-confirm]
+```
+
+### `comments`
+
+```bash
+airtable comments list   [--base TEXT] [--table TEXT] [--record TEXT]
+airtable comments create [--base TEXT] [--table TEXT] [--record TEXT] [--text TEXT]
+airtable comments delete [--base TEXT] [--table TEXT] [--record TEXT] [--comment TEXT] [--confirm/--no-confirm]
+```
+
+### `webhooks`
+
+```bash
+airtable webhooks list     [--base TEXT]
+airtable webhooks create   [--base TEXT] [--url TEXT] [--filters JSON] [--specification JSON]
+airtable webhooks update   [--base TEXT] [--webhook TEXT] [--enable/--disable] [--refresh-expiry]
+airtable webhooks delete   [--base TEXT] [--webhook TEXT] [--confirm/--no-confirm]
+airtable webhooks payloads [--base TEXT] [--webhook TEXT] [--cursor INT]
+```
+
+## Examples
+
+```bash
+# Configure auth and set a default base
+airtable auth configure --token patXXX --default-base appXXXXXXXX
+
+# List all bases as JSON
+airtable --output json bases list
+
+# List tables in a base
+airtable --base appXXXXXXXX tables list
+
+# List all records across all pages
+airtable --base appXXXXXXXX records list --table tblXXXXXXXX --all-pages
+
+# Filter and sort records
+airtable --base appXXX records list --table tblXXX \
+  --filter "Status = 'Active'" \
+  --sort "Name:asc" \
+  --output json
+
+# Create a single record
+airtable --base appXXX records create --table tblXXX \
+  --fields '{"Name": "Alice", "Status": "Active"}'
+
+# Bulk create from a JSON file
+echo '[{"Name": "Foo"}, {"Name": "Bar"}]' > records.json
+airtable --base appXXX records create --table tblXXX --fields-file records.json
+
+# Update a record
+airtable --base appXXX records update --table tblXXX \
+  --record recXXXXXXXXXXXXXX \
+  --fields '{"Status": "Done"}'
+
+# Delete records without confirmation prompt
+airtable --no-interactive --base appXXX records delete \
+  --table tblXXX \
+  --record recAAA --record recBBB \
+  --no-confirm
+
+# Create a webhook
+airtable --base appXXX webhooks create --url https://example.com/hook
+
+# Disable a webhook
+airtable --base appXXX webhooks update --webhook whdXXX --disable
+
+# Script-friendly: pipe JSON output
+airtable --no-interactive --output json --base appXXX records list --table tblXXX \
+  | jq '.[].fields.Name'
+```
+
+## Interactive Mode
+
+When a required argument is missing and the terminal is interactive (TTY), the CLI automatically prompts with fuzzy-search pickers — for example, selecting a base by name or picking a record from a list. Pass `--no-interactive` to suppress all prompts and require every argument as a flag.
+
+## Configuration File
+
+`~/.config/airtable-cli/config.toml`
+
+```toml
+[auth]
+token = "patXXXXXXXXXXXXXX"
+
+[defaults]
+base_id = "appXXXXXXXX"
+
+[output]
+format = "table"
+color = true
+```
+
+Environment variables `AIRTABLE_PAT` and `AIRTABLE_BASE_ID` take precedence over the config file.
+
+## Rate Limiting
+
+The client uses a token bucket (5 requests/second) and automatically retries on HTTP 429 responses with exponential backoff (up to 3 retries).
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+```

airtable_cli-0.1.0/README.md

@@ -0,0 +1,212 @@
+# airtable-cli
+
+A command-line tool for interacting with the [Airtable Web API](https://airtable.com/developers/web/api/introduction). Manage bases, tables, fields, records, comments, and webhooks from your terminal — with interactive fuzzy-search prompts or fully non-interactive scripting mode.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+**via pip** (simplest):
+```bash
+pip install airtable-cli
+```
+
+**via pipx** (recommended — isolates the tool from your system Python):
+```bash
+pipx install airtable-cli
+```
+
+**via Homebrew** (macOS/Linux):
+```bash
+brew tap professor-eggs/airtable-cli
+brew install airtable-cli
+```
+
+**from source** (development):
+```bash
+git clone https://github.com/professor-eggs/airtable-cli
+cd airtable-cli
+pip install -e ".[dev]"
+```
+
+## Authentication
+
+Get a Personal Access Token from [airtable.com/create/tokens](https://airtable.com/create/tokens), then configure the CLI:
+
+```bash
+airtable auth configure --token patXXXXXXXXXXXXXX
+```
+
+You can also set the token via environment variable (takes precedence over the config file):
+
+```bash
+export AIRTABLE_PAT=patXXXXXXXXXXXXXX
+```
+
+The config file is stored at `~/.config/airtable-cli/config.toml`.
+
+## Usage
+
+```
+airtable [--base TEXT] [--output table|json|yaml] [--no-interactive] [--version]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--base` | Override the default base ID for this invocation (env: `AIRTABLE_BASE_ID`) |
+| `--output`, `-o` | Output format: `table` (default), `json`, or `yaml` |
+| `--no-interactive` | Disable all prompts — required args must be passed as flags |
+| `--version` | Print version and exit |
+
+## Command Reference
+
+### `auth`
+
+```bash
+airtable auth configure [--token TEXT] [--default-base TEXT]
+airtable auth show
+airtable auth revoke
+```
+
+### `bases`
+
+```bash
+airtable bases list
+airtable bases schema [--base TEXT]
+```
+
+### `tables`
+
+```bash
+airtable tables list   [--base TEXT]
+airtable tables get    [--base TEXT] [--table TEXT]
+airtable tables create [--base TEXT] [--name TEXT] [--description TEXT] [--fields JSON]
+```
+
+### `fields`
+
+```bash
+airtable fields list   [--base TEXT] [--table TEXT]
+airtable fields create [--base TEXT] [--table TEXT] [--name TEXT] [--type TEXT] [--options JSON]
+airtable fields update [--base TEXT] [--table TEXT] [--field TEXT] [--name TEXT] [--options JSON]
+```
+
+### `records`
+
+```bash
+airtable records list   [--base TEXT] [--table TEXT] [--view TEXT] [--filter TEXT]
+                        [--sort FIELD:asc|desc]... [--max-records INT]
+                        [--fields TEXT]... [--all-pages] [--cell-format json|string]
+airtable records get    [--base TEXT] [--table TEXT] [--record TEXT]
+airtable records create [--base TEXT] [--table TEXT] [--fields JSON] [--fields-file PATH] [--typecast]
+airtable records update [--base TEXT] [--table TEXT] [--record TEXT]...
+                        [--fields JSON] [--fields-file PATH] [--mode patch|put] [--typecast]
+airtable records delete [--base TEXT] [--table TEXT] [--record TEXT]... [--confirm/--no-confirm]
+```
+
+### `comments`
+
+```bash
+airtable comments list   [--base TEXT] [--table TEXT] [--record TEXT]
+airtable comments create [--base TEXT] [--table TEXT] [--record TEXT] [--text TEXT]
+airtable comments delete [--base TEXT] [--table TEXT] [--record TEXT] [--comment TEXT] [--confirm/--no-confirm]
+```
+
+### `webhooks`
+
+```bash
+airtable webhooks list     [--base TEXT]
+airtable webhooks create   [--base TEXT] [--url TEXT] [--filters JSON] [--specification JSON]
+airtable webhooks update   [--base TEXT] [--webhook TEXT] [--enable/--disable] [--refresh-expiry]
+airtable webhooks delete   [--base TEXT] [--webhook TEXT] [--confirm/--no-confirm]
+airtable webhooks payloads [--base TEXT] [--webhook TEXT] [--cursor INT]
+```
+
+## Examples
+
+```bash
+# Configure auth and set a default base
+airtable auth configure --token patXXX --default-base appXXXXXXXX
+
+# List all bases as JSON
+airtable --output json bases list
+
+# List tables in a base
+airtable --base appXXXXXXXX tables list
+
+# List all records across all pages
+airtable --base appXXXXXXXX records list --table tblXXXXXXXX --all-pages
+
+# Filter and sort records
+airtable --base appXXX records list --table tblXXX \
+  --filter "Status = 'Active'" \
+  --sort "Name:asc" \
+  --output json
+
+# Create a single record
+airtable --base appXXX records create --table tblXXX \
+  --fields '{"Name": "Alice", "Status": "Active"}'
+
+# Bulk create from a JSON file
+echo '[{"Name": "Foo"}, {"Name": "Bar"}]' > records.json
+airtable --base appXXX records create --table tblXXX --fields-file records.json
+
+# Update a record
+airtable --base appXXX records update --table tblXXX \
+  --record recXXXXXXXXXXXXXX \
+  --fields '{"Status": "Done"}'
+
+# Delete records without confirmation prompt
+airtable --no-interactive --base appXXX records delete \
+  --table tblXXX \
+  --record recAAA --record recBBB \
+  --no-confirm
+
+# Create a webhook
+airtable --base appXXX webhooks create --url https://example.com/hook
+
+# Disable a webhook
+airtable --base appXXX webhooks update --webhook whdXXX --disable
+
+# Script-friendly: pipe JSON output
+airtable --no-interactive --output json --base appXXX records list --table tblXXX \
+  | jq '.[].fields.Name'
+```
+
+## Interactive Mode
+
+When a required argument is missing and the terminal is interactive (TTY), the CLI automatically prompts with fuzzy-search pickers — for example, selecting a base by name or picking a record from a list. Pass `--no-interactive` to suppress all prompts and require every argument as a flag.
+
+## Configuration File
+
+`~/.config/airtable-cli/config.toml`
+
+```toml
+[auth]
+token = "patXXXXXXXXXXXXXX"
+
+[defaults]
+base_id = "appXXXXXXXX"
+
+[output]
+format = "table"
+color = true
+```
+
+Environment variables `AIRTABLE_PAT` and `AIRTABLE_BASE_ID` take precedence over the config file.
+
+## Rate Limiting
+
+The client uses a token bucket (5 requests/second) and automatically retries on HTTP 429 responses with exponential backoff (up to 3 retries).
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+```

airtable_cli-0.1.0/airtable_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

airtable_cli-0.1.0/airtable_cli/client.py

@@ -0,0 +1,132 @@
+"""httpx wrapper with auth, rate limiting (token bucket), pagination, and error handling."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Generator
+from typing import Any, Optional
+
+import httpx
+from rich.console import Console
+
+_console = Console(stderr=True)
+
+BASE_URL_V0 = "https://api.airtable.com/v0"
+BASE_URL_META = "https://api.airtable.com/v0/meta"
+BASE_URL_BASES = "https://api.airtable.com/v0/bases"
+
+MAX_RETRIES = 3
+RATE_LIMIT = 5  # requests per second
+
+
+class AirtableAPIError(Exception):
+    def __init__(self, status_code: int, error_type: str, message: str) -> None:
+        self.status_code = status_code
+        self.error_type = error_type
+        self.message = message
+        super().__init__(f"[{status_code}] {error_type}: {message}")
+
+
+class _TokenBucket:
+    """Simple token bucket for rate limiting."""
+
+    def __init__(self, rate: float) -> None:
+        self.rate = rate
+        self.tokens = rate
+        self.last = time.monotonic()
+
+    def consume(self) -> None:
+        now = time.monotonic()
+        elapsed = now - self.last
+        self.tokens = min(self.rate, self.tokens + elapsed * self.rate)
+        self.last = now
+        if self.tokens < 1:
+            sleep_time = (1 - self.tokens) / self.rate
+            time.sleep(sleep_time)
+            self.tokens = 0
+        else:
+            self.tokens -= 1
+
+
+_bucket = _TokenBucket(RATE_LIMIT)
+
+
+def _get_client(token: str) -> httpx.Client:
+    return httpx.Client(
+        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+        timeout=30.0,
+    )
+
+
+def _handle_response(response: httpx.Response) -> dict[str, Any]:
+    if response.is_success:
+        if response.content:
+            return response.json()
+        return {}
+    try:
+        body = response.json()
+        err = body.get("error", {})
+        error_type = err.get("type", "UNKNOWN_ERROR")
+        message = err.get("message", response.text)
+    except Exception:
+        error_type = "UNKNOWN_ERROR"
+        message = response.text
+    raise AirtableAPIError(response.status_code, error_type, message)
+
+
+def _request(
+    method: str,
+    url: str,
+    token: str,
+    *,
+    params: Optional[dict] = None,
+    json: Optional[dict | list] = None,
+) -> dict[str, Any]:
+    _bucket.consume()
+    backoff = 1.0
+    for attempt in range(MAX_RETRIES):
+        with _get_client(token) as client:
+            response = client.request(method, url, params=params, json=json)
+        if response.status_code == 429:
+            if attempt < MAX_RETRIES - 1:
+                time.sleep(backoff)
+                backoff *= 2
+                continue
+        return _handle_response(response)
+    return _handle_response(response)  # type: ignore[reportPossiblyUnbound]
+
+
+def get(url: str, token: str, params: Optional[dict] = None) -> dict[str, Any]:
+    return _request("GET", url, token, params=params)
+
+
+def post(url: str, token: str, json: dict | list) -> dict[str, Any]:
+    return _request("POST", url, token, json=json)
+
+
+def patch(url: str, token: str, json: dict | list) -> dict[str, Any]:
+    return _request("PATCH", url, token, json=json)
+
+
+def put(url: str, token: str, json: dict | list) -> dict[str, Any]:
+    return _request("PUT", url, token, json=json)
+
+
+def delete(url: str, token: str, params: Optional[dict] = None) -> dict[str, Any]:
+    return _request("DELETE", url, token, params=params)
+
+
+def paginate(
+    url: str,
+    token: str,
+    params: Optional[dict] = None,
+) -> Generator[dict[str, Any], None, None]:
+    """Yield successive pages until no offset is returned."""
+    params = dict(params or {})
+    while True:
+        data = get(url, token, params=params)
+        yield data
+        offset = data.get("offset")
+        if not offset:
+            break
+        params["offset"] = offset