Calvin Command Reference

Reference for Calvin CLI commands (v0.6.0)

Synopsis

calvin [OPTIONS] [COMMAND]

No command:

TTY: opens an interactive menu
--json: prints detected project state as JSON
- state = "no_promptpack": no project .promptpack/ and no other layers
- state = "global_layers_only": no project .promptpack/, but at least one global layer exists (user and/or additional; can be 0 assets)
  - Backward-compat: state_aliases includes "user_layer_only"
- state = "empty_promptpack": .promptpack/ exists but contains no assets
- state = "configured": .promptpack/ exists and contains assets

Global Options

Option	Short	Description
`--json`	-	Output machine-readable JSON
`--verbose`	`-v`	Verbosity level (`-v`, `-vv`, `-vvv`)
`--color`	-	Color output: `auto`, `always`, `never`
`--no-animation`	-	Disable progress animations
`--help`	`-h`	Print help information
`--version`	`-V`	Print version information

Core Commands

`calvin deploy`

Deploy PromptPack assets (replaces sync + install).

calvin deploy [OPTIONS]

Options:

Option	Short	Description
`--source <PATH>`	`-s`	Path to `.promptpack` directory (default: `.promptpack`)
`--targets <LIST>`	`-t`	Comma-separated targets (e.g. `claude-code,cursor`)
`--home`	-	Deploy to user home directory
`--project`	-	Deploy to current project (override config)
`--remote <DEST>`	-	Deploy to remote destination (`user@host:/path`)
`--force`	`-f`	Force overwrite of modified files
`--yes`	`-y`	Non-interactive; auto-confirm overwrites
`--dry-run`	-	Preview changes without writing
`--cleanup`	-	Remove orphan files (files previously deployed but no longer generated)

Multi-Layer System:

Calvin automatically loads assets from multiple layers in priority order:

User layer (lowest priority): ~/.calvin/.promptpack/
Additional layers (middle priority): Custom paths via --layer
Project layer (highest priority): ./.promptpack/ (or --source <PATH>)

When assets with the same ID exist in multiple layers, higher-priority layers override lower ones. Use -v to see the resolved layer stack.

Target selection:

--targets (CLI) has highest priority.
CALVIN_TARGETS (env) overrides config files.
Otherwise, deploy reads [targets] from the resolved layer stack (e.g. ~/.calvin/.promptpack/config.toml, additional layers, then project config.toml); higher-priority layers override lower ones.
In interactive mode (TTY, without --yes, and without --targets), Calvin asks you to confirm target platforms before deploying.

Lockfile location:

Project deployments track state in ./calvin.lock (project root)
Home deployments track state in ~/.calvin/calvin.lock (global)
--source changes the project layer input, but does not change where calvin.lock is written

Orphan Cleanup:

When you change your configuration (e.g., from target = "project" to target = "home"), previously deployed files may become orphaned. The --cleanup flag removes these files:

Only files with a Calvin signature () are automatically deleted
Files without a signature are skipped (warning shown)
Use --cleanup --force to delete all orphan files regardless of signature
In interactive mode (without --yes), prompts for confirmation

Examples:

calvin deploy
calvin deploy --targets claude-code,cursor
calvin deploy --home --yes
calvin deploy --project --yes
calvin deploy --remote user@server:/home/user/project --yes
calvin deploy --dry-run
calvin deploy --cleanup              # Remove orphan files
calvin deploy --cleanup --force      # Remove all orphans (including unsigned)
calvin deploy -v                     # Show layer stack

`calvin check`

Check configuration and security (replaces doctor + audit).

calvin check [OPTIONS]

Options:

Option	Description
`--mode <MODE>`	Security mode: `balanced` (default), `strict`, `yolo`
`--strict-warnings`	Fail on warnings too (CI mode)
`--all`	Check all registered projects (uses global registry)
`--all-layers`	Check all resolved layers (user, custom, project)

Examples:

calvin check
calvin check --mode strict
calvin check --strict-warnings
calvin check --all                  # Check all registered projects
calvin check --all-layers           # Check all layers for current project

JSON Output for --all:

{"event":"check","project":"/path/to/project-a","platform":"cursor","name":"rules_valid","status":"pass"}
{"event":"check","project":"/path/to/project-b","platform":"claude","name":"commands_valid","status":"pass"}
{"event":"complete","projects_checked":2,"total_passed":10,"total_failed":0}

`calvin explain`

Explain Calvin's usage (for humans / AI assistants).

calvin explain [OPTIONS]

Options:

Option	Description
`--brief`	Short version (just the essentials)

Examples:

calvin explain
calvin explain --brief
calvin explain --json

`calvin watch`

Watch .promptpack/ for changes and deploy continuously.

Compilation uses the resolved multi-layer stack (user/custom/project), but by default only the project layer is watched. Use --watch-all-layers to watch changes in user/custom layers too.

calvin watch [OPTIONS]

Options:

Option	Short	Description
`--source <PATH>`	`-s`	Path to `.promptpack` directory (default: `.promptpack`)
`--home`	-	Deploy to user home directory (~/...)
`--watch-all-layers`	-	Watch all resolved layers (user/custom/project), not just the project layer

JSON output (NDJSON):

{"event":"watch_started","source":".promptpack"}
{"event":"file_changed","path":"policies/security.md"}
{"event":"sync_started"}
{"event":"sync_complete","written":5,"skipped":2,"errors":0}
{"event":"shutdown"}

`calvin diff`

Preview what would be generated, without writing.

Compilation uses the resolved multi-layer stack (user/custom/project), the same as deploy, and respects merged [targets] enabled = [...] configuration.

calvin diff [OPTIONS]

Options:

Option	Short	Description
`--source <PATH>`	`-s`	Path to `.promptpack` directory (default: `.promptpack`)
`--home`	-	Preview changes for home directory outputs (~/...)

`calvin clean`

Remove deployed files tracked in the lockfile.

calvin clean [OPTIONS]

Options:

Option	Short	Description
`--source <PATH>`	`-s`	Path to `.promptpack` directory (default: `.promptpack`)
`--home`	-	Clean only home directory deployments (~/)
`--project`	-	Clean only project directory deployments (./)
`--all`	-	Registry-wide clean: clean all registered projects
`--dry-run`	-	Preview what would be deleted without deleting
`--yes`	`-y`	Non-interactive; skip confirmation prompt
`--force`	`-f`	Force delete even if files were modified

Safety Features:

Only deletes files tracked in the lockfile (calvin.lock)
Verifies files have Calvin signature before deletion
Skips files that were modified after deployment (hash mismatch)
Updates lockfile after successful deletion

Behavior by Scope:

Option	Cleans
`--home`	Files deployed to `~/` (home directory)
`--project`	Files deployed to `.` (project directory)
`--all`	All registered projects in the global registry
(none)	Interactive mode with tree menu

Note: --all means "all projects" (registry-wide), not "all scopes" (home + project). To clean both scopes in the current project, use interactive mode or run --home and --project separately.

Examples:

calvin clean                        # Interactive mode with tree menu
calvin clean --all --yes            # Clean ALL registered projects
calvin clean --home --yes           # Delete all home deployments
calvin clean --project --dry-run    # Preview project deployment cleanup
calvin clean --force --yes          # Force delete all (skip checks)

JSON Output:

{"event":"start","command":"clean","type":"clean_start","scope":"all","file_count":5}
{"event":"progress","command":"clean","type":"file_deleted","path":"~/.claude/commands/workflow.md","key":"home:~/.claude/commands/workflow.md"}
{"event":"progress","command":"clean","type":"file_skipped","path":"~/.cursor/rules/style.mdc","key":"home:~/.cursor/rules/style.mdc","reason":"modified"}
{"event":"complete","command":"clean","type":"clean_complete","deleted":3,"skipped":2,"errors":0}

Note: The type field is deprecated and will be removed in v1.0. Use event + command instead.

Registry-Wide Clean (--all) JSON Output:

{"event":"start","command":"clean","type":"clean_all_start","projects":3}
{"event":"progress","command":"clean","type":"project_complete","path":"/path/to/project-a","deleted":5,"skipped":0,"errors":0}
{"event":"progress","command":"clean","type":"project_complete","path":"/path/to/project-b","deleted":3,"skipped":1,"errors":0}
{"event":"progress","command":"clean","type":"project_skipped","path":"/path/to/project-c","reason":"missing_lockfile"}
{"event":"complete","command":"clean","type":"clean_all_complete","projects":3,"deleted":8,"errors":1}

`calvin projects`

List all projects registered in the global Calvin registry.

calvin projects [OPTIONS]

Options:

Option	Description
`--prune`	Remove entries for projects with missing lockfiles

Description:

Every successful calvin deploy registers the project in a global registry at ~/.calvin/registry.toml. This command lists all registered projects, their asset counts, and last deployment times.

Examples:

calvin projects                # List all registered projects
calvin projects --prune        # Remove stale entries
calvin projects --json         # JSON output for scripting

JSON Output:

{
  "event": "data",
  "command": "projects",
  "type": "projects",
  "count": 2,
  "projects": [
    {
      "path": "/path/to/project-a",
      "lockfile": "/path/to/project-a/calvin.lock",
      "last_deployed": "2025-12-24T12:00:00Z",
      "asset_count": 5,
      "lockfile_exists": true
    },
    {
      "path": "/path/to/project-b",
      "lockfile": "/path/to/project-b/calvin.lock",
      "last_deployed": "2025-12-23T10:30:00Z",
      "asset_count": 3,
      "lockfile_exists": true
    }
  ],
  "pruned": []
}

Note: The type field is deprecated. Use event + command instead.

`calvin layers`

Show the resolved multi-layer stack for the current project.

calvin layers [--json]

Description:

Displays all active promptpack layers in priority order (project → custom → user). Shows each layer's path and asset count, plus merged/overridden asset statistics.

Examples:

calvin layers                # Show layer stack with UI
calvin layers --json         # JSON output for scripting

JSON Output:

{
  "event": "data",
  "command": "layers",
  "layers": [
    {
      "name": "project",
      "layer_type": "project",
      "original_path": "./.promptpack",
      "resolved_path": "/path/to/project/.promptpack",
      "asset_count": 5
    },
    {
      "name": "user",
      "layer_type": "user",
      "original_path": "~/.calvin/.promptpack",
      "resolved_path": "/home/user/.calvin/.promptpack",
      "asset_count": 3
    }
  ],
  "merged_asset_count": 7,
  "overridden_asset_count": 1
}

`calvin provenance`

Show lockfile provenance for deployed outputs (source layer, asset, file, overrides).

calvin provenance [OPTIONS]

Options:

Option	Description
`--filter <SUBSTR>`	Filter outputs by substring match on path/key

Description:

Reads the lockfile and displays the source information for each deployed output: which layer, asset, and source file it came from, plus any override relationships.

Examples:

calvin provenance               # Show all outputs with provenance
calvin provenance --filter cursor   # Filter to cursor outputs only
calvin provenance --json        # JSON output

JSON Output:

{
  "event": "data",
  "command": "provenance",
  "type": "provenance",
  "count": 2,
  "entries": [
    {
      "key": "project:.cursor/rules/policy/RULE.md",
      "scope": "project",
      "path": ".cursor/rules/policy/RULE.md",
      "hash": "abc123",
      "source_layer": "project",
      "source_asset": "policy",
      "source_file": ".promptpack/policy.md",
      "overrides": "user"
    }
  ]
}

Note: The type field is deprecated. Use event + command instead.

`calvin init`

Initialize a new .promptpack directory.

calvin init [OPTIONS]

Description:

Creates a new .promptpack directory in the current project with a basic configuration and example assets.

Examples:

calvin init

`calvin version`

Show Calvin + adapter version information.

calvin version [--json]

Deprecated / Hidden Commands

These commands are kept for backward compatibility but are hidden from --help and print a deprecation warning (suppressed in --json).

Deprecated	Replacement
`calvin sync`	`calvin deploy`
`calvin install`	`calvin deploy --home`
`calvin doctor`	`calvin check`
`calvin audit`	`calvin check --strict-warnings`

Debug/placeholder commands (no stable API yet): calvin parse, calvin migrate.

Exit Codes

Code	Meaning
`0`	Success
`1`	Runtime error or failed check
`2`	Invalid arguments

Navigation Menu

Calvin Command Reference

Synopsis

Global Options

Core Commands

`calvin deploy`

`calvin check`

`calvin explain`

`calvin watch`

`calvin diff`

`calvin clean`

`calvin projects`

`calvin layers`

`calvin provenance`

`calvin init`

`calvin version`

Deprecated / Hidden Commands

Exit Codes

See Also

FilesExpand file tree

command-reference.md

Latest commit

History

command-reference.md

File metadata and controls

Calvin Command Reference

Synopsis

Global Options

Core Commands

calvin deploy

calvin check

calvin explain

calvin watch

calvin diff

calvin clean

calvin projects

calvin layers

calvin provenance

calvin init

calvin version

Deprecated / Hidden Commands

Exit Codes

See Also

`calvin deploy`

`calvin check`

`calvin explain`

`calvin watch`

`calvin diff`

`calvin clean`

`calvin projects`

`calvin layers`

`calvin provenance`

`calvin init`

`calvin version`