Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/stagware/nocodb-cli

Open-source CLI and TypeScript SDK for NocoDB
https://github.com/stagware/nocodb-cli

cli nocodb

Last synced: 5 months ago
JSON representation

Open-source CLI and TypeScript SDK for NocoDB

Awesome Lists containing this project

README 

          
# nocodb-cli



A Node.js + TypeScript SDK and CLI for NocoDB v2 APIs.



## Setup



```sh

npm install

```



Build packages before running the CLI locally:



```sh

npm run build

```



## Workspaces (Multi-Account Support)



Workspaces allow you to manage multiple NocoDB instances or bases with distinct URLs, tokens, and default Base IDs.



```sh

# Add a workspace

nocodb workspace add work https://noco.company.com  --base 

nocodb workspace add personal https://noco.me.com 



# Switch context

nocodb workspace use work

nocodb workspace list     # show all workspaces, active marked with *

nocodb workspace show     # show current workspace config

```



## Cloud Workspaces (☁ NocoDB Cloud Only)



Manage workspaces on NocoDB Cloud (`app.nocodb.com`). These commands are nested under `workspace cloud` to avoid collision with local workspace management above.



```sh

# List / get

nocodb workspace cloud list

nocodb workspace cloud get 



# Create / update / delete

nocodb workspace cloud create -d '{"title":"My Workspace"}'

nocodb workspace cloud update  -d '{"title":"Renamed"}'

nocodb workspace cloud delete 



# Workspace users

nocodb workspace cloud users 

nocodb workspace cloud user-get  

nocodb workspace cloud invite  -d '{"email":"bob@test.com","roles":"viewer"}'

nocodb workspace cloud user-update   -d '{"roles":"editor"}'

nocodb workspace cloud user-remove  



# Workspace bases

nocodb workspace cloud bases 

nocodb workspace cloud create-base  -d '{"title":"New Base"}'

```



> **Note:** These endpoints only work when connected to NocoDB Cloud. Self-hosted NocoDB does not have workspace APIs.



## Aliases (Namespaced IDs)



Aliases allow you to use friendly names instead of UUIDs. They are namespaced by workspace.



```sh

# Set aliases in the active workspace

nocodb alias set tasks 

nocodb alias set prayer 



# Usage (Current Workspace)

nocodb rows list tasks



# Usage (Cross-Workspace / Explicit)

nocodb rows list work.tasks

nocodb rows list personal.tasks



# Base Resolution

# If a workspace name is used where a Base ID is expected, it resolves to that workspace's default base.

nocodb tables list personal



# Management

nocodb alias list         # list aliases for active workspace

nocodb alias list personal # list aliases for specific workspace

nocodb alias delete tasks

nocodb alias clear        # clear all aliases for active workspace

```



## Environment Variables



For CI/CD pipelines or ephemeral environments, you can configure the CLI entirely via environment variables. These override workspace config but are overridden by CLI flags.



| Variable | Description |

|----------|-------------|

| `NOCO_BASE_URL` | NocoDB instance URL (e.g., `https://app.nocodb.com`) |

| `NOCO_TOKEN` | API token (sets the `xc-token` header) |

| `NOCO_BASE_ID` | Default base ID |



```sh

# Bash

export NOCO_BASE_URL=https://app.nocodb.com

export NOCO_TOKEN=your-api-token

export NOCO_BASE_ID=p_abc123

nocodb bases list



# PowerShell

$env:NOCO_BASE_URL="https://app.nocodb.com"

$env:NOCO_TOKEN="your-api-token"

$env:NOCO_BASE_ID="p_abc123"

nocodb bases list

```



If no workspace is configured, the CLI creates an ephemeral workspace from env vars (requires at minimum `NOCO_BASE_URL`).



## Configure (Legacy/Global)



These settings act as fallbacks if no workspace is active.



```sh

nocodb config set baseUrl http://localhost:8080

nocodb config set baseId 

nocodb header set xc-token 

```



## Auth Check



Quickly verify your authentication and see the current user:



```sh

nocodb me

nocodb me --pretty

nocodb me --select email,display_name

```



## Bases



```sh

nocodb bases list

nocodb bases get 

nocodb bases info 

nocodb bases create --data '{"title":"My Base"}'

nocodb bases update  --data '{"title":"New Name"}'

nocodb bases delete 

```



## Tables



```sh

nocodb tables list 

nocodb tables get 

nocodb tables create  --data '{"table_name":"MyTable"}'

nocodb tables update  --data '{"table_name":"NewName"}'

nocodb tables delete 

```



## Views



```sh

nocodb views list 

nocodb views get  

nocodb views create  --data '{"title":"Grid"}'

nocodb views create  --type form --data '{"title":"My Form"}'

nocodb views update  --data '{"title":"New View"}'

nocodb views delete 

```



Supported `--type` values: `grid` (default), `form`, `gallery`, `kanban`.



### View Config



Get or update view-type-specific configuration (form settings, gallery cover image, kanban grouping, grid row height):



