How to Configure Auto-Update Behavior in OfficeCLI Using Config Files and CLI Commands

You control OfficeCLI's auto-update behavior through the autoUpdate boolean in ~/.officecli/config.json or via the officecli config autoUpdate <true|false> command; no dedicated environment variable exists for user configuration.

OfficeCLI, the open-source CLI tool from the iOfficeAI repository, manages its self-updating mechanism through a per-user JSON configuration system. The UpdateChecker class in src/officecli/Core/UpdateChecker.cs provides both the background update logic and a built-in config command interface. Understanding how to manipulate the AppConfig settings allows you to enable or disable automatic updates across your development environments.

Where OfficeCLI Stores Auto-Update Settings

OfficeCLI persists user preferences in a dedicated configuration directory. According to the source code in src/officecli/Core/UpdateChecker.cs, the UpdateChecker.ConfigDir property points to ~/.officecli, while ConfigPath resolves to ~/.officecli/config.json【5†L28-L31】.

The AppConfig class defines the schema for this JSON file, including the critical AutoUpdate boolean field that defaults to true【5†L13-L18】. This single flag determines whether the application checks for and applies new versions in the background.

When running inside restricted environments such as containers where the home directory may be read-only, OfficeCLI falls back to /tmp/officecli-config.json【5†L73-L78】.

How to Check and Modify Auto-Update Settings

You can interact with the configuration using the built-in officecli config command implemented in HandleConfigCommand, or by manually editing the JSON file.

Using the CLI Command

The HandleConfigCommand method (lines 44-86 in UpdateChecker.cs) supports reading and writing config values:

Check the current setting:

officecli config autoUpdate

Disable auto-updates:

officecli config autoUpdate false

Enable auto-updates:

officecli config autoUpdate true

When you provide a second argument, the command writes the new value to the config file and persists it to disk immediately.

Editing the Config File Directly

You can manually create or modify ~/.officecli/config.json:

{
  "autoUpdate": false,
  "log": false,
  "lastUpdateCheck": "2026-07-31T12:00:00Z"
}

Save this file and OfficeCLI will respect the autoUpdate value on the next invocation.

How the Auto-Update Logic Works

The update mechanism follows a strict gate-checking pattern controlled by your config:

1. Startup: Program.cs invokes UpdateChecker.CheckInBackground() on every run.
2. Config Loading: The method calls LoadConfig() to read from ~/.officecli/config.json (or the /tmp fallback).
3. Gate Check: If config.AutoUpdate is false, the method returns early and skips the background refresh entirely【5†L66-L68】.
4. Background Spawn: Only when config.AutoUpdate is true and a day has passed since the last check does the system spawn a background process to query GitHub for new releases【5†L84-L88】.
5. Application: The background process (RunRefresh()) downloads and verifies the binary, writing a .update file. The next process start applies this pending update—again gated by the AutoUpdate setting.

Environment Variables vs. Config Files

There is no dedicated environment variable for controlling auto-update behavior in user-facing scenarios. The codebase only references OFFICECLI_SKIP_UPDATE as an internal mechanism to prevent child processes from recursively triggering updates during the refresh cycle. All user-level toggling must occur through the config file or the officecli config command interface.

Summary

• OfficeCLI stores auto-update preferences in ~/.officecli/config.json via the AppConfig class.
• The ** autoUpdate ** boolean (default true) controls whether CheckInBackground() executes the update logic.
• Use officecli config autoUpdate <true|false> to toggle the setting without manually editing JSON.
• Container environments automatically fall back to /tmp/officecli-config.json when the home directory is inaccessible.
• Environment variables like OFFICECLI_SKIP_UPDATE are reserved for internal process management and should not be used for user configuration.

Frequently Asked Questions

Where is the OfficeCLI config file located?

OfficeCLI stores its configuration at ~/.officecli/config.json on standard systems. If the application detects a container environment or an unwritable home directory, it automatically falls back to /tmp/officecli-config.json to ensure the config remains mutable.

How do I disable auto-updates in OfficeCLI?

Run the command officecli config autoUpdate false to disable automatic updates. Alternatively, manually set "autoUpdate": false in the JSON config file. When this value is false, the CheckInBackground() method skips both the update check and any pending update application.

Is there an environment variable to disable auto-updates?

No, OfficeCLI does not expose a user-facing environment variable for controlling auto-update behavior. The only related variable, OFFICECLI_SKIP_UPDATE, is used internally to prevent recursive update checks in child processes. Users must use the config file or CLI command to modify update settings.

What happens if I set autoUpdate to false?

When autoUpdate is false, OfficeCLI will not spawn the background process that checks GitHub for new releases, nor will it apply any pending updates waiting in the .update file. The application runs your current version indefinitely until you manually update or re-enable the flag.

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