From 89762e570294300ae15ad0ba0f67de5608ef394d Mon Sep 17 00:00:00 2001 From: ayal Date: Tue, 17 Feb 2026 15:12:31 +0200 Subject: [PATCH] feat: add entity records CRUD skill documentation Add reference docs for the new `base44 entities records` commands (list, get, create, update, delete) and update the CLI skill to include them in the Entity Management table and common workflows. Co-authored-by: Cursor --- skills/base44-cli/SKILL.md | 19 +++ .../base44-cli/references/entities-records.md | 158 ++++++++++++++++++ 2 files changed, 177 insertions(+) create mode 100644 skills/base44-cli/references/entities-records.md diff --git a/skills/base44-cli/SKILL.md b/skills/base44-cli/SKILL.md index f89f174..7859bcd 100644 --- a/skills/base44-cli/SKILL.md +++ b/skills/base44-cli/SKILL.md @@ -212,6 +212,7 @@ npx base44 | ---------------------- | ------------------------------------------- | --------------------------------------------------- | | Create Entities | Define entities in `base44/entities` folder | [entities-create.md](references/entities-create.md) | | `base44 entities push` | Push local entities to Base44 | [entities-push.md](references/entities-push.md) | +| `base44 entities records *` | CRUD operations on entity records (data) | [entities-records.md](references/entities-records.md) | | RLS Patterns | Row-level security examples and operators | [rls-examples.md](references/rls-examples.md) ⚠️ **READ FOR RLS** | #### Entity Schema (Quick Reference) @@ -466,6 +467,24 @@ npx base44 connectors push npx base44 site deploy -y ``` +### Managing Entity Records (Data) +```bash +# List records +npx base44 entities records list Task + +# Get a specific record +npx base44 entities records get Task + +# Create a record +npx base44 entities records create Task --data '{"title": "My task", "status": "todo"}' + +# Update a record +npx base44 entities records update Task --data '{"status": "done"}' + +# Delete a record +npx base44 entities records delete Task -y +``` + ### Opening the Dashboard ```bash # Open app dashboard in browser diff --git a/skills/base44-cli/references/entities-records.md b/skills/base44-cli/references/entities-records.md new file mode 100644 index 0000000..526f96d --- /dev/null +++ b/skills/base44-cli/references/entities-records.md @@ -0,0 +1,158 @@ +# base44 entities records + +Manage entity records (data) via the CLI. Supports listing, getting, creating, updating, and deleting individual records. + +> **Note:** These commands operate on record **data**, not entity schemas. To manage entity schemas, use `base44 entities push`. + +## Commands + +### List Records + +```bash +npx base44 entities records list [options] +``` + +**Options:** + +| Option | Description | Default | +|--------|-------------|---------| +| `-f, --filter ` | JSON query filter | - | +| `-s, --sort ` | Sort field (prefix with `-` for descending) | - | +| `-l, --limit ` | Max records to return | `50` | +| `--skip ` | Number of records to skip | - | +| `--fields ` | Comma-separated fields to return | - | + +**Example:** + +```bash +# List all Tasks +npx base44 entities records list Task + +# List with filter and sort +npx base44 entities records list Task --filter '{"status": "todo"}' --sort "-created_date" --limit 10 + +# List specific fields only +npx base44 entities records list Task --fields "title,status" +``` + +**Output:** JSON array of records printed to stdout. + +### Get Record + +```bash +npx base44 entities records get +``` + +**Example:** + +```bash +npx base44 entities records get Task 64f1a2b3c4d5e6f7a8b9c0d1 +``` + +**Output:** JSON object of the record printed to stdout. + +### Create Record + +```bash +npx base44 entities records create [options] +``` + +**Options:** + +| Option | Description | +|--------|-------------| +| `-d, --data ` | JSON object with record data | +| `--file ` | Read record data from a JSON/JSONC file | + +One of `--data` or `--file` is required. + +**Example:** + +```bash +# Inline JSON +npx base44 entities records create Task --data '{"title": "Buy groceries", "status": "todo", "priority": 3}' + +# From file +npx base44 entities records create Task --file new-task.json +``` + +**Output:** JSON object of the created record (includes generated `id`, `created_date`, etc.). + +### Update Record + +```bash +npx base44 entities records update [options] +``` + +**Options:** + +| Option | Description | +|--------|-------------| +| `-d, --data ` | JSON object with fields to update | +| `--file ` | Read update data from a JSON/JSONC file | + +One of `--data` or `--file` is required. Only the specified fields are updated (partial update). + +**Example:** + +```bash +# Update status and priority +npx base44 entities records update Task 64f1a2b3c4d5e6f7a8b9c0d1 --data '{"status": "done", "priority": 1}' +``` + +**Output:** JSON object of the updated record. + +### Delete Record + +```bash +npx base44 entities records delete [options] +``` + +**Options:** + +| Option | Description | +|--------|-------------| +| `-y, --yes` | Skip confirmation prompt | + +**Example:** + +```bash +# With confirmation prompt +npx base44 entities records delete Task 64f1a2b3c4d5e6f7a8b9c0d1 + +# Skip confirmation +npx base44 entities records delete Task 64f1a2b3c4d5e6f7a8b9c0d1 -y +``` + +## Authentication + +**Required**: Yes. All record commands require authentication. If not authenticated, you'll be prompted to login first. + +## Prerequisites + +- Must be run from a Base44 project directory (has `base44/.app.jsonc`) +- The entity must already exist (pushed via `base44 entities push`) +- The app must be a Backend Platform app (created via CLI) + +## Entity Name Format + +Use the entity schema name in PascalCase as it appears in your entity definition file: + +- Entity file `base44/entities/task.jsonc` with `"name": "Task"` → use `Task` +- Entity file `base44/entities/team-member.jsonc` with `"name": "TeamMember"` → use `TeamMember` + +## Error Handling + +| Error | Cause | Solution | +|-------|-------|----------| +| Entity schema not found | Entity hasn't been pushed | Run `npx base44 entities push` first | +| Not authenticated | No valid session | Run `npx base44 login` | +| Invalid JSON in --data | Malformed JSON string | Check JSON syntax, use single quotes around the value | +| Record not found (404) | Record ID doesn't exist | Verify the record ID with `records list` | + +## Notes + +- The `User` entity cannot be managed through these commands. Use the Base44 dashboard for user management. +- All output is JSON, suitable for piping to `jq` or other tools. +- Delete performs a soft delete (records can be restored via the dashboard). +- Records are always accessed with admin/builder privileges (bypasses RLS).