Skip to main content
Version: Next

Upgrades and migration

Run shine --version before upgrading and read every item that applies to your starting version and the features you use. When skipping versions, these requirements apply cumulatively; the groups below do not require installing each intermediate release. Prepare the applicable configuration or script changes below before updating the program.

When upgrading from 1.x, also read Upgrade from Shine 1.x.

This page covers advance preparation and manual migration. For new features and fixes, see Release notes.

Review external App presets when moving to 2.10​

If you maintain App presets with Bun scripts, use Shine 2.10 to run shine preset lint ./my-presets before using them in automation. Shine can now recognize undeclared access that 2.9 missed, such as a read through a saved Bun.file handle. For each blocking finding, correct the script or declare the access it needs, then run lint again. See App code checks.

From 2.7.x or earlier: SSH and downgrade planning​

  • If you use Shine over SSH, coordinate both ends before upgrading. Upgrade the local and remote installations together, then reconnect; updating only one end can interrupt existing workflows.
  • Before enabling SSH file authorization, back up your policies and review the file authorization migration. Existing environment-variable policies do not authorize files. Downgrading the binary does not undo a policy migration.
  • Keep a compatible Shine version for installed Apps. After the newer version writes App state, Shine 2.7.x and earlier cannot read it. Before downgrading, back up configuration and use the newer version to complete uninstall as described in Upgrade and downgrade. Do not delete installation records to bypass the compatibility check.

From 2.6.x or earlier: Preset environment inputs​

When upgrading from 2.6 or earlier, review these compatibility changes before updating external Presets or automation. Source builds now require Rust 1.90; prebuilt binaries do not require Rust.

Convert legacy Preset environment inputs. Shell Bun commands and App generators, hooks and artifacts require structured env entries containing source, optional target, and sensitivity. Legacy string arrays are rejected. Use Shine 2.7 or later to preview the conversion before applying it; the migrator automatically backs up the metadata it changes:

OperationCommand
Preview this source's migrationshine preset migrate ./my-presets --dry-run
Apply after reviewing the previewshine preset migrate ./my-presets
Validate the migrated metadatashine preset validate ./my-presets
Check authoring issuesshine preset lint ./my-presets

The migrator needs explicit sensitivity from the old declarations; missing or conflicting classifications require manual correction. Migrate Git-managed overlays in their upstream checkout, then pull again. Migration backs up metadata but does not execute scripts, decrypt values, or renew trust. Review changed external snapshots before normal install/upgrade. See runtime environment inputs.

From 2.5.x or earlier: uninstall scripts​

Shine 2.6 removes --purge from uninstall, app uninstall, and shell uninstall. Remove that option from scripts; commands that still contain it fail before loading configuration.

From 2.3.x or earlier: replace HTTP service dependencies​

Shine 2.4.0 removed the old HTTP service. If applications such as Surge or Clash Verge still reference it, switch them to local files before upgrading. Replace SHINE_APP_HTTP_DIR in scripts; application artifacts can keep persistent output in SHINE_STATE_DIR or SHINE_CACHE_DIR.

After updating references and upgrading to 2.4.0 or later, run as the user who installed the service:

shine clear serve

This stops the old service and removes its user service registration, even if the old configuration can no longer be loaded. Before upgrading, the old binary's shine serve uninstall can also remove the service.

Upgrading does not remove files in the old http/ directory. Keep any files you still need and update application references before deleting them.

From 2.3.x or earlier: environment layering​

This release changes value precedence to: built-in defaults < overlay baseline < global [env] < global env file < project [env] < project env file. Older versions ranked overlays and env files differently, so effective values can change after upgrading; no automatic migration preserves the old result. See the configuration reference.

  1. Before upgrading, record important projects' value sources and privately back up configuration you will edit. Keep secrets out of public logs.
  2. Replace old env-write --force usage: use --global --env-file for the global env file, --project --env-file for project env files, and --overlay for a manual overlay. Edit a Git-managed overlay upstream or use local overrides.
  3. After upgrading, run shine env list and shine env explain KEY outside projects and in each important project to confirm the effective sources.
  4. Old explicit entries still take precedence, even when they equal a previous default. Delete an entry with shine env delete and an explicit layer only when you no longer need it, then check inheritance again. Editing a plaintext key does not stop the matching KEY_SECRET from taking precedence.
  5. Run shine update to inspect installed configuration, then review and run shine upgrade. Editing environment values or upgrading the program does not update installed configuration automatically.

Downgrading Shine restores old precedence, but not deleted values or updated application configuration. Restore private backups where needed, checking for later edits before replacing files; there is no dedicated env rollback command. Older versions may write defaults again, but this does not recover deleted custom values.