cvkit

 ██████╗██╗   ██╗██╗  ██╗██╗████████╗
██╔════╝██║   ██║██║ ██╔╝██║╚══██╔══╝
██║     ██║   ██║█████╔╝ ██║   ██║
██║     ╚██╗ ██╔╝██╔═██╗ ██║   ██║
╚██████╗ ╚████╔╝ ██║  ██╗██║   ██║
 ╚═════╝  ╚═══╝  ╚═╝  ╚═╝╚═╝   ╚═╝

Computer Vision Toolkit for terminal workflows.

Install

npm install -g cvkit

Quick start

cvkit
cvkit inspect ./test/fixtures/sample.jpg
cvkit config set GEMINI_API_KEY=your-key

AI loop

cvkit now supports natural-language prompts in the REPL. Direct commands still work as before, but non-command input is routed through Gemini tool calling over the local workspace.

Examples:

find all images that do not have labels
how many class 0 annotations are in this dataset?
read labels/frame_001.txt

AI writes are gated. If the model wants to call write_file or edit_file, cvkit asks for a y/n confirmation before mutating the workspace.

Command reference

Command	Description
cvkit	Show the banner splash screen, then help
cvkit --help	Show help
cvkit --version	Show the current version
cvkit inspect <imagePath>	Inspect image metadata
cvkit config set <KEY=VALUE>	Save a config value
cvkit config list	List config values with secret masking

Configuration

Configuration lives in ~/.cvkit/config.json.

cvkit config set GEMINI_API_KEY=your-key
cvkit config set DEFAULT_MODEL=gemini-3-flash-preview
cvkit config list

AI credentials are resolved in this order:

1. GEMINI_API_KEY from ~/.cvkit/config.json
2. GEMINI_API_KEY from the runtime environment or .env
3. CVKIT_GEMINI_KEY from the runtime environment or .env

Create a local .env from the example file when you want a shared runtime fallback without storing the key in user config:

cp .env.example .env

HTTP server

The Cloud Run wrapper exposes a minimal HTTP API:

• GET /health
• POST /v1/ai/respond

The HTTP AI endpoint is intentionally read-only. It exposes read_file, glob_files, grep_files, inspect_image, and list_dir, but not write_file or edit_file.

Example:

curl http://localhost:8080/health
curl -X POST http://localhost:8080/v1/ai/respond \
  -H "content-type: application/json" \
  -d '{"input":"summarize the workspace"}'

Docker

Build and run the HTTP wrapper locally:

npm run build
docker build -t cvkit .
docker run --rm -p 8080:8080 --env-file .env cvkit

For local development with Postgres:

docker compose up --build

Cloud Run

Deploy the HTTP wrapper to Cloud Run with authenticated access and a Secret Manager-backed Gemini key:

chmod +x deploy/cloud-run.sh
deploy/cloud-run.sh <project-id> <region> <gemini-secret-name> [service-name] [secret-version]

Roadmap

• Phase 0: scaffold, splash screen, inspect, config
• Phase 1+: future expansion beyond the verified baseline

License

MIT