migrate
Migrate an entire project between C# and Calor.
calor migrate <path> [options]
Overview
The migrate command converts all applicable files in a project or directory. It:
- Scans for convertible files
- Creates a migration plan
- Converts files in parallel (optional)
- Generates detailed reports
- Handles errors gracefully without stopping
Quick Start
# Preview migration (dry run)
calor migrate ./src --dry-run
# Migrate C# to Calor
calor migrate ./src
# Migrate with report
calor migrate ./src --report migration-report.md
# Migrate Calor back to C#
calor migrate ./src --direction calor-to-cs
Options
| Option | Short | Default | Description |
|---|---|---|---|
--dry-run | -n | false | Preview changes without writing files |
--benchmark | -b | false | Include before/after metrics comparison |
--direction | -d | cs-to-calor | Migration direction |
--parallel | -p | true | Run conversions in parallel |
--report | -r | None | Save migration report to file (.md or .json) |
--verbose | -v | false | Enable verbose output |
--skip-analyze | — | false | Skip the migration analysis phase |
--skip-verify | — | false | Skip the Z3 contract verification phase |
--verification-timeout | — | 5000 | Z3 verification timeout per contract, in milliseconds |
--explicit-call-closers | — | false | Emit explicit §/C for every §C call (v0.6.0-compatible output). |
--lossy | — | false | Allow reported semantic substitutions or drops. The default is lossless migration |
Migration Plan
Before converting, the command analyzes your codebase and creates a plan:
calor migrate ./src --dry-run
Output:
=== Migration Plan ===
Direction: C# → Calor
Source: ./src
Files to Convert:
✓ 24 files fully convertible
⚠ 8 files partially convertible (will have warnings)
✗ 3 files skipped (unsupported constructs)
Benchmark Summary
Use --benchmark to see aggregate metrics:
calor migrate ./src --benchmark
Output includes:
=== Benchmark Summary ===
Token Savings: 17,090 tokens (37.8% reduction)
Migration Reports
Generate detailed reports for documentation:
# Markdown report
calor migrate ./src --report migration-report.md
# JSON report
calor migrate ./src --report migration-report.json
Each file result in the JSON report carries losses[], where every entry
names its path (interop, rescue, passthrough, lossy, or dropped)
and, for rescues, the trigger and enabledBy that applied. It also carries
conversionPaths, the same per-file summary calor convert --format json
writes (see Which Path Preserved Each Member).
The console summary adds one line when any member was preserved:
Preservation paths: 1 by automatic rescue (parse-failure: 1; no passthrough request needed)
migrate rescues fewer members than convert. It rescues a member whose Calor
does not parse, but not one whose Calor parses and then fails the C# round
trip: migrate checks the round trip once for the whole project, not file by
file. Such a file fails. In the default lossless mode one failed file means no
file is written, so every file then reports outcome: "refused". Its counts
still show what conversion did. calor migrate has no --passthrough option.
For example, take a two-file project: Inventory.cs converts natively, and
Counter.cs has a statement label that fails the C# round trip. calor convert Counter.cs alone rescues Counter as §CSHARP and exits 0. calor migrate on
the project exits 1, writes no .calr file, and reports outcome: "refused" for
both files. The MCP calor_migrate and calor_batch tools give the same result.
To migrate the rest, convert the failing file with calor convert (or fix the C#
first), then migrate the others. The C# interoperability guide
lists which C# shapes convert natively in 0.25 and which can fail the round trip.
Exit Codes
| Code | Meaning |
|---|---|
0 | No files failed; warnings alone do not fail the command |
1 | The path was missing, one or more files failed, or migration raised a handled error |
See Also
- calor convert - Convert single files
- calor assess - Find migration candidates
- Adding Calor to Existing Projects - Complete migration guide