nself migrate-from-v099

One-shot migration for projects still running the v0.9.9 Bash-era CLI. Run it once, then upgrade.

Quick start

# From your existing v0.9.9 project directory:
nself migrate-from-v099

# The command will:
# 1. Inspect your old config files
# 2. Show you exactly what will change
# 3. Ask for confirmation before touching anything
# 4. Produce a v1.0.x-compatible project in place

Synopsis

nself migrate-from-v099 [FLAGS]

Description

ɳSelf v1.0.0 was a complete rewrite of the CLI from Bash to Go, shipped on 2026-03-29. The Go CLI has a different project structure, a new environment cascade, regenerated nginx config, and updated plugin manifests. Projects created with v0.9.9 will not start with the new CLI until they are migrated.

nself migrate-from-v099 is a one-shot helper that does the upgrade automatically. It inspects your existing files, maps old keys to new ones, rewrites the env cascade, regenerates managed configs via nself build, and leaves your hand-managed files (likenginx/conf.d/*.conf and application code) untouched.

Run this command exactly once per project. After it completes, use nself migrate for all future upgrades and schema changes.

What it changes

What it does NOT change

• Your Postgres data — no schema changes, no data loss
• Your application source code
• Files in nginx/conf.d/ — these are hand-managed and preserved as-is
• Any files outside the project directory
• Your plugin license key

Flags

Step-by-step walkthrough

Step 1: Back up and stop the old stack

# Back up your data first
pg_dump -h localhost -U postgres mydb > backup-$(date +%Y%m%d).sql

# Stop the running stack
docker compose down

Step 2: Install the new CLI

brew upgrade nself
nself --version
# nself version 1.0.13

Step 3: Preview the migration

cd my-project
nself migrate-from-v099 --dry-run
# WILL WRITE:   .env.dev (from .env)
# WILL WRITE:   .env.secrets (secrets extracted from .env)
# WILL BACKUP:  docker-compose.yml → .nself-v099-backup/docker-compose.yml
# WILL REMOVE:  docker-compose.yml (will regenerate via nself build)
# WILL BACKUP:  nginx/nginx.conf → .nself-v099-backup/nginx/nginx.conf
# WILL REMOVE:  nginx/nginx.conf (will regenerate via nself build)
# WILL REMOVE:  env keys: HASURA_VERSION, NHOST_AUTH_VERSION, STORAGE_VERSION
# WILL KEEP:    nginx/conf.d/ (hand-managed — untouched)
# WILL KEEP:    All application source code

Step 4: Run the migration

nself migrate-from-v099
# Backing up to .nself-v099-backup/ ...
#
# This will migrate your v0.9.9 project to v1.0.x format.
# Changes shown above. Proceed? [y/N]: y
#
# ✓ .env split into .env.dev and .env.secrets
# ✓ docker-compose.yml backed up and removed
# ✓ nginx/nginx.conf backed up and removed
# ✓ Plugin manifests converted
# ✓ Running nself build to regenerate managed configs...
# ✓ Migration complete.
#
# Next: nself start

Step 5: Start the new stack

nself start
nself status

Troubleshooting

The stack does not start after migration

Run nself doctor for a diagnostic report. The most common cause is a missing env var that was not carried over. Check .env.dev against the output of nself doctor.

Rolling back

The migration stores a snapshot in .nself-v099-backup/. To restore:

cp -r .nself-v099-backup/. .
brew install nself@0.9.9   # if available
docker compose up -d

Custom nginx config in nginx/sites/

Files in nginx/sites/ are managed by nself build and will be overwritten. Move any custom rules to nginx/conf.d/ before running the migration. The dry-run output will warn you if it detects customizations in nginx/sites/.

Environment variables

• NSELF_BACKUP_DIR — alternative way to set the backup directory

Exit codes

• 0 — migration completed successfully
• 1 — migration failed; original files restored from backup
• 2 — invalid arguments or not a v0.9.9 project directory
• 3 — user declined the confirmation prompt

Related

• nself migrate — ongoing migration and schema management after upgrading
• nself doctor — diagnose configuration problems after migration
• nself build — regenerate managed config files