# LifeOS Upgrade Process: How to Update and Maintain Configuration Across Versions

> Learn the LifeOS upgrade process. Run bun Tools/Update.ts --apply for a non-destructive update that preserves your configuration across versions.

- Repository: [Daniel Miessler 🛡️/LifeOS](https://github.com/danielmiessler/LifeOS)
- Tags: how-to-guide
- Published: 2026-08-12

---

**Run the `bun Tools/Update.ts --apply` command to perform an idempotent, non-destructive upgrade that preserves all user-created files.**

LifeOS upgrades are designed to be **additive and non-destructive**, ensuring your personal configuration remains intact while system files are updated. This guide covers the complete upgrade workflow based on the [[`LifeOS/Workflows/Update.md`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Workflows/Update.md)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Workflows/Update.md) specification and the TypeScript toolchain in `LifeOS/Tools/`.

## Understanding the Core Upgrade Philosophy

The LifeOS upgrade process follows one immutable rule: **"Update is additive and non-destructive"** [[1]](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Workflows/Update.md#L34-L36). This means:

- No user-created files are removed
- No custom settings are overwritten
- Only system-owned components are updated or added

## The 7-Step Update Workflow

Each upgrade executes the following sequence, enforced by [[`LifeOS/Tools/Update.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/Update.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/Update.ts):

### 1. Environment Detection

```bash
bun Tools/DetectEnv.ts

```

[[`DetectEnv.ts`](https://github.com/danielmiessler/LifeOS/blob/main/DetectEnv.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DetectEnv.ts) identifies your OS, shell harness, and `<configRoot>` path. All subsequent operations use these detected paths—nothing is hard-coded.

### 2. Version Comparison

The system reads `<configRoot>/LIFEOS/VERSION` and queries `https://api.github.com/repos/<LIFEOS_REPO>/releases/latest`. If behind, it re-runs [`install.sh`](https://github.com/danielmiessler/LifeOS/blob/main/install.sh). The **VERSION file** serves as the install marker, preventing false "already current" states.

### 3. System Overlay (Copy-Missing)

```bash
bun Tools/DeployCore.ts --apply

```

[[`DeployCore.ts`](https://github.com/danielmiessler/LifeOS/blob/main/DeployCore.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DeployCore.ts) copies new system templates (e.g., `CLAUDE/`, [`settings.system.json`](https://github.com/danielmiessler/LifeOS/blob/main/settings.system.json)) using **copy-missing semantics**: only files that don't exist are added.

### 4. Hook Re-Merge

```bash
bun Tools/InstallHooks.ts --apply

```

[[`InstallHooks.ts`](https://github.com/danielmiessler/LifeOS/blob/main/InstallHooks.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/InstallHooks.ts) merges new hook entries into [`settings.json`](https://github.com/danielmiessler/LifeOS/blob/main/settings.json), with automatic backup. Hook merging is **deduplicated**—your custom hooks survive intact.

### 5. User Template Scaffolding

```bash
bun Tools/ScaffoldUser.ts --apply

```

[[`ScaffoldUser.ts`](https://github.com/danielmiessler/LifeOS/blob/main/ScaffoldUser.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ScaffoldUser.ts) adds **new** USER template files (e.g., [`Goals.md`](https://github.com/danielmiessler/LifeOS/blob/main/Goals.md), [`Identity.md`](https://github.com/danielmiessler/LifeOS/blob/main/Identity.md)) without touching your existing personal templates.

### 6. Import Activation

```bash
bun Tools/ActivateImports.ts --apply

```

[[`ActivateImports.ts`](https://github.com/danielmiessler/LifeOS/blob/main/ActivateImports.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ActivateImports.ts) inserts new import lines into the system prompt, preserving existing ones.

### 7. Verification

Evidence classes confirm hooks fire and imports resolve before the upgrade completes.

## How Configuration Persistence Works

Three mechanisms protect your setup:

| Mechanism | Location | Protection Method |
|-----------|----------|-----------------|
| **User-owned tree** | `<configRoot>/LIFEOS/USER_TEMPLATES/` | Copy-missing strategy in [`ScaffoldUser.ts`](https://github.com/danielmiessler/LifeOS/blob/main/ScaffoldUser.ts) |
| **Version marker** | `<configRoot>/LIFEOS/VERSION` | Overwritten only by new payload, never stale copies |
| **Settings merge** | [`settings.json`](https://github.com/danielmiessler/LifeOS/blob/main/settings.json) | Deduplicated hook merging with backup |

## Running the Complete Upgrade

### Quick Method (Recommended)

```bash

# Dry-run first to preview changes

bun Tools/Update.ts

# Apply the upgrade

bun Tools/Update.ts --apply

```

### Manual Step-by-Step

```bash

# 1. Detect environment

bun Tools/DetectEnv.ts

# 2. Overlay system files

bun Tools/DeployCore.ts --apply

# 3. Merge new hooks

bun Tools/InstallHooks.ts --apply

# 4. Scaffold new user templates

bun Tools/ScaffoldUser.ts --apply

# 5. Activate new imports

bun Tools/ActivateImports.ts --apply

```

All tools default to **dry-run mode**. The `--apply` flag is required for actual changes.

## Handling Legacy Migrations

Pre-7.x aliases (like the old `pai` command) are automatically redirected. The Update workflow adjusts your shell rc file to point legacy aliases to the new launcher, preserving muscle memory [[2]](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Workflows/Update.md#L24-L30).

## Key Upgrade Files Reference

| File | Purpose |
|------|---------|
| [[`LifeOS/Workflows/Update.md`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Workflows/Update.md)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Workflows/Update.md) | Canonical upgrade documentation |
| [[`LifeOS/Tools/Update.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/Update.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/Update.ts) | Main orchestration script |
| [[`LifeOS/Tools/DetectEnv.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DetectEnv.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DetectEnv.ts) | Environment detection |
| [[`LifeOS/Tools/DeployCore.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DeployCore.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DeployCore.ts) | System file deployment |
| [[`LifeOS/Tools/InstallHooks.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/InstallHooks.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/InstallHooks.ts) | Hook merging |
| [[`LifeOS/Tools/ScaffoldUser.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ScaffoldUser.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ScaffoldUser.ts) | User template scaffolding |
| [[`LifeOS/Tools/ActivateImports.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ActivateImports.ts)](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ActivateImports.ts) | Import activation |

## Summary

- **LifeOS upgrades are idempotent**—run `bun Tools/Update.ts --apply` safely again and again.
- **Your configuration is never overwritten**—copy-missing semantics protect all user files in `USER_TEMPLATES/`.
- **Always dry-run first**—preview changes with commands before using `--apply`.
- **Hooks and imports merge intelligently**—deduplication prevents duplicates while preserving custom entries.
- **Legacy aliases migrate automatically**—no manual intervention needed for pre-7.x setups.

## Frequently Asked Questions

### Will upgrading LifeOS delete my custom templates?

No. The upgrade process uses **copy-missing** logic in [`ScaffoldUser.ts`](https://github.com/danielmiessler/LifeOS/blob/main/ScaffoldUser.ts), which only adds files that don't exist. Your existing templates in `<configRoot>/LIFEOS/USER_TEMPLATES/` remain untouched.

### How do I know if an upgrade is available?

The [`Update.ts`](https://github.com/danielmiessler/LifeOS/blob/main/Update.ts) tool automatically compares your `<configRoot>/LIFEOS/VERSION` file against the latest GitHub release. Run `bun Tools/Update.ts` (without `--apply`) to check status without making changes.

### Can I preview what an upgrade will change before applying it?

Yes. All LifeOS tools default to **dry-run mode**. Simply omit the `--apply` flag to see a JSON plan of proposed changes. This applies to [`Update.ts`](https://github.com/danielmiessler/LifeOS/blob/main/Update.ts), [`DeployCore.ts`](https://github.com/danielmiessler/LifeOS/blob/main/DeployCore.ts), [`InstallHooks.ts`](https://github.com/danielmiessler/LifeOS/blob/main/InstallHooks.ts), and all other upgrade tools.

### What happens to my custom hooks in settings.json during an upgrade?

They are preserved. [`InstallHooks.ts`](https://github.com/danielmiessler/LifeOS/blob/main/InstallHooks.ts) performs **deduplicated merging**—new hooks from the release are added, existing hooks (including your custom ones) remain unchanged, and a backup of [`settings.json`](https://github.com/danielmiessler/LifeOS/blob/main/settings.json) is created before any modification.