# Airtable on boxd

> Airtable merges spreadsheet functionality with database power, enabling teams to organize projects, track tasks, and collaborate through customizable views, automation, and integrations for data management.

- Page: https://boxd.sh/integrations/airtable/
- CLI: `run airtable` (26 commands, 11 marked common)
- SDK: `import { airtable } from "@boxd/run"`; every parameter and response type is at `@boxd/run/airtable`
- Triggers: 6
- Connect: `run auth airtable` (Sign in with Airtable), or https://app.boxd.sh/integrations/detail/airtable
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth airtable      # once: prints a link to connect your account
run airtable           # list its commands
run airtable list-bases
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { airtable } from "@boxd/run";

const result = await airtable.listBases({});
console.log(result);

airtable.on("base-metadata-changed", async (event) => {
  // Base Metadata Changed: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run airtable.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run airtable <command> --help` lists the optional ones. "common" marks what `run airtable` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `create-base` | `airtable.createBase()` | `--name` `--tables` `--workspaceId` | 0 | Creates a new Airtable base with specified tables and fields within a workspace |
| `create-comment` | `airtable.createComment()` | `--baseId` `--recordId` `--tableIdOrName` `--text` | 1 | Create a comment on a specific Airtable record |
| `create-field` | `airtable.createField()` | `--baseId` `--name` `--tableIdOrName` | 3 | Creates a new field within a specified table in an Airtable base |
| `create-multiple-records` ·common ·deprecated | `airtable.createMultipleRecords()` | `--baseId` `--records` `--tableIdOrName` | 2 | Use create-records instead |
| `create-record` ·common ·deprecated | `airtable.createRecord()` | `--baseId` `--tableIdOrName` | 3 | Use CreateRecords instead |
| `create-record-from-natural-language` ·common | `airtable.createRecordFromNaturalLanguage()` | `--baseId` `--nl-query` `--tableIdOrName` | 1 | Creates a new record in an Airtable table from a natural language description |
| `create-records` ·common | `airtable.createRecords()` | `--baseId` `--records` `--tableIdOrName` | 2 | Create multiple records (up to 10) in a specified Airtable table |
| `create-table` | `airtable.createTable()` | `--base-id` `--fields` `--name` | 3 | Creates a new table within a specified existing Airtable base, allowing definition of its name, description, and field structure |
| `delete-comment` | `airtable.deleteComment()` | `--baseId` `--recordId` `--rowCommentId` `--tableIdOrName` | 0 | Delete a comment from a record in an Airtable table |
| `delete-multiple-records` | `airtable.deleteMultipleRecords()` | `--baseId` `--recordIds` `--tableIdOrName` | 0 | Delete up to 10 specified records from a table within an Airtable base |
| `delete-record` | `airtable.deleteRecord()` | `--baseId` `--recordId` `--tableIdOrName` | 0 | Permanently deletes a specific record from an existing table within an existing Airtable base |
| `get-attachment-info` | `airtable.getAttachmentInfo()` | `--attachmentFieldIdOrName` `--baseId` `--recordId` `--tableIdOrName` | 0 | Retrieves attachment information from a specific field in an Airtable record |
| `get-base-schema` ·common | `airtable.getBaseSchema()` | `--baseId` | 1 | Retrieves the detailed schema for a specified Airtable base, including its tables, fields, field types, and configurations, using the `baseId` |
| `get-record` ·common | `airtable.getRecord()` | `--baseId` `--recordId` `--tableIdOrName` | 4 | Retrieves a specific record from an Airtable table by its record ID |
| `get-user-info` | `airtable.getUserInfo()` | — | 0 | Retrieves information, such as ID and permission scopes, for the currently authenticated Airtable user from the `/meta/whoami` endpoint |
| `list-bases` ·common | `airtable.listBases()` | — | 1 | Retrieves all Airtable bases accessible to the authenticated user, which may include an 'offset' for pagination |
| `list-comments` | `airtable.listComments()` | `--baseId` `--recordId` `--tableIdOrName` | 2 | List comments on a specific Airtable record |
| `list-records` | `airtable.listRecords()` | `--baseId` `--tableIdOrName` | 12 | List records from an Airtable table with filtering, sorting, and pagination |
| `update-comment` | `airtable.updateComment()` | `--baseId` `--recordId` `--rowCommentId` `--tableIdOrName` `--text` | 0 | Update an existing comment on a specific Airtable record |
| `update-field` | `airtable.updateField()` | `--baseId` `--fieldId` `--tableId` | 2 | Updates a field's name or description in an Airtable table |
| `update-multiple-records` ·common | `airtable.updateMultipleRecords()` | `--baseId` `--records` `--tableIdOrName` | 3 | Update up to 10 records in an Airtable table with selective field modifications |
| `update-multiple-records-put` ·common | `airtable.updateMultipleRecordsPut()` | `--baseId` `--records` `--tableIdOrName` | 3 | Destructively update multiple records in Airtable using PUT, clearing unspecified fields |
| `update-record` ·common | `airtable.updateRecord()` | `--baseId` `--fields` `--recordId` `--tableIdOrName` | 2 | Modifies specified fields of an existing record in an Airtable base and table; the base, table, and record must exist |
| `update-record-put` ·common | `airtable.updateRecordPut()` | `--baseId` `--fields` `--recordId` `--tableIdOrName` | 2 | Updates an existing record in an Airtable base using PUT method |
| `update-table` | `airtable.updateTable()` | `--baseId` `--tableIdOrName` | 3 | Updates the name, description, and/or date dependency settings of a table in Airtable |
| `upload-attachment` | `airtable.uploadAttachment()` | `--attachmentFieldIdOrName` `--baseId` `--contentType` `--file` `--filename` `--recordId` | 0 | Uploads a file attachment to a specified field in an Airtable record |

## Triggers

`airtable.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"base-metadata-changed"` | Base Metadata Changed | — | Triggers when an existing Airtable base changes its name or permission level |
| `"base-schema-changed"` | Base Schema Changed | `baseId` | Triggers when tables, fields, or views change in an Airtable base |
| `"user-profile-changed"` | User Profile Changed | — | Triggers when the connected Airtable user's profile information changes |
| `"view-created"` | View Created | `baseId` | Triggers when a new view is created in an Airtable base |
| `"view-deleted"` | View Deleted | `baseId` | Triggers when a previously known Airtable view is deleted |
| `"view-metadata-changed"` | View Metadata Changed | `baseId` | Triggers when an Airtable view changes its name or type |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.