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.

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 fetches a fresh token.
  • 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 dev yourself - 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.ts file from disk, as if you'd just started culvii 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.
  • Server-side idle timeout. If the platform doesn't see any activity (a sync, an orphan message, or a heartbeat) for 30 minutes, it closes the session with "Dev session timed out after 30 minutes of inactivity." A save, or any file-watcher activity, resets this timer.

None of these intervals are configurable.

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)
5 reconnect attempts exhaustedfatal error, connection lost1
Server idle timeout (30 min)"Dev session timed out after 30 minutes of inactivity."1

culvii deploy, culvii workspace create, culvii key create