# How to Update Archify: Manual Installation and Update Checking Guide

> Learn how to update Archify. This guide details manual installation and update checking for the Archify tool, ensuring you always have the latest stable release.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-12

---

**Archify does not perform automatic self-updates; instead, it checks a fixed, signed manifest for newer stable releases and surfaces notifications to the user, requiring manual installation via package managers or ZIP extraction.**

Archify is an open-source skill framework maintained in the `tt-a1i/archify` repository. While the tool actively monitors for new releases, the actual update process remains strictly manual, giving operators full control over their environments. Understanding this update mechanism requires examining the contract defined in `archify/scripts/update-contract.mjs` and the execution logic in `archify/scripts/check-update.mjs`.

## Understanding Archify's Update Mechanism

Unlike many modern CLI tools, Archify follows a **notification-only update strategy**. The system validates its current state against a remote manifest but never downloads or installs binaries automatically.

### Why Archify Does Not Auto-Update

The `checkForUpdate` function explicitly returns status objects like `update_available` rather than performing modifications. According to the source code in `archify/scripts/check-update.mjs`, this design protects production environments from unexpected changes. When a newer version exists, Archify returns the candidate version, SHA-256 digest, severity level, and release notes URL, leaving the actual installation to the user through standard Skill installation commands such as `npx skills add tt-a1i/archify -g`.

### The Update Check Workflow

The entire flow executes through six distinct phases: local validation, cache preparation, operation reservation, manifest fetching, semantic version comparison, and state persistence. Each phase protects against corrupted state, network abuse, or race conditions when multiple processes check simultaneously.

## How the Update Check Works in `archify/scripts/check-update.mjs`

This module implements the core update-check workflow. It processes the local release descriptor, manages filesystem caching, and determines whether the installed version lags behind the published stable release.

### Local Release Validation