```sh

nocodb views config get  --view-type form --pretty

nocodb views config update  --view-type form -d '{"heading":"My Form"}'

nocodb views config get  --view-type gallery

nocodb views config update  --view-type grid -d '{"row_height":2}'

```



Supported `--view-type` values: `form`, `gallery`, `kanban` (for get), `grid`, `form`, `gallery`, `kanban` (for update).



### View Columns



List field visibility and order settings for a view:



```sh

nocodb views columns list  --pretty

```



## Comments



Manage row comments:



```sh

nocodb comments list --table-id  --row-id 

nocodb comments create -d '{"fk_model_id":"","row_id":"1","comment":"Looks good!"}'

nocodb comments update  -d '{"comment":"Updated text"}'

nocodb comments delete 

```



## Shared Views



Manage public view links:



```sh

nocodb shared-views list 

nocodb shared-views create 

nocodb shared-views create  -d '{"password":"secret"}'

nocodb shared-views update  -d '{"password":"new-secret"}'

nocodb shared-views delete 

```



## Shared Base



Manage public base sharing:



```sh

nocodb shared-base get 

nocodb shared-base create 

nocodb shared-base create  -d '{"roles":"viewer","password":"secret"}'

nocodb shared-base update  -d '{"roles":"editor"}'

nocodb shared-base delete 

```



## Filters



```sh

nocodb filters list 

nocodb filters get 

nocodb filters create  --data '{"field":"Name","op":"eq","value":"A"}'

nocodb filters update  --data '{"value":"B"}'

nocodb filters delete 

```



## Sorts



```sh

nocodb sorts list 

nocodb sorts get 

nocodb sorts create  --data '{"field":"Name","direction":"asc"}'

nocodb sorts update  --data '{"direction":"desc"}'

nocodb sorts delete 

```



## Columns



```sh

nocodb columns list 

nocodb columns get 

nocodb columns create  --data '{"title":"Status","column_name":"Status","uidt":"SingleSelect","colOptions":{"options":[{"title":"Open"},{"title":"Done"}]}}'

nocodb columns update  --data '{"title":"State"}'

nocodb columns delete 

```



## Schema Introspection



Discover table structures including columns, primary keys, display values, and relations:



```sh

nocodb schema introspect 

nocodb schema introspect  --pretty

nocodb schema introspect  --format table

```



The output includes:

- Table `id`, `title`, `table_name`

- `primaryKey` and `displayValue` column names

- Full column list with `id`, `title`, `column_name`, `uidt`, `primaryKey`, `required`, `unique`

- `relation` object on link columns (`type` and `targetTableId`)



## Settings



Timeout and retry behavior can be configured via `~/.nocodb-cli/settings.json`. Override the directory with `NOCODB_SETTINGS_DIR` env var.



```sh

nocodb settings show           # print current effective settings

nocodb settings path           # print the settings file path

nocodb settings set timeoutMs 5000

nocodb settings set retryCount 5

nocodb settings set retryDelay 500

nocodb settings set retryStatusCodes '[429,500,502,503]'

nocodb settings reset          # restore defaults

```



Default values:



| Key | Default | Description |

|-----|---------|-------------|

| `timeoutMs` | `30000` | Request timeout in milliseconds |

| `retryCount` | `3` | Number of retries (0 to disable) |

| `retryDelay` | `300` | Delay between retries in milliseconds |

| `retryStatusCodes` | `[408,409,425,429,500,502,503,504]` | HTTP status codes that trigger a retry |



CLI flags `--timeout ` and `--retries ` override settings for a single invocation:



```sh

nocodb --timeout 5000 bases list

nocodb --retries 0 bases list     # disable retries for this call

```



Use `--verbose` on any command to see request timing and retry information:



```sh

nocodb --verbose rows list 

```



## Output formats



All commands support `--pretty` for indented JSON, `--format ` for alternative output, and `--select` for field filtering:



```sh

nocodb bases list --pretty              # indented JSON

nocodb bases list --format csv          # CSV output

nocodb bases list --format table        # ASCII table

nocodb rows list  --format table

```



### Field selection



Use `--select` to pick specific fields from the output — useful for scripting and piping:



```sh

nocodb bases list --select id,title

nocodb rows list  --select Name,Status --format csv

nocodb me --select email,display_name

```



`--select` works with all output formats (JSON, CSV, table) and handles both single objects and list responses.



## Links



Manage linked records between tables:



```sh

nocodb links list   

nocodb links create    --data '[{"Id":100},{"Id":200}]'

nocodb links delete    --data '[{"Id":100}]'

```



## Storage



```sh

nocodb storage upload ./photo.png

nocodb storage upload ./doc.pdf --pretty

```



## Sources (Data Sources)



Manage data sources (database connections) within a base:



```sh

nocodb sources list 

nocodb sources get  

nocodb sources create  --data '{"alias":"my-pg","type":"pg","config":{...}}'

nocodb sources update   --data '{"alias":"renamed"}'

nocodb sources delete  

```



## Tokens (Base-Scoped)



API tokens are scoped to a base (v2 API):



