Overview

The Culvii CLI (culvii) is the command-line interface for the Culvii platform. It handles two distinct responsibilities:

Human identity (OAuth track): Interactive commands that require a logged-in developer — workspace management, key management, deploy, rename, and any operation that targets the platform. Initiated with culvii login. Tokens stored in ~/.culvii/tokens.json (mode 0600).

Machine identity (API key track): Used by culvii dev for the live development sync loop. Authenticated via x-api-key header. Keys are auto-created by culvii dev on first run, or manually with culvii key create.

Both tracks feed the same audit trail.

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",
      "api_key": "ck_dev_...",
      "workspace_keys": {
        "payments": "ck_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 flags override context for that invocation only — they do not write to the file.

Three environments

Environment	Purpose
dev	Live development loop. Always local (http://localhost:3000).
sandbox	Pre-production integration testing.
prod	Live customer workloads.

Each environment runs its own separate server and database. culvii dev always connects to dev. All other commands default to the environment in your active context and can be overridden with --env.