Migration CLI

Potato includes a migration tool to help upgrade configuration files from older formats to the current v2 format. This tool automatically detects and applies necessary changes while preserving your existing settings.

Usage

# Basic migration (prints migrated config to stdout)
potato migrate config.yaml --to-v2
 
# Save to a new file
potato migrate config.yaml --to-v2 --output new_config.yaml
 
# Modify the original file in place
potato migrate config.yaml --to-v2 --in-place
 
# Preview changes without applying them
potato migrate config.yaml --to-v2 --dry-run

Command Options

Note: --in-place and --output cannot be used together.

Migration Rules

The migration tool applies the following transformations:

1. Textarea to Multiline

Converts the old textarea format to the new multiline format for text schemas.

Before:

annotation_schemes:
  - annotation_type: "text"
    name: "feedback"
    textarea:
      on: true
      rows: 4
      cols: 50

After:

annotation_schemes:
  - annotation_type: "text"
    name: "feedback"
    multiline: true
    rows: 4
    cols: 50

2. Legacy User Config

Detects old user_config format and suggests adding explicit login configuration.

Before:

user_config:
  allow_all_users: true

After:

user_config:
  allow_all_users: true
login:
  type: open

3. Label Requirement Format

Converts boolean label_requirement to the dictionary format.

Before:

annotation_schemes:
  - annotation_type: "multirate"
    name: "ratings"
    label_requirement: true

After:

annotation_schemes:
  - annotation_type: "multirate"
    name: "ratings"
    label_requirement:
      required: true

4. Output Format Suggestions

Provides recommendations when using older output formats. If output_annotation_format is set to csv or tsv, suggests using json for richer annotation data support (spans, metadata).

Examples

Preview Changes (Dry Run)

$ potato migrate old_config.yaml --to-v2 --dry-run
 
Migration changes:
 
[textarea_to_multiline] Convert textarea.on to multiline format:
  - Converted textarea.on to multiline in schema 'feedback'
 
[legacy_user_config] Migrate legacy user_config to login format:
  - Added login.type: open (from allow_all_users: true)
 
Dry run - no changes written.

Migrate and Save to New File

$ potato migrate old_config.yaml --to-v2 --output migrated_config.yaml
 
Migration changes:
...
 
Wrote migrated config to migrated_config.yaml

Quiet Mode

# Just output the migrated YAML, no status messages
$ potato migrate old_config.yaml --to-v2 --quiet > new_config.yaml

When to Use Migration

Consider using the migration tool when:

• Upgrading from an older version of Potato
• You see deprecation warnings when starting the server
• Configuration options don't work as expected
• You want to ensure your config follows current best practices

Troubleshooting

"Configuration file is empty"

The YAML file couldn't be parsed or is empty. Check that:

• The file exists and is readable
• The YAML syntax is valid
• The file contains configuration content

"Invalid YAML in configuration file"

There's a syntax error in your YAML. Common issues:

• Incorrect indentation
• Missing colons after keys
• Unquoted special characters

No migrations needed

If you see "No migrations needed - config is already up to date", your configuration already uses the current v2 format.

Further Reading

• What's New in v2 - Overview of v2 changes
• Configuration Basics - Current configuration format

For implementation details, see the source documentation.