cmd migrate

nself migrate

Moved to nself db in v1.5.0, removed in v1.6.0. The old spelling keeps working until then.

See cmd-db for the current command. Command-Canon lists every move.

Previous content

Detect and migrate ɳSelf v0.9.x projects to the current v1.x format.

Description

nself migrate detects and migrates v0.9.x project artifacts to the current v1.x format. Running nself migrate without a subcommand performs a detection scan, the same as nself migrate detect, and reports which v0.9 artifacts are present.

The run subcommand performs the full automated migration: it stops running containers, backs up the current project state to .nself/backup/{timestamp}/, moves nginx configs from the flat nginx/ layout to nginx/sites/ (v1 layout), regenerates docker-compose.yml, and prints a summary of every change made. The migration is idempotent: running it on an already-migrated project exits cleanly with no changes.

After migration, the CLI prints the exact nself plugin install commands for every v0.9 plugin detected in your .env. Run those commands to re-install your plugins using the signed v1 bundle system.

If anything goes wrong, use nself migrate rollback to restore from the automatic backup.

Note: nself migrate manages v0.9→v1 project migration. For database schema migrations within a v1 project, see cmd-db.

Env cascade order migration (CLI-R18)

Every bare nself migrate run also checks the project's .env cascade for CLI-R18 drift, independent of the v0.9→v1 artifact scan above. CLI-R18 changed the load order (later wins) from:

.env.dev → .env.{staging|prod} → .env.secrets → .env.local → .env → .env.ai

to:

.env → .env.{dev|staging|prod} → .env.secrets → .env.local

with .env.ai eliminated as a cascade layer — its content folds into .env.secrets. For every variable whose winning file or value would differ between the two orders, nself migrate:

• Auto-fixes the common case (bare .env or .env.ai used to win over .env.secrets/.env.{env}): writes the pre-migration effective value into .env.secrets, so the resolved config doesn't silently change. A folded .env.ai is archived to .env.ai.migrated once every one of its keys is resolved this way.
• Flags for manual review the two shapes it refuses to guess on: a personal .env.local override that a committed file was incorrectly shadowing (fixing this automatically would either perpetuate the bug or silently override your personal file), and a dev-only value that was leaking into staging/prod under the old always-load-.env.dev quirk (baking that leak into .env.secrets would just relocate the bug).
• Reports "no change needed" when the two orders already resolve identically — the common case for most projects.

Set NSELF_LEGACY_ENV_ORDER=1 to keep a project on the old order temporarily (one minor version, with a warning on every use) while you review flagged items. See cmd-env → env explain to inspect the cascade in effect at any time, and Config-Env-Vars for the full reference.

Plugin re-install warning

After nself migrate run completes, the output includes a plugin re-install block:

┌─────────────────────────────────────────────────────────┐
│  v0.9 PLUGINS DETECTED — RE-INSTALL REQUIRED            │
│                                                         │
│  v0.9 plugin code is not compatible with v1 signed      │
│  bundles. Re-install your plugins using:                │
│                                                         │
│    nself plugin install ai mux notify cron              │
│                                                         │
│  Your license key is already set.                       │
└─────────────────────────────────────────────────────────┘

The plugin list is generated from PLUGIN_<NAME>=true entries in your v0.9 .env. Plugin names are mapped from v0.9 naming to v1 bundle naming automatically.

Moving from another platform

nself migrate supabase and nself migrate firebase (and the other source spellings) move to nself db import <source> in v1.5, and the old spelling is removed in v1.6.0. In v1.5 mode the command runs the importer pipeline with a verify report; in v1.4 mode the two keep writing migration artifacts. Come-Home lists every source with its guide, command and password result.

CI fixture

A v0.9 test fixture lives at internal/migration/testdata/v0.9-fixture/. The GitHub Actions workflow .github/workflows/migration-fixture.yml runs migration regression tests on every push to main and nightly. To run locally:

go test -mod=vendor -run TestE2E ./internal/migration/...

Examples

# Scan for v0.9 artifacts (non-destructive)
nself migrate
nself migrate detect

# Perform the v0.9→v1 migration
nself migrate run

# Restore from the most recent backup
nself migrate rollback --yes

# List available backups
nself migrate rollback --list

# Restore from a specific backup
nself migrate rollback --backup 20260417-143022 --yes

--yes confirms the restore without a prompt. From v1.5 a rollback without --yes asks on a terminal and is refused with E403 anywhere else (scripts, CI); in v1.4 it still runs but prints a deprecation warning (under --json, in meta.deprecations).

See Upgrade-From-v0.9 for the full step-by-step migration guide.

See Also

• Commands — full command index
• Core-Services — what a stack is made of

← Commands | Home →