How to Update Archify: Manual Installation and Update Checking Guide

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 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.

# 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:

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:

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:

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.

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