Configuration

Calvin supports multiple configuration methods with clear priority order:

CLI flags (highest priority)
Environment variables (CALVIN_*)
Project config (.promptpack/config.toml)
User config (~/.config/calvin/config.toml)
Built-in defaults (lowest priority)

Environment Variables

Configure Calvin behavior through environment variables:

Variable	Description	Valid Values	Default
`CALVIN_SECURITY_MODE`	Security enforcement level	`yolo`, `balanced`, `strict`	`balanced`
`CALVIN_VERBOSITY`	Output verbosity	`quiet`, `normal`, `verbose`, `debug`	`normal`
`CALVIN_TARGETS`	Target platforms (comma-separated)	See targets below	All targets
`CALVIN_ATOMIC_WRITES`	Use atomic file writes	`true`, `false`, `0`, `1`	`true`
`CALVIN_SOURCES_USE_USER_LAYER`	Enable user layer	`true`, `false`	`true`
`CALVIN_SOURCES_USER_LAYER_PATH`	Custom user layer path	Any path	`~/.calvin/.promptpack`

Valid Targets

The following target names are valid for CALVIN_TARGETS:

Target	Aliases
`claude-code`	`claude`
`cursor`	—
`vscode`	`vs-code`
`antigravity`	—
`codex`	—
`all`	(meta-target, expands to all)

Typo Detection

Calvin provides helpful suggestions when you mistype environment variable values.

If you set an invalid value, Calvin will warn you and suggest corrections:

$ CALVIN_SECURITY_MODE=strct calvin deploy
Warning: Invalid CALVIN_SECURITY_MODE value 'strct'. Did you mean 'strict'?
Valid values: yolo, balanced, strict

Project Configuration

Create .promptpack/config.toml in your project:

# Format version
[format]
version = "1.0"

# Security settings
[security]
mode = "balanced"  # yolo | balanced | strict
allow_naked = false

# Security deny list
[security.deny]
patterns = ["*.secret", "*.key"]
exclude = [".env.example"] # Patterns to exclude from denial

# MCP Server Configuration
[mcp]
# Define MCP servers with command and arguments
[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]

# Target platforms
[targets]
enabled = ["claude-code", "cursor", "vscode"]

# Multi-layer sources (optional)
[sources]
use_user_layer = true              # Enable ~/.calvin/.promptpack
# user_layer_path = "~/.my-layer"  # Custom user layer path (env var only)
# NOTE: additional_layers cannot be set in project config for security

# Sync settings
[sync]
atomic_writes = true
respect_lockfile = true # Respect manual edits tracked in lockfile

# Output settings
[output]
verbosity = "normal"  # quiet | normal | verbose | debug
color = "auto"        # auto | always | never
animation = "auto"    # auto | always | never | minimal
unicode = true        # Use unicode characters in output

# Deploy settings
[deploy]
target = "project"  # project | home

Target Configuration

The [targets] section controls which platforms receive deployments:

[targets]
enabled = ["cursor", "claude-code"]

Important Semantics:

Missing enabled field = Deploy to all targets (default)
enabled = [] (empty list) = Deploy to NO targets
enabled = ["cursor"] = Deploy only to specified targets

Sources Configuration (Multi-Layer)

Calvin supports multiple layers of promptpacks that merge together:

[sources]
use_user_layer = true  # Default: true

Layer Priority (highest to lowest):

Project layer (./.promptpack) — project-specific
User layer (~/.calvin/.promptpack) — personal defaults
Additional layers (CLI only) — team or org-wide

Security Restriction: For security, additional_layers and user_layer_path can only be set via CLI flags or environment variables, not in project config.

CLI Flags:

calvin deploy --layer /path/to/team-layer  # Add extra layer
calvin deploy --no-user-layer              # Disable user layer
calvin deploy --source /custom/.promptpack # Override project source

Overriding with CLI

CLI flags always take precedence over configuration:

# Config says cursor only, but CLI overrides to claude-code
calvin deploy -t claude-code

# Config says balanced, but CLI sets strict
calvin deploy --security-mode strict

Security Modes

Mode	Behavior
`yolo`	No enforcement, INFO logs only
`balanced`	Generate protections, WARN on issues
`strict`	Block on security violations

Examples

Minimal Configuration

[targets]
enabled = ["cursor", "vscode"]

Team Configuration

[format]
version = "1.0"

[security]
mode = "strict"

[security.deny]
patterns = ["*.env", "*.secret", "credentials/*"]

[targets]
enabled = ["claude-code", "cursor", "vscode"]

[deploy]
target = "project"

Personal Global Config

Create at ~/.config/calvin/config.toml:

[security]
mode = "balanced"

[output]
verbosity = "verbose"
color = "always"

[deploy]
target = "home"

Configuration

On this page