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

> Easily migrate workflow schemas with the Archify CLI. Learn how to convert legacy schemas to JSON-IR format with this complete guide and ensure seamless workflow updates.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-02

---

**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:

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

```

This reads [`source.json`](https://github.com/tt-a1i/archify/blob/main/source.json), applies the v1→v2 transformation, and writes the validated result to [`target.json`](https://github.com/tt-a1i/archify/blob/main/target.json).

### Output to STDOUT for Piping

Print the migrated schema as raw JSON without file persistence:

```bash
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:

```bash
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:

```bash
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

```bash
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

```bash
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.