Upgrading from nSelf v0.9 to v1.0.9

nSelf v1.0.0 shipped on 2026-03-29 with a complete CLI rewrite from Bash to Go. If you are running a v0.9.x project, this post walks you through what changed and exactly how to upgrade.

The short version: run brew upgrade nself-org/nself/nself, then nself migrate run in your project directory. That is it.

Why we rewrote the CLI in Go

The v0.9 Bash CLI was a single nself.sh script that orchestrated Docker Compose. It worked, but it had real problems:

• Shell scripts are hard to test. A typo in a conditonal can ruin a production deploy.
• Cross-platform support was fragile. macOS and Linux behaved differently in ways we kept patching.
• Distribution required curl-piping a 4,000-line shell script. Users were rightly skeptical.
• Adding new features meant more Bash, which meant more fragility.

v1.0.0 is a single Go binary. It ships as a self-contained executable for macOS (arm64 + amd64), Linux (amd64 + arm64), and Windows (WSL2). Install once via Homebrew or a one-line installer. No dependencies, no shell bootstrap, no chmod +x.

The CLI now has 161 source files, 40 test files, and 1,900+ test cases. We run the same binary in development and production on nself.org. The Go rewrite was a prerequisite for the reliability guarantee in v1.0 LTS.

What changed from v0.9 to v1.0.9

The CLI itself. nself.sh start is now nself start. The bootstrap script is gone. The binary handles everything.

Plugin format. v0.9 plugins were shell scripts. v1.0 plugins are signed Go bundles, verified against our registry. This means every plugin that worked with v0.9 needs to be re-installed using the new system. The license key format is the same; the installation method changed.

Environment files. v0.9 used a single .env file for everything — development defaults, production secrets, all in one place. v1.0 introduces an env cascade:

.env.dev     → team defaults (tracked in git)
.env.local   → your machine overrides (gitignored)
.env.prod    → production config (tracked, no secrets)
.env.secrets → real credentials (gitignored)

Your old .env still works, but the new cascade gives you proper secret isolation.

Nginx layout. v0.9 stored nginx configs directly in nginx/. v1.0 uses nginx/sites/ for managed configs and nginx/conf.d/ for hand-edited fragments. The migration handles this automatically.

How to upgrade

Step 1: Upgrade the CLI

# macOS
brew upgrade nself-org/nself/nself

# Linux
curl -fsSL https://install.nself.org | bash

# Verify
nself --version
# nself v1.0.9 (darwin/arm64)

Step 2: Run the migration

Navigate to your v0.9 project directory and run:

cd ~/my-nself-project

# See what will be migrated
nself migrate detect

# Run the migration
nself migrate run

The migration stops your containers, backs up the current project state to .nself/backup/{timestamp}/, moves your nginx configs to the v1 layout, and regenerates docker-compose.yml. It is idempotent: running it on an already-migrated project exits cleanly.

Step 3: Re-install plugins

v0.9 plugin code is not compatible with v1 signed bundles. After the migration, the CLI prints the exact commands to re-install each plugin it detected in your v0.9 .env.

nself license set nself_pro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
nself plugin install ai mux claw notify cron

Step 4: Verify

nself build
nself start
nself doctor

If anything goes wrong, you can restore from the automatic backup:

nself migrate rollback

What the P94 release adds for v0.9 users

Beyond the migration tooling, v1.0.9 includes several improvements that directly benefit users upgrading from v0.9:

• nself start, nself build, and nself up now detect v0.9 project artifacts and give a clear error with the migration URL rather than failing with a confusing Docker error.
• nself doctor --check-legacy scans your host for stale v0.9 global paths (~/.nself/, ~/.nself/plugins/, /usr/local/share/nself) and tells you exactly what to clean up.
• The nself migrate run output now shows the exact nself plugin install command for your specific plugin list, not a generic instruction.
• The CLI update check (nself update) surfaces the migration guide URL directly in the terminal when running a v0.9 CLI.

Getting help

• Full migration guide with command reference and troubleshooting: docs.nself.org/migrate/from-v0.9
• GitHub Discussions: github.com/nself-org/cli/discussions
• Discord: discord.nself.org

If you run into a migration edge case that is not covered, open a discussion on GitHub. We read every one.