Safe automation workflow

The reliable write sequence is context → apply → validate. It gives an Agent or script a bounded view, prevents writes based on stale data, and proves the committed file still satisfies the requested validation level.

Every automation command below passes --json explicitly. The default output is designed for people and is not a machine contract.

1. Read a bounded context

eidos --json context tracker.eidos Tasks \
  --fields Title,Status \
  --limit 50

context returns file revision, compact schema, and logical rows. Add --full only when stable IDs, system fields, settings, relations, and saved views are needed.

Filters use portable JSON and may reference fields by name or stable ID:

eidos --json context tracker.eidos Tasks \
  --where '{"op":"ne","field":"Status","value":"done"}' \
  --fields Title,Status

ne is the Boolean complement of eq, so an empty Status also matches. Add an is-not-null rule when empty values should be excluded.

2. Apply an exact change

Save a request as request.json or pass it on stdin:

{
  "revision": "1",
  "table": "Tasks",
  "match": { "_id": "019..." },
  "expect": 1,
  "set": { "Status": "doing" },
  "returning": ["Title", "Status"]
}

eidos --json apply tracker.eidos request.json

revision rejects stale work. expect prevents an unexpectedly broad update. The CLI validates the proposed final state before commit and returns the rows requested by returning.

3. Validate the committed file

eidos --json validate tracker.eidos --level full

Treat a nonzero exit status at any step as a failed workflow. Do not continue from guessed or partially parsed output.

Lower-level operations

rows add, rows update, rows delete, schema-apply, and view-apply remain available for automation that already owns stable IDs and revision state. Schema changes support dry-run execution against the real transaction path before commit.

eidos --json schema-apply tracker.eidos \
  --expected-revision 1 \
  --op @schema-change.json \
  --dry-run

Create a Calendar View from the stable Table and date/datetime Field IDs in schema output:

eidos --json view-apply tracker.eidos - <<'JSON'
{
  "expectedRevision": "2",
  "changes": [{
    "kind": "create-view",
    "clientKey": "calendar",
    "tableId": "019...",
    "name": "Calendar",
    "type": "calendar",
    "query": {},
    "layout": { "dateField": "019..." },
    "position": "1"
  }]
}
JSON

The CLI allocates the View ID and returns it under createdViews. View query and layout references use stable Field IDs; display names are not accepted in the persisted View document. update-view supports explicit name, type, query, layout, and position patches; delete-view removes the stable View ID.