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

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.