---
title: "Migrate Application"
description: "Documentation for Migrate Application Command in ZeyOS SDK CLI"
canonical_url: "https://www.zeyos.com/sdk/application-management/zeysdk-migrate"
markdown_url: "https://www.zeyos.com/ai/guide/sdk/application-management/zeysdk-migrate.md"
section: "sdk"
authority: "guide"
language: "en"
source_repository: "zeyos/sdk-v2"
source_path: "docs/application-management/zeysdk-migrate.md"
source_revision: "a99897af74253b4dc5af6fecb9301cea0ae18e27"
---

# Migrate Application

The `migrate` command converts recognized legacy SDK metadata and instance sync files in the current directory to the current layout.

```bash
zeysdk migrate [options]
```

**Options**

| Option | Description |
|--------|-------------|
| `--link` | Link application after migration |
| `--verbose` | Show detailed output |

**Directory Structure Migration**

The command recognizes these legacy files:

- `.zeysdk.assets.json`
- `.zeysdk.package.json`
- `.zeysdk.sync.<INSTANCE_ID>.json`, where the instance ID is a safe SDK identifier

It updates them toward this structure:

```
my-app/
|-- .zeysdk/
|   |-- sync.json                 # Active link, created later by link/use
|   `-- sync.<INSTANCE_ID>.json   # Migrated non-active instance state
|-- assets/
|-- resources/
|-- services/
|-- settings/
|-- weblets/
`-- zeyos.app.json
```

**Process**

1. **Pre-migration Validation**
   - Requires at least one recognized legacy package, assets, or instance sync file
   - Requires each JSON metadata file, including an existing `zeyos.app.json`, to contain a JSON object
   - Requires the merged manifest to contain `identifier` and `name`
   - Refuses to overwrite an existing `.zeysdk/sync.<INSTANCE_ID>.json` destination

2. **Configuration Migration**
   - Merges existing `zeyos.app.json`, then `.zeysdk.assets.json`, then `.zeysdk.package.json`
   - Later sources win when the same property appears more than once
   - Writes the merged result atomically to `zeyos.app.json`

3. **Directory Migration**
   - Creates `.zeysdk` when needed
   - Moves `.zeysdk.sync.<INSTANCE_ID>.json` to `.zeysdk/sync.<INSTANCE_ID>.json`
   - Removes the legacy package and assets files after the new manifest succeeds
   - Preserves existing asset directories and files

4. **Rollback and Optional Linking**
   - Stages legacy metadata files and records moved sync files while migration is in progress
   - Restores moved files and the previous manifest if migration fails
   - Runs the normal interactive `zeysdk link` flow only after migration succeeds when `--link` is used
   - Does not roll the completed file migration back if that later link step fails

**Examples**

```bash
zeysdk migrate
zeysdk migrate --link
zeysdk migrate --verbose
```

**Error Handling**

| Error | Description | Resolution |
|-------|-------------|------------|
| No legacy inputs | No recognized legacy files were found | Run from the legacy app root and verify filenames |
| Invalid metadata | A JSON file is not an object or merged metadata lacks `identifier`/`name` | Repair the legacy metadata before retrying |
| Sync conflict | A destination sync file already exists | Reconcile the old and current sync files manually |
| Permission denied | Cannot modify files | Check file permissions |
| Migration conflict | Incompatible changes | Resolve conflicts manually |
| Link failed | Post-migration link failed | Check instance credentials |

**Notes**

- Migration does not move credentials or create an active `.zeysdk/sync.json`; use `--link`, `zeysdk link`, or `zeysdk use` as appropriate afterward
- Successful migration removes the recognized legacy metadata files; a cleanup failure can leave a `.migrating-<id>` file and emits a warning
- `--link` validates and saves an instance connection after file migration
- `--verbose` shows detailed progress information

**Best Practices**

- Commit or manually copy the legacy hidden files before migration; the normal snapshot glob does not include root files such as `.zeysdk.assets.json`
- Review generated `zeyos.app.json` before pushing changes
- Run `zeysdk compare` after migration to inspect local and remote differences
- Commit the migrated structure separately from feature changes