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. 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 Meta API v3, and each is mapped to the script command that does the same job.
Prefer the MCP schema tools on Cloud / licensed self-hosted (see mcp-patterns); use these recipes on Community Edition, in scripts, and as the fallback.
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" table:list <baseId> 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.
- It has no commands for hooks, select-choice options or view field lists — use the recipes below for those.
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 /meta/... ['{"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 /meta/bases/$BASE_ID/tables
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 (see api-reference → Plan Availability).
ID Prefixes
| Prefix |
Meaning |
w... |
Workspace |
p... |
Base (project) |
m... |
Table (model) |
c... |
Field (column) |
vw... |
View |
Hierarchy: WORKSPACE → BASE → TABLE → VIEW/FIELD → RECORD.
Command Map — nocodb.sh → REST (Meta API 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> |
GET /meta/workspaces/{workspaceId}/bases |
|
base:get / base:update / base:delete |
GET / PATCH / DELETE /meta/bases/{baseId} |
|
base:create <ws> '{…}' |
POST /meta/workspaces/{workspaceId}/bases |
| Tables |
table:list / table:create |
GET / POST /meta/bases/{baseId}/tables |
|
table:get / table:update / table:delete |
GET / PATCH / DELETE /meta/bases/{baseId}/tables/{tableId} |
| Fields |
field:list |
GET /meta/bases/{baseId}/tables/{tableId} — the fields array |
|
field:create |
POST /meta/bases/{baseId}/tables/{tableId}/fields |
|
field:get / field:update / field:delete |
GET / PATCH / DELETE /meta/bases/{baseId}/fields/{fieldId} |
|
(none) add / remove select choices |
POST / DELETE /meta/bases/{baseId}/fields/{fieldId}/options |
| Views |
view:list / view:create |
GET / POST /meta/bases/{baseId}/tables/{tableId}/views (type in the body: {"title":"…","type":"grid"}) |
|
view:get / view:update / view:delete |
GET / PATCH / DELETE /meta/bases/{baseId}/views/{viewId} |
|
(none) show / hide / order fields |
PATCH …/views/{viewId} with the complete ordered fields list |
| Filters |
filter:list / filter:create |
GET / POST /meta/bases/{baseId}/views/{viewId}/filters (PUT replaces the set) |
|
(update / delete) |
PATCH / DELETE /meta/bases/{baseId}/filters/{filterId} |
| Sorts |
sort:list / sort:create |
GET / POST /meta/bases/{baseId}/views/{viewId}/sorts |
|
(update / delete) |
PATCH / DELETE /meta/bases/{baseId}/sorts/{sortId} |
| Hooks |
(none) |
GET / POST /meta/bases/{baseId}/tables/{tableId}/hooks; GET / PATCH / DELETE /meta/bases/{baseId}/hooks/{hookId} |
| Scripts |
script:list / script:create |
GET / POST /meta/bases/{baseId}/scripts |
| Teams |
team:list / team:create |
GET / POST /meta/workspaces/{workspaceId}/teams |
| Tokens |
token:list / token:create / token:delete |
GET / POST /meta/tokens, DELETE /meta/tokens/{tokenId} |
| Links |
link:list / link:add / link:remove |
GET / POST / DELETE /data/{baseId}/{tableId}/links/{linkFieldId}/{recordId} |
| Attachments |
attachment:upload |
POST /data/{baseId}/{modelId}/records/{recordId}/fields/{fieldId}/upload |
| Public view links |
(none) |
not in the REST spec — MCP shareView on Cloud / licensed, or the UI |
Schema Quick Reference (curl)
# Bases
nocodb_api GET /meta/workspaces/$WORKSPACE_ID/bases
nocodb_api POST /meta/workspaces/$WORKSPACE_ID/bases '{"title":"New Base"}'
nocodb_api GET /meta/bases/$BASE_ID
nocodb_api PATCH /meta/bases/$BASE_ID '{"title":"Renamed"}'
# Tables
nocodb_api GET /meta/bases/$BASE_ID/tables
nocodb_api POST /meta/bases/$BASE_ID/tables '{"title":"Customers"}'
nocodb_api GET /meta/bases/$BASE_ID/tables/$TABLE_ID
nocodb_api PATCH /meta/bases/$BASE_ID/tables/$TABLE_ID '{"title":"Renamed"}'
nocodb_api DELETE /meta/bases/$BASE_ID/tables/$TABLE_ID
# Fields
nocodb_api POST /meta/bases/$BASE_ID/tables/$TABLE_ID/fields '{"title":"Phone","type":"PhoneNumber"}'
nocodb_api PATCH /meta/bases/$BASE_ID/fields/$FIELD_ID '{"title":"Mobile"}'
nocodb_api DELETE /meta/bases/$BASE_ID/fields/$FIELD_ID
# Views (cloud Enterprise / licensed self-hosted)
nocodb_api GET /meta/bases/$BASE_ID/tables/$TABLE_ID/views
nocodb_api POST /meta/bases/$BASE_ID/tables/$TABLE_ID/views '{"title":"All","type":"grid"}'
nocodb_api POST /meta/bases/$BASE_ID/tables/$TABLE_ID/views '{"title":"Pipeline","type":"kanban","options":{"stack_by":{"field_id":"<singleSelectFieldId>"}}}'
nocodb_api PATCH /meta/bases/$BASE_ID/views/$VIEW_ID '{"title":"Renamed"}'
nocodb_api DELETE /meta/bases/$BASE_ID/views/$VIEW_ID
# Sorts & Filters (per view)
nocodb_api POST /meta/bases/$BASE_ID/views/$VIEW_ID/sorts '{"field_id":"<fieldId>","direction":"desc"}'
nocodb_api POST /meta/bases/$BASE_ID/views/$VIEW_ID/filters '{"field_id":"<fieldId>","operator":"eq","value":"Active"}'
# Webhooks
nocodb_api GET /meta/bases/$BASE_ID/tables/$TABLE_ID/hooks
nocodb_api POST /meta/bases/$BASE_ID/tables/$TABLE_ID/hooks '<HookV3Create JSON>'
nocodb_api PATCH /meta/bases/$BASE_ID/hooks/$HOOK_ID '{"active":false}'
nocodb_api DELETE /meta/bases/$BASE_ID/hooks/$HOOK_ID
See Reference Files
references/base-table-field.md — bases, tables, fields, select options, field types
references/view-filter-sort.md — views, filters, sorts, field lists per view
references/relations-links.md — link / lookup / rollup setup
Filter Syntax in Record Queries
The where grammar (field,operator,value) for the Data API and for MCP queryRecords is documented in nocodb-ops/skills/cli-reference/references/filter-syntax.md. View filters (this plugin) use structured {field_id, operator, value} objects instead.
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 api-reference → Plan Availability |
Could not resolve name "X" (script) |
Name not unique or wrong scope |
Pass IDs instead of names; set NOCODB_VERBOSE=1 |
Field type X not supported |
Type spelling |
Check field-types.md for the canonical names — CamelCase, e.g. LinkToAnotherRecord, not link_to_another_record |
When to Use What
| Situation |
Use |
| Cloud / licensed, interactive work in Claude |
MCP listTools → callTool |
| One-off table or field tweak from a shell |
nocodb.sh (names resolve for you) or curl |
| Scripted multi-step migration |
curl / the nocodb_api wrapper with IDs |
| Community Edition |
curl — the MCP server has record tools only |
| Webhook config |
curl (the script has no hook commands) or MCP createHook |
1---2name: cli-reference-53description: |4 Command-line access to NocoDB for schema work — curl recipes on Meta API v3 by resource, 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"6 - "NocoDB command line schema commands"7 - "how do I create a table with curl"8 - "nocodb.sh commands"9 - "NocoDB agent-skills CLI"10metadata:11 source: https://skillmd.com/skills/agents-store/cli-reference-512---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. 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 Meta API v3, and each is mapped to the script command that does the same job.1718Prefer the MCP schema tools on Cloud / licensed self-hosted (see **mcp-patterns**); use these recipes on Community Edition, in scripts, and as the fallback.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" table:list <baseId>` 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.29- It has no commands for hooks, select-choice options or view field lists — use the recipes below for those.3031## Setup for the curl Recipes3233```bash34export NOCODB_URL="https://your-instance.example.com" # required for self-hosted35export NOCODB_TOKEN="your-api-token" # NocoDB → Team & Settings → API Tokens → Add New Token36```3738A one-line wrapper keeps repeated calls short (paths are under `/api/v3`):3940```bash41nocodb_api() { # nocodb_api METHOD /meta/... ['{"json":"body"}']42 local m="$1" p="$2" b="${3:-}"43 if [ -n "$b" ]; then44 curl -sS -X "$m" -H "xc-token: ${NOCODB_TOKEN}" -H "Content-Type: application/json" -d "$b" "${NOCODB_URL}/api/v3${p}"45 else46 curl -sS -X "$m" -H "xc-token: ${NOCODB_TOKEN}" -H "Content-Type: application/json" "${NOCODB_URL}/api/v3${p}"47 fi48}49# nocodb_api GET /meta/bases/$BASE_ID/tables50```5152## Plan Requirements5354- **All plans:** Base, Table, Field, Filter, Sort, Record, Link, Attachment APIs.55- **Cloud Business and above / licensed self-hosted:** Hooks, Comments, Workflows, Documents, Base collaboration.56- **Cloud Enterprise / licensed self-hosted:** Views, Dashboards, Scripts.57- **Workspace** list/create is open; per-workspace changes, Teams and Tokens depend on the plan (see **api-reference** → Plan Availability).5859## ID Prefixes6061| Prefix | Meaning |62|--------|---------|63| `w...` | Workspace |64| `p...` | Base (project) |65| `m...` | Table (model) |66| `c...` | Field (column) |67| `vw...` | View |6869Hierarchy: `WORKSPACE → BASE → TABLE → VIEW/FIELD → RECORD`.7071## Command Map — `nocodb.sh` → REST (Meta API v3)7273Paths are relative to `${NOCODB_URL}/api/v3`.7475| Resource | Script command | REST call |76|----------|----------------|-----------|77| Workspaces | `workspace:list` / `workspace:get` | `GET /meta/workspaces`, `GET /meta/workspaces/{workspaceId}` |78| Bases | `base:list <ws>` | `GET /meta/workspaces/{workspaceId}/bases` |79| | `base:get` / `base:update` / `base:delete` | `GET` / `PATCH` / `DELETE /meta/bases/{baseId}` |80| | `base:create <ws> '{…}'` | `POST /meta/workspaces/{workspaceId}/bases` |81| Tables | `table:list` / `table:create` | `GET` / `POST /meta/bases/{baseId}/tables` |82| | `table:get` / `table:update` / `table:delete` | `GET` / `PATCH` / `DELETE /meta/bases/{baseId}/tables/{tableId}` |83| Fields | `field:list` | `GET /meta/bases/{baseId}/tables/{tableId}` — the `fields` array |84| | `field:create` | `POST /meta/bases/{baseId}/tables/{tableId}/fields` |85| | `field:get` / `field:update` / `field:delete` | `GET` / `PATCH` / `DELETE /meta/bases/{baseId}/fields/{fieldId}` |86| | *(none)* add / remove select choices | `POST` / `DELETE /meta/bases/{baseId}/fields/{fieldId}/options` |87| Views | `view:list` / `view:create` | `GET` / `POST /meta/bases/{baseId}/tables/{tableId}/views` (type in the body: `{"title":"…","type":"grid"}`) |88| | `view:get` / `view:update` / `view:delete` | `GET` / `PATCH` / `DELETE /meta/bases/{baseId}/views/{viewId}` |89| | *(none)* show / hide / order fields | `PATCH …/views/{viewId}` with the complete ordered `fields` list |90| Filters | `filter:list` / `filter:create` | `GET` / `POST /meta/bases/{baseId}/views/{viewId}/filters` (`PUT` replaces the set) |91| | *(update / delete)* | `PATCH` / `DELETE /meta/bases/{baseId}/filters/{filterId}` |92| Sorts | `sort:list` / `sort:create` | `GET` / `POST /meta/bases/{baseId}/views/{viewId}/sorts` |93| | *(update / delete)* | `PATCH` / `DELETE /meta/bases/{baseId}/sorts/{sortId}` |94| Hooks | *(none)* | `GET` / `POST /meta/bases/{baseId}/tables/{tableId}/hooks`; `GET` / `PATCH` / `DELETE /meta/bases/{baseId}/hooks/{hookId}` |95| Scripts | `script:list` / `script:create` | `GET` / `POST /meta/bases/{baseId}/scripts` |96| Teams | `team:list` / `team:create` | `GET` / `POST /meta/workspaces/{workspaceId}/teams` |97| Tokens | `token:list` / `token:create` / `token:delete` | `GET` / `POST /meta/tokens`, `DELETE /meta/tokens/{tokenId}` |98| Links | `link:list` / `link:add` / `link:remove` | `GET` / `POST` / `DELETE /data/{baseId}/{tableId}/links/{linkFieldId}/{recordId}` |99| Attachments | `attachment:upload` | `POST /data/{baseId}/{modelId}/records/{recordId}/fields/{fieldId}/upload` |100| Public view links | *(none)* | not in the REST spec — MCP `shareView` on Cloud / licensed, or the UI |101102## Schema Quick Reference (curl)103104```bash105# Bases106nocodb_api GET /meta/workspaces/$WORKSPACE_ID/bases107nocodb_api POST /meta/workspaces/$WORKSPACE_ID/bases '{"title":"New Base"}'108nocodb_api GET /meta/bases/$BASE_ID109nocodb_api PATCH /meta/bases/$BASE_ID '{"title":"Renamed"}'110111# Tables112nocodb_api GET /meta/bases/$BASE_ID/tables113nocodb_api POST /meta/bases/$BASE_ID/tables '{"title":"Customers"}'114nocodb_api GET /meta/bases/$BASE_ID/tables/$TABLE_ID115nocodb_api PATCH /meta/bases/$BASE_ID/tables/$TABLE_ID '{"title":"Renamed"}'116nocodb_api DELETE /meta/bases/$BASE_ID/tables/$TABLE_ID117118# Fields119nocodb_api POST /meta/bases/$BASE_ID/tables/$TABLE_ID/fields '{"title":"Phone","type":"PhoneNumber"}'120nocodb_api PATCH /meta/bases/$BASE_ID/fields/$FIELD_ID '{"title":"Mobile"}'121nocodb_api DELETE /meta/bases/$BASE_ID/fields/$FIELD_ID122123# Views (cloud Enterprise / licensed self-hosted)124nocodb_api GET /meta/bases/$BASE_ID/tables/$TABLE_ID/views125nocodb_api POST /meta/bases/$BASE_ID/tables/$TABLE_ID/views '{"title":"All","type":"grid"}'126nocodb_api POST /meta/bases/$BASE_ID/tables/$TABLE_ID/views '{"title":"Pipeline","type":"kanban","options":{"stack_by":{"field_id":"<singleSelectFieldId>"}}}'127nocodb_api PATCH /meta/bases/$BASE_ID/views/$VIEW_ID '{"title":"Renamed"}'128nocodb_api DELETE /meta/bases/$BASE_ID/views/$VIEW_ID129130# Sorts & Filters (per view)131nocodb_api POST /meta/bases/$BASE_ID/views/$VIEW_ID/sorts '{"field_id":"<fieldId>","direction":"desc"}'132nocodb_api POST /meta/bases/$BASE_ID/views/$VIEW_ID/filters '{"field_id":"<fieldId>","operator":"eq","value":"Active"}'133134# Webhooks135nocodb_api GET /meta/bases/$BASE_ID/tables/$TABLE_ID/hooks136nocodb_api POST /meta/bases/$BASE_ID/tables/$TABLE_ID/hooks '<HookV3Create JSON>'137nocodb_api PATCH /meta/bases/$BASE_ID/hooks/$HOOK_ID '{"active":false}'138nocodb_api DELETE /meta/bases/$BASE_ID/hooks/$HOOK_ID139```140141## See Reference Files142143- **`references/base-table-field.md`** — bases, tables, fields, select options, field types144- **`references/view-filter-sort.md`** — views, filters, sorts, field lists per view145- **`references/relations-links.md`** — link / lookup / rollup setup146147## Filter Syntax in Record Queries148149The `where` grammar `(field,operator,value)` for the Data API and for MCP `queryRecords` is documented in `nocodb-ops/skills/cli-reference/references/filter-syntax.md`. View filters (this plugin) use structured `{field_id, operator, value}` objects instead.150151## Common Pitfalls152153| Symptom | Cause | Fix |154|---------|-------|-----|155| `nc` hangs or prints a netcat error | `nc` is netcat, not a NocoDB tool | Use `curl` (this skill) or `nocodb.sh` |156| `NOCODB_TOKEN required` / empty `xc-token` header | Token env-var missing | `export NOCODB_TOKEN=...` |157| 401 Unauthorized | Token wrong or revoked | Regenerate in NocoDB → Team & Settings → API Tokens |158| 403 Forbidden | Token lacks permission for that base, or the plan lacks the API | Share the base with the token's user; check **api-reference** → Plan Availability |159| `Could not resolve name "X"` (script) | Name not unique or wrong scope | Pass IDs instead of names; set `NOCODB_VERBOSE=1` |160| `Field type X not supported` | Type spelling | Check `field-types.md` for the canonical names — CamelCase, e.g. `LinkToAnotherRecord`, not `link_to_another_record` |161162## When to Use What163164| Situation | Use |165|-----------|-----|166| Cloud / licensed, interactive work in Claude | MCP `listTools` → `callTool` |167| One-off table or field tweak from a shell | `nocodb.sh` (names resolve for you) or `curl` |168| Scripted multi-step migration | `curl` / the `nocodb_api` wrapper with IDs |169| Community Edition | `curl` — the MCP server has record tools only |170| Webhook config | `curl` (the script has no hook commands) or MCP `createHook` |