Skip to main content

culvii dev

Start the live development sync loop.

Synopsis​

culvii dev

Description​

Starts the live development sync loop. Local .culvii.ts files are the authoring surface; all execution and state live on the Culvii platform's dev environment. Every file save streams a definition payload over a persistent WebSocket to the platform, which upserts it as draft state. The UI reads from the same database and reflects changes immediately.

Always connects to http://localhost:3000. The --env flag has no effect on this command — it is intentionally hardcoded to the local dev server. Use culvii deploy to target sandbox or prod.

On first run: auto-provisions a workspace named dev-{user-id} (derived from the first 12 characters of your user ID) and creates a developer-scoped API key for it. Both are cached in ~/.culvii/config.

Draft state is ephemeral. It exists only while the WebSocket connection is open. On Ctrl+C, all draft rows owned by this session are soft-deleted. Draft state never reaches sandbox or production.

File discovery​

By default, recursively finds all *.culvii.ts files in the current directory, skipping node_modules/, dist/, and .git/.

Override with a culvii.yaml in the project root:

entrypoints:
  - src/agents/payment-processor.ts
  - src/workflows/onboarding.ts

If culvii.yaml exists and has at least one entrypoint, the glob is skipped entirely.

How it works​

  1. Reads active tenant context from ~/.culvii/config.
  2. Auto-provisions a dev-{user-id} workspace if needed (idempotent — returns existing if slug taken).
  3. Reads or creates a developer-scoped API key for the workspace.
  4. Opens a WebSocket to GET /api/dev/sync authenticated via the API key.
  5. On session start, the platform soft-deletes any stale draft rows from previous crashed sessions (different sessionId).
  6. Starts file watcher. On each save: evaluates the .culvii.ts file, computes a configHash, sends a sync message if hash changed.
  7. Platform upserts the definition as a draft row. Last write wins.
  8. When a definition is deleted from code: sends an orphan message; platform sets orphanedAt.
  9. On Ctrl+C: WebSocket closes, platform soft-deletes all draft rows owned by this session.

Examples​

culvii dev
# → tenant: culvii-dev  |  workspace: dev-culvii-dev  |  env: dev
# → Watching ./... Connected to dev-culvii-dev (dev)
# → ✓ synced payment-processor
# → ✓ synced onboarding-flow
# → ^C
# → Disconnected. Draft state discarded.

Error behaviour​

ConditionMessageExit
No OAuth session"No active context. Run culvii login first."1
Workspace auto-provisioning fails"Failed to auto-provision workspace: <reason>"1
API key auto-creation fails"Failed to auto-create API key: <reason>"1
Workspace mismatch on WebSocket"Workspace mismatch. Connection closed."1 (fatal)
Invalid slug in definition"⚠ Sync failed for <slug>: <reason>"— (loop continues)

culvii deploy, culvii workspace create, culvii key create