estøkad

CLI

@estokad/cli is the customer-side command-line tool. It loads schemas/*.ts from your repo, compiles to JSON IR via @estokad/schema, and pushes to the management API.

Install

pnpm add -D @estokad/cli @estokad/schema
pnpm estokad init

estokad init scaffolds:

estokad.config.ts                  # workspace, region, apiUrl, paths
schemas/index.ts                   # re-export entry point
schemas/site-settings.ts           # tiny singleton, smoke test the loop
.estokad/.gitignore

Configure

Three sources, highest precedence first: CLI flags → env vars → estokad.config.ts.

| Setting | Env var | Default | |---|---|---| | workspace | ESTOKAD_WORKSPACE | (required) | | apiUrl | ESTOKAD_API_URL | (required) | | apiKey | ESTOKAD_API_KEY | (required, never in config file) | | region | ESTOKAD_REGION | eu-fra-1 | | schemas | — | ./schemas | | state | — | ./.estokad/schema-state.json |

The state file maps type/field names to UUIDs across runs so renames stay stable. Commit it so your team shares identity.

Commands

estokad init

Scaffolds a fresh customer repo. Pass --force to overwrite existing files.

estokad push

$ estokad push
  workspace your-workspace @ http://localhost:3001
  ✓ loaded 12 definitions from ./schemas
  ✓ compiled to JSON IR (12 types)
  ✓ pushed to your-workspace@eu-fra-1 (12 types)
  ✓ state saved to ./.estokad/schema-state.json

Exit codes: 0 success, 2 config or schema-load error, 3 API rejected the push.

Pass --migrate to push schema changes that would invalidate existing entries (narrowed types, removed enum options, added required fields). Existing rows keep their old data until next edited.

estokad status

$ estokad status
  estokad status
    workspace your-workspace @ http://localhost:3001
    region    eu-fra-1
    local     12 types · 7c8b…
    remote    12 types · 7c8b…
    drift     in sync

Local hash is a stable hash of the compiled IR. Remote hash is the join of every type's schema_hash from the API. Drift means someone pushed from another machine since you last did.

estokad pull (M1.2b)

Reverse direction — pulls remote schemas into local files. Useful when the Studio's visual schema editor (M1.5b) writes back changes that engineering needs to synchronise into Git.

estokad diff (M1.2b)

Shows the set of changes a push would apply. Read-only.

CI integration

Run estokad push from CI on every merge to main. The standard workflow:

- run: pnpm install
- run: pnpm estokad push
  env:
    ESTOKAD_API_KEY: ${{ secrets.ESTOKAD_API_KEY }}

The ESTOKAD_API_KEY should be a management-scope key. Rotate at least quarterly.

Errors

The CLI is intentionally noisy on failure. Common ones:

  • apiKey is required — set ESTOKAD_API_KEY in your env or pass --api-key.
  • migration_conflicts — your schema change would invalidate existing entries. Re-run with --migrate to push anyway, or fix the conflict (rename the field, widen the type).
  • module_inactive — your schema uses a field option (cross-space references, locale fields) that requires a paid module the workspace doesn't have. Activate it in /settings/subscription or remove the field option.