Eidos

Agents and automation

The Rust eidos CLI is the structured machine interface for AI Agents and automation. It reads and writes .eidos files directly, emits JSON only, and uses the same typed data model as the Eidos File Runtime. It does not connect to Eidos Desktop.

Status: Alpha · current stable CLI 0.34.0. The CLI is released independently from Eidos Desktop.

Current capability boundary

The Alpha can create and inspect Eidos Files, query stored scalar and list fields, follow forward Relations, apply atomic row or schema mutations with revision checks, and run validation.

It preserves and reports existing Formula, Lookup, inverse Relation, and view metadata, but it does not create or evaluate those virtual fields yet. Graft owns version history and sync; the CLI does not. Raw SQLite writes are unsupported because they bypass the typed transaction and validation boundary.

1. Install the CLI

macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://download.eidos.space/cli/install.sh | sh

Windows PowerShell:

irm https://download.eidos.space/cli/install.ps1 | iex

The installer resolves the stable CLI version, downloads the matching cli-v* GitHub Release archive, and verifies its SHA-256 digest against that Release’s SHA256SUMS before replacing the binary. Desktop installers and CLI archives are separate products and release streams.

2. Install the matching Eidos Skill

The CLI enforces the typed transaction boundary. The Eidos Skill teaches Codex the safe context → apply → validate workflow and when to use Graft for review or recovery.

Install the Skill from the same public tag as CLI 0.34.0:

npx skills add \
  https://github.com/mayneyao/eidos/tree/cli-v0.34.0/skills/eidos \
  --skill eidos -g -a codex -y

This command uses the open skills installer and requires Node.js 18 or newer. The versioned source keeps the workflow aligned with the installed CLI instead of following the moving development branch. Start a new Codex task after installation so the Agent can discover the Skill.

3. Start with a read-only task

Use the Eidos skill to inspect ./tracker.eidos.
Show context first and do not mutate yet.

The Agent should confirm the target file, table, fields, stable IDs, and current revision before it proposes a mutation.

Safe write loop

  1. Read compact, bounded context.
  2. Apply one exact, revision-bound transaction.
  3. Run full validation after the final mutation.
  4. If the file is tracked by Graft, review the logical diff before committing and use history to restore when needed.
eidos tracker.eidos context Tasks --fields Title,Status --limit 50
eidos tracker.eidos apply - <<'JSON'
{
  "revision": "1",
  "table": "Tasks",
  "match": {"_id": "019..."},
  "expect": 1,
  "set": {"Status": "doing"},
  "returning": ["Title", "Status"]
}
JSON
eidos tracker.eidos validate --level full
graft status --json
graft diff --rows --json HEAD

During Alpha, do not let the CLI write a file while the Web Editor or Desktop is actively editing the same file. Close it in the editor first, or work on a copy or a Graft branch.

For application embedding, use the Runtime and UI packages. For the on-disk contract, read the format reference.