Safe automation workflow

The reliable write sequence follows three steps: context → apply → check. It gives an Agent or script a bounded view. It prevents writes based on stale data. It proves that the committed file satisfies the requested validation level.

Every automation command below passes --json explicitly. We design the default terminal output for people, not as a machine contract.

0. Initialize the Eidos Skill

The standalone CLI bundles the Skill for Agent workflows. Initialize it in the current project, or install it globally:

eidos self skill init
eidos self skill init --global

You do not need Node.js, npm, or npx. Use eidos self skill init --space <DIR> for another project. The command refuses to replace edited Skill files unless you add --force.

1. Read a bounded context

eidos --json data query tracker.eidos Tasks \
  --compact \
  --fields Title,Status \
  --limit 50

--compact returns the file revision, compact schema, and logical rows. Pass --fields to restrict returned columns. Pass --where to filter rows:

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

ne is the Boolean complement of eq. An empty Status also matches. Add an is-not-null rule when you must exclude empty values.

2. Apply an exact change

Save a request as request.json or pass it on standard input:

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

eidos --json data mutate tracker.eidos request.json

You can also use inline mutation flags:

eidos --json data mutate tracker.eidos \
  --table Tasks \
  --match '{"_id":"019..."}' \
  --set '{"Status":"doing"}' \
  --expected-revision 1

revision and --expected-revision reject stale work. The CLI checks the proposed final state before commit and returns the modified rows.

3. Check the committed file

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

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

Row and schema commands for agents

For common schema changes, use the commands under schema instead of manual JSON. Table and Field references can use names or stable IDs. The CLI resolves them before the revision-checked transaction:

eidos --json schema field add tracker.eidos \
  --table Tasks --name Due --type date \
  --expected-revision 1 --dry-run

eidos --json schema field add tracker.eidos \
  --table Tasks --name Owners --type relation --target-table People \
  --cardinality many --on-delete detach \
  --expected-revision 2

eidos --json schema table update tracker.eidos Tasks \
  --record-label Title --content-field Notes --dry-run

eidos --json schema field update tracker.eidos Estimate \
  --table Tasks --type integer --dry-run

eidos --json schema field update tracker.eidos Owners \
  --table Tasks --cardinality one --dry-run

table update changes name, settings, record label, Markdown content Field, position, and default-Table status. field update changes name, settings, position, record-label selection, stored-type conversion, and atomic option renames. Conversion uses the editor recommended policies by default. Review the dry-run classification first. Pass --confirm-lossy only for an intentional explicit-lossy commit. File Fields use asset commands and do not support type conversion. Running schema field update on a relation changes its target, cardinality, or deletion policy. Field nullability is not exposed.

Use data mutate --key when you have a stable business key instead of a Row ID. It accepts one object or an array. It updates the single matching row, and creates a row when no match exists. The key must contain stored, non-null Fields. It must identify at most one existing row:

eidos --json data mutate tracker.eidos \
  --table Tasks \
  --key "External ID" \
  --insert '[{"External ID":"task-1","Title":"Ship CLI","Status":"doing"}]' \
  --expected-revision 3 \
  --dry-run

The response includes a plan that shows create or update for each input. Dry-run Row IDs are temporary, so use the IDs returned by the committed apply. Omit --dry-run to commit the entire batch as one revision. The command rejects duplicate input keys and keys matching multiple existing rows without changing the file.

Use data mutate --changes when a single atomic batch combines creates, updates, and deletes for one Table:

eidos --json data mutate tracker.eidos \
  --table Tasks \
  --expected-revision 4 \
  --changes '[
    {"kind":"update","rowId":"019...","values":{"Status":"done"}},
    {"kind":"create","clientKey":"new-task","values":{"External ID":"task-2","Title":"Document"}},
    {"kind":"delete","rowId":"019..."}
  ]'

data mutate applies every change or none. Use --dry-run to inspect the result without changing the revision. The lower-level schema apply and schema view apply commands remain available when an Agent already owns the exact stable-ID mutation document.

Attachment automation

Do not copy a local file and build File-field JSON by hand. The data asset import command stages bytes in the managed assets/ folder. It derives canonical metadata, updates the cell with a revision check, and cleans staged files if the mutation fails:

eidos --json data asset import tracker.eidos \
  --table Tasks --row 019... --field Files \
  --source /absolute/path/report.pdf \
  --expected-revision 5

Repeat --source for an atomic multi-file import. Use --replace only when you must replace the whole cell. If a file already exists in the .eidos directory tree, use data asset attach with --uri assets/name.ext to reference it without copying.

Delete exact entry IDs with data asset detach --entry 019..., or use --all. Detach and replace operations keep physical files on disk because other records can still reference them. Check local paths, byte counts, media types, symlinks, and unreferenced managed files with:

eidos --json data asset verify tracker.eidos --diagnostics-limit 100

Broken references make the command exit non-zero. Unreferenced assets generate warnings and the CLI does not delete them automatically. After stale-revision, reload the target row and plan again instead of replaying the attachment mutation.

Runtime Formula and Lookup

Use the canonical Runtime for derived Fields. Preview Formula source text before you commit it. The result shows the inferred type, dependencies, diagnostics, and optional sample values:

eidos --json schema field preview tracker.eidos \
  --table Tasks --name Total \
  --formula '"Estimate" * 2' --type integer

Formula uses a fixed SQLite 3.45 scalar-expression subset. See Formula expressions for supported functions and syntax. Do not send arbitrary SQL or invent function aliases.

Create or update a Formula with revision-checked Runtime preflight:

eidos --json schema field add tracker.eidos \
  --table Tasks --name Total --type formula \
  --formula '"Estimate" * 2' --result-type integer \
  --expected-revision 4 --dry-run

eidos --json schema field update tracker.eidos Total \
  --table Tasks --formula '"Estimate" + 1' --result-type integer \
  --expected-revision 4

Create a Lookup after its Relation and target Field exist:

eidos --json schema field add tracker.eidos \
  --table Tasks --name OwnerScore --type lookup \
  --relation-field Owners --target-field Score \
  --aggregate sum --expected-revision 5

schema table create can include Formula fields in its initial field array. Add Relation and Lookup fields after you create the referenced schema.

Lookup aggregates are values, first, count, sum, average, min, and max. Add --distinct when you require distinct values. data query calculates Formula, Lookup, and inverse Relation Fields automatically when a Table contains them. You can project, filter, and sort derived Fields. You cannot edit derived Fields in row mutations. The Runtime rejects invalid types, missing targets, stale plans, and dependency cycles before commit. Deleting a Formula or Lookup is explicitly lossy. Preview it first and pass --confirm-lossy only after you check the impact.

Lower-level operations

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

schema apply accepts Runtime schema batches. It resolves Table and Field names in settings, position, record-label, conversion, option-rename, Relation, Formula, and Lookup operations. CLI invocations do not share Runtime mutation tokens, so committed changes have no cross-command undo. Use Eidos Lite history or a known file copy for recovery.

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

eidos --json schema 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. The persisted View document does not accept names. schema view update supports explicit name, type, query, layout, and position patches. schema view delete deletes the stable View ID.