How to Configure OfficeCLI Auto-Update Behavior Using Config Commands and Environment Variables

You can permanently toggle OfficeCLI's background update checks using officecli config autoUpdate true|false, or temporarily skip them for a single invocation by setting the OFFICECLI_SKIP_UPDATE=1 environment variable.

OfficeCLI, maintained in the iOfficeAI/OfficeCLI repository, automatically queries GitHub for new releases on startup to ensure users run the latest version. Learning how to configure OfficeCLI auto-update behavior is critical for CI/CD environments where deterministic builds are required or in air-gapped networks where external calls must be avoided.

Where Auto-Update Settings Are Stored

According to the source code in src/officecli/Core/UpdateChecker.cs (line 30), OfficeCLI persists its settings in a JSON file located at ~/.officecli/config.json. This file contains an AutoUpdate boolean flag that defaults to true, meaning the CLI will attempt to contact GitHub on startup unless explicitly configured otherwise.

Persistent Configuration Using the config Command

To change auto-update behavior permanently, use the built-in configuration command. The parsing logic for officecli config <key> [value] resides in UpdateChecker.cs (lines 444-492), where the CLI validates the key name and writes the updated value to disk.

Disabling Auto-Updates

Run the following to write AutoUpdate: false to your config file and prevent future background checks:

officecli config autoUpdate false

Re-enabling Auto-Updates

To restore automatic version checking, set the flag back to true:

officecli config autoUpdate true

One-Time Overrides with Environment Variables

For temporary suppression—such as in automated scripts or CI jobs—OfficeCLI respects the OFFICECLI_SKIP_UPDATE environment variable. As implemented in src/officecli/Program.cs (line 268), setting this variable to 1 causes an early exit from the update routine for that specific invocation, regardless of the stored config value.

Use this method when you cannot modify the persistent config but need to eliminate network calls for a single run:

OFFICECLI_SKIP_UPDATE=1 officecli get mydoc.docx some/path

In PowerShell, set the variable for the current session:

$env:OFFICECLI_SKIP_UPDATE = '1'
officecli get mydoc.docx some/path

Core Update Logic Implementation

The decision to check for updates occurs in UpdateChecker.cs (lines 66-88). The code first verifies that config.AutoUpdate is enabled, then compares the LastUpdateCheck timestamp against CheckIntervalHours to enforce a time-based throttle.

// Core decision flow from UpdateChecker.cs (lines 66-88)
if (config.AutoUpdate) {
    if (!config.LastUpdateCheck.HasValue ||
        (DateTime.UtcNow - config.LastUpdateCheck.Value).TotalHours >= CheckIntervalHours) {
        // Proceed to contact GitHub API for new releases
    }
}

This implementation ensures the CLI respects both the boolean flag and the elapsed time since the previous check, preventing excessive API requests.

Programmatic Configuration (Advanced)

For developers extending OfficeCLI, you can manipulate the configuration object directly using the UpdateChecker class methods:

var cfg = OfficeCLI.Core.UpdateChecker.LoadConfig();
cfg.AutoUpdate = false;
OfficeCLI.Core.UpdateChecker.SaveConfig(cfg);

This accesses the same AppConfig definition and persistence layer used by the CLI's built-in commands, ensuring consistency with the JSON schema.

Summary

• Persistent control: Use officecli config autoUpdate false to write "AutoUpdate": false to ~/.officecli/config.json, or true to re-enable background checks.
• Temporary bypass: Set OFFICECLI_SKIP_UPDATE=1 before invoking officecli to skip the check for a single run, as handled in Program.cs (line 268).
• Storage location: Configuration lives in ~/.officecli/config.json by default, defined in UpdateChecker.cs (line 30).
• Check interval: The logic in UpdateChecker.cs (lines 66-88) combines the AutoUpdate flag with a CheckIntervalHours throttle to regulate GitHub API calls.

Frequently Asked Questions

What is the default auto-update behavior in OfficeCLI?

By default, the AutoUpdate property in ~/.officecli/config.json is set to true. The application checks for new releases according to the interval logic defined in UpdateChecker.cs, provided the OFFICECLI_SKIP_UPDATE environment variable is not set.

Can I disable auto-updates without using the command line?

Yes. Since the configuration is stored as plain JSON in ~/.officecli/config.json, you can manually edit this file and set "AutoUpdate": false. However, using officecli config autoUpdate false is recommended to ensure proper schema validation as implemented in UpdateChecker.cs (lines 444-492).

Will setting OFFICECLI_SKIP_UPDATE permanently change my configuration?

No. The environment variable acts as a runtime override only. As seen in src/officecli/Program.cs (line 268), it causes an early return from the update routine without persisting any changes to disk. Your config.json retains its previous AutoUpdate value for subsequent executions where the variable is unset.

How frequently does OfficeCLI check for updates when enabled?

The source code in UpdateChecker.cs (lines 66-88) enforces a time-based interval using CheckIntervalHours. The CLI compares the current UTC time against config.LastUpdateCheck and only contacts GitHub if the elapsed duration exceeds this threshold, preventing checks on every single execution.

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