# migrate

Migrate artifact files to the current schema version

Canonical URL: https://docs.asterdoc.com/cli/commands/migrate/

Rewrites artifact files written for an earlier [schema version](/schemas#schema-versions) so they follow the current one.

## Usage

```bash
asterdoc migrate <path> [options]
```

## Arguments

| Argument | Description                                        |
| -------- | -------------------------------------------------- |
| `path`   | An artifact file, or a directory of artifact files |

## Options

| Option             | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `--dry-run`        | Print the diff for each file and change nothing                    |
| `--from <version>` | Schema version of files whose `$schema` names no published version |

## Description

Each artifact file names the schema version it follows in `$schema`, such as `https://schema.asterdoc.com/2026-10-28.json`. For each file, `migrate` reads that version, applies every migration step from it to the current version in order, and rewrites the file in place with the current `$schema`.

* A JSON file stays JSON and keeps its indentation. A YAML file stays YAML and keeps its comments.
* The migrated artifact must validate against the current version. If it does not, the file is left unchanged and the failure is reported.
* A step that cannot convert a value safely names the value, and the file is left unchanged.
* A file whose `$schema` names no published version (missing, the undated `schema.json`, an unpublished date, or another address) needs `--from` to name its version.
* A Paradoc artifact, with `$schema` on `schema.paradoc.dev`, is one of these. The [version history](/schemas#version-history) names the version to give `--from`.
* A bundle's inline parts migrate with it, at any depth. A part without `$schema` follows its bundle. A part that declares an earlier version is first brought to its bundle's version, so a current bundle with an outdated part still migrates. A part that declares a later version than its bundle, or no published version, fails and names the part.
* In a directory, `migrate` reads every `.json`, `.yaml`, and `.yml` file outside `node_modules` and `dist`. Files that are not artifacts, such as `package.json`, are skipped. A file that cannot be parsed is reported, and the run continues.

Nothing else changes an artifact file's version: loading never migrates. Every other command that reads an artifact file, such as `validate` or `render`, refuses one that is not the current version and names this command.

## Examples

Review the changes for a directory, then apply them:

```bash
asterdoc migrate forms/ --dry-run
asterdoc migrate forms/
```

Name the version of files that have no `$schema`:

```bash
asterdoc migrate forms/ --from 2026-10-28
```

## Output

```
migrated  forms/lease.yaml  2026-10-28 → 2026-10-28
current   forms/notice.json

1 migrated, 1 current, 0 failed  (schema version 2026-10-28)
```

The command exits with status 1 when any file fails.

## See also

* [Schemas](/schemas) - Schema versions and their addresses
* [validate](/cli/commands/validate) - Validate an artifact against the current schema