NocoDB from the Command Line -- curl Recipes and the Official Script
NocoDB has no standalone nc binary -- on Linux and macOS nc is the netcat utility and must not be used for NocoDB. The official command-line tool is the Bash script nocodb.sh (needs curl and jq), published as an agent skill. This plugin does not bundle it; every recipe here is plain curl on the NocoDB v3 REST API, and each one is mapped to the script command that does the same job.
Prefer the MCP tools (see mcp-patterns) for interactive work; use these recipes in scripts, on a machine without the MCP connection, and for the few things MCP does not cover (such as attachment upload).
The Official Script (optional)
npx skills add nocodb/agent-skills
- The script is
scripts/nocodb.sh inside the installed nocodb skill directory; that skill's README gives the exact path for your agent. Run it by that path, for example "$NOCODB_SH" record:list <baseId> <tableId> after export NOCODB_SH=<path to nocodb.sh>.
- It reads
NOCODB_TOKEN, NOCODB_URL (default https://app.nocodb.com) and NOCODB_VERBOSE.
- It accepts names or IDs for bases, tables and views; set
NOCODB_VERBOSE=1 to see how names resolve.
Setup for the curl Recipes
export NOCODB_URL="https://your-instance.example.com" # required for self-hosted
export NOCODB_TOKEN="your-api-token" # NocoDB → Team & Settings → API Tokens → Add New Token
A one-line wrapper keeps repeated calls short (paths are under /api/v3):
nocodb_api() { # nocodb_api METHOD /path ['{"json":"body"}']
local m="$1" p="$2" b="${3:-}"
if [ -n "$b" ]; then
curl -sS -X "$m" -H "xc-token: ${NOCODB_TOKEN}" -H "Content-Type: application/json" -d "$b" "${NOCODB_URL}/api/v3${p}"
else
curl -sS -X "$m" -H "xc-token: ${NOCODB_TOKEN}" -H "Content-Type: application/json" "${NOCODB_URL}/api/v3${p}"
fi
}
# nocodb_api GET /data/$BASE_ID/$TABLE_ID/count
NOCODB_TOKEN is the API token. It is distinct from NOCODB_MCP_TOKEN (the MCP connection token, used only by .mcp.json).
Plan Requirements
- All plans: Base, Table, Field, Filter, Sort, Record, Link, Attachment APIs.
- Cloud Business and above / licensed self-hosted: Hooks, Comments, Workflows, Documents, Base collaboration.
- Cloud Enterprise / licensed self-hosted: Views, Dashboards, Scripts.
- Workspace list/create is open; per-workspace changes, Teams and Tokens depend on the plan.
ID Prefixes
| Prefix |
Meaning |
w... |
Workspace |
p... |
Base (project) |
m... |
Table (model) |
c... |
Field (column) |
vw... |
View |
Hierarchy: WORKSPACE → BASE → TABLE → VIEW/FIELD → RECORD. Record paths take the base and the table ID: /data/{baseId}/{tableId}/....
Command Map -- nocodb.sh → REST (v3)
Paths are relative to ${NOCODB_URL}/api/v3.
| Resource |
Script command |
REST call |
| Workspaces |
workspace:list / workspace:get |
GET /meta/workspaces, GET /meta/workspaces/{workspaceId} |
| Bases |
base:list <ws> / base:get |
GET /meta/workspaces/{workspaceId}/bases, GET /meta/bases/{baseId} |
| Tables |
table:list / table:get |
GET /meta/bases/{baseId}/tables, GET /meta/bases/{baseId}/tables/{tableId} |
| Fields |
field:list |
GET /meta/bases/{baseId}/tables/{tableId} -- the fields array |
| Records |
record:list |
GET /data/{baseId}/{tableId}/records (where, sort, fields, page, pageSize, viewId query parameters) |
|
record:get |
GET /data/{baseId}/{tableId}/records/{recordId} |
|
record:create |
POST /data/{baseId}/{tableId}/records -- body [{"fields":{…}}] |
|
record:update / record:update-many |
PATCH /data/{baseId}/{tableId}/records -- body [{"id":…,"fields":{…}}] |
|
record:delete |
DELETE /data/{baseId}/{tableId}/records -- body [{"id":…}] |
|
record:count |
GET /data/{baseId}/{tableId}/count (where, viewId) |
|
(none) upsert |
POST /data/{baseId}/{tableId}/records/upsert |
| Links |
link:list / link:add / link:remove |
GET / POST / DELETE /data/{baseId}/{tableId}/links/{linkFieldId}/{recordId} |
| Attachments |
attachment:upload |
POST /data/{baseId}/{tableId}/records/{recordId}/fields/{fieldId}/upload |
| Buttons |
action:trigger |
POST /data/{baseId}/{tableId}/actions/{buttonFieldId} |
| Views |
view:list / view:get |
GET /meta/bases/{baseId}/tables/{tableId}/views, GET /meta/bases/{baseId}/views/{viewId} |
| Filters |
filter:list |
GET /meta/bases/{baseId}/views/{viewId}/filters |
| Sorts |
sort:list |
GET /meta/bases/{baseId}/views/{viewId}/sorts |
| Where help |
where:help |
see references/filter-syntax.md |
Schema writes (create / change tables, fields, views, hooks) are the job of the nocodb-dev plugin; its cli-reference skill carries the full write-side command map.
Data Quick Reference (curl)
# List — page 1, 50 per page, sorted, filtered (URL-encode the JSON and the where string)
nocodb_api GET "/data/$BASE_ID/$TABLE_ID/records?pageSize=50&page=1&sort=%5B%7B%22field%22%3A%22Name%22%2C%22direction%22%3A%22asc%22%7D%5D"
# One record, a count
nocodb_api GET "/data/$BASE_ID/$TABLE_ID/records/31"
nocodb_api GET "/data/$BASE_ID/$TABLE_ID/count"
# Create / update / delete — bodies are arrays
nocodb_api POST /data/$BASE_ID/$TABLE_ID/records '[{"fields":{"Name":"Alice"}}]'
nocodb_api PATCH /data/$BASE_ID/$TABLE_ID/records '[{"id":31,"fields":{"Status":"Done"}}]'
nocodb_api DELETE /data/$BASE_ID/$TABLE_ID/records '[{"id":31}]'
sort is a JSON array of {"field","direction"} objects (asc | desc), exactly as in the MCP queryRecords tool. The where string uses the grammar in references/filter-syntax.md -- dates carry a sub-operator (exactDate) and ranges are two bounds, on REST as on MCP.
See Reference Files
references/record-link.md -- records, linked records, attachments, button actions (curl)
references/filter-syntax.md -- the complete where filter syntax for REST and MCP queries
references/view-filter-sort.md -- reading views, filters and sorts (curl)
references/base-table-field.md -- reading workspaces, bases, tables and fields (curl)
Common Pitfalls
| Symptom |
Cause |
Fix |
nc hangs or prints a netcat error |
nc is netcat, not a NocoDB tool |
Use curl (this skill) or nocodb.sh |
NOCODB_TOKEN required / empty xc-token header |
Token env var missing |
export NOCODB_TOKEN=... |
| 401 Unauthorized |
Token wrong or revoked |
Regenerate in NocoDB → Team & Settings → API Tokens |
| 403 Forbidden |
Token lacks permission for that base, or the plan lacks the API |
Share the base with the token's user; check the plan list above |
Could not resolve name "X" (script) |
Name not unique or wrong scope |
Pass IDs instead of names; set NOCODB_VERBOSE=1 |
| Error on a date filter |
Bare date in where, or btw on a date |
(Date,gte,exactDate,2026-06-01)~and(Date,lte,exactDate,2026-06-30) |
1---2name: cli-reference-63description: |4 Command-line access to NocoDB data -- curl recipes on the Data API v3 (records, links, attachments) and Meta API v3, mapped to the commands of the official nocodb.sh script (installed with npx skills add nocodb/agent-skills). Loaded only on explicit cite. Use when:5 - "NocoDB CLI commands"6 - "NocoDB curl recipes"7 - "NocoDB agent-skills"8 - "what CLI commands are available"9 - "nocodb.sh commands"10metadata:11 source: https://skillmd.com/skills/agents-store/cli-reference-612---1314# NocoDB from the Command Line -- curl Recipes and the Official Script1516NocoDB has **no standalone `nc` binary** -- on Linux and macOS `nc` is the netcat utility and must not be used for NocoDB. The official command-line tool is the Bash script `nocodb.sh` (needs `curl` and `jq`), published as an agent skill. This plugin does **not** bundle it; every recipe here is plain `curl` on the NocoDB v3 REST API, and each one is mapped to the script command that does the same job.1718Prefer the MCP tools (see **mcp-patterns**) for interactive work; use these recipes in scripts, on a machine without the MCP connection, and for the few things MCP does not cover (such as attachment upload).1920## The Official Script (optional)2122```bash23npx skills add nocodb/agent-skills24```2526- The script is `scripts/nocodb.sh` inside the installed `nocodb` skill directory; that skill's README gives the exact path for your agent. Run it by that path, for example `"$NOCODB_SH" record:list <baseId> <tableId>` after `export NOCODB_SH=<path to nocodb.sh>`.27- It reads `NOCODB_TOKEN`, `NOCODB_URL` (default `https://app.nocodb.com`) and `NOCODB_VERBOSE`.28- It accepts **names** or **IDs** for bases, tables and views; set `NOCODB_VERBOSE=1` to see how names resolve.2930## Setup for the curl Recipes3132```bash33export NOCODB_URL="https://your-instance.example.com" # required for self-hosted34export NOCODB_TOKEN="your-api-token" # NocoDB → Team & Settings → API Tokens → Add New Token35```3637A one-line wrapper keeps repeated calls short (paths are under `/api/v3`):3839```bash40nocodb_api() { # nocodb_api METHOD /path ['{"json":"body"}']41 local m="$1" p="$2" b="${3:-}"42 if [ -n "$b" ]; then43 curl -sS -X "$m" -H "xc-token: ${NOCODB_TOKEN}" -H "Content-Type: application/json" -d "$b" "${NOCODB_URL}/api/v3${p}"44 else45 curl -sS -X "$m" -H "xc-token: ${NOCODB_TOKEN}" -H "Content-Type: application/json" "${NOCODB_URL}/api/v3${p}"46 fi47}48# nocodb_api GET /data/$BASE_ID/$TABLE_ID/count49```5051`NOCODB_TOKEN` is the **API token**. It is distinct from `NOCODB_MCP_TOKEN` (the MCP connection token, used only by `.mcp.json`).5253## Plan Requirements5455- **All plans:** Base, Table, Field, Filter, Sort, Record, Link, Attachment APIs.56- **Cloud Business and above / licensed self-hosted:** Hooks, Comments, Workflows, Documents, Base collaboration.57- **Cloud Enterprise / licensed self-hosted:** Views, Dashboards, Scripts.58- **Workspace** list/create is open; per-workspace changes, Teams and Tokens depend on the plan.5960## ID Prefixes6162| Prefix | Meaning |63|--------|---------|64| `w...` | Workspace |65| `p...` | Base (project) |66| `m...` | Table (model) |67| `c...` | Field (column) |68| `vw...` | View |6970Hierarchy: `WORKSPACE → BASE → TABLE → VIEW/FIELD → RECORD`. Record paths take the base **and** the table ID: `/data/{baseId}/{tableId}/...`.7172## Command Map -- `nocodb.sh` → REST (v3)7374Paths are relative to `${NOCODB_URL}/api/v3`.7576| Resource | Script command | REST call |77|----------|----------------|-----------|78| Workspaces | `workspace:list` / `workspace:get` | `GET /meta/workspaces`, `GET /meta/workspaces/{workspaceId}` |79| Bases | `base:list <ws>` / `base:get` | `GET /meta/workspaces/{workspaceId}/bases`, `GET /meta/bases/{baseId}` |80| Tables | `table:list` / `table:get` | `GET /meta/bases/{baseId}/tables`, `GET /meta/bases/{baseId}/tables/{tableId}` |81| Fields | `field:list` | `GET /meta/bases/{baseId}/tables/{tableId}` -- the `fields` array |82| Records | `record:list` | `GET /data/{baseId}/{tableId}/records` (`where`, `sort`, `fields`, `page`, `pageSize`, `viewId` query parameters) |83| | `record:get` | `GET /data/{baseId}/{tableId}/records/{recordId}` |84| | `record:create` | `POST /data/{baseId}/{tableId}/records` -- body `[{"fields":{…}}]` |85| | `record:update` / `record:update-many` | `PATCH /data/{baseId}/{tableId}/records` -- body `[{"id":…,"fields":{…}}]` |86| | `record:delete` | `DELETE /data/{baseId}/{tableId}/records` -- body `[{"id":…}]` |87| | `record:count` | `GET /data/{baseId}/{tableId}/count` (`where`, `viewId`) |88| | *(none)* upsert | `POST /data/{baseId}/{tableId}/records/upsert` |89| Links | `link:list` / `link:add` / `link:remove` | `GET` / `POST` / `DELETE /data/{baseId}/{tableId}/links/{linkFieldId}/{recordId}` |90| Attachments | `attachment:upload` | `POST /data/{baseId}/{tableId}/records/{recordId}/fields/{fieldId}/upload` |91| Buttons | `action:trigger` | `POST /data/{baseId}/{tableId}/actions/{buttonFieldId}` |92| Views | `view:list` / `view:get` | `GET /meta/bases/{baseId}/tables/{tableId}/views`, `GET /meta/bases/{baseId}/views/{viewId}` |93| Filters | `filter:list` | `GET /meta/bases/{baseId}/views/{viewId}/filters` |94| Sorts | `sort:list` | `GET /meta/bases/{baseId}/views/{viewId}/sorts` |95| Where help | `where:help` | see `references/filter-syntax.md` |9697Schema writes (create / change tables, fields, views, hooks) are the job of the **nocodb-dev** plugin; its `cli-reference` skill carries the full write-side command map.9899## Data Quick Reference (curl)100101```bash102# List — page 1, 50 per page, sorted, filtered (URL-encode the JSON and the where string)103nocodb_api GET "/data/$BASE_ID/$TABLE_ID/records?pageSize=50&page=1&sort=%5B%7B%22field%22%3A%22Name%22%2C%22direction%22%3A%22asc%22%7D%5D"104105# One record, a count106nocodb_api GET "/data/$BASE_ID/$TABLE_ID/records/31"107nocodb_api GET "/data/$BASE_ID/$TABLE_ID/count"108109# Create / update / delete — bodies are arrays110nocodb_api POST /data/$BASE_ID/$TABLE_ID/records '[{"fields":{"Name":"Alice"}}]'111nocodb_api PATCH /data/$BASE_ID/$TABLE_ID/records '[{"id":31,"fields":{"Status":"Done"}}]'112nocodb_api DELETE /data/$BASE_ID/$TABLE_ID/records '[{"id":31}]'113```114115`sort` is a JSON array of `{"field","direction"}` objects (`asc` | `desc`), exactly as in the MCP `queryRecords` tool. The `where` string uses the grammar in `references/filter-syntax.md` -- dates carry a sub-operator (`exactDate`) and ranges are two bounds, on REST as on MCP.116117## See Reference Files118119- **`references/record-link.md`** -- records, linked records, attachments, button actions (curl)120- **`references/filter-syntax.md`** -- the complete `where` filter syntax for REST and MCP queries121- **`references/view-filter-sort.md`** -- reading views, filters and sorts (curl)122- **`references/base-table-field.md`** -- reading workspaces, bases, tables and fields (curl)123124## Common Pitfalls125126| Symptom | Cause | Fix |127|---------|-------|-----|128| `nc` hangs or prints a netcat error | `nc` is netcat, not a NocoDB tool | Use `curl` (this skill) or `nocodb.sh` |129| `NOCODB_TOKEN required` / empty `xc-token` header | Token env var missing | `export NOCODB_TOKEN=...` |130| 401 Unauthorized | Token wrong or revoked | Regenerate in NocoDB → Team & Settings → API Tokens |131| 403 Forbidden | Token lacks permission for that base, or the plan lacks the API | Share the base with the token's user; check the plan list above |132| `Could not resolve name "X"` (script) | Name not unique or wrong scope | Pass IDs instead of names; set `NOCODB_VERBOSE=1` |133| Error on a date filter | Bare date in `where`, or `btw` on a date | `(Date,gte,exactDate,2026-06-01)~and(Date,lte,exactDate,2026-06-30)` |