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

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. This guide walks through the complete update workflow as implemented in the 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 and invoked by collect_doctor() inside self_update.py:

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.

The dry-run performs three operations:

• Pulls the remote archive URL — defaults to a GitHub tarball (lines 31-41 in 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)

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:

loopx update --execute

The execute_update_plan() function (lines 35-43 and 55-62 in 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:

# 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

# 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	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	Health check implementation	Supplies install freshness payload via collect_doctor()
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 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 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, the upgrade command generates heartbeat prompts for host automation systems. The binary update mechanism lives exclusively in loopx/self_update.py under the update subcommand.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}