How to Configure OfficeCLI Auto-Update Behavior and Config File Location

OfficeCLI stores its auto-update settings in ~/.officecli/config.json (falling back to /tmp/officecli-config.json in read-only containers) and defaults to checking for updates every 24 hours, which you can toggle via the officecli config autoupdate command or by editing the JSON directly.

The iOfficeAI/OfficeCLI repository implements a self-updating mechanism that runs silently in the background. According to the source code in src/officecli/Core/UpdateChecker.cs, the tool manages its configuration through a simple JSON file that controls update frequency, logging, and whether automatic upgrades are permitted.

Configuration File Location and Storage

OfficeCLI uses a deterministic path resolution strategy that prioritizes the user's home directory while providing a fallback for containerized environments.

Primary Config Path

The primary configuration file is ~/.officecli/config.json.

In src/officecli/Core/UpdateChecker.cs, the paths are constructed at lines 28-30:

• ConfigDir resolves to $HOME/.officecli
• ConfigPath resolves to $HOME/.officecli/config.json

The CLI creates this directory automatically if it does not exist when CheckInBackground is invoked.

Container Fallback Path

When running inside Docker, Kubernetes, AWS Lambda, or Google Cloud Run where the home directory is read-only, OfficeCLI falls back to /tmp/officecli-config.json.

This logic appears at lines 61-65 in UpdateChecker.cs, ensuring the tool remains functional in serverless and ephemeral compute environments.

Understanding the Auto-Update Configuration Schema

The configuration file maps to the AppConfig class defined in UpdateChecker.cs (lines 97-105):

public class AppConfig
{
    public DateTime? LastUpdateCheck { get; set; }
    public string?   LatestVersion      { get; set; }
    public bool      AutoUpdate  = true;   // <-- defaults to true
    public bool      Log;
    public string?   InstalledBinaryVersion;
    public string?   LastSkillRefreshVersion;
}

Key fields:

• AutoUpdate: Boolean flag defaulting to true (lines 100-102). When enabled, the CLI attempts to upgrade itself automatically.
• LastUpdateCheck: Timestamp of the last successful check, used to enforce the 24-hour check interval.
• LatestVersion: Caches the most recent version available from the repository.

How the Auto-Update Mechanism Works

The update flow operates on every CLI invocation through a background process to avoid blocking user commands.

The Check Interval Logic

1. CheckInBackground (line 73) loads the config and verifies the AutoUpdate flag.
2. If AutoUpdate is true and LastUpdateCheck exceeds the CheckIntervalHours threshold (24 hours), the method spawns a detached process at lines 77-80.
3. This process executes the hidden command __update-check__, which triggers RunRefresh (lines 93-164).

The Update Process

RunRefresh performs the following operations:

• Resolves the latest release from the official mirror or GitHub.
• Verifies the SHA-256 hash of the download.
• Downloads the appropriate binary asset for your platform.
• Executes a smoke test via RunVersionVerify.
• Replaces the existing executable (or writes a .update file on Windows for replacement on next start).

Package Manager Restrictions

If the binary is installed via Homebrew, the updater aborts after recording the latest version without modifying the executable (lines 58-60). This prevents conflicts with Homebrew's own version management.

Configuring Auto-Update Settings via CLI

OfficeCLI exposes a config sub-command implemented in HandleConfigCommand (lines 30-86) that allows runtime modification without manual file editing.

Reading the Current Setting

officecli config autoupdate

Output: true or false.

Enabling Auto-Update

officecli config autoupdate true

The command updates the in-memory AppConfig and persists it via SaveConfig (lines 82-88).

Disabling Auto-Update

officecli config autoupdate false

Example: Disabling on Shared Workstations

# Verify current state

$ officecli config autoupdate
true

# Disable permanently

$ officecli config autoupdate false
autoupdate = false

# Confirm change

$ officecli config autoupdate
false

After execution, ~/.officecli/config.json contains:

{
  "autoUpdate": false,
  "log": false,
  "lastUpdateCheck": null,
  "latestVersion": null,
  "installedBinaryVersion": null,
  "lastSkillRefreshVersion": null
}

The CLI ignores unknown JSON keys, allowing you to add custom metadata without breaking functionality.

Programmatic Configuration Management

You can interact with the configuration directly using the UpdateChecker class.

Reading Config Programmatically

using OfficeCli.Core;

// Load configuration (searches home then /tmp fallback)
AppConfig cfg = UpdateChecker.LoadConfig();

// Inspect the auto-update flag
bool isAuto = cfg.AutoUpdate;
Console.WriteLine($"Auto-update enabled: {isAuto}");

Modifying Config from Code

AppConfig cfg = UpdateChecker.LoadConfig();
cfg.AutoUpdate = false;               // disable automatic updates
UpdateChecker.SaveConfig(cfg);        // persists to ~/.officecli/config.json

Simulating Background Checks

For testing purposes, you can force an immediate refresh regardless of the 24-hour interval:

// Normally invoked by the spawned background process
UpdateChecker.RunRefresh();

Summary

• Configuration location: Primary path is ~/.officecli/config.json; containers use /tmp/officecli-config.json when the home directory is read-only.
• Default behavior: AutoUpdate defaults to true with a 24-hour check interval defined in src/officecli/Core/UpdateChecker.cs.
• CLI control: Use officecli config autoupdate <true|false> to toggle settings without editing files.
• Update flow: CheckInBackground spawns a silent process running __update-check__, which executes RunRefresh to download, verify, and replace the binary.
• Homebrew exception: Automatic replacement is disabled for Homebrew-managed installations to prevent package manager conflicts.

Frequently Asked Questions

Where is the OfficeCLI configuration file stored?

OfficeCLI stores its configuration at ~/.officecli/config.json by default. The path is constructed in UpdateChecker.cs (lines 28-30) using the ConfigDir and ConfigPath properties. In containerized environments where the home directory is read-only—such as Docker, Kubernetes, or Lambda—the tool falls back to /tmp/officecli-config.json (lines 61-65).

How do I disable automatic updates in OfficeCLI?

Run the command officecli config autoupdate false to disable the feature permanently. This updates the AutoUpdate field in the JSON configuration file to false. Alternatively, manually edit ~/.officecli/config.json and set "autoUpdate": false. The change takes effect immediately on the next CLI invocation.

What happens if OfficeCLI is installed via Homebrew?

When OfficeCLI detects it is managed by Homebrew, the auto-updater aborts after recording the latest version information but does not attempt to replace the binary. This check occurs at lines 58-60 in UpdateChecker.cs to prevent conflicts with Homebrew's own versioning system. You should use brew upgrade officecli instead to update Homebrew-managed installations.

Can I manually trigger an update check in OfficeCLI?

While the standard flow relies on the 24-hour interval triggered by CheckInBackground, you can programmatically force a refresh by calling UpdateChecker.RunRefresh() from within a C# application referencing the OfficeCLI core library. This method bypasses the timestamp check and immediately attempts to resolve, download, and install the latest version from the official repository.

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