Migrate command

Migrate from other rule management tools like Ruler.

Overview

The migrate command helps you transition from other rule management tools to AlignTrue. Currently supports migration from Ruler.

Usage

aligntrue migrate <subcommand> [options]

Subcommands

ruler - Migrate from Ruler to AlignTrue

Automatically detects and converts Ruler configurations to AlignTrue format.

What it does:

1. Detects .ruler/ directory and validates structure
2. Copies all .ruler/*.md files to .aligntrue/rules/ (preserving directory structure)
3. Optionally includes AGENTS.md if it exists and wasn’t generated by AlignTrue
4. Converts ruler.toml to .aligntrue/config.yaml (imports enabled exporters)
5. Optionally keeps .ruler/ directory for reference

Prerequisites:

• .ruler/ directory exists in current project
• At least one .md file in .ruler/

Examples:

# Interactive migration (prompts for confirmation)
aligntrue migrate ruler
 
# Migrate without prompts
aligntrue migrate ruler --yes
 
# Preview migration without making changes
aligntrue migrate ruler --dry-run

Example output:

Migrating from Ruler to AlignTrue

Copying files from .ruler/ to .aligntrue/rules/...
  ✓ 5 files copied

AGENTS.md found (not generated by AlignTrue)
? Include AGENTS.md in your rules? (y/N)

Note: .aligntrue/rules/ had existing files. Please review for duplicates.

Migration complete! Run "aligntrue sync" to export your rules to configured agents.

Notes:

• Ruler migration is also offered during aligntrue init if a .ruler/ directory is detected
• Existing files in .aligntrue/rules/ are preserved; review for duplicates
• The .ruler/ directory can be kept for reference or removed

Flags

Exit codes

• 0 - Success
• 1 - Validation error (e.g., .ruler/ not found)
• 2 - System error (permissions, disk space, etc.)

Troubleshooting

”No .ruler directory found” error

Cause: You’re trying to run ruler migration but there’s no .ruler/ directory.

Fix:

1. Verify you’re in the correct project directory
2. Check if rules are in a different location
3. If you don’t have a .ruler/ directory, start fresh with aligntrue init

Remote sync

To push your local rules to a remote git repository, configure remotes in your config:

# .aligntrue/config.yaml
remotes:
  shared:
    url: git@github.com:yourusername/rules-backup.git
    branch: main
  personal: git@github.com:yourusername/rules-backup.git

See Personal Repository Setup for details.

See also

• Personal Repository Setup - Setting up remotes for pushing rules
• CLI Reference - All CLI commands