```sh

nocodb tokens list 

nocodb tokens create  -d '{"description":"CI/CD token"}'

nocodb tokens delete  

```



## Raw requests



Use this to call any endpoint directly.



```sh

nocodb request GET /api/v2/meta/bases --pretty

```



## Swagger discovery (base-scoped)



```sh

nocodb meta swagger  --pretty

nocodb meta swagger  --out ./swagger.json

nocodb meta endpoints 

nocodb meta endpoints  --tag Tables

nocodb meta cache clear 

nocodb meta cache clear --all

```



## Dynamic API commands



```sh

nocodb meta endpoints  --pretty

nocodb --base  api   --pretty

nocodb --base  api   --data '{"key":"value"}'

```



## Rows (CRUD + upsert helpers)



```sh

nocodb rows list 

nocodb rows list  --all              # auto-paginate to fetch every row

nocodb rows list  --all -q where='(Status,eq,Active)'

nocodb rows read  

nocodb rows create  --data '{"Title":"Example"}'

nocodb rows update  --data '{"Id":1,"Title":"Updated"}'

nocodb rows delete  --data '{"Id":1}'

nocodb rows upsert  --match Email=alice@example.com --data '{"Email":"alice@example.com","Title":"Alice"}'

nocodb rows upsert  --match Email=alice@example.com --data '{"Title":"Alice"}' --update-only

nocodb rows upsert  --match Email=alice@example.com --data '{"Email":"alice@example.com","Title":"Alice"}' --create-only

nocodb rows bulk-create  --data '[{"Title":"A"},{"Title":"B"}]'

nocodb rows bulk-update  --data '[{"Id":1,"Title":"A1"},{"Id":2,"Title":"B1"}]'

nocodb rows bulk-upsert  --match Email --data '[{"Email":"alice@example.com","Title":"Alice"},{"Email":"bob@example.com","Title":"Bob"}]'

nocodb rows bulk-delete  --data '[{"Id":1},{"Id":2}]'

```



## Data Import / Export



Export all rows from a table to a file or stdout:



```sh

nocodb data export                           # JSON to stdout

nocodb data export  --format csv             # CSV to stdout

nocodb data export  --out ./rows.json        # JSON file

nocodb data export  --out ./rows.csv         # CSV file (inferred from extension)

nocodb data export  -q where='(Status,eq,Active)'  # with filters

```



Import rows from a CSV or JSON file into a table (requires `--base` for schema validation):



```sh

nocodb --base  data import  ./rows.json              # JSON array

nocodb --base  data import  ./rows.csv               # CSV (inferred from extension)

nocodb --base  data import  ./rows.csv --format csv  # explicit format

```



Upsert mode — match on a field to update existing rows and create new ones:



```sh

nocodb --base  data import  ./rows.csv --match Email

nocodb --base  data import  ./rows.json --match Email --create-only

nocodb --base  data import  ./rows.json --match Email --update-only

```



Export auto-paginates (fetches all rows). Import validates rows against the table's swagger schema and batches in groups of 1000.



## E2E test script



Run a repeatable end-to-end flow that creates tables, exercises CRUD, refreshes swagger, and attempts link tests.



```sh

set NOCO_BASE_URL=https://noco.stagware.org

set NOCO_BASE_ID=

set NOCO_TOKEN=

node scripts/e2e-cli.mjs

```



PowerShell:



```sh

$env:NOCO_BASE_URL="https://noco.stagware.org"

$env:NOCO_BASE_ID=""

$env:NOCO_TOKEN=""

node scripts/e2e-cli.mjs

```



Set `NOCO_KEEP=1` to keep the generated tables instead of deleting them.

You can also run `npm run e2e` from the repo root.



The script attempts:

- Table creation with broad column type coverage (falls back if unsupported types are rejected)

- CRUD on multiple tables

- Link/lookup/rollup/formula column creation (best-effort, logs if unsupported)

- Attachment upload and row update

- Comments CRUD on a row

- Shared views create/list/delete on a view

- Shared base create/get/delete on the test base

- View config get and view columns list

- Cloud workspace list/get/users/bases (gracefully skipped on self-hosted instances)

- Writes a JSON summary report to `scripts/e2e-report.json`



## Error messages



The CLI provides contextual error messages for HTTP failures. When the NocoDB server returns an error, you'll see the status code and any response body the server sent back:



```

HTTP 401 — Unauthorized

```



```

HTTP 400 — Bad Request

{

  "msg": "Field 'Title' is required"

}

```



Non-HTTP errors (invalid JSON input, missing config, validation failures) are printed as-is.



## Notes



- The SDK is in `packages/sdk` and the CLI is in `packages/cli`.

- The SDK uses fully typed generics (e.g., `Promise>`) for all metadata operations.

- Meta swagger is cached under your CLI config directory for faster reuse.

- Use `nocodb config set baseId ` to avoid repeating `--base` for dynamic commands.

- If an endpoint differs in your NocoDB deployment, use `nocodb request` or `nocodb meta endpoints`.