How to Sync Records with the CLI

This guide shows you how to create and inspect Records from the command line. A Record is an instance of a Schema — the business data a Space holds.

Prerequisites

• You are logged in (ligantic auth login).
• A current Space is set (ligantic space select or ligantic space use <id>).

If no Space is selected, Record commands exit with a hint:

error: no space selected — run `ligantic space select` or `ligantic space use <id>`, or pass --space <id>

List Records

records list takes the Schema as a positional argument, by ID or by (case-insensitive) name:

ligantic records list customer

The table shows the Record id plus one column per top-level key of the Record data. Paginate with --limit and --offset:

ligantic records list customer --limit 50 --offset 0

Query Records

records query runs a Record query: it returns only the fields you select, and can add relationship aggregates or group the Records. Paths in --select, --filter, and --sort are field IDs (listed by schemas show) or standard properties such as id and createdAt:

ligantic records query customer --select '["id", {"kind":"field","id":"name","alias":"name","path":"<fieldId>"}]' --limit 10

For a larger query, keep the request body in a file and pass it with --data @<file> (or --data - for stdin). Flags override the matching fields of the file:

cat > query.json <<'JSON'
{
  "select": ["id", "createdAt"],
  "sort": [{ "orderBy": "createdAt", "order": "desc" }]
}
JSON
ligantic records query customer --data @query.json --limit 5 --json

The result is { "rows": […], "count": …, "offset": …, "limit": … }, with one row per Record keyed by select alias. The SDK offers the same query:

const result = await client.records.query(spaceId, schemaId, {
  select: ["id", "createdAt"],
  sort: [{ orderBy: "createdAt", order: "desc" }],
  limit: 5,
});

Create a Record

Pass the Record data as a JSON string:

ligantic records create customer --data '{"name":"Ada","email":"ada@example.com"}'

On success the command prints the new Record ID:

created <recordId>

With --json it prints the full creation result, which you can pipe into other tools:

ligantic records create customer --data '{"name":"Ada"}' --json

Show a Record

ligantic records show customer <recordId>

Name-Based Schema Lookup

Whenever you pass a <schema> argument, the CLI first tries an exact ID match, then a case-insensitive name match. If more than one Schema shares the name, it errors and lists the candidate IDs so you can disambiguate:

error: ambiguous schema name 'customer' — use the id: sc_a1b2, sc_c3d4

Updating a Record

Replace a Record's data with a full data object (update is an alias for put):

ligantic records put customer <recordId> --data '{"name":"New"}'

On success the command prints the updated Record ID:

updated <recordId>

Deleting a Record

ligantic records delete customer <recordId> --yes

Deleting is irreversible, so the command needs --yes. Without it you are asked to confirm on a terminal, and in a script it fails with exit code 2. On success the command prints the deleted Record ID:

deleted <recordId>

Linking Records

Records are linked to one another through a Schema's relationship fields. records link creates a link from a source Record to one or more target Records via a named relationship field — the CLI resolves the relationship's direction for you, so you never reason about from/to:

ligantic records link customer <recordId> Owner person_1 person_2

<field> is a relationship field name on the Schema (or a relationship version id); each <targetId> is a Record in the relationship's other Schema. On success it prints linked <recordId> -> <targetId> via <field> per target, as each link is created (or a JSON object under --json) — so if a later target fails, the lines above the error are links that were already persisted.

To remove a single link, use records unlink (one target at a time):

# …later
ligantic records unlink customer <recordId> Owner person_1 --yes

Like records delete, records unlink needs --yes (or a confirmation on a terminal).

unlink deletes only the first matching row. Duplicate rows between the same pair can exist, so if records show still lists a row afterwards, run unlink again.

To inspect a Record's links, records show always includes the raw relationship rows (the fromEntityId/toEntityId + schemaRelationshipVersionId, not resolved to text); records list includes them with --relationships:

ligantic records show customer <recordId>
ligantic records list customer --relationships

Targeted JSON Patch

records put replaces the whole Record. To change only some fields, use records patch, which merges a JSON object into the Record's data:

ligantic records patch customer <recordId> --patch '{"name":"New"}'

For an RFC 6902 JSON Patch array, pass it with --ops instead. The SDK offers the same JSON Patch operation:

await client.records.patch(spaceId, schemaId, recordId, {
  operations: [{ op: "replace", path: "/name", value: "New" }],
});

See SDK API Reference — Records.