Skip to main content
Not yet available

This command is planned for a future release.

culvii dev

Start the live development sync loop.

Synopsis​

culvii dev

Description​

Starts the live development sync loop. This implements the online-local development model: local 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 connection to the platform, which upserts it as draft state into the dev database. The UI reads from the same database and reflects changes immediately.

On first run: culvii dev checks ~/.culvii/config.json for an existing dev-{username} workspace. If none is found, it calls POST /api/workspaces to auto-provision one and writes the workspace ID into the active context.

Draft state is ephemeral. It exists only in the dev database and is discarded when the WebSocket closes (Ctrl+C, process exit, or TCP timeout). Draft state never reaches sandbox or production.

Requirements:

  • An active OAuth session (for workspace auto-provisioning on first run)
  • A developer-scoped API key that is scoped to the workspace (not tenant-wide)

If no key is found in the active context, the command exits with a message directing the user to culvii key create.

How it works​

  1. Reads active context; provisions dev-{username} workspace if needed.
  2. Reads developer-scoped API key from context.
  3. Opens a WebSocket connection to GET /api/dev/sync with the key.
  4. Starts a file watcher on the project directory.
  5. On each save: debounces 300ms, parses and validates the definition, sends a JSON message over the WebSocket.
  6. Platform upserts the definition as a draft row, keyed on (workspaceId, slug, resourceType). Last write wins.
  7. On Ctrl+C or disconnect: all draft rows owned by this connection are deleted.

Each agent is synced independently​

When a workbook contains multiple agents, each agent is sent as a separate message with its own slug and resourceId. Sub-agents are not nested inside a parent definition blob. This is required because every agent is a first-class resource with its own immutable ID.

Custom tool functions​

Tool execute functions are JavaScript closures and cannot be serialised to JSON. Only tool name strings, built-in tools, and MCP tools survive the sync. This is a known limitation — agents with custom tools cannot run from database-loaded state until a custom tool execution strategy is designed (Phase 2).

Examples​

culvii dev
# → Provisioned dev workspace: dev-alice
# → Watching ./... Connected to dev-alice (dev)
# → ✓ synced payment-classifier
# → ✓ synced invoice-router
# → ^C
# → Disconnected. Draft state discarded.

Error behaviour​

ConditionMessageExit
No API key in context"No API key found. Run culvii key create --workspace dev-alice --scope developer."1
Key is revoked"API key revoked. Run culvii key create to mint a new one."1
Tenant-wide key used"culvii dev requires a workspace-scoped API key."1
Invalid slug in definition fileWarn: "Sync failed for <slug>: invalid slug format." Loop continues.—
Workspace mismatch"Workspace mismatch — possible key misconfiguration." Connection closed.1
Definition parse errorWarn: "Invalid definition in <file> — skipping sync." Loop continues.—

culvii key create, culvii workspace create, culvii deploy