Overview

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

Human identity (OAuth track): Interactive commands that require a logged-in developer — workspace management, key management, audit, and any operation that writes to production. Initiated with culvii login. Tokens stored in ~/.culvii/config.json (mode 0600).

Machine identity (API key track): Programmatic commands used by the SDK, CI/CD pipelines, and the live dev loop. Authenticated via x-api-key header. Keys created with culvii key create.

Both tracks feed the same audit trail.

Installation

npm install -g @culvii/cli

Requires Node.js 18+. Supported on macOS (arm64, x64), Linux (x64, arm64). Windows support is planned for a future release; WSL2 is an acceptable workaround in the interim.

Config file

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

Shape:

{
  "version": 1,
  "active": "acme",
  "endpoints": {
    "dev": "https://api-dev.culvii.com",
    "sandbox": "https://api-sandbox.culvii.com",
    "prod": "https://api.culvii.com"
  },
  "contexts": {
    "acme": {
      "tenant_id": "org_01HXYZ...",
      "tenant_slug": "acme",
      "workspace_id": "wsp_01HXYZ...",
      "workspace_slug": "dev-alice",
      "environment": "dev"
    }
  }
}

The active key names the context in use. culvii config use-context switches it. Per-command --env and --workspace flags override context for that invocation only; they do not write to the file.

Three environments

Environment	API base	Purpose
dev	https://api-dev.culvii.com	Live development loop. Personal per-developer workspace.
sandbox	https://api-sandbox.culvii.com	Pre-production integration testing. Realistic seed data.
prod	https://api.culvii.com	Live customer workloads.

Each environment runs its own separate database. There is no shared or centralised cross-environment database.