Clean Command Guide

The clean command removes files that Calvin has deployed, helping you maintain control over your AI assistant configurations.

When to Use Clean

Use clean when you need to:

• Remove all deployments before switching to a new promptpack
• Clean up a specific scope (home or project) without affecting the other
• Test from scratch by starting with a clean slate
• Undo accidental deployments safely

Basic Usage

Interactive Mode

Simply run calvin clean without arguments to enter interactive mode:

calvin clean

This displays a tree menu where you can select exactly which files to remove:

▼ ● Deployments (135 files)
  ▼ ○ Home (~/) (108 files)
    ▶ ○ claude-code (27 files)
    ▶ ● cursor (27 files)
    ▶ ◐ antigravity (27 files)
  ▶ ○ Project (./) (27 files)

───────────────────────────────────────────────────
Selected: 54 files from 2 targets
● = selected    ◐ = partial    ○ = not selected
───────────────────────────────────────────────────
[a] All    [n] None    [i] Invert    [Enter] Confirm    [q] Quit

Keyboard Controls

Command Line Options

For non-interactive use, specify the scope explicitly:

# Clean home directory deployments
calvin clean --home --yes

# Clean project directory deployments
calvin clean --project --yes

# Clean all deployments
calvin clean --all --yes

Available Options

Safety Features

Calvin's clean command includes several safety measures:

1. Signature Verification

Only files containing Calvin's signature are deleted:

<!-- Generated by Calvin. DO NOT EDIT. -->

Files without this signature are skipped to prevent deleting user-created content.

Skills note: skill supplemental files (scripts, reference docs) may not contain signature markers. Calvin treats these as safe-to-delete only when the skill directory’s SKILL.md file is Calvin-signed.

2. Hash Verification

Files are checked against their recorded hash. If a file was modified after deployment, it's skipped unless --force is used.

3. Lockfile Tracking

Only files tracked in the relevant lockfile are considered:

• Project deployments: ./calvin.lock
• Home deployments: ~/.calvin/calvin.lock

The lockfile is updated after deletion to reflect the current state.

4. Confirmation Prompt

A confirmation is required before deletion (unless --yes is specified).

Common Workflows

Preview Before Cleaning

Use --dry-run to see what would be deleted:

calvin clean --home --dry-run

Output:

🧹 Calvin Clean (Dry Run)

Source: .promptpack
Scope: Home (~)

Files to be deleted:
  - ~/.claude/commands/workflow.md
  - ~/.cursor/rules/coding-style.mdc
  - ~/.cursor/rules/testing.mdc

╭─────────────────────────╮
│ Dry Run Complete        │
│                         │
│ 3 files would be deleted│
╰─────────────────────────╯

Clean and Redeploy

To ensure a fresh deployment:

calvin clean --all --yes
calvin deploy --yes

CI/CD Usage

For automated environments, use JSON output:

calvin clean --all --yes --json

Output:

{"type":"clean_start","scope":"all","file_count":5}
{"type":"file_deleted","path":"~/.claude/commands/workflow.md","key":"home:~/.claude/commands/workflow.md"}
{"type":"clean_complete","deleted":5,"skipped":0,"errors":0}

Handling Edge Cases

Modified Files

Files that were modified after deployment are skipped by default:

⚠️  1 file skipped (modified)
    - ~/.cursor/rules/custom.mdc (modified)

Use --force to delete them anyway:

calvin clean --home --yes --force

Missing Files

If a file in the lockfile no longer exists, it's silently removed from the lockfile.

Permission Issues

Files that can't be deleted due to permissions are skipped and reported:

✗ Failed to delete 1 file:
    - ~/.claude/commands/protected.md: Permission denied

Integration with Deploy

The clean command is independent from deploy. This design allows:

• Explicit control: You decide when to clean, not the system
• Safe experimentation: Test deployments without worrying about accidental cleanup
• Predictable behavior: Each command does one thing well

For cleaning orphan files (files previously deployed but no longer generated), use:

calvin deploy --cleanup

Troubleshooting

"No lockfile found"

The clean command requires a lockfile to know which files to remove. Run calvin deploy first to create one.

Files Not Being Deleted

1. Check if the file has Calvin's signature
2. Verify the file hash matches the lockfile
3. Try --force to bypass checks

Interactive Mode Not Working

Interactive mode requires:

• A TTY terminal (not piped input)
• No --yes or --dry-run flags
• No explicit scope (--home / --project / --all)