When invoking a project-scoped blocks command, either use the resolved account's saved selection or pass --project <tenantId> for that one command without changing saved state. --project applies to CLI commands only, never SDK calls.

Blocks Data — Gateway Configuration

The Data schema/rules model of a Blocks project is configured entirely through the blocks CLI now — there is no supported reason to hand-roll fetch/curl calls against api.seliseblocks.com/data/v4 anymore. The CLI reads and writes local files under blocks/data/ and talks to the Data service for you.

Prerequisite: blocks init has been run (creates blocks/data/schemas/ and blocks/data/rules.json) and a project is selected (blocks use <tenantId>). If either is missing, or auth state is unknown, run the blocks-bootstrap skill first — it covers auth status probing, login, and project selection in detail; this skill assumes that's already done.

Check the data-source configuration first

Before touching schemas, confirm what database actually backs this project's Data Gateway:

blocks data config get --json

By default every Blocks project runs on Blocks-managed storage — most of the time this is the only data-source command you'll ever need, just to confirm it. Only reach for the mutating commands below if the user explicitly wants to point the gateway at their own external database — this is a rare, deliberate action, not a routine step:

blocks data config create --connection-string "<connection string>" --database-name "<name>" --dry-run --json
blocks data config create --connection-string "<connection string>" --database-name "<name>" --yes --json

blocks data config update --item-id <id> --connection-string "<new connection string>" --dry-run --json
blocks data config update --item-id <id> --connection-string "<new connection string>" --yes --json

data config update also takes --database-name, --collection-name-pattern, and --collection-name-editable (boolean) — use these to rename the target database or adjust how collection names are derived/whether they're editable, on an existing configuration (--item-id required either way). The update reads the current configuration and merges, so a connection-string-only change keeps isCollectionNameEditable and collectionNamePattern (the PUT would otherwise reset them to false/empty).

Treat --connection-string as a secret: never print it back unredacted, and don't log it outside the command's own --dry-run preview (which redacts it).

Probe first, ask second

Don't assume the local workspace matches the cloud project. Before editing anything, find out what's actually there:

blocks data schema list --json     # what schemas exist in the selected project (read-only)
blocks data schema pull --json     # sync them into blocks/data/schemas/*.json locally
blocks data rules pull --json      # sync data-access policies into blocks/data/rules.json

Pulling before editing avoids clobbering schema changes someone else made in the portal or another session.

Workflow: define or edit a schema

1. Pull current state (above), so local files reflect the project.
2. Edit the relevant JSON file(s) under blocks/data/schemas/ — add/rename fields, change types, add a new schema file. This is plain file editing; there's no file-oriented CLI subcommand for individual field edits (data schema push always sends the whole schema), you edit the JSON directly. (data schema fields exists as a raw API alternative that adds/updates fields on an existing schema without touching the local file — see "More granular Schema commands" below — but for the local-file workflow described here, just edit the JSON.)
3. Validate locally, no API call:

   blocks data validate --json

   Fix anything it flags before going further — this catches malformed schema/rules JSON before it reaches the network.
4. Dry-run the push to see exactly what would change (create vs. update, which schemas):

   blocks data schema push --dry-run --json

5. Get user approval, then push for real:

   blocks data schema push --yes --json

   This is mutating — it creates new schemas and updates existing ones in a single call. Never skip straight to --yes.

   Access for new schemas: a schema the push creates gets User access (only signed-in users can read/write it). --access public instead opens read, write, edit and delete to anonymous callers — only pass it when the user explicitly wants a public collection. Existing schemas keep whatever access they have. The output's newSchemaAccess says which level the created schemas got. For anything finer (Custom + policies), use security entries in rules.json (below).

6. Reload so it goes live. Schema/rule edits are staged until reload succeeds — the runtime gateway doesn't see them before this:

   blocks data reload --dry-run --json
   blocks data reload --yes --json

Shortcut — recommended default: validation, schema push, rules deploy, and reload are exactly what blocks data sync automates behind a single confirmation. Rules deployment comes from the pulled/edited blocks/data/rules.json; it is not a separately numbered step above.

blocks data sync --dry-run --json
blocks data sync --yes --json

Reach for data sync first unless the user specifically wants to inspect or run one step at a time — it's also the only way to guarantee the reload actually happens: nothing else in this CLI calls data reload automatically, so a bare schema push (or rules deploy) without a following data reload can leave changes staged but not live. Keep the manual step-by-step above for cases where you want to push schema without touching rules, or need to stop and inspect a dry-run at an individual step.

Workflow: data-access policies / schema security

Same shape as schemas, in blocks/data/rules.json:

blocks data rules pull --json                 # get current policies locally
# edit blocks/data/rules.json
blocks data validate --json                   # local-only check
blocks data rules deploy --dry-run --json     # preview
blocks data rules deploy --yes --json         # apply, after approval
blocks data reload --dry-run --json           # then reload so it's live
blocks data reload --yes --json

Shortcut: blocks data sync covers this too (validate → schema push → rules deploy → reload, one confirmation) — see the schema workflow above.

data rules deploy applies schema security and data-access policies together — there's no finer-grained CLI split between "field access level" and "policy rule"; both live in rules.json.

security entries set a schema's access level per operation. Target the schema by schemaName (resolved in the destination project, like policies), so a single data sync can create a schema and lock it down with no window in between:

{
  "security": [
    { "schemaName": "Expense", "operation": 0, "policyType": 0, "accessLevel": 3, "fieldNames": [] }
  ],
  "policies": []
}

• operation: 0 READ, 1 WRITE, 2 EDIT, 3 DELETE — one entry per operation (4 ALL is rejected: the service ignores it).
• policyType: 0 row-level (RLS), 1 column-level (CLS, needs fieldNames).
• accessLevel: 0 Inherited, 1 User, 2 Public, 3 Custom (Custom = governed by your policies).

rules deploy (and --dry-run, data validate, data sync) checks these entries before anything is sent, and fails without writing anything if a schemaName doesn't exist in the project yet.

For a single policy without touching the rest of rules.json, use the granular commands instead of a full pull/edit/deploy round-trip:

blocks data rules policy get <schemaName> --json          # read-only, all policies for one schema
blocks data rules policy delete <itemId> --dry-run --json
blocks data rules policy delete <itemId> --yes --json

There's no single-policy create/update command — those go through data rules deploy (it POSTs new policies and PUTs existing ones from rules.json).

Workflow: field-level validation rules

Data validations are a separate resource from schema field types — a schema field's type says what kind of value it holds, a validation rule says what values are acceptable. There's no file-oriented pull/push for these yet (no blocks/data/validations.json); work with them directly:

blocks data validation by-schema <schemaId> --json                        # everything for one schema
blocks data validation by-schema-field <schemaId> <fieldName> --json      # one field's rule
blocks data validation list --schema-id <schemaId> --json                 # paginated browse

Create or replace the rules on a field. One rule needs no JSON at all — use the scalar flags, and name the type rather than numbering it:

blocks data validation save --schema-id <schemaId> --field-name email \
  --type regex --value "^[^@]+@[^@]+\.[^@]+$" --error-message "Enter a valid email" \
  --dry-run --json
blocks data validation save --schema-id <schemaId> --field-name email \
  --type regex --value "^[^@]+@[^@]+\.[^@]+$" --error-message "Enter a valid email" \
  --yes --json

blocks data validation delete <validationId> --dry-run --json
blocks data validation delete <validationId> --yes --json

--type accepts notempty, regex, minlength, maxlength, lengthrange, equal, notequal, greaterthan, lessthan, greaterthanorequal, lessthanorequal, range (hyphens and case are ignored, and the raw enum numbers below still work). --value is the pattern, bound, or comparison value; --secondary-value is the upper bound and is required for lengthrange and range. --type notempty takes no --value. Rules are active unless you pass --is-active=false.

Several rules on one field still need a validations array via --body/--file. Prefer --file: inline JSON is shell-dependent, and in PowerShell the documented --body '{"a":1}' form loses its double quotes before the CLI sees it. The CLI now detects that and says so, but a file avoids the problem on every platform.

blocks data validation save --schema-id <schemaId> --field-name email --file rules.json --dry-run --json

--item-id is optional and rarely needed. Without it the command looks the field up and updates the rule record already there, so a second save on the same field is an update, not the "Validation already exists for this schema field" failure it used to be. The endpoint replaces the whole rule list, so the rules you pass are the rules the field ends up with — the dry-run reports target (create or update) and replacesExistingRules so you can see what a save would drop before approving it.

If a save reports gatewayReload.ok: false, the rules were stored and only the reload failed. Run blocks data reload --yes; do not re-run the save.

type inside a validations entry is the Data Gateway's ValidationType enum, zero-based in declaration order — 0 NotEmpty, 1 Regex, 2 MinLength, 3 MaxLength, 4 LengthRange, 5 Equal, 6 NotEqual, 7 GreaterThan, 8 LessThan, 9 GreaterThanOrEqual, 10 LessThanOrEqual, 11 Range. value is interpreted per type: a pattern for 1, a number for the length and comparison types, a range for 4/11.

The separate --schema-type flag on the data schema * commands is a different enum with no zero: 1 Entity, 2 Dto.

Prefer --type <name> over the numbers: the API publishes no named constants for this enum, so a number written from memory can store a different rule than the one asked for without any error.

Field types (including GeoJson)

A field's type is case-sensitive and must be exactly one of the scalars String, Int, Float, Boolean, DateTime, ID, GeoJson — or the name of another schema (a reference/Dto field). string or GeoJSON is not a scalar to the server; data validate, data schema push and data schema fields refuse a miscased scalar locally and name the correct spelling.

GeoJson holds an RFC 7946 geometry (Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection; coordinates are [longitude, latitude]), validated on write. On an Entity schema, a non-array GeoJson field gets a MongoDB 2dsphere index automatically when the field is saved, and loses it when the field is deleted or its type changes — you never create it yourself. Array GeoJson fields (isArray: true) are deliberately not indexed (MongoDB can't), so geo queries on them still work but scan. Querying geo fields (near/within/intersects) is covered by the blocks-data-gateway-crud skill.

{ "name": "location", "type": "GeoJson", "isArray": false }

Schema indexes

User-managed MongoDB indexes on an Entity schema's collection (single-field or compound, optionally unique, max 15 per schema):

blocks data schema indexes list <schemaId> --json                                   # indexes + read-only systemIndexes
blocks data schema indexes create --schema-id <id> --fields status,createdDate:desc --dry-run --json
blocks data schema indexes create --schema-id <id> --fields email --unique --yes --json
blocks data schema indexes delete <indexItemId> --dry-run --json

list returns indexes (yours: deletable, counted against the 15) and systemIndexes — the automatic 2dsphere index of each GeoJson field, with ids like system:location_2dsphere. System indexes cannot be deleted (the CLI refuses system:* ids) and GeoJson fields cannot be given a manual index (FIELD_NOT_INDEXABLE); both follow the field definition. --fields takes name[:asc|desc] (default asc), 1–10 distinct scalar fields.

More granular Schema commands

data schema list/pull/push cover the everyday file-based workflow above. For one-off lookups or advanced schema metadata, these go straight to the API without touching local files:

blocks data schema get <id> --json                    # single schema by id
blocks data schema get-by-name <schemaName> --json    # full field detail by collection name
blocks data schema aggregation --json                  # schemas + access-level summary (Public/User/Custom x Read/Write/Edit/Delete)
blocks data schema change-logs --json                  # unadapted change logs; data reload clears these
blocks data schema delete <id> --dry-run --json        # irreversible
blocks data schema delete <id> --yes --json

data schema info list/save/update and data schema fields are the two-step alternative to data schema push (metadata first, fields second) — prefer the file-based push workflow above for normal schema authoring; reach for these only if the user specifically wants to add fields to an existing schema without touching its full JSON file, or needs the raw /schemas/info metadata-only shape.

Every mutating command here supports --dry-run; run it, show the user, then --yes — the standard pattern across every blocks mutation.

What this skill does NOT cover (and why)

Two things the old, pre-CLI version of this skill used to handle no longer have any supported path — do not paper over the gap by inventing a command or improvising a raw API call:

• Mock/sample data cleanup. There is no blocks data mock* command, and the SDK's data.utilities.mockData() (in @seliseblocks/client) is read-only — it inventories mock data, it does not delete it. If a user asks to "wipe the demo data" or "clean up sample records," tell them plainly: this isn't exposed in the current CLI or SDK. Check whether the OS portal (https://os.seliseblocks.com) has a Data-section control for it; if not, there's no way to do this today short of deleting real records through generated GraphQL mutations one at a time, which is not the same thing and should not be presented as equivalent.
• Schema export/import between projects (e.g. cloning a dev project's data model into staging). No CLI command and no SDK method exist for this. If a user wants to copy a data model between projects, the honest answer is: not supported by current tooling. Check the OS portal for a manual option; otherwise the only fallback is manually recreating schemas in the target project's blocks/data/schemas/ and pushing them — which is a manual reconstruction, not a real export/import, and should be described as such.

The one thing that goes through the SDK, not the CLI

AI-generated regex for field validation is real, but it lives only in @seliseblocks/client, not in blocks. There's no CLI command for it because it's a single request/response utility call better suited to being scripted inline in app code than wrapped as a terminal command:

import { createBlocksClient } from "@seliseblocks/client";

const blocks = createBlocksClient({
  apiUrl: "https://api.seliseblocks.com",
  xBlocksKey: "<project-tenant-id>",
  accessToken: () => currentAccessToken
});

const suggestion = await blocks.data.utilities.generateRegex({
  description: "a valid US phone number, digits only, 10 characters"
});

Once you have the pattern, put it into the relevant field's validation in blocks/data/schemas/<Schema>.json and continue with the normal push/reload workflow above — the CLI genuinely has no equivalent command.

Gotchas

• Reload or it didn't happen. data schema push and data rules deploy stage changes; data reload is what makes them visible to the runtime gateway (and to any app querying it via @seliseblocks/client).
• data validate is local-only — it does not confirm the push will succeed against the server, only that the JSON is well-formed. Still run --dry-run on the actual push/deploy/reload commands.
• Never define platform-managed system fields (ItemId, CreatedDate, CreatedBy, LastUpdatedDate, LastUpdatedBy, Language, OrganizationId, Tags) in your schema JSON — Blocks adds these to every entity schema automatically.
• Check data config get before assuming Blocks-managed storage. Most projects use it, but don't state it as fact without checking — and never create/update a data source configuration without explicit user intent, it repoints the project at a different database.

Example trigger prompts

• "Add an email field to my Customer schema and push it."
• "Pull the current schemas so I can see what's already defined."
• "Validate my local schema files before I push."
• "Set up a data-access policy so only admins can delete Order records."
• "Reload the data schema, I just pushed some field changes."
• "Suggest a regex for validating a postal code field."
• "What database is this project actually using?" → data config get.
• "Add a validation rule so the phone field only accepts digits." → data validation save.
• "What validation rules exist on the Order schema?" → data validation by-schema.
• "Add a location field to my Store schema so I can search nearby stores." → a GeoJson field; its 2dsphere index is automatic.
• "Add a unique index on email." / "What indexes does Order have?" → data schema indexes create|list.
• "Delete this one data-access policy without touching the rest of my rules file." → data rules policy delete.
• "Can you wipe the demo/sample data from my project?" → explain this isn't supported by the CLI or SDK today; point to the portal.
• "Copy my dev project's schemas over to staging." → explain export/import isn't supported by current tooling; point to the portal or manual recreation.