How Auto-Updates Work in OfficeCLI and How to Disable or Skip Them

OfficeCLI checks for new releases automatically in the background via UpdateChecker.cs, and you can permanently disable this behavior with officecli config autoUpdate false or skip it once using the OFFICECLI_SKIP_UPDATE=1 environment variable.

OfficeCLI, the open-source command-line tool from iOfficeAI/OfficeCLI, includes a self-updating mechanism that runs silently during command invocations. The update logic centers around the UpdateChecker class and stores its settings in a JSON configuration file, allowing you to control behavior through both persistent settings and environment variables.

Configuration Storage and the AutoUpdate Flag

Auto-update behavior is governed by the AutoUpdate boolean property stored in ~/.officecli/config.json. When the CLI initializes, it loads this configuration to determine whether to spawn background version checks. The UpdateChecker class reads this value at runtime and respects it for the duration of the session.

How the Background Check Works

In src/officecli/Core/UpdateChecker.cs, the CheckInBackground() method executes at the start of every CLI invocation. The flow follows these steps:

• Validation: It first checks for the OFFICECLI_SKIP_UPDATE environment variable; if present, the method returns immediately.
• Interval Check: If AutoUpdate is true and LastUpdateCheck exceeds the default CheckIntervalHours (24 hours), it proceeds.
• Spawn Process: The method calls SpawnRefreshProcess() to fire a detached background process that runs RunRefresh().
• Download: RunRefresh() queries https://d.officecli.ai (falling back to GitHub releases), downloads the latest binary to a temporary .update file, and exits.
• Application: On the next OfficeCLI run, ApplyPendingUpdate() detects the .update file and atomically swaps the old binary with the new version.

Permanently Disabling Auto-Updates

To disable automatic updates across all sessions, update the configuration setting:

officecli config autoUpdate false

This command writes "AutoUpdate": false to ~/.officecli/config.json. Verify the change by viewing your current settings:

officecli config

To re-enable updates later, run:

officecli config autoUpdate true

Skipping Updates for a Single Invocation

For one-time suppression without modifying persistent configuration, prefix your command with the environment variable:

OFFICECLI_SKIP_UPDATE=1 officecli view mydoc.pptx html

The CheckInBackground() method inspects this variable at entry and bypasses the entire update workflow when the value is set.

Inspecting the Configuration Directly

You can view the raw JSON to confirm the AutoUpdate state and last check timestamp:

cat ~/.officecli/config.json

Example output showing disabled auto-updates:

{
  "AutoUpdate": false,
  "LastUpdateCheck": "2026-07-12T03:14:00Z"
}

Summary

• Background mechanism: The UpdateChecker class in src/officecli/Core/UpdateChecker.cs handles version checks every 24 hours when AutoUpdate is enabled in ~/.officecli/config.json.
• Permanent disable: Run officecli config autoUpdate false to persistently disable automatic checking.
• Temporary skip: Set OFFICECLI_SKIP_UPDATE=1 to bypass the update check for a single command execution.
• Update application: Staged updates written to .update files are applied atomically on the next CLI startup via ApplyPendingUpdate().

Frequently Asked Questions

Can I change the 24-hour check interval?

No. The CheckIntervalHours value is hardcoded as a constant within UpdateChecker.cs and is not exposed as a user-configurable setting in the JSON configuration file.

What happens if the update download fails?

If the release mirror at d.officecli.ai or the GitHub fallback is unreachable, RunRefresh() logs the error silently and terminates without modifying the existing binary. The CLI continues operating on the current version until the next scheduled interval.

Does disabling auto-update prevent manual updates?

Disabling AutoUpdate stops only the automatic background checks. You can still perform manual updates by running the appropriate install command or by downloading and replacing the binary directly from the GitHub releases page.

Where is the staged update file stored?

The .update temporary file is written to the same directory as the OfficeCLI executable. The ApplyPendingUpdate() method looks for this file at startup and performs an atomic file swap to complete the installation.

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