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 runs in the dev environment - not a local server. See Three environments. The --env flag has no effect on this command. 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). It's cached in ~/.culvii/config, so later runs reuse it instead of creating a new one.
Draft state is ephemeral. It exists only while the WebSocket connection is open. On Ctrl+C, the platform stops any active dev agent sessions and clears the temporary draft state owned by this session. 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
- Reads active tenant context from
~/.culvii/config. - Auto-provisions a
dev-{user-id}workspace if needed (idempotent - returns existing if slug taken). - Opens a persistent connection to the platform, authenticated with your OAuth access token - the same one
culvii logingave you, not a separate API key. - On session start, the platform clears any stale draft state from previous sessions.
- Starts file watcher. On each save: evaluates the
.culvii.tsfile and sends a sync message if the definition changed. - Platform upserts the definition as a draft row. Last write wins.
- When a definition is deleted from code: sends an orphan message; platform marks the resource as removed.
- On Ctrl+C: WebSocket closes, platform stops any active dev agent sessions and clears the temporary draft state owned by this session.
Connectivity and reconnection
The WebSocket connection is not fire-and-forget - the CLI actively manages it:
- Heartbeat. The client pings the platform every 20 seconds. If a pong doesn't come back within 5 seconds, twice in a row, the client treats the connection as dead and starts reconnecting.
- Reconnect backoff. On any drop (dead heartbeat, network blip, wifi disconnect), the CLI retries with backoff: 1s, 2s, 4s, 8s, 16s. Each attempt tries to refresh the access token first, so a reconnect after your laptop was asleep past the token's expiry still authenticates correctly. If your connection is down when a refresh attempt runs, the refresh silently fails and that reconnect attempt goes out on the last token that worked, instead of aborting - so a brief outage that clears up within the 5 retries recovers on its own without you seeing a session-expired error.
- Give up after 5 attempts. If none of the 5 retries succeed, the CLI prints a fatal error and exits with code 1. You have to rerun
culvii devyourself - it does not keep retrying forever. - Reconnect is a full resync, not a resume. When a retry succeeds, the platform assigns a new session ID and the CLI re-syncs every local
.culvii.tsfile from disk, as if you'd just startedculvii dev. Nothing is preserved from the old session - this is safe because your source of truth is the file on disk, not draft state on the platform. - Proactive token refresh. Independently of any disconnect, the CLI forces a reconnect every 50 minutes to refresh its auth token before it expires (OAuth tokens are valid for about an hour). This shows up as a brief, automatic reconnect - not an error.
- Session rejected outright. If the platform responds to the WebSocket handshake with 401 (your refresh token itself was revoked, or the session is no longer valid), the CLI doesn't retry - it exits immediately and tells you to run
culvii loginagain. Retrying with the same rejected credentials would just fail the same way. - Server-side idle timeout. The platform closes the session after 30 minutes without developer activity (such as a file save). WebSocket heartbeats keep the connection alive but do not reset this inactivity timer. Leaving
culvii devrunning unattended on an unchanged project will eventually hit this - it's not a bug, just the platform reclaiming an idle draft session.
None of these intervals are configurable.
Examples
culvii dev
# → tenant: culvii-dev | workspace: dev-01j9example0 | env: dev
# → Watching ./... Connected to dev-01j9example0 (dev)
# → ✓ synced payment-processor
# → ✓ synced onboarding-flow
# → ^C
# → Disconnected. Draft state discarded.
Error behaviour
| Condition | Message | Exit |
|---|---|---|
| No OAuth session | "No active context. Run culvii login first." | 1 |
| Workspace auto-provisioning fails | "Failed to auto-provision workspace: <reason>" | 1 |
| Session rejected (401) by the platform | "Your session was rejected by the server. Run culvii login to re-authenticate. Shutting down..." | 1 (fatal) |
| Invalid slug in definition | "⚠ Sync failed for <slug>: <reason>" | - (loop continues) |
| 5 reconnect attempts exhausted | fatal error, connection lost | 1 |
| Server idle timeout (30 min) | "Dev session timed out after 30 minutes of inactivity." | 1 |