Before checking the network, Archify reads [`archify/skill-release.json`](https://github.com/tt-a1i/archify/blob/main/archify/skill-release.json) to establish identity. The `validateLocalRelease` function verifies the JSON contains authentic version numbers, repository URLs, and manifest URLs. This prevents the checker from comparing against corrupted or tampered local metadata.

### Cache Management and Rate Limiting

To protect users from excessive network calls, Archify implements aggressive caching through `versionCacheDirectory` and `prepareCacheDirectory`. The system creates per-version cache directories storing the last successful check timestamp, offered update candidates, and user acknowledgement flags. By default, the check runs at most once every **72 hours**, significantly reducing network overhead.

### Operation Reservation and Race Condition Prevention

When a fresh check is required, `acquireOperation` calls `reserveOperation` to generate a unique token via `operationName('reserved', …)`. This reservation guarantees that only one process performs the network request at a time, preventing duplicate manifest fetches in concurrent execution environments.

### Fetching the Signed Manifest

The `fetchCandidate` function performs a GET request to `DEFAULT_MANIFEST_URL` with a short timeout. The response must pass `validateStableUpdateManifest`, ensuring it contains:
- **version**: Valid semver string
- **SHA-256 artifact digest**: For integrity verification
- **release notes URL**: For user documentation
- **severity**: Either `normal` or `security`

### Version Comparison and Status Results

After fetching, `compareSemver` evaluates the candidate against the local version. The function returns distinct statuses:
- **`update_available`**: Newer version exists and user has not acknowledged it. Contains `latestVersion`, `digest`, `severity`, `summary`, and release notes link.
- **`current`**: Installed version matches or exceeds the manifest version.
- **`already-notified`**: User previously acknowledged this specific update candidate.

All results trigger `commitOperation` to persist state to the cache directory.

## Disabling Update Checks

Set the environment variable `ARCHIFY_UPDATE_CHECK_DISABLED=1` to short-circuit the entire workflow. When disabled, `checkForUpdate` immediately returns `silent('runtime-unavailable')`. This configuration is essential for offline environments, air-gapped systems, or CI pipelines where network access is restricted or undesirable.

```bash

# Disable updates for a single command

ARCHIFY_UPDATE_CHECK_DISABLED=1 archify validate

# Or export for the session

export ARCHIFY_UPDATE_CHECK_DISABLED=1

```

## Installing Updates Manually

Archify explicitly delegates installation to the user. After receiving an `update_available` notification, upgrade through one of these methods:

1. **Package Manager**: Run `npx skills add tt-a1i/archify -g` to fetch and install the latest release globally.
2. **Manual Extraction**: Download the release ZIP archive referenced in the manifest using the provided SHA-256 digest for verification, then extract to your Skill directory.

Neither method requires shutting down running Archify processes, though restarting any active sessions ensures the new version loads.

## Code Examples

### Basic Update Check Implementation

Use this pattern in CLI wrappers or startup scripts to surface available updates:

```javascript
import { checkForUpdate } from './archify/scripts/check-update.mjs';

(async () => {
  const result = await checkForUpdate();
  if (result.status === 'update_available') {
    console.log(`🔔 Archify ${result.latestVersion} is available!`);
    console.log(`Release notes: ${result.releaseNotes}`);
  } else {
    console.log(`✅ Archify is up‑to‑date (${result.installedVersion})`);
  }
})();

```

### Disabling Network Checks for CI Environments

Prevent network timeouts in automated pipelines:

```javascript
import { checkForUpdate } from './archify/scripts/check-update.mjs';

process.env.ARCHIFY_UPDATE_CHECK_DISABLED = '1';

(async () => {
  const result = await checkForUpdate();
  // result will be a silent status; no network traffic occurs
  console.log('Update check disabled – result:', result);
})();

```

### Inspecting Cache State Directly

Advanced debugging of the 72-hour cache mechanism:

```javascript
import { readState, defaultCacheDirectory } from './archify/scripts/check-update.mjs';

(async () => {
  const cacheDir = defaultCacheDirectory();
  const state = await readState(cacheDir, '2.17.0-dev.1');
  console.log('Cached check state:', JSON.stringify(state, null, 2));
})();

```

## Summary

- **Archify never auto-updates**; it only checks `archify/scripts/check-update.mjs` to compare local versions against a signed manifest at `DEFAULT_MANIFEST_URL`.
- **Caching limits checks** to once per 72 hours using `versionCacheDirectory` and `prepareCacheDirectory`.
- **Race condition protection** via `acquireOperation` and `reserveOperation` ensures single-process manifest fetching.
- **Disable checks** by setting `ARCHIFY_UPDATE_CHECK_DISABLED=1` for offline or CI environments.
- **Manual installation** requires running `npx skills add tt-a1i/archify -g` or extracting the official ZIP archive after receiving an `update_available` notification.

## Frequently Asked Questions

### Does Archify update automatically?

No. According to the `tt-a1i/archify` source code, Archify only notifies users when updates exist. The `checkForUpdate` function returns status objects like `update_available` but never modifies installed files. Users must manually execute installation commands or extract release archives.

### How often does Archify check for updates?

Archify checks at most once every 72 hours. The `prepareCacheDirectory` function creates per-version state files tracking the last successful check timestamp. This cache prevents excessive network requests to `DEFAULT_MANIFEST_URL` while ensuring users eventually learn about critical security updates.

### How do I disable update notifications?

Set the environment variable `ARCHIFY_UPDATE_CHECK_DISABLED=1` before running Archify. This short-circuits the entire check flow in `archify/scripts/check-update.mjs`, causing `checkForUpdate` to return `silent('runtime-unavailable')` without network activity. This is recommended for CI pipelines and air-gapped environments.

### What information does the update manifest contain?

The manifest fetched by `fetchCandidate` and validated by `validateStableUpdateManifest` contains the semantic version string, SHA-256 artifact digest for integrity verification, release notes URL, and severity classification (`normal` or `security`). This data allows Archify to return detailed `update_available` objects without downloading the actual binaries.