# How to Update LoopX to the Latest Version: A Step-by-Step Guide

> Easily update LoopX with our step-by-step guide. Learn to preview changes, execute updates, and rollback to previous versions using simple commands. Keep LoopX current effortlessly.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-08

---

**Update LoopX using `loopx update --check` to preview changes and `loopx update --execute` to apply them, with automatic rollback support via `loopx update --rollback previous`.**

LoopX is a self-contained CLI binary distributed through a one-line install script. Keeping it current requires understanding its built-in **self-update mechanism** located in [`loopx/self_update.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/self_update.py). This guide walks through the complete update workflow as implemented in the [huangruiteng/loopx](https://github.com/huangruiteng/loopx) repository: verifying your installation, running dry-run checks, executing updates, and rolling back if needed.

## Verify Your Current LoopX Installation

Before updating, run the **health check** command to establish a baseline. The `loopx doctor` command gathers *install freshness* data that the updater compares against remote sources.

This verification step is implemented in [`loopx/doctor.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/doctor.py) and invoked by `collect_doctor()` inside [`self_update.py`](https://github.com/huangruiteng/loopx/blob/main/self_update.py):

```bash
loopx doctor

```

The doctor output includes your current version, installation path, and runtime health metrics. Save this output—it becomes your reference point if you need to rollback later.

## How to Check for LoopX Updates Without Installing (Dry-Run)

LoopX provides a **check-only mode** that builds an update plan without modifying your system. The `loopx update --check` command assembles this plan through `build_update_plan()` in [`self_update.py`](https://github.com/huangruiteng/loopx/blob/main/self_update.py).

The dry-run performs three operations:

- **Pulls the remote archive URL** — defaults to a GitHub tarball (lines 31-41 in [`self_update.py`](https://github.com/huangruiteng/loopx/blob/main/self_update.py))
- **Looks up the latest version** — via `_source_version_check()` (lines 24-36)
- **Evaluates upgrade necessity** — using `_runtime_activation_qualification()` to compare your current runtime against the target commit (lines 76-90)

```bash
loopx update --check

```

The output is a markdown-formatted plan generated by `render_update_plan_markdown()`. This report shows:
- Whether an upgrade is required
- The exact version differences
- The installer command that would execute

*Pipe this to a file for review: `loopx update --check > update_plan.md`*

## How to Execute a LoopX Update

When the dry-run confirms a newer version is available, apply it with the **execute flag**:

```bash
loopx update --execute

```

The `execute_update_plan()` function (lines 35-43 and 55-62 in [`self_update.py`](https://github.com/huangruiteng/loopx/blob/main/self_update.py)) handles the actual upgrade:

1. Streams the installer script from the remote source
2. Replaces the binary at `~/.local/bin/loopx` (via symlink swap)
3. Automatically runs `loopx doctor` to verify the new binary functions correctly

The entire process is **atomic**—if the doctor check fails, the operation aborts before the symlink switch completes.

## How to Roll Back a LoopX Update

LoopX maintains **rollback safety** through automatic snapshot preservation. If an update causes issues, revert using:

```bash

# Roll back to the immediately previous release

loopx update --rollback previous

# Or specify a specific release ID

loopx update --rollback <release-id>

```

The rollback mechanism in `build_rollback_plan()` (lines 27-42) and its executor (lines 3-13 and 84-92) performs:

- Symlink swap at `~/.local/bin/loopx` to point at the chosen snapshot
- Automatic `loopx doctor` execution to confirm restored health

Rollback plans are generated during every successful update, ensuring you always have a recovery path.

## Complete LoopX Update Workflow Example

```bash

# 1. Verify current state

loopx doctor

# 2. Preview the update (no changes made)

loopx update --check

# 3. Apply the update

loopx update --execute

# 4. Verify new version

loopx doctor

# 5. If issues occur, roll back

loopx update --rollback previous

```

## Key Implementation Files in LoopX

Understanding these source files deepens your confidence in the update process:

| File | Purpose | Key Functions |
|------|---------|-------------|
| [`loopx/self_update.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/self_update.py) | Core update orchestration | `build_update_plan()`, `execute_update_plan()`, `build_rollback_plan()`, `_source_version_check()`, `_runtime_activation_qualification()`, `render_update_plan_markdown()` |
| [`loopx/doctor.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/doctor.py) | Health check implementation | Supplies *install freshness* payload via `collect_doctor()` |
| [`loopx/upgrade.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/upgrade.py) | Host automation prompts | Unrelated to binary updates; builds heartbeat plans for managed environments |

## Summary

- **Always start with `loopx doctor`** to establish a baseline before updating
- **Use `loopx update --check`** to preview changes risk-free
- **Execute with `loopx update --execute`** for atomic, verified upgrades
- **Recover with `loopx update --rollback previous`** if updates fail
- The entire workflow is implemented in [`loopx/self_update.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/self_update.py) with automatic health verification at every stage

## Frequently Asked Questions

### What happens if a LoopX update fails mid-installation?

LoopX uses atomic symlink swaps in `execute_update_plan()`. If `loopx doctor` fails after the binary replacement, the operation aborts and the original symlink remains intact. No partial installations persist.

### Can I update LoopX without internet access?

No. The `_source_version_check()` function in [`self_update.py`](https://github.com/huangruiteng/loopx/blob/main/self_update.py) requires network access to query the remote version and download the GitHub-hosted tarball. Offline updates are not supported.

### Where does LoopX store previous versions for rollback?

Rollback snapshots are preserved alongside the active binary. The `build_rollback_plan()` function maintains references to these snapshots, and the symlink at `~/.local/bin/loopx` switches between them.

### Is `loopx upgrade` the same as `loopx update`?

No. According to [`loopx/upgrade.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/upgrade.py), the `upgrade` command generates heartbeat prompts for host automation systems. The binary update mechanism lives exclusively in [`loopx/self_update.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/self_update.py) under the `update` subcommand.