Overview

The Culvii CLI (culvii) is the command-line interface for the Culvii platform. Every command - workspace management, deploy, culvii dev - runs as your logged-in identity. There's no separate machine/API-key identity: culvii login opens an OAuth flow, and the resulting tokens (stored in ~/.culvii/tokens.json, mode 0600) authenticate everything, including the WebSocket culvii dev opens. The CLI refreshes the access token for you in the background - see culvii login for how that works and what happens if it fails.

Installation

npm install -g @culvii/cli

Requires Node.js 22+. Supported on macOS (arm64, x64) and Linux (x64, arm64).

Config file

The CLI stores context in ~/.culvii/config (permissions: 0600 on POSIX).

{
  "active": "culvii-dev",
  "contexts": {
    "culvii-dev": {
      "tenant_id": "uuid",
      "tenant_slug": "culvii-dev",
      "workspace_id": "uuid",
      "workspace_slug": "dev-culvii-dev",
      "environment": "dev"
    },
    "acme": {
      "tenant_id": "uuid",
      "tenant_slug": "acme",
      "workspace_id": null,
      "workspace_slug": null,
      "environment": "dev"
    }
  },
  "anonymousId": "uuid"
}

active names the context in use. culvii switch changes it. Per-command --env and --workspace-slug flags override context for that invocation only - they do not write to the file.

Three environments

dev, sandbox, and prod keep their data fully segregated - which one a command touches is decided by the --env flag you pass it (or the environment stored in your active context, when a command allows falling back to that). You log in once with culvii login; that session works across all three, you don't authenticate per environment.

Environment	Purpose
dev	Where culvii dev syncs draft state while you're iterating.
sandbox	Pre-production integration testing.
prod	Live customer workloads.

How commands pick an environment differs per command - don't assume a stored default applies:

• culvii dev always runs in dev. It's hardcoded; passing --env to it does nothing.
• culvii deploy always requires an explicit --env. There's no fallback to your active context - a consequential command like deploy shouldn't run against the wrong environment because you forgot to switch. You pass --env sandbox or --env prod on every invocation.
• workspace create and workspace list fall back to the environment stored in your active context if you omit --env; whoami (no --env flag at all) shows whichever workspace that stored environment resolves to. That stored default is what culvii env shows and changes - see culvii env, which is a convenience for these commands only, not deploy or dev.