Skip to main content
The moon migrate command helps you migrate existing moon workspaces to newer versions by automatically updating configuration files, renaming settings, and applying breaking changes. 
moon migrate <subcommand>

​
Subcommands

​
v2

Migrate an existing moon v1 workspace to moon v2. 
moon migrate v2 [options]

​
Options

​
--yes

Useful for automated migration scripts or CI/CD pipelines.

​
How it works

The migration process:
  1. Prompts for confirmation - Unless --yes is provided, asks before modifying files
  2. Migrates configuration files in this order:
    • workspace.yml - Core workspace settings
    • toolchain.yml → toolchains.yml - Toolchain configuration
    • tasks.yml and tasks/**/*.yml - Global and inherited task configs
    • **/moon.yml - Individual project configurations
  3. Updates settings automatically:
    • Renames deprecated settings
    • Removes obsolete options
    • Restructures configuration to match v2 schema
    • Converts variable syntax ($projectName → $projectTitle)
  4. Reformats files - Strips comments and standardizes YAML formatting
The migration will strip all comments from configuration files and re-format them. Make sure to commit any important comments or documentation before running the migration.
Pkl-based configuration files (.pkl extension) cannot be automatically migrated. You’ll need to manually update these files.

​
Migration changes

​
Workspace configuration

Changes applied to workspace.yml:
  • runner → pipeline
  • unstable_remote → remote
  • vcs.manager → vcs.client
  • vcs.syncHooks → vcs.sync
  • codeowners.syncOnRun → codeowners.sync
  • codeowners.orderBy: project-name → project-id
  • constraints.enforceProjectTypeRelationships → constraints.enforceLayerRelationships
  • docker.scaffold.include → docker.scaffold.configsPhaseGlobs
  • docker.prune.installToolchainDeps → docker.prune.installToolchainDependencies
  • Removes: experiments, docker.scaffold.copyToolchainFiles, hasher.batchSize, pipeline.archivableTargets
  • Extracts extensions to separate extensions.yml file

​
Toolchain configuration

Changes applied when migrating toolchain.yml → toolchains.yml:
  • File renamed from toolchain.yml to toolchains.yml
  • Node.js settings:
    • node.binExecArgs → node.executeArgs
    • node.bun, node.npm, node.pnpm, node.yarn → separate toolchain entries
    • Removes: node.addEnginesConstraint
    • Moves package manager settings to javascript section
  • Python settings:
    • python → unstable_python
    • python.pip, python.uv → unstable_pip, unstable_uv
    • Removes: rootRequirementsOnly, rootVenvOnly
  • Deno settings:
    • Removes: deno.depsFile, deno.lockfile
  • All unstable settings promoted to stable (removes unstable_ prefix)

​
Task configuration

Changes applied to tasks.yml, tasks/**/*.yml, and project tasks:
  • platform → toolchains
  • command → script (if command contains shell operators: ||, &&, |, ;, >, >>, <)
  • local: true → preset: server
  • preset: watcher removed
  • deps[].args converted from string to array
  • Renames tasks.yml → tasks/all.yml
  • Adds inheritedBy field based on file name patterns:
    • tag-* → { tag: "*" }
    • Detects toolchain, stack, layer, language from filename

​
Project configuration

Changes applied to **/moon.yml files:
  • type → layer
  • platform → toolchains.default
  • toolchain → toolchains
  • project.name → project.title
  • project.metadata flattened into project
  • docker.scaffold.include → docker.scaffold.sourcesPhaseGlobs
  • toolchains.*.disabled removed
  • Task changes applied (same as task configuration above)

​
Variable syntax

All token variables updated:
  • $projectName → $projectTitle
  • $projectType → $projectLayer
  • $taskPlatform → $taskToolchain

​
Examples

​
Interactive migration

moon migrate v2
You’ll be prompted: 
? Migrate configuration files?
  This will strip comments and re-format the files.
  [y/N]
Type y to proceed with the migration.

​
Automatic migration

moon migrate v2 --yes
All migrations will be applied immediately without prompts. Perfect for automation: 
#!/bin/bash
# Backup workspace
tar -czf workspace-backup.tar.gz .moon/ **/moon.yml

# Run migration
moon migrate v2 --yes

# Verify and commit
git add -A
git commit -m "chore: migrate to moon v2"

​
Before and after examples

​
Workspace configuration

Before (v1): 
runner:
  cacheLifetime: 24h

vcs:
  manager: git
  syncHooks: true

experiments:
  - action-pipeline-v2
After (v2): 
pipeline:
  cacheLifetime: 24h

vcs:
  client: git
  sync: true

​
Task configuration

Before (v1 - tasks.yml): 
tasks:
  build:
    command: 'tsc && vite build'
    platform: node
After (v2 - tasks/all.yml): 
tasks:
  build:
    script: 'tsc && vite build'
    toolchains:
      - node

​
Project configuration

Before (v1): 
type: application
platform: node

project:
  name: My API
  metadata:
    tier: 1

tasks:
  start:
    command: node server.js
    local: true
After (v2): 
layer: application

toolchains:
  default: node

project:
  title: My API
  tier: 1

tasks:
  start:
    command: node server.js
    preset: server

​
Best practices

  1. Backup first - Always commit your current configuration or create a backup before migrating: 
    git add -A && git commit -m "chore: backup before v2 migration"
  2. Review changes - After migration, review all changed files: 
    git diff
  3. Test thoroughly - Run your tasks to ensure everything still works: 
    moon check --all
  4. Update documentation - If you have internal docs referencing old settings, update them
  5. Handle Pkl files manually - Pkl configuration files must be migrated by hand

​
Limitations

  • Pkl files not supported - .pkl configuration files cannot be auto-migrated
  • Comments are removed - All YAML comments will be stripped during migration
  • Custom formatting lost - Files are reformatted using standard YAML formatting
  • No rollback - The command doesn’t create automatic backups; use version control

​
Exit codes

  • 0 - Migration completed successfully
  • Non-zero - Migration failed or was cancelled

Build docs developers (and LLMs) love

Get started for freeTalk to us