How to Use the Archify CLI to Migrate Workflow Schemas: A Complete Guide

The Archify CLI provides a migrate workflow sub-command that converts legacy workflow schemas to the current JSON-IR format by parsing, transforming, and emitting updated JSON files.

Archify's command-line interface streamlines schema upgrades through a dedicated migration toolchain. This article covers the exact commands, flags, and source files you need to migrate workflow definitions from older versions to the current v2 schema.

How the Migration Pipeline Works

The Archify CLI migration process follows a three-step pipeline implemented in the source code. Understanding these stages helps troubleshoot issues and customize transformations.

Step 1: Load the Source Schema

The CLI parses the input workflow JSON file, accepting legacy formats such as v1 schemas with deprecated field structures. The entry point at archify/bin/archify.mjs handles argument parsing and delegates to the migration module.

Step 2: Transform Using Migration Logic

The core transformation occurs in archify/migrations/workflow-v2.mjs. This module performs three operations:

• Maps deprecated fields to their modern equivalents
• Renames node types to match current specifications
• Updates contract versions to v2 compatibility

Step 3: Emit the Validated Output

The CLI writes the transformed schema to a destination file or outputs to stdout for piping. The emitted JSON conforms to the current v2 schema and passes built-in validation rules.

Essential CLI Commands for Workflow Migration

Basic File-to-File Migration

Migrate a legacy workflow and save the result to a new file:

node archify/bin/archify.mjs migrate workflow source.json target.json

This reads source.json, applies the v1→v2 transformation, and writes the validated result to target.json.

Output to STDOUT for Piping

Print the migrated schema as raw JSON without file persistence:

node archify/bin/archify.mjs migrate workflow source.json --json

Use this pattern to chain commands or inspect output before saving.

Combine Migration with Validation

Verify the migrated schema immediately after conversion:

node archify/bin/archify.mjs migrate workflow source.json target.json && \
node archify/bin/archify.mjs validate target.json

This sequential execution ensures migrated workflows pass all validation checks.

Migration Flags and Options

Flag	Purpose
--json	Output raw JSON without pretty-printing
--dry-run	Execute migration without writing files (safe testing)
-h, --help	Display command-specific help documentation

Test Migrations Safely

Preview transformation results before committing changes:

node archify/bin/archify.mjs migrate workflow legacy.json --dry-run

This executes the full pipeline except the final write operation, printing what would change.

Practical Migration Examples

Example 1: Upgrade a Legacy Workflow File

node archify/bin/archify.mjs migrate workflow examples/legacy-workflow.json migrated-workflow.json

This converts a sample legacy definition to the current schema format.

Example 2: Pipe Migrated Output to Another Command

node archify/bin/archify.mjs migrate workflow examples/legacy-workflow.json --json | \
  node archify/bin/archify.mjs view -

The hyphen (-) instructs the receiving command to read JSON from stdin, enabling seamless pipeline construction.

Key Source Files in the Archify Repository

File Path	Function
archify/bin/archify.mjs	CLI entry point; routes sub-commands including migrate, validate, and compare
archify/migrations/workflow-v2.mjs	Implements v1→v2 transformation logic with field mapping and node renaming
archify/test/workflow-migration.test.mjs	Automated test suite verifying migration correctness across edge cases

These files demonstrate how Archify's migration system operates according to the tt-a1i/archify source code. Engineers can reference workflow-v2.mjs to understand specific transformation rules or extend the test suite for custom schema variants.

Version-Specific Migration Behavior

The current implementation supports v1→v2 migrations. The workflow-v2.mjs module encapsulates all transformation knowledge, making future version upgrades modular—new migration files can follow the same pattern for v2→v3 transitions.

Summary

• Use migrate workflow as the primary CLI sub-command for schema upgrades
• Reference archify/migrations/workflow-v2.mjs for transformation logic and field mappings
• Apply --dry-run to preview changes without file modification
• Chain with validate to ensure migrated schemas meet current requirements
• Pipe with --json for integration into automated workflows and CI pipelines

Frequently Asked Questions

What workflow schema versions does Archify support for migration?

Archify currently supports migration from v1 schemas to the v2 JSON-IR format. The migration logic in archify/migrations/workflow-v2.mjs handles all supported transformations, and future versions will follow the same modular pattern for additional upgrade paths.

How can I verify a migration worked correctly before overwriting files?

Use the --dry-run flag to execute the transformation pipeline without writing output, or migrate to a temporary file and run node archify/bin/archify.mjs validate against the result. The test suite at archify/test/workflow-migration.test.mjs also demonstrates expected input-output pairs for verification.

Where does Archify store its migration transformation rules?

All v1→v2 transformation rules reside in archify/migrations/workflow-v2.mjs. This module contains the explicit field mappings, node type renames, and contract version updates applied during migration, making the migration logic inspectable and extensible.

Can I pipe migrated workflow output directly to other Archify commands?

Yes. Use the --json flag to output raw JSON to stdout, then pipe to commands accepting stdin. The pattern migrate workflow input.json --json | archify view - demonstrates this capability, with the hyphen indicating stdin reading.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}