culvii dev

Start the live development sync loop.

Synopsis

culvii dev [--workspace <slug>]

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 dev-{org-slug} workspace 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.

Flags

Flag	Description
--workspace <slug>	Connect to a specific workspace instead of the default dev-{org-slug}.

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 org context from ~/.culvii/config.
2. Auto-provisions dev-{org-slug} 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
# → org: 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.

# Use a specific workspace
culvii dev --workspace payments-staging

Error behaviour

Condition	Message	Exit
No OAuth session	"No active context. Run culvii login first."	1
Workspace not found (--workspace flag)	"Workspace not found: <slug>"	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)

Related commands

culvii deploy, culvii workspace create, culvii